salidium 0.1.0 → 0.2.1

package/README.md

@@ -1,122 +1,69 @@
 # Salidium
 
-Salidium translates coding-agent work into a trustworthy, structured explanation a human can read in seconds:
+**Visualize your agent's work with diagrams and evidence you can check, not walls of text.**
 
-- **What** the agent is doing and what changed
-- **Why** (the user's ask and the agent's stated discoveries — always attributed)
-- **How** (plan and approach)
-- **Verified** — what evidence actually shows (test/build/typecheck/lint runs parsed from real output)
-- **Left** — what remains
-- **Review** — what needs a human (waiting for permission, failing checks, unverified changes, destructive commands, claims without evidence)
-
-The daemon, event store, deterministic report, and interface run entirely on your machine with no Salidium telemetry or hosted service. Salidium observes the agent you already run through supported integration points (hooks and the agent's own session logs), derives facts deterministically, and relays the agent's claims verbatim and labelled. Every observed statement links back to the raw record it came from.
-
-The optional visual explanation uses your selected installed Claude Code or Codex CLI. Once per completed turn, Salidium sends that agent a bounded, redacted summary of the ask, statements, file names, and check outcomes; the CLI may contact its provider and consume your existing plan or API allowance. The invocation is tool-free, treats the session evidence as untrusted data, and accepts only a bounded, runtime-validated result. Older Codex versions that do not support the tool-disable flags fail closed and simply omit the generated block. Set `SALIDIUM_EXPLAINER=off` (or the legacy `SALIDIUM_EXPLAIN=0`) to send nothing to an agent. The deterministic report still works when explanation is off, unavailable, or fails.
-
-It is also allowed to say nothing. A claim the classifier cannot place is recorded and reachable through `record`, and filed under no heading — Salidium may say less than it knows, and may not say something it does not know.
-
-The session page is laid out as a written document rather than a dashboard: the product mark, the session title, the facts that identify the run, and the **badges** — did it work, what needs a human, what is unfinished — then a rule, then the **explanation**: one sentence saying what the session is about, followed by the diagrams that carry the meaning. Supporting facts stay behind their toolbar controls so the explanation remains the canvas.
-
-Detail is opened by section rather than by one global depth control. **Evidence** opens coverage, checks, changes, and the event record; **Rewind** reconstructs the session at a chosen moment; and **Quantities** and **History** share one supporting inspector beside the page, replacing one another without squeezing the explanation into a third column.
-
-The session list groups by the question it answers — **Needs you**, **Working**, **Recent** — because you are usually running more than one agent at a time. It folds away with `[`, and the sessions that started and ended without running a turn are collapsed behind one line. Light, dark and system themes are all first-class and the choice is remembered.
-
-Providers today: **Claude Code** (hooks + transcript, primary) and **Codex** (rollout files + hooks).
-
-## Run it
-
-Requirements: Node ≥ 24, because the daemon uses the built-in `node:sqlite`.
+Reading back a Claude Code or Codex run means scrolling the whole transcript. Salidium reads it and
+draws what happened. You do not have to wait for the run to end. The report updates while the agent
+is still working, and an explanation is written at the end of each turn.
 
 ```bash
 npx salidium
 ```
 
-On first run, Salidium detects Claude Code and Codex from their local commands or state directories. If a detected agent still needs configuration, Salidium shows the settings files it wants to update and asks one combined permission question. Approved connections are merged with existing hooks and settings, checked, then Salidium starts and opens the interface. If Salidium adds or changes Codex hooks, Codex requires one additional review in `/hooks` before those hooks run.
-
-Later, the same command starts or finds the daemon and opens Salidium without repeating completed setup. In a non-interactive terminal, Salidium never waits for input and does not change provider settings unless `--yes` is passed. Use `--no-open` when a browser should not open.
-
-`salidium` is a single self-contained script with no runtime dependencies: its public workspace
-packages are not published separately and are bundled into it, so running it adds nothing to your
-tree but Salidium itself.
-
-```bash
-salidium install-hooks  # connect detected agents manually
-salidium uninstall-hooks
-salidium doctor         # check or troubleshoot the local setup
-salidium show           # print the same report as text (--detail=summary|detail|source)
-salidium audit-claims   # measure the claim classifier against every session in your own store
-salidium reingest --all # re-read your session files after an upgrade taught the adapters something new
-salidium retention      # preview/set forever, 30, 90, or 365 day local history retention
-salidium retention compact # offline integrity-check and return reusable database pages to the OS
-salidium pin [session]  # exempt a session from automatic retention
-salidium forget <id>    # remove a session while preventing source-file resurrection
-salidium status         # daemon and hook state
-salidium restart        # stop it, start it again, and open the UI on the new token
-salidium stop
-```
-
-`install-hooks`, `uninstall-hooks`, and `doctor` remain available for manual setup and recovery. Installation and removal touch only Salidium-owned hook entries; unrelated provider settings and hooks are preserved.
-
-Existing transcripts from the last 7 days are imported on first start (`SALIDIUM_HISTORY_DAYS`, a whole number 0 or greater); new sessions appear within a second of their first hook. State lives in `~/.salidium` (0700): `salidium.db`, `daemon.json` (port + token, 0600), the hook relay script, and a spool for hooks that fired while the daemon was down.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twinkling-reality/salidium/main/apps/site/public/tour-dark.gif">
+  <img src="https://raw.githubusercontent.com/twinkling-reality/salidium/main/apps/site/public/tour-light.gif" alt="Salidium in use: a report of a checkout fix, the session list folded away to give the report the window, the Evidence panel showing which changed files have had a passing check, the record behind one of them, and the report wound back to a moment when the check was still green.">
+</picture>
+
+Salidium is [MIT-licensed](LICENSE), open source, and local-first. The report, event store, and
+interface run on your machine with no Salidium telemetry. Raw transcripts stay local. Optional
+generated explanations send a bounded, redacted excerpt through your installed agent CLI, which
+may contact its provider; they can be turned off.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/twinkling-reality/salidium/main/apps/site/public/report-dark.png">
+  <img src="https://raw.githubusercontent.com/twinkling-reality/salidium/main/apps/site/public/report-light.png" alt="A full report: the verdict, Why drawn as two paths converging on one order charged twice, How drawn as one idempotency key per order, and the approach the agent abandoned beside the one it adopted.">
+</picture>
+
+Supported agents: Claude Code and Codex. Node.js 24 or newer is required. On first run Salidium
+finds the agents, shows the local settings it wants to update, asks permission, and opens the
+interface.
+
+## Documentation
+
+The documentation is at [salidium.com/docs](https://salidium.com/docs).
+
+1. [Install](https://salidium.com/docs/install)
+2. [Opening the page](https://salidium.com/docs/the-page)
+3. [Sessions](https://salidium.com/docs/sessions)
+4. [Reading a report](https://salidium.com/docs/report)
+5. [Evidence](https://salidium.com/docs/evidence)
+6. [Rewind, History and Quantities](https://salidium.com/docs/rewind)
+7. [Records](https://salidium.com/docs/records)
+8. [How we know](https://salidium.com/docs/provenance)
+9. [Explanations](https://salidium.com/docs/explanations)
+10. [What stays on your machine](https://salidium.com/docs/local)
+11. [Keyboard](https://salidium.com/docs/keyboard)
+12. [CLI](https://salidium.com/docs/cli)
+13. [Environment](https://salidium.com/docs/environment)
+14. [Limits](https://salidium.com/docs/limits)
+
+In this repository: [Using Salidium](docs/using-salidium.md),
+[architecture](docs/architecture.md), the
+[open-source and hosted-service boundary](docs/open-source-boundary.md),
+[long-term intelligence](docs/long-term-intelligence.md) and its
+[evaluation protocol](docs/evaluation-protocol.md), [contributing](CONTRIBUTING.md), and the
+[security policy](SECURITY.md).
 
 ## Development
 
 ```bash
-pnpm install
-pnpm build        # typecheck + build every package and the UI
-pnpm salidium     # run the CLI from source (Node type stripping)
-pnpm typecheck    # tsc --build (project references)
-pnpm lint         # biome check
-pnpm format       # biome format --write
-pnpm test         # vitest: unit, adapter fixtures, daemon integration, performance
-pnpm test:e2e     # real-daemon Chromium + automated accessibility checks
-pnpm test:e2e:full # Chromium, Firefox, and WebKit portability matrix
-pnpm package      # build the publishable bundle into packages/cli/bundle
-pnpm --filter @salidium/ui dev   # Vite dev server for the UI, proxied to the running daemon (open it with #token=… from ~/.salidium/daemon.json)
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
 ```
 
-CI runs lint, build and the full test suite on Ubuntu with Node 24, plus focused native macOS and
-Windows checks. It then packs the tarball, unpacks it somewhere with no workspace above it and
-starts the daemon from it — because the published bundle and the checkout resolve paths
-differently, and only the second arrangement is what a user gets.
-
-Release preparation, the manual-only publish workflow, and rollback steps are documented in
-[`docs/releasing.md`](docs/releasing.md).
-
-### Measuring the claims layer
-
-`salidium audit-claims` replays every agent message in your store through the classifier and reports what it did with them: the distribution by kind and by rule, how many messages produced nothing at all, and a seeded random sample of each rule's output to read. Classifier behavior can vary with providers and writing styles, so the honest way to know whether its conservative rules hold for your sessions is to measure your own local corpus.
-
-```bash
-salidium audit-claims                          # counts, plus 8 sampled claims per rule
-salidium audit-claims --only=discovery --sample=20
-salidium audit-claims --json                   # for a script
-```
-
-`pnpm salidium …` runs the CLI from source with Node's type stripping (`--conditions=development`); `pnpm build` emits `dist/` for every package.
-
-## Architecture (short)
-
-```
-agent runtime ──hooks (async sh relay)──▶ ┐
-              ──session log (tailed)────▶ ├─▶ provider adapter → canonical events → dedupe → redact → reducer → semantic state + change log
-                                          ┘                                                     │
-                                                                  SQLite (events, changes, checkpoints) ◀─┘─▶ SSE → UI (same reducer)
-```
-
-- `packages/protocol` — zod schemas shared by everything: canonical events, semantic changes, wire protocol, provenance vocabulary.
-- `packages/core` — pure derivation: `applyEvent(state, event) → SemanticChange[]`, session projections, verification parsing, review rules, redaction, replay.
-- `packages/adapter-kit`, `packages/adapters/*` — provider parsers (transcript/rollout lines + hook payloads → events with deterministic ids).
-- `packages/daemon` — tailing, hook ingress, persistence, git snapshots, loopback HTTP/SSE server.
-- `packages/ui` — React client that folds the event stream with the same reducer.
-- `packages/cli` — `salidium` command.
-
-See [docs/architecture.md](docs/architecture.md) for the decisions and boundaries.
-
-## Status
-
-MVP. The integration and replay paths are exercised against synthetic fixtures and local provider
-sessions for Claude Code and Codex. The claim classifier is deliberately conservative, but its
-behavior may vary across providers and writing styles; `audit-claims` is how to evaluate it on your
-own store. Native Windows history import is supported, but live hooks still require POSIX `sh` and
-`curl`. See the architecture document for the complete limitations.
+Run from source with `pnpm salidium`. The public CLI is bundled as one self-contained script, and
+the separately releasable `@salidium/sync-contract` contains only strict interoperability schemas.

package/bundle/salidium.mjs

@@ -1114,7 +1114,8 @@ function applyVerificationReview(state, event, log) {
       epistemic: v.outcomeEpistemic
     });
   } else if (v.outcome === "pass" && v.scope !== "partial") {
-    resolve(state, event, (r) => r.id === `verification-failed:${v.method}` || r.rule === "changes-unverified");
+    const covers = v.method !== "lint";
+    resolve(state, event, (r) => r.id === `verification-failed:${v.method}` || covers && r.rule === "changes-unverified");
   }
 }
 function applyReviewRulesAfterEvent(state, event, log) {
@@ -23044,6 +23045,7 @@ var SessionCoordinator = class _SessionCoordinator {
       cadence: envAllows ? "turn" : "off",
       idleEndMs: IDLE_END_MS,
       explainSession: explainWithStatus,
+      now: Date.now,
       ...args.options
     };
     const cp = store.latestCheckpoint(sessionId, REDUCER_VERSION);
@@ -23083,7 +23085,7 @@ var SessionCoordinator = class _SessionCoordinator {
     return coord;
   }
   get summary() {
-    const s = summarizeSession(this.state, Date.now());
+    const s = summarizeSession(this.state, this.opts.now());
     s.explanationStatus = this.explanationIsCurrent() ? "generated" : this.explanationStatus;
     return s;
   }
@@ -23397,10 +23399,13 @@ var SessionRegistry = class {
    * load: it is one value for the whole daemon, and a coordinator is created on the ingest path.
    */
   explainerCadence = "turn";
+  /** Handed to every coordinator this registry loads; see `CoordinatorOptions.now`. */
+  now;
   constructor(store, opts = {}) {
     this.store = store;
     if (opts.explainerCadence)
       this.explainerCadence = opts.explainerCadence;
+    this.now = opts.now;
     this.listener = {
       onEvents: (sessionId, events, changes) => {
         for (const s of this.allSubscribers) {
@@ -23444,7 +23449,7 @@ var SessionRegistry = class {
         cwd: hint?.cwd,
         store: this.store,
         listener: this.listener,
-        options: { cadence: this.explainerCadence }
+        options: { cadence: this.explainerCadence, ...this.now ? { now: this.now } : {} }
       });
       c.onError = (err) => this.onPersistError?.(sessionId, err);
       this.live.set(sessionId, c);
@@ -24169,7 +24174,7 @@ import { dirname as dirname2 } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { isDeepStrictEqual } from "node:util";
 import { gunzipSync, gzipSync } from "node:zlib";
-var SCHEMA_VERSION = 5;
+var SCHEMA_VERSION = 6;
 var INGEST_PARSER_REVISION = "2026-08-19.1";
 function existingSchemaVersion(db) {
   try {
@@ -24312,6 +24317,109 @@ CREATE TABLE IF NOT EXISTS usage_rollups (
   cache_write_tokens INTEGER NOT NULL DEFAULT 0
 );
 `;
+var SCHEMA_6_DDL = `
+CREATE TABLE IF NOT EXISTS sync_identity (
+  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+  replica_id TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS sync_streams (
+  stream_id TEXT PRIMARY KEY,
+  replica_id TEXT NOT NULL,
+  -- Positions are unique per generation, not per replica. A replica restored from an older backup
+  -- bumps this so its reused positions are a declared restart rather than a content conflict.
+  replica_generation INTEGER NOT NULL DEFAULT 1,
+  destination_id TEXT NOT NULL UNIQUE,
+  next_control_position INTEGER NOT NULL DEFAULT 0,
+  next_data_position INTEGER NOT NULL DEFAULT 0,
+  acknowledged_control_position INTEGER NOT NULL DEFAULT -1,
+  acknowledged_data_position INTEGER NOT NULL DEFAULT -1,
+  previous_control_operation_id TEXT,
+  previous_data_operation_id TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS sync_consent_revisions (
+  stream_id TEXT NOT NULL,
+  grant_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'revoked')),
+  destination_id TEXT NOT NULL,
+  json TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  PRIMARY KEY (stream_id, grant_id, revision),
+  FOREIGN KEY (stream_id) REFERENCES sync_streams(stream_id)
+);
+CREATE INDEX IF NOT EXISTS sync_consent_current
+  ON sync_consent_revisions(stream_id, grant_id, revision DESC);
+CREATE TABLE IF NOT EXISTS intelligence_records (
+  stream_id TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  grant_id TEXT NOT NULL,
+  grant_revision INTEGER NOT NULL,
+  current INTEGER NOT NULL CHECK (current IN (0, 1)),
+  json TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  PRIMARY KEY (stream_id, item_id, revision),
+  FOREIGN KEY (stream_id) REFERENCES sync_streams(stream_id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS intelligence_one_current_revision
+  ON intelligence_records(stream_id, item_id) WHERE current = 1;
+CREATE TABLE IF NOT EXISTS intelligence_evidence_map (
+  evidence_id TEXT PRIMARY KEY,
+  independence_id TEXT NOT NULL,
+  session_id TEXT,
+  event_id TEXT,
+  authority TEXT NOT NULL,
+  role TEXT NOT NULL,
+  captured_at TEXT NOT NULL,
+  descriptor_digest TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS intelligence_tombstones (
+  stream_id TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  delete_through_revision INTEGER NOT NULL,
+  reason TEXT NOT NULL,
+  requested_at TEXT NOT NULL,
+  receipt_id TEXT,
+  completed_at TEXT,
+  PRIMARY KEY (stream_id, item_id),
+  FOREIGN KEY (stream_id) REFERENCES sync_streams(stream_id)
+);
+CREATE TABLE IF NOT EXISTS sync_outbox (
+  stream_id TEXT NOT NULL,
+  lane TEXT NOT NULL CHECK (lane IN ('control', 'data')),
+  position INTEGER NOT NULL,
+  operation_id TEXT NOT NULL UNIQUE,
+  operation_type TEXT NOT NULL,
+  content_digest TEXT NOT NULL,
+  grant_id TEXT,
+  item_id TEXT,
+  json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TEXT,
+  acknowledged_at TEXT,
+  -- A destination can refuse an operation permanently. That is a distinct outcome from durable
+  -- acceptance and must never be recorded as one, or a refused record would read as delivered.
+  refused_at TEXT,
+  refusal_code TEXT,
+  PRIMARY KEY (stream_id, lane, position),
+  FOREIGN KEY (stream_id) REFERENCES sync_streams(stream_id)
+);
+CREATE INDEX IF NOT EXISTS sync_outbox_pending
+  ON sync_outbox(stream_id, lane, acknowledged_at, position);
+CREATE TABLE IF NOT EXISTS sync_deletion_receipts (
+  receipt_id TEXT PRIMARY KEY,
+  stream_id TEXT NOT NULL,
+  operation_id TEXT NOT NULL,
+  json TEXT NOT NULL,
+  completed_at TEXT NOT NULL,
+  FOREIGN KEY (stream_id) REFERENCES sync_streams(stream_id)
+);
+`;
 function canonicalizeTimestamp(value) {
   if (typeof value !== "string" || value.length === 0)
     return void 0;
@@ -24579,6 +24687,10 @@ function migrateToSchema5(db, migratedAt = (/* @__PURE__ */ new Date()).toISOStr
     enqueueMissing.run(source.path, source.sessionId, source.provider, source.agentId ?? null, INGEST_PARSER_REVISION, migratedAt);
   db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("schema_5_migrated_at", migratedAt);
 }
+function migrateToSchema6(db, migratedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  db.exec(SCHEMA_6_DDL);
+  db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("schema_6_migrated_at", migratedAt);
+}
 var SESSION_PAGE = 500;
 var REAL_SESSION = `COALESCE(json_extract(summary_json, '$.internal'), 0) = 0
        AND instr(COALESCE(title, ''), '[salidium-explainer]') = 0`;
@@ -24632,6 +24744,8 @@ var SqliteStore = class {
     }
     this.db.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA temp_store = MEMORY; PRAGMA foreign_keys = ON;");
     this.db.exec(DDL);
+    if (priorVersion === void 0 && !hadLegacyTables)
+      this.db.exec(SCHEMA_6_DDL);
     try {
       this.db.exec("ALTER TABLE changes ADD COLUMN reducer_version TEXT");
     } catch {
@@ -24647,6 +24761,8 @@ var SqliteStore = class {
           migrateToSchema4(this.db);
         if ((priorVersion ?? 0) < 5)
           migrateToSchema5(this.db);
+        if ((priorVersion ?? 0) < 6)
+          migrateToSchema6(this.db);
         this.db.exec("COMMIT");
       } catch (error51) {
         try {
@@ -25336,7 +25452,8 @@ async function startDaemon(overrides = {}) {
   const stored = readSettings(config2.home, (reason) => log.warn("settings invalid; optional explanations disabled", { reason }));
   const envOff = configuredExplainerMode(process.env) === "off";
   const registry2 = new SessionRegistry(store, {
-    explainerCadence: effectiveCadence(stored.explainerCadence)
+    explainerCadence: effectiveCadence(stored.explainerCadence),
+    ...overrides.now ? { now: overrides.now } : {}
   });
   const explainerSettings = () => {
     const usage = registry2.explainerUsage();
@@ -25937,7 +26054,11 @@ function createIntegration(definition) {
         ];
       }
       if (inspection.status === "configured") {
-        return [{ level: "ok", message: `${definition.name} connection is configured` }];
+        const ok = {
+          level: "ok",
+          message: `${definition.name} connection is configured`
+        };
+        return definition.standingNote ? [ok, { level: "info", message: definition.standingNote }] : [ok];
       }
       if (inspection.status === "partial") {
         return [
@@ -25978,6 +26099,7 @@ var codex = createIntegration({
   id: "codex",
   name: "Codex",
   command: "codex",
+  standingNote: "Codex honours a hook only once it has been trusted there: open /hooks in Codex. Salidium cannot tell whether that has been done",
   stateDirectory(context) {
     return environment(context).CODEX_HOME ?? join11(context.userHome, ".codex");
   },
@@ -26300,7 +26422,7 @@ function providerDisplayName(provider, providers = []) {
 }
 
 // src/main.ts
-var HELP = `salidium \u2014 see what your coding agent did, why, how, what's verified, what's left, what needs you.
+var HELP = `salidium: see what your coding agent did, why, how, what is verified, what is left, and what it flagged for a human.
 
 Usage:
   salidium                      Connect detected agents on first run, then start and open Salidium
@@ -26570,6 +26692,9 @@ ${uiUrl(running)}
           for (const validation of provider.validate(context)) {
             if (validation.level === "attention")
               process.stdout.write(`  needs attention: ${validation.message}
+`);
+            else if (validation.level === "info")
+              process.stdout.write(`  note: ${validation.message}
 `);
           }
         }