Percorso 3: famiglia di artefatti di sessione SQLite

Questa nota delimita clawdbot-d63.2, mentre clawdbot-d63.1 gestisce l'helper sovrapposto per l'archiviazione durante il ripristino/l'eliminazione in src/config/sessions/session-accessor.sqlite.ts. Il file di implementazione presentava modifiche non salvate durante questa fase, pertanto questo artefatto registra il contratto esatto e i punti di modifica senza entrare in conflitto con il worker parallelo.

Famiglia autorevole

Dopo il passaggio a SQLite, le trascrizioni delle sessioni attive sono righe SQLite. La famiglia di archiviazione di una sessione è:

• Le righe transcript_events, transcript_event_identities e sessions per l'attuale sessionId della voce.
• Lo stesso insieme di righe della trascrizione SQLite per ogni sessionId a cui fa riferimento entry.compactionCheckpoints[*].preCompaction.sessionId.
• Lo stesso insieme di righe della trascrizione SQLite per ogni sessionId a cui fa riferimento entry.compactionCheckpoints[*].postCompaction.sessionId.
• Lo stesso insieme di righe della trascrizione SQLite per ogni sessionId in entry.usageFamilySessionIds.

Archiviare solo le righe a cui non fa più riferimento alcuna riga session_entries rimanente né i metadati della famiglia di Compaction o di utilizzo di alcuna voce rimanente. Ciò preserva lo stato di diramazione/ripristino dei checkpoint e di aggregazione dell'utilizzo finché non viene eliminato l'ultimo riferimento attivo.

Artefatti esterni alla famiglia dopo il passaggio

Le varianti generate dei file di trascrizione degli argomenti e i file sidecar delle traiettorie non costituiscono stato di runtime SQLite attivo. Sono artefatti di file legacy:

• Le varianti degli argomenti come <sessionId>-topic-<thread>.jsonl esistono solo per il formato di trascrizione basato su file. SQLite utilizza l'ID canonico della sessione più session_routes/i metadati di consegna della voce invece di file JSONL per ogni argomento.
• I file sidecar delle traiettorie come .trajectory.jsonl e .trajectory-path.json prendono il nome da percorsi sessionFile JSONL reali. I valori sessionFile di SQLite sono marcatori sqlite:<agentId>:<sessionId>:<storePath> e non indicano file sidecar.
• I lettori del livello di archiviazione devono continuare a leggere i file JSONL legacy archiviati, ma la conservazione in fase di runtime non deve esaminare le directory delle sessioni attive né riaprire i file di trascrizione JSONL per le sessioni SQLite.

L'importazione di Doctor resta responsabile della migrazione dei file JSONL primari legacy e dei relativi file sidecar delle traiettorie adiacenti. La conservazione SQLite in fase di runtime non deve aggiungere un secondo importatore né un fallback su file.

Punti di modifica

Estendere l'helper di archiviazione SQLite introdotto da clawdbot-d63.1 invece di aggiungere un percorso parallelo.

1. Aggiungere un raccoglitore locale vicino a deleteSqliteSessionStateIfUnreferenced:

   • collectSqliteSessionArtifactFamily(entry: SessionEntry): Set<string>
   • Includere entry.sessionId, gli ID di sessione precedenti/successivi al checkpoint e usageFamilySessionIds.
   • Filtrare le stringhe vuote ed eliminare i duplicati in modo deterministico.

2. Aggiungere un raccoglitore di riferimenti per l'archivio successivo alla rimozione:

   • readReferencedSqliteSessionArtifactFamilyIds(database): Set<string>
   • Iterare l'attuale session_entries, analizzare ogni entry_json e raccogliere gli stessi ID di famiglia da ogni voce superstite.

3. Modificare i chiamanti di ripristino/eliminazione/manutenzione che attualmente archiviano un solo sessionId rimosso affinché passino l'intera famiglia della voce rimossa.

4. Per ogni ID di famiglia, archiviare le righe della trascrizione SQLite con il motivo specificato dal chiamante (reset o deleted), quindi eliminare la riga sessions solo quando l'ID di famiglia è assente dall'insieme di riferimenti successivo alla rimozione.

5. Mantenere centralizzata l'eliminazione degli eventi della trascrizione tramite il percorso esistente di pulizia delle righe di sessione SQLite. Non aggiungere letture JSONL attive.

Test mirati

Aggiungere test esclusivi per SQLite a src/config/sessions/session-accessor.conformance.test.ts o al test del ciclo di vita parallelo dopo il commit di clawdbot-d63.1:

• L'eliminazione di una voce con una trascrizione precedente alla Compaction archivia sia la sessione corrente sia la sessione precedente alla Compaction, quindi rimuove entrambi gli insiemi di righe SQLite.
• L'eliminazione di una delle due voci che condividono una pre-sessione di Compaction non archivia nulla per la pre-sessione condivisa finché non viene rimossa l'ultima voce che vi fa riferimento.
• L'eliminazione di una voce con usageFamilySessionIds archivia le righe della trascrizione SQLite del predecessore quando nessun'altra voce fa riferimento a tale famiglia di utilizzo.
• Una chiave di sessione con struttura da argomento e un marcatore SQLite non causa alcuna lettura del JSONL generato per l'argomento né alcuna ricerca di file sidecar.

Per la verifica mirata utilizzare:

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

Se i test finali si trovano in store.session-lifecycle-mutation.test.ts, eseguire esplicitamente tale file con lo stesso wrapper. I gate generali pnpm devono rimanere su Crabbox/Testbox per questo worktree Codex.