feat: injectable session storage — ChatSessionRepository port (SDK P2, slice 2)

[roackb2]

Summary

Second slice of SDK maturation P2 (pluggable storage, posture rung 5), following the merged artifact-repository pattern (#224): chat session persistence is now injectable, so a hosted service can back the session catalog and session bodies with its own storage instead of the file catalog under the state root.

Design

Port already existed — this slice makes it real. ChatSessionRepository (list / readCatalog / read / save) was an internal interface with one implementer; the engine and the whole turn path constructed FileChatSessionRepository from a sessionStoragePath string at nine call sites. Now:

• Port cleanup: dropped deriveStoragePaths() from the port — it's file-layout detail only the File implementation needs internally. Hosted implementers no longer have to invent fake paths. Port doc added.
• Resolve once at the engine boundary: createConversationEngine({ sessionRepository }) resolves config.sessionRepository ?? new FileChatSessionRepository({ sessionStoragePath }) in config normalization. The instance flows to:
  • the session service (create/read/update/rename/archive/lease/settings)
  • turn context building (ConversationTurnContextBuilder)
  • preflight lease acquisition + compaction seed persistence
  • completed-turn persistence
  • background memory-maintenance turn-summary writes
  • lease clearing (clearLeaseFromStorage now takes the repository)
  • quickstart runner pass-through (runQuickstartConversationCli({ sessionRepository }))
• Direct EngineConversationTurnService.run(args) callers get the same resolve-once at the run() boundary (args.sessionRepository ?? File default), and every inner service receives the instance in its args instead of re-deriving storage from paths — deleting all nine scattered constructions.
• Session policy stays in Heddle: leases, records, and compaction state remain service-owned; the repository only persists.

Curated surface (rung 5): exports ChatSessionRepository, FileChatSessionRepository, ChatSessionCatalog(Entry), and ChatSession so implementers have the full contract.

Proof

• New engine test: session create/read/rename through an in-memory repository, asserting the on-disk chat-sessions.catalog.json is never created.
• Reworked inner-service tests (preflight/persistence/memory) now inject repository instances through the port rather than paths — the turn path is exercised port-first.

Verification

• yarn build — pass
• yarn test:unit — 601 passed · yarn test:integration — 285 passed
• yarn lint — clean

Docs: "Bring your own session storage" guide section, ladder README rung 5 updated, curated index rung-5 note updated. Traces and memory remain path-oriented — next slices, same pattern.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CjFdZgZhov8wdwFinVTfjz