Skip to content

feat: local session store and API (Phase 2, sessions PR 1/2) - #11

Merged
andrecoliveira merged 8 commits into
mainfrom
feat/session-store
Nov 15, 2026
Merged

andrecoliveira merged 8 commits into
mainfrom
feat/session-store

Conversation

@andrecoliveira

Copy link
Copy Markdown
Owner

Outcome

PR 1 of 2 for the Phase 2 sessions slice (spec, approved 2026-11-16; plan). It persists discovered graph revisions and Sandbox sessions in a local SQLite store outside the analyzed project. The Studio UI that uses the store is PR 2.

  • @archwise/application:
    • store ports: WorkspaceRepository, RevisionRepository, SessionRepository, Clock, IdGenerator, Digest;
    • SessionService: reserves a fresh session per launch, persists it on the first Sandbox save, and supports list, resume-in-place, rename and delete;
    • revision deduplication by a fingerprint of the content plus the view;
    • an in-memory adapter, and a reusable store contract suite at @archwise/application/testing.
  • @archwise/storage (new): built on node:sqlite, with no new npm dependency (ADR 0006). It provides:
    • OS data directory resolution, with an ARCHWISE_DATA_DIR override and mode 0700;
    • transactional migrations, re-checked under the write lock;
    • a backup before migrating, keeping the newest three;
    • a read-only integrity probe, with quarantine of a corrupt file and its WAL;
    • refusal of newer schemas;
    • a busy timeout on every connection, plus WAL;
    • a new storage-inward-only boundary rule, with regression tests.
  • CLI:
    • discovery is recorded as an archwise.graph revision through the new adapter;
    • the loopback server gains a protected session API under /api/v1/sessions*, requiring the capability cookie, a same-origin Origin on mutations, JSON bodies, a 300 kB limit, and 404s that never echo input;
    • new --sessions and --no-store flags;
    • store failures exit with code 2 and an actionable message;
    • the store is disabled when its directory is inside the analyzed project.
  • Docs: ADR 0006 and docs/sessions.md, plus updates to README, roadmap (Phase 2 status), architecture, security, code organization, the Alpha guide and package READMEs, and a changeset.

Verification

  • pnpm check (pnpm 10.34.9, Node 26, macOS): 329 Vitest + 16 Node integration tests pass.
  • The integration test runs the built CLI end to end: --sessions empty, then --serve, then save over HTTP, then kill the process, then --sessions lists the session. The analyzed fixture stays byte-identical.
  • Lifecycle tests cover:
    • backup before migration;
    • rollback leaving the file unchanged;
    • refusal of newer schemas;
    • quarantine including the WAL;
    • unwritable directory or file;
    • parallel first opens across 4 threads;
    • interleaved writes from two handles.
  • Independent whole-branch review: 0 Critical, 4 Important (all fixed, each with a test that failed first), and 7 Minor. Three Minors were upgraded by effect and fixed: WAL loss on quarantine, backup pruning order, and a read-only file. One documentation overstatement was fixed.
    • While fixing it, I found that a read-write integrity probe deleted a corrupt file's WAL on close. The probe is now read-only.
  • Deferred minors, recorded for PR 2:
    • Resuming strands the reserved ID. The semantics must be decided before autosave.
    • The 404 body text is inconsistent.
    • The store runs integrity_check on every launch, where quick_check might do.

Review notes

  • Security/privacy impact and offline behavior:
    • The store is local-only. It holds absolute root paths and Sandbox documents, which are never returned by the API or exported.
    • No source contents are stored.
    • New mutating routes are capability-protected and same-origin only.
  • Public contracts, migrations, and compatibility impact:
    • New store schema v1, with migration infrastructure.
    • archwise.graph revisions are now produced by the CLI.
    • /api/v1/graph and --graph are unchanged.
  • Documentation or ADR updates: ADR 0006 and the docs listed above. The docs state explicitly that the Studio still uses localStorage until PR 2.
  • Screenshots or accessibility evidence for UI changes: not applicable (no UI change).
  • Parent PR, if this change is stacked: none.

Checklist

  • The change has one coherent scope.
  • New contribution commits include my DCO Signed-off-by trailer.
  • Relevant tests or documentation checks were run.
  • No secrets, private fixtures, or machine-specific paths are included.
  • Implemented behavior is distinguished from future proposals.

🤖 Generated with Claude Code

andrecoliveira and others added 8 commits November 15, 2026 20:29
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
Compose the SQLite store and SessionService in the CLI:
- record each discovery as a revision;
- serve the session API;
- list sessions with --sessions;
- opt out with --no-store.

Store failures exit with code 2 and an actionable message. Corrupt files are
quarantined. Docs: ADR 0006, the sessions guide, and updates to README,
roadmap, architecture, security, alpha guide and package READMEs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
- Set busy_timeout on every connection before any work, and re-read the
  schema version under the write lock, so concurrent first opens succeed.
- Probe integrity through a read-only connection so a corrupt file's WAL
  is quarantined intact instead of being deleted on close.
- Prune backups by schema version, then time.
- Report a read-only store file as unwritable (exit 2).
- Include the view identity in the revision fingerprint so a changed view
  (e.g. framework labels) is never served from a stale revision.
- Disable the store when its directory is inside the analyzed project.
- CLI and docs no longer claim the Studio already saves sessions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: André Oliveira <coliveira.andre@gmail.com>
@andrecoliveira
andrecoliveira merged commit 7475553 into main Nov 15, 2026
12 checks passed
@andrecoliveira
andrecoliveira deleted the feat/session-store branch November 15, 2026 23:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant