중급5분 소요openclawreferencepath3-live-sqlite-e2e-harness

Path 3 live SQLite E2E harness

Path 3 live SQLite E2E harness 문서는 OpenClaw 공식 문서(reference/path3-live-sqlite-e2e-harness)를 한국어로 정리한 가이드입니다. Design for live Gateway proof of the Path 3 SQLite session/transcript flip 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Design for live Gateway proof of the Path 3 SQLite session/transcript flip

한국어 가이드 범위: reference/path3-live-sqlite-e2e-harness 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Command shape
Isolated built-CLI proof
Preflight
Agent-driven scenario
Per-step assertions
Evidence artifact
Safety rules
Passing result

상세 내용

본문

The Path 3 live SQLite E2E harness proves the Gateway is using SQLite as the canonical session and transcript store while legacy JSONL files remain migration input or archive material. It is a maintainer proof harness, not a normal user diagnostic.

Command shape

The command connects to an already running Gateway. It does not start, stop, import, or re-run the migration unless an explicit migration mode is added later. A CI or isolated-local variant can use test/helpers/openclaw-test-instance.ts, but the live proof path should inspect the actual operator Gateway and its real per-agent SQLite database.

node scripts/path3-live-sqlite-e2e.mjs \
  --url http://127.0.0.1:18789 \
  --agent main \
  --session-key agent:main:path3-live-e2e:<timestamp> \
  --json

Isolated built-CLI proof

The built-CLI proof runner seeds an isolated legacy session store, starts the rebuilt Gateway, and proves that startup imports hot legacy sessions into SQLite before runtime reads begin. It must not run openclaw doctor --fix before the first Gateway start, because that would prove the manual migration path instead of the upgrade path users receive on first boot after the flip.

Preflight

Preflight collects a baseline and fails before sending a proof turn if the Gateway is not usable:

주요 항목:

GET /health and Gateway deep status must report a running, reachable
The CLI and Gateway versions must match the branch being tested.
The harness records a log cursor for the active Gateway file log.
The harness records per-agent SQLite table counts for sessions,
The harness records mtime, size, and existence for legacy
lsof -p <gateway-pid> must show SQLite DB/WAL/SHM handles and no hot

Agent-driven scenario

The live scenario uses a dedicated proof session key and drives the Gateway through public RPC paths wherever possible. One agent turn should be enough to exercise ordinary persistence, but the full proof should cover the 3.1b seams that previously required individual live checks:

주요 항목:

Ordinary chat turn: create or reuse the proof session, send a real agent
Transcript identity: verify the same marker appears in Gateway history and in
Session metadata accessors: read the proof session and selected existing live
Session patch projection: apply a reversible model/session metadata change on
Compaction checkpoint lifecycle: list, branch, and restore a checkpoint only
Restart recovery: run the safe recovery marker path against a controlled proof
Cleanup lifecycle: delete or reset the proof session, then verify SQLite

Per-step assertions

Each step snapshots before and after state and writes a structured assertion record:

주요 항목:

SQLite row counts advance only where expected.
Trajectory runtime rows advance for marker-backed proof sessions that record
The proof session row has the expected session_id, status, timestamps,
Gateway history/session projection matches the SQLite transcript tail.
No proof-session JSONL file is created or modified.
No proof-session .trajectory.jsonl, .trajectory-path.json, or
Existing legacy JSONL files and sessions.json remain unchanged unless the
The Gateway process does not open .jsonl or sessions.json handles.
Logs since the previous cursor contain no ERROR, FATAL, SQLITE_,

Evidence artifact

The harness should write evidence under .artifacts/path3-live-e2e// and keep it out of git:

주요 항목:

summary.json: command args, Gateway version, result, failed assertion, and
sqlite-before.json and sqlite-after.json: row counts and selected proof
legacy-files.json: legacy file existence, mtime, size, and whether each
gateway-log-scan.json: cursor range, matched log lines, and allowlist
events.jsonl: ordered per-step observations suitable for PR proof comments.

Safety rules

affected SQLite DB and legacy session directory.

주요 항목:

Live mode must never re-import legacy JSONL while the Gateway is running.
Live mode must not mutate non-proof sessions except for explicitly selected,
Any destructive or broad migration step requires a fresh backup of the
Backups should be scoped to the touched agent DB/session directory and reused
The cleanup step must leave no proof session, proof JSONL, or modified legacy

Passing result

A passing live run means the Gateway accepted a real agent-driven session flow, all observed canonical state was in SQLite, legacy runtime files stayed quiescent, and log health stayed clean for the measured window. It does not mean legacy JSONL parity remains clean after live traffic; live drift is expected once SQLite is the canonical store.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/path3-live-sqlite-e2e-harness
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

node scripts/path3-live-sqlite-e2e.mjs \
  --url http://127.0.0.1:18789 \
  --agent main \
  --session-key agent:main:path3-live-e2e:<timestamp> \
  --json

Path 3 live SQLite E2E harness

핵심 요약

Design for live Gateway proof of the Path 3 SQLite session/transcript flip

한국어 가이드 범위: reference/path3-live-sqlite-e2e-harness 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Command shape
Isolated built-CLI proof
Preflight
Agent-driven scenario
Per-step assertions
Evidence artifact
Safety rules
Passing result

상세 내용

본문

Command shape

node scripts/path3-live-sqlite-e2e.mjs \
  --url http://127.0.0.1:18789 \
  --agent main \
  --session-key agent:main:path3-live-e2e:<timestamp> \
  --json

Isolated built-CLI proof

Preflight

Preflight collects a baseline and fails before sending a proof turn if the Gateway is not usable:

주요 항목:

GET /health and Gateway deep status must report a running, reachable
The CLI and Gateway versions must match the branch being tested.
The harness records a log cursor for the active Gateway file log.
The harness records per-agent SQLite table counts for sessions,
The harness records mtime, size, and existence for legacy
lsof -p <gateway-pid> must show SQLite DB/WAL/SHM handles and no hot

Agent-driven scenario

주요 항목:

Ordinary chat turn: create or reuse the proof session, send a real agent
Transcript identity: verify the same marker appears in Gateway history and in
Session metadata accessors: read the proof session and selected existing live
Session patch projection: apply a reversible model/session metadata change on
Compaction checkpoint lifecycle: list, branch, and restore a checkpoint only
Restart recovery: run the safe recovery marker path against a controlled proof
Cleanup lifecycle: delete or reset the proof session, then verify SQLite

Per-step assertions

Each step snapshots before and after state and writes a structured assertion record:

주요 항목:

SQLite row counts advance only where expected.
Trajectory runtime rows advance for marker-backed proof sessions that record
The proof session row has the expected session_id, status, timestamps,
Gateway history/session projection matches the SQLite transcript tail.
No proof-session JSONL file is created or modified.
No proof-session .trajectory.jsonl, .trajectory-path.json, or
Existing legacy JSONL files and sessions.json remain unchanged unless the
The Gateway process does not open .jsonl or sessions.json handles.
Logs since the previous cursor contain no ERROR, FATAL, SQLITE_,

Evidence artifact

The harness should write evidence under .artifacts/path3-live-e2e// and keep it out of git:

주요 항목:

summary.json: command args, Gateway version, result, failed assertion, and
sqlite-before.json and sqlite-after.json: row counts and selected proof
legacy-files.json: legacy file existence, mtime, size, and whether each
gateway-log-scan.json: cursor range, matched log lines, and allowlist
events.jsonl: ordered per-step observations suitable for PR proof comments.

Safety rules

affected SQLite DB and legacy session directory.

주요 항목:

Live mode must never re-import legacy JSONL while the Gateway is running.
Live mode must not mutate non-proof sessions except for explicitly selected,
Any destructive or broad migration step requires a fresh backup of the
Backups should be scoped to the touched agent DB/session directory and reused
The cleanup step must leave no proof session, proof JSONL, or modified legacy

Passing result

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/path3-live-sqlite-e2e-harness
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

node scripts/path3-live-sqlite-e2e.mjs \
  --url http://127.0.0.1:18789 \
  --agent main \
  --session-key agent:main:path3-live-e2e:<timestamp> \
  --json

Path 3 live SQLite E2E harness

핵심 요약

문서 구성

상세 내용

본문

Command shape

Isolated built-CLI proof

Preflight

Agent-driven scenario

Per-step assertions

Evidence artifact

Safety rules

Passing result

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Path 3 live SQLite E2E harness

핵심 요약

문서 구성

상세 내용

본문

Command shape

Isolated built-CLI proof

Preflight

Agent-driven scenario

Per-step assertions

Evidence artifact

Safety rules

Passing result

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드