OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Get started

경로 3 SQLite 세션 아티팩트 계열

경로 3 SQLite 세션 아티팩트 패밀리

이 메모에서는 clawdbot-d63.2의 범위를 정합니다. 한편 clawdbot-d63.1은 src/config/sessions/session-accessor.sqlite.ts에서 범위가 겹치는 재설정/삭제 아카이브 헬퍼를 담당합니다. 이번 작업 중 구현 파일에 커밋되지 않은 변경 사항이 있었으므로, 이 아티팩트에는 다른 작업자와 충돌하지 않도록 정확한 계약과 패치 지점을 기록합니다.

권위 있는 패밀리

SQLite 전환 후 활성 세션 트랜스크립트는 SQLite 행입니다. 세션의 아카이브 패밀리는 다음과 같습니다.

  • 항목의 현재 sessionId에 해당하는 transcript_events, transcript_event_identities, sessions 행
  • entry.compactionCheckpoints[*].preCompaction.sessionId가 참조하는 모든 sessionId에 해당하는 동일한 SQLite 트랜스크립트 행 집합
  • entry.compactionCheckpoints[*].postCompaction.sessionId가 참조하는 모든 sessionId에 해당하는 동일한 SQLite 트랜스크립트 행 집합
  • entry.usageFamilySessionIds의 모든 sessionId에 해당하는 동일한 SQLite 트랜스크립트 행 집합

남아 있는 어떤 session_entries 행에서도, 또는 남아 있는 어떤 항목의 Compaction이나 사용량 패밀리 메타데이터에서도 더 이상 참조하지 않는 행만 아카이브하십시오. 이렇게 하면 마지막 활성 참조가 사라질 때까지 체크포인트 분기/복원 및 사용량 롤업 상태가 보존됩니다.

전환 후 패밀리가 아닌 아티팩트

생성된 주제 트랜스크립트 파일 변형과 트래젝터리 사이드카는 활성 SQLite 런타임 상태가 아닙니다. 이는 레거시 파일 아티팩트입니다.

  • <sessionId>-topic-<thread>.jsonl 같은 주제 변형은 파일 기반 트랜스크립트 형식에만 존재합니다. SQLite는 주제별 JSONL 파일 대신 정규 세션 ID와 session_routes/항목 전달 메타데이터를 사용합니다.
  • .trajectory.jsonl 및 .trajectory-path.json 같은 트래젝터리 사이드카는 실제 JSONL sessionFile 경로를 기반으로 이름이 지정됩니다. SQLite sessionFile 값은 sqlite:<agentId>:<sessionId>:<storePath> 마커이며 사이드카 파일을 나타내지 않습니다.
  • 아카이브 계층 리더는 레거시 아카이브 JSONL 파일을 계속 읽어야 하지만, 런타임 보존 처리는 활성 세션 디렉터리를 스캔하거나 SQLite 세션의 JSONL 트랜스크립트 파일을 다시 열어서는 안 됩니다.

Doctor 가져오기는 레거시 기본 JSONL 파일과 인접한 트래젝터리 사이드카의 마이그레이션 담당자로 유지됩니다. 런타임 SQLite 보존 처리에 두 번째 가져오기 도구나 파일 폴백을 추가해서는 안 됩니다.

패치 지점

병렬 경로를 추가하지 말고 clawdbot-d63.1에서 도입한 SQLite 아카이브 헬퍼를 확장하십시오.

  1. deleteSqliteSessionStateIfUnreferenced 근처에 로컬 수집기를 추가합니다.

    • collectSqliteSessionArtifactFamily(entry: SessionEntry): Set<string>
    • entry.sessionId, 체크포인트의 전/후 세션 ID 및 usageFamilySessionIds를 포함합니다.
    • 빈 문자열을 필터링하고 결정론적으로 중복을 제거합니다.

  2. 제거 후 저장소를 위한 참조 수집기를 추가합니다.

    • readReferencedSqliteSessionArtifactFamilyIds(database): Set<string>
    • 현재 session_entries를 순회하고 각 entry_json을 파싱한 다음, 남아 있는 모든 항목에서 동일한 패밀리 ID를 수집합니다.

  3. 현재 제거된 sessionId 하나를 아카이브하는 재설정/삭제/유지관리 호출자가 제거된 항목의 전체 패밀리를 전달하도록 변경합니다.

  4. 각 패밀리 ID에 대해 호출자의 사유(reset 또는 deleted)로 SQLite 트랜스크립트 행을 아카이브한 다음, 해당 패밀리 ID가 제거 후 참조 집합에 없을 때만 sessions 행을 삭제합니다.

  5. 기존 SQLite 세션 행 정리 경로를 통해 트랜스크립트 이벤트 삭제를 중앙화된 상태로 유지합니다. 활성 JSONL 읽기를 추가하지 마십시오.

집중 테스트

clawdbot-d63.1이 커밋된 후 src/config/sessions/session-accessor.conformance.test.ts 또는 같은 계층의 수명 주기 테스트에 SQLite 전용 테스트를 추가합니다.

  • Compaction 이전 트랜스크립트가 있는 항목을 삭제하면 현재 세션과 Compaction 이전 세션이 모두 아카이브된 후, 두 SQLite 행 집합이 모두 제거됩니다.
  • Compaction 이전 세션을 공유하는 두 항목 중 하나를 삭제하면, 마지막으로 참조하는 항목이 제거될 때까지 공유된 이전 세션에 대해서는 아무것도 아카이브되지 않습니다.
  • usageFamilySessionIds가 있는 항목을 삭제하면 다른 항목에서 해당 사용량 패밀리를 참조하지 않을 때 선행 SQLite 트랜스크립트 행이 아카이브됩니다.
  • SQLite 마커가 있는 주제 형태의 세션 키로 인해 생성된 주제 JSONL 읽기 또는 사이드카 조회가 발생하지 않습니다.

집중 검증에는 다음을 사용해야 합니다.

bash
node scripts/run-vitest.mjs src/config/sessions/session-accessor.conformance.test.ts

최종 테스트가 store.session-lifecycle-mutation.test.ts에 있다면 동일한 래퍼로 해당 파일을 명시적으로 실행하십시오. 이 Codex 작업 트리의 광범위한 pnpm 게이트는 Crabbox/Testbox에서 실행해야 합니다.

Was this useful?
On this page

On this page