@smartmemory/compose 0.3.7 → 0.4.0

package/bin/judgment-migrate.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+/**
+ * bin/judgment-migrate.js — ledger to SmartMemory decision migration
+ * (GOV-COMPOSE-SEAM-1 step 1 `canon-on-decisions`).
+ *
+ * Phase P1 ships `--dry-run` ONLY. It reads `docs/judgment/records/ledger.jsonl`,
+ * maps every decision-shaped entry through `lib/judgment-decisions.js`, and
+ * prints the mapping plus the value-spike numbers. It writes nothing, anywhere.
+ *
+ * The write path is P2 and the backfill is P3; both are blocked until the spike
+ * is reported against its pre-registered threshold, and the backfill is
+ * additionally blocked on the P2.5 inferred-conviction review gate (D4).
+ * Invoking this without `--dry-run` therefore refuses rather than doing
+ * something plausible.
+ *
+ * Usage:
+ *   node bin/judgment-migrate.js --dry-run [--json] [--review-batch]
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+
+import { mapLedger, applyReviewFile, CONFIDENCE } from '../lib/judgment-decisions.js';
+import { createSmartmemoryClient } from '../lib/smartmemory-client.js';
+import { getSmartmemoryConfig } from '../lib/smartmemory-config.js';
+import { readSidecar, sidecarPath, writeJudgmentDecision } from '../lib/judgment-decision-write.js';
+
+/** Pre-registered 2026-08-22, before any count was taken. */
+const SPIKE_THRESHOLD_RULES = 10;
+
+function readLedger(cwd) {
+  const path = join(cwd, 'docs', 'judgment', 'records', 'ledger.jsonl');
+  if (!existsSync(path)) {
+    throw new Error(`judgment-migrate: no ledger at ${path}`);
+  }
+  return readFileSync(path, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line, i) => {
+      try {
+        return JSON.parse(line);
+      } catch (err) {
+        throw new Error(`judgment-migrate: ledger line ${i + 1} is not JSON: ${err.message}`);
+      }
+    });
+}
+
+/**
+ * The owner's P2.5 verdicts. Absent, the dry run still reports (it writes
+ * nothing), but it says so — a report that silently skipped the gate would read
+ * exactly like one that passed it.
+ */
+function readReview(cwd) {
+  const path = join(cwd, 'docs', 'features', 'GOV-COMPOSE-SEAM-1', 'conviction-review.json');
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function truncate(s, n) {
+  const one = (s ?? '').replace(/\s+/g, ' ').trim();
+  return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+}
+
+function report(mapped, opts) {
+  const { decisions, skipped } = mapped;
+
+  const byKind = {};
+  for (const d of decisions) {
+    byKind[d.entry.kind] = (byKind[d.entry.kind] ?? 0) + 1;
+  }
+
+  const candidates = decisions.filter((d) => d.enforceability.verdict === 'candidate');
+  const inferred = decisions.filter((d) => d.decision.context_snapshot.conviction_review_required);
+  const reviewed = decisions.filter((d) => d.decision.context_snapshot.conviction_review);
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({
+      total_entries: decisions.length + skipped.length,
+      decision_shaped: decisions.length,
+      by_kind: byKind,
+      skipped: skipped.length,
+      enforceable_candidates: candidates.length,
+      threshold: SPIKE_THRESHOLD_RULES,
+      inferred_conviction_review_required: inferred.length,
+      inferred_conviction_reviewed: reviewed.length,
+      review_ruled_at: opts.review?.ruled_at ?? null,
+      decisions: decisions.map((d) => ({
+        seq: d.seq,
+        kind: d.entry.kind,
+        decision: d.decision,
+        enforceability: d.enforceability,
+      })),
+    }, null, 2)}\n`);
+    return candidates.length;
+  }
+
+  const out = [];
+  out.push('# judgment-migrate --dry-run (GOV-COMPOSE-SEAM-1 canon-on-decisions P1)');
+  out.push('');
+  out.push('NOTHING WAS WRITTEN. This is the mapping and the spike measurement only.');
+  out.push('');
+  out.push(`Ledger entries:        ${decisions.length + skipped.length}`);
+  out.push(`Decision-shaped:       ${decisions.length}  (${Object.entries(byKind).map(([k, v]) => `${k}=${v}`).join(' ')})`);
+  out.push(`Not decisions:         ${skipped.length}  (note/escalate/override/attest/calibrate — D3)`);
+  out.push('');
+  out.push('## Value spike (threshold pre-registered 2026-08-22)');
+  out.push('');
+  out.push(`Enforceable CANDIDATES: ${candidates.length}   (threshold to ship consume-bundle: >= ${SPIKE_THRESHOLD_RULES})`);
+  out.push('');
+  out.push('A candidate is NOT a counted rule. The classifier fires when all three D5');
+  out.push('signals are present; the reported spike number is the ADJUDICATED count after a');
+  out.push('human confirms each candidate actually names a step, names an observable, and');
+  out.push('could be violated by a real build. Report the adjudicated number, not this one.');
+  out.push('');
+  out.push('## Enforceable candidates (adjudicate these)');
+  out.push('');
+  for (const d of candidates) {
+    const s = d.enforceability.signals;
+    out.push(`- [${d.seq}] ${d.entry.kind} / ${d.decision.decision_type}  step=${s.namesStep} obs=${s.namesObservable} violable=${s.violable}`);
+    out.push(`      ${truncate(d.decision.content, 100)}`);
+  }
+  out.push('');
+  out.push('## Inferred convictions (P2.5 review gate — D4)');
+  out.push('');
+  out.push(`Inferred scale: high=${CONFIDENCE.inferred.high} medium=${CONFIDENCE.inferred.medium} low=${CONFIDENCE.inferred.low}`);
+  out.push(`Stated scale:   high=${CONFIDENCE.stated.high} medium=${CONFIDENCE.stated.medium} low=${CONFIDENCE.stated.low}`);
+  out.push('');
+  if (!opts.review) {
+    out.push(`${inferred.length} decision-shaped entries carry an agent-inferred conviction, and NO`);
+    out.push('verdict file was found. The backfill REFUSES these until the owner rules on each.');
+    for (const d of inferred) {
+      const c = d.decision.context_snapshot.conviction;
+      out.push(`- [${d.seq}] ${c.level} (inferred -> ${d.decision.confidence})  ${truncate(d.decision.content, 90)}`);
+    }
+  } else {
+    const byGroup = {};
+    for (const d of reviewed) {
+      const r = d.decision.context_snapshot.conviction_review;
+      byGroup[r.verdict] = (byGroup[r.verdict] ?? 0) + 1;
+    }
+    out.push(`RULED ${reviewed.length}/${reviewed.length} by ${opts.review.ruled_by} on ${opts.review.ruled_at}:`);
+    for (const [v, n] of Object.entries(byGroup)) out.push(`  ${v}: ${n}`);
+    out.push('');
+    for (const d of reviewed) {
+      const snap = d.decision.context_snapshot;
+      const marks = [
+        snap.conviction_strength_dropped ? 'strength-dropped' : null,
+        snap.conviction_unrated ? 'UNRATED, not rule-eligible' : null,
+      ].filter(Boolean).join(', ');
+      out.push(`- [${d.seq}] ${snap.conviction.level} ${snap.conviction_review.verdict} -> ${d.decision.confidence}/${d.decision.source_type}${marks ? `  (${marks})` : ''}`);
+      out.push(`      ${truncate(d.decision.content, 90)}`);
+    }
+  }
+
+  if (opts.reviewBatch) {
+    out.push('');
+    out.push('## Review batch (full text of each inferred entry)');
+    for (const d of (opts.review ? reviewed : inferred)) {
+      out.push('');
+      out.push(`### [${d.seq}] ${d.entry.title}`);
+      out.push(`conviction: ${d.decision.context_snapshot.conviction.level} (inferred)`);
+      out.push('');
+      out.push(d.entry.body ?? '(no body)');
+    }
+  }
+
+  out.push('');
+  process.stdout.write(`${out.join('\n')}\n`);
+  return candidates.length;
+}
+
+
+// ── P3: the backfill ────────────────────────────────────────────────────────
+
+/**
+ * Resume state is the SHARED idempotency ledger in `lib/judgment-decision-write.js`
+ * (`docs/judgment/records/decision-ids.json`), NOT a private file.
+ *
+ * This backfill briefly kept its own under `.compose/data/`, keyed identically
+ * but read separately from the live write path. Same key, two ledgers, neither
+ * reading the other: a decision recorded live and then backfilled would be
+ * written twice, and the create endpoint has no server-side idempotency to
+ * catch it. That is the same "two mechanisms guarding one fact" failure D2
+ * retired the markdown hash chain over. Merged 2026-08-22; the old file is
+ * adopted on first read by `readSidecar` so a migration already run is not
+ * repeated.
+ *
+ * The per-write flush and the verify-before-skip both survive the merge — they
+ * moved INTO the shared writer, which is where the live path needed them too.
+ */
+
+/**
+ * Resolve where the backfill writes.
+ *
+ * Flags override `.compose/compose.json#smartmemory`. Both a workspace and a
+ * key-env name are REQUIRED and there is no default: a backfill that guesses
+ * its destination can write 43 decisions into someone's working memory, and
+ * that is not recoverable by re-running it.
+ */
+function resolveTarget(cwd, argv) {
+  const flag = (name) => {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const cfg = getSmartmemoryConfig(cwd);
+  const baseUrl = flag('--api-url') ?? cfg.baseUrl ?? process.env.SMARTMEMORY_API_URL;
+  const workspaceId = flag('--workspace') ?? cfg.workspaceId;
+  const apiKeyEnv = flag('--api-key-env') ?? cfg.apiKeyEnv;
+
+  const missing = [];
+  if (!baseUrl) missing.push('--api-url (or smartmemory.baseUrl)');
+  if (!workspaceId) missing.push('--workspace (or smartmemory.workspaceId)');
+  if (!apiKeyEnv) missing.push('--api-key-env (or smartmemory.apiKeyEnv)');
+  if (missing.length) {
+    throw new Error(
+      `judgment-migrate --apply: refusing to guess a destination. Missing ${missing.join(', ')}.`,
+    );
+  }
+  if (!process.env[apiKeyEnv]) {
+    throw new Error(`judgment-migrate --apply: $${apiKeyEnv} is not set`);
+  }
+  // `enabled: true` is the flags themselves. The config gate exists so the
+  // coupling is OFF by default for the live tool path; naming a destination
+  // explicitly on an `--apply` invocation IS the opt-in, and requiring the
+  // operator to also edit compose.json first would mean a one-off migration
+  // could not run without turning the live emitter on for every later build.
+  return { enabled: true, baseUrl, workspaceId, apiKeyEnv, timeoutMs: 15000 };
+}
+
+/** The payload the HTTP contract accepts. Anything the mapper carries that the
+ *  route has no field for rides in `context_snapshot`, never silently dropped. */
+function toCreateBody(d) {
+  return {
+    content: d.content,
+    decision_type: d.decision_type,
+    confidence: d.confidence,
+    domain: d.domain,
+    tags: d.tags,
+    rejected_alternatives: d.rejected_alternatives,
+    rationale: d.rationale,
+    source_type: d.source_type,
+    context_snapshot: d.context_snapshot,
+  };
+}
+
+async function backfill(cwd, mapped, target, opts) {
+  const client = createSmartmemoryClient(target);
+  const written = [];
+  const skipped = [];
+  const failed = [];
+
+  for (const row of mapped.decisions) {
+    const d = row.decision;
+    const key = d.idempotency_key;
+    try {
+      // One write path for the live tool call and the bulk migration. It owns
+      // the shared ledger, the verify-before-skip, the provenance check and the
+      // per-write flush; this loop owns only batching and reporting.
+      const res = await writeJudgmentDecision(cwd, d, { client, config: target });
+      if (res === null) {
+        failed.push({ seq: row.seq, key, stage: 'config', error: 'smartmemory coupling is disabled' });
+        if (opts.failFast) break;
+        continue;
+      }
+      (res.skipped ? skipped : written).push({ seq: row.seq, key, decision_id: res.decision_id });
+    } catch (err) {
+      // Fail-closed. A dropped decision silently un-governs a build, so the
+      // backfill reports and stops counting it as done rather than warning on.
+      failed.push({ seq: row.seq, key, stage: 'create', error: err.message });
+      if (opts.failFast) break;
+    }
+  }
+
+  return { written, skipped, failed, state: { written: readSidecar(cwd) } };
+}
+
+/**
+ * The `correct` -> supersede half of D3, which this backfill CANNOT complete.
+ *
+ * `POST /memory/decisions/{id}/supersede` mints its replacement from
+ * `new_content` / `new_decision_type` / `new_confidence` alone — it accepts no
+ * `source_type`, no `context_snapshot`, no tags. Calling it after writing the
+ * 43 would produce a 44th, 45th and 46th decision with no idempotency key and
+ * no provenance, and would break the "run it twice, get 43" property.
+ *
+ * So the link is recorded and reported, not faked. Closing it needs a service
+ * change (supersede taking an existing decision id, or create taking
+ * `supersedes`), which is a separate piece of work.
+ */
+function pendingSupersedes(mapped) {
+  return mapped.decisions
+    .filter((r) => r.decision.supersedes_slug)
+    .map((r) => ({ seq: r.seq, slug: r.decision.supersedes_slug, content: r.decision.content }));
+}
+
+function writeReport(cwd, result, mapped, target) {
+  const pend = pendingSupersedes(mapped);
+  const lines = [];
+  lines.push('# GOV-COMPOSE-SEAM-1 `canon-on-decisions` P3 — backfill report');
+  lines.push('');
+  lines.push(`**Target workspace:** \`${target.workspaceId}\` · **API:** \`${target.baseUrl}\``);
+  lines.push('');
+  lines.push(`- Decision-shaped ledger entries: **${mapped.decisions.length}**`);
+  lines.push(`- Written this run: **${result.written.length}**`);
+  lines.push(`- Already present (verified server-side, skipped): **${result.skipped.length}**`);
+  lines.push(`- Failed: **${result.failed.length}**`);
+  lines.push('');
+  if (result.failed.length) {
+    lines.push('## Failures');
+    lines.push('');
+    for (const f of result.failed) lines.push(`- [${f.seq}] ${f.stage}: ${f.error}`);
+    lines.push('');
+  }
+  lines.push('## Superseding links NOT applied');
+  lines.push('');
+  lines.push('`POST /memory/decisions/{id}/supersede` builds its replacement from `new_content`,');
+  lines.push('`new_decision_type` and `new_confidence` only — no `source_type`, no');
+  lines.push('`context_snapshot`, no tags. Using it here would mint extra decisions with no');
+  lines.push('idempotency key and break the run-it-twice property, so these links are recorded');
+  lines.push('and left unapplied rather than faked. Closing them needs a service change.');
+  lines.push('');
+  for (const p of pend) lines.push(`- [${p.seq}] supersedes \`${p.slug}\` — ${p.content}`);
+  lines.push('');
+  const out = join(cwd, 'docs', 'features', 'GOV-COMPOSE-SEAM-1', 'migration-report.md');
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, `${lines.join('\n')}\n`);
+  return out;
+}
+
+async function main(argv) {
+  const opts = {
+    dryRun: argv.includes('--dry-run'),
+    apply: argv.includes('--apply'),
+    json: argv.includes('--json'),
+    reviewBatch: argv.includes('--review-batch'),
+    failFast: !argv.includes('--keep-going'),
+  };
+
+  if (!opts.dryRun && !opts.apply) {
+    process.stderr.write(
+      'judgment-migrate: pass --dry-run (report only, writes nothing) or --apply (backfill).\n'
+      + 'Refusing rather than doing something plausible.\n',
+    );
+    return 2;
+  }
+
+  const cwd = resolve(process.env.COMPOSE_CWD ?? process.cwd());
+  const events = readLedger(cwd);
+  const mapped = mapLedger(events);
+
+  // The P2.5 gate runs BEFORE anything else, in both modes. It throws on the
+  // first inferred conviction the owner has not ruled on, so the refusal shows
+  // up before a single write rather than halfway through a backfill.
+  opts.review = readReview(cwd);
+  if (opts.review) applyReviewFile(mapped, opts.review);
+
+  if (opts.dryRun) {
+    report(mapped, opts);
+    return 0;
+  }
+
+  // --apply
+  if (!opts.review) {
+    process.stderr.write(
+      'judgment-migrate --apply: no conviction-review.json found. The P2.5 gate has not been\n'
+      + 'ruled, so the inferred convictions cannot be written. Refusing.\n',
+    );
+    return 2;
+  }
+
+  const target = resolveTarget(cwd, argv);
+  const result = await backfill(cwd, mapped, target, opts);
+  const reportPath = writeReport(cwd, result, mapped, target);
+
+  process.stdout.write(
+    `judgment-migrate --apply -> ${target.workspaceId}\n`
+    + `  written: ${result.written.length}  skipped(verified): ${result.skipped.length}  `
+    + `failed: ${result.failed.length}\n`
+    + `  report: ${reportPath}\n`,
+  );
+  return result.failed.length ? 1 : 0;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code; },
+  (err) => { process.stderr.write(`judgment-migrate: ${err.message}\n`); process.exitCode = 1; },
+);

package/contracts/comp-obs-contract.schema.json

@@ -2,10 +2,12 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://forge.local/contracts/comp-obs-contract.schema.json",
   "title": "COMP-OBS-CONTRACT — Wave 6 shared data model",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "_source": "docs/features/COMP-OBS-CONTRACT/schema.json",
   "_roadmap": "Wave 6 — Situational Awareness",
   "_changelog": {
+    "0.2.7": "COMP-LIFECYCLE-BACKFILL (2026-09-05) — DecisionEvent kind=phase_transition metadata gains three OPTIONAL fields (origin, recorded_at, confidence). additionalProperties:false is kept; required stays [from_phase, to_phase], so every 0.2.6 event still validates.",
+    "0.2.6": "COMP-POLICY-CHECK (2026-08-17) — DecisionEvent gains kind=policy_violation (pre-response policy check, emitter server/decision-event-emit.js buildPolicyViolationEvent) with a closed metadata subschema {step_id, rule, matched, suppressed, user_mode, build_id}. Additive — 0.2.5 events continue to validate. Note: BuildStreamEvent.schema_version const stays 0.2.5 (no BuildStreamEvent change in this bump).",
     "0.2.5": "STRAT-PAR-STREAM — added BuildStreamEvent typed discriminated union (12 kinds): 6 new agent-narration kinds (agent_started, tool_use_summary, agent_relay closed + live; iteration_update, tier_result, health_event closed + reserved) and 6 legacy build-level kinds imported from compose/lib/build-stream-writer.js (capability_profile, capability_violation, step_usage, gate_tier_result, health_score, build_end — open metadata, catalog only; STRAT-PAR-STREAM-LEGACY-CLOSE will tighten). Additive — v0.2.4 specs continue to validate.",
     "0.2.4": "COMP-OBS-DRIFT — added optional breach_started_at + breach_event_id to DriftAxis for stable threshold-event identity across WS reconnect; live emit and snapshot rehydration both compose the event id from these persisted fields.",
     "0.2.3": "Codex review (2026-04-24) — two joinable-data fixes + SURFACE-split propagation. (a) `StatusSnapshot.drift_alerts[]` now a locally-defined subschema that mandates `breached: true`, so STATUS cannot emit non-alert axes through the alerts field. (b) gate `DecisionEvent.metadata.gate_log_entry_id` promoted to required — every gate DecisionEvent MUST carry its GateLogEntry id. `GateLogEntry.decision_event_id` remains nullable (explicit emission-failure escape hatch, reader reconciliation documented in prose). (c) Propagate 2026-04-23 SURFACE split (ROADMAP): `COMP-OBS-SURFACE` → `COMP-OBS-TIMELINE` (region ②, DecisionEvent producer+reader) + `COMP-OBS-STEPDETAIL` (step-level surface, no direct contract consumption in v1). `_consumers` updated; no field-shape changes beyond (a)+(b). DecisionEvent emitter ownership restated: BRANCH emits kind=branch, GATELOG emits kind=gate, TIMELINE adds kind=phase_transition (on lifecycle.advance) + kind=iteration (wrapping existing iteration-loop events), DRIFT emits kind=drift_threshold on breach.",
@@ -216,7 +218,7 @@
         "id":           { "type": "string", "format": "uuid" },
         "feature_code": { "type": "string" },
         "timestamp":    { "type": "string", "format": "date-time" },
-        "kind":         { "type": "string", "enum": ["gate", "branch", "iteration", "phase_transition", "drift_threshold"] },
+        "kind":         { "type": "string", "enum": ["gate", "branch", "iteration", "phase_transition", "drift_threshold", "policy_violation"] },
         "title":        { "type": "string", "maxLength": 140 },
         "roles": {
           "type": "array",
@@ -264,11 +266,15 @@
         },
         {
           "if":   { "properties": { "kind": { "const": "phase_transition" } } },
-          "then": { "properties": { "metadata": { "type": "object", "required": ["from_phase", "to_phase"], "properties": { "from_phase": { "type": "string" }, "to_phase": { "type": "string" } }, "additionalProperties": false } } }
+          "then": { "properties": { "metadata": { "type": "object", "required": ["from_phase", "to_phase"], "properties": { "from_phase": { "type": "string" }, "to_phase": { "type": "string" }, "origin": { "type": "string", "enum": ["live", "backfill"], "description": "ABSENT means live; emitters pass stored provenance unchanged." }, "recorded_at": { "type": "string", "format": "date-time" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } } }
         },
         {
           "if":   { "properties": { "kind": { "const": "drift_threshold" } } },
           "then": { "properties": { "metadata": { "type": "object", "required": ["axis_id", "ratio", "threshold"], "properties": { "axis_id": { "type": "string", "enum": ["path_drift", "contract_drift", "review_debt_drift"] }, "ratio": { "type": "number" }, "threshold": { "type": "number" } }, "additionalProperties": false } } }
+        },
+        {
+          "if":   { "properties": { "kind": { "const": "policy_violation" } } },
+          "then": { "properties": { "metadata": { "type": "object", "required": ["step_id", "rule", "matched", "suppressed", "user_mode"], "properties": { "step_id": { "type": "string" }, "rule": { "type": "string" }, "matched": { "type": "string" }, "suppressed": { "type": "boolean" }, "user_mode": { "type": "string", "enum": ["AUTONOMOUS", "PACED", "SKILL_GATED"] }, "build_id": { "type": ["string", "null"] } }, "additionalProperties": false } } }
         }
       ]
     },

package/contracts/fluid-record.schema.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://compose.smartmemory.dev/contracts/fluid-record.schema.json",
+  "title": "fluid-record",
+  "version": "0.2.0",
+  "description": "The canonical record shape carried across the fluid-store provider seam (PROVIDER-SEAM, what-to-build 8k, owner-locked 2026-07-21). The seam is drawn at records + lifecycle events + capability discovery ONLY. Semantic machinery (recall, challenge, conviction, calibration, contradiction) is NEVER modelled here — those are provider capabilities that light up when the configured provider declares them, and a provider that lacks one lacks it visibly. Kind-generic from day one: COMP-PLAN-IDEA-UNIFY implements `idea` as the seam's pilot workload, and positions/joints/decisions adopt this same shape next without a contract change.",
+  "_source": "docs/features/COMP-PLAN-IDEA-UNIFY/design.md",
+  "_roadmap": "COMP-PLAN-IDEA-UNIFY",
+  "type": "object",
+
+  "definitions": {
+
+    "kind": {
+      "type": "string",
+      "description": "The fluid record's type. A provider declares which kinds it implements via supportedKinds(); an unsupported kind is refused loudly, never silently coerced. `cluster` is a record rather than a string label because an umbrella carries a hand-authored multi-sentence Theme paragraph: that is cluster-scoped content with nowhere to live on a member idea except duplicated onto every one of them, which is a drift generator. Members reference their cluster by handle via the record's `cluster` field.",
+      "enum": ["idea", "position", "joint", "decision", "thread", "question", "cluster"]
+    },
+
+    "handle": {
+      "type": "string",
+      "description": "Stable, human-facing external identifier (IDEA-7, JOINT-3). Distinct from `id` ON PURPOSE: `id` is provider-assigned and changes when the record is imported into a different provider, whereas the handle is quoted in docs, commits, and conversation (e.g. IDEA-20 is cited in the substrate ruling) and MUST survive a provider swap unchanged. Allocated monotonically per kind; a retired handle is never reused. The suffix is bounded to 9 digits: allocation reads it as a Number, and a value past the exact-integer range makes `max + 1` equal `max`, which would hand the same handle out twice.",
+      "pattern": "^[A-Z][A-Z0-9]*-[1-9][0-9]{0,8}$"
+    },
+
+    "status": {
+      "type": "string",
+      "description": "Canonical fluid lifecycle state. This is the source of truth for the record's state; any provider-native status field is a projection of it, never the reverse.",
+      "enum": ["new", "discussing", "promoted", "killed"]
+    },
+
+    "priority": {
+      "type": ["string", "null"],
+      "description": "Triage rank. null means untriaged (the ideabox renders this as an em dash).",
+      "enum": ["P0", "P1", "P2", null]
+    },
+
+    "effort": {
+      "type": ["string", "null"],
+      "description": "T-shirt size of the work, the X axis of the cockpit's 2x2 prioritization matrix. Null means unassigned, which is the matrix's `Unassigned` tray rather than a default size. Separate from `priority` on purpose: priority is a decision about sequencing, effort is an estimate of cost, and collapsing them loses the pair that makes a Quick Win distinguishable from a Big Bet.",
+      "enum": ["S", "M", "L", null]
+    },
+
+    "impact": {
+      "type": ["string", "null"],
+      "description": "Expected value of the work, the Y axis of the cockpit's 2x2 prioritization matrix. Null means unassigned. Lower-case by contract because that is what the markdown surface has always written and what `lib/ideabox.js` validates against; a casing change here would silently invalidate every existing assignment on upgrade.",
+      "enum": ["low", "medium", "high", null]
+    },
+
+    "link": {
+      "type": "object",
+      "description": "A typed edge to another record or to committed (git) canon. Promotion writes an edge of type `promoted_to` rather than mutating the record into a feature, so the idea to feature transition is provenance in the graph rather than a lost jump.",
+      "required": ["type", "target"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["promoted_to", "maps_to", "informs", "blocks", "supports", "contradicts", "supersedes", "duplicate_of"]
+        },
+        "target": {
+          "type": "string",
+          "description": "Handle of another fluid record, or a committed feature code (COMP-FOO-1) when the edge crosses the crystallization boundary into git canon."
+        },
+        "note": { "type": "string" }
+      }
+    },
+
+    "provenance": {
+      "type": "object",
+      "description": "Stamped by the writing tool, never settable by a caller. Captured at write time, never retrofitted (what-to-build 12: provenance is never retrofitted successfully).",
+      "required": ["origin", "recorded_at"],
+      "additionalProperties": false,
+      "properties": {
+        "origin": {
+          "type": "string",
+          "description": "Which door the record came through. `import:ideabox` marks a record created by the one-time markdown import, distinguishing migrated rows from natively captured ones for the lifetime of the record.",
+          "enum": ["cli:ideabox", "ui:ideabox", "mcp:compose", "import:ideabox", "pipeline:plan"]
+        },
+        "recorded_at": { "type": "string", "format": "date-time" },
+        "author": { "type": ["string", "null"] }
+      }
+    },
+
+    "record": {
+      "type": "object",
+      "description": "One fluid record as it crosses the seam.",
+      "required": ["id", "handle", "kind", "title", "status", "provenance", "created_at", "updated_at"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Provider-assigned opaque identifier. Callers MUST NOT parse it or persist it as a cross-document reference — use `handle` for that."
+        },
+        "handle": { "$ref": "#/definitions/handle" },
+        "kind": { "$ref": "#/definitions/kind" },
+        "title": { "type": "string", "minLength": 1 },
+        "body": {
+          "type": "string",
+          "description": "Free prose. The ideabox's `Idea:` paragraph lands here."
+        },
+        "status": { "$ref": "#/definitions/status" },
+        "status_label": {
+          "type": ["string", "null"],
+          "description": "The human-facing status token when it carries more than the canonical enum can (`RE-AIMED (2026-07-21)`, `PROMOTED (-> FEAT-1)`). Canonical `status` drives all behavior; this only preserves what the author wrote so a closed enum does not quietly flatten it away. Null when the author's token was already canonical."
+        },
+        "priority": { "$ref": "#/definitions/priority" },
+        "effort": { "$ref": "#/definitions/effort" },
+        "impact": { "$ref": "#/definitions/impact" },
+        "cluster": {
+          "type": ["string", "null"],
+          "description": "HANDLE of the `cluster` record this record belongs to (e.g. CLUS-1), or null when ungrouped. Carries the editorial grouping the ideabox renders as `### Umbrella A - Resilience: fail loud, recover fast`. This is RECORD DATA, not presentation: the headings and their theme prose are hand-authored information, and a projection that cannot reproduce them from the store would clobber them on first regeneration - the failure mode `roadmap generate` already has. A handle rather than the display name so renaming an umbrella does not orphan its members."
+        },
+        "cluster_order": {
+          "type": ["integer", "null"],
+          "description": "Position of this record's cluster in the rendered projection, preserving hand-authored cluster ORDERING (Umbrella A before B) across a regenerate. Null when ungrouped."
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Bare tag tokens without the leading hash (ux, core, distribution)."
+        },
+        "source": {
+          "type": ["string", "null"],
+          "description": "Where the idea came from, as free text."
+        },
+        "links": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/link" }
+        },
+        "killed": {
+          "type": ["object", "null"],
+          "description": "Set when status is `killed`. A kill is a dated event with a reason (what-to-build 11), so the reason is structured rather than appended to prose.",
+          "required": ["at", "reason"],
+          "additionalProperties": false,
+          "properties": {
+            "at": { "type": "string", "format": "date-time" },
+            "reason": { "type": "string" }
+          }
+        },
+        "discussion": {
+          "type": "array",
+          "description": "Append-only comment trail (`compose ideabox discuss`). Append-only because a deliberation trail that can be rewritten is not evidence.",
+          "items": {
+            "type": "object",
+            "required": ["at", "text"],
+            "additionalProperties": false,
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "text": { "type": "string" },
+              "author": {
+                "type": ["string", "null"],
+                "description": "Who wrote the entry, or null when unattributed. Spaces ARE allowed — `Jane Doe` is the common case, and the markdown parser used to require `\\w+`, which silently dropped the whole entry (COMP-FLUID-SEAM-GUARANTEES F7-1). A colon and line breaks are forbidden: the projection's grammar is `- [date] author: text` and takes everything up to the FIRST colon as the author, so an author containing one could not be represented and would parse back as something else. Constrained here rather than escaped in the renderer, because a value the surface cannot express is a value the store should refuse to hold.",
+                "pattern": "^[^:\\n\\r]*$"
+              }
+            }
+          }
+        },
+        "provenance": { "$ref": "#/definitions/provenance" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" }
+      }
+    },
+
+    "lifecycle_event": {
+      "type": "object",
+      "description": "An append-only fact about a record's life. Events are part of the seam because they are portable across providers; the SEMANTIC readings of them (conviction, calibration) are not, and are never derived here.",
+      "required": ["handle", "type", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "handle": { "$ref": "#/definitions/handle" },
+        "type": {
+          "type": "string",
+          "enum": ["created", "updated", "triaged", "discussed", "promoted", "killed", "linked", "imported", "deleted"]
+        },
+        "at": { "type": "string", "format": "date-time" },
+        "detail": {
+          "type": "object",
+          "description": "Type-specific payload. Deliberately unconstrained: constraining it here would drag provider-specific semantics into the seam."
+        }
+      }
+    },
+
+    "capability": {
+      "type": "string",
+      "description": "STORAGE capabilities are the seam's own contract and every provider must implement them. SEMANTIC capabilities are the reason the seam exists: they are declared, never abstracted. Asking a provider for one it has not declared is an error (FluidCapabilityUnavailable), never an empty result - an empty result is indistinguishable from a real answer and would fake the capability.",
+      "enum": [
+        "RECORDS",
+        "EVENTS",
+        "LINKS",
+        "RECALL",
+        "CHALLENGE",
+        "CONVICTION",
+        "CALIBRATION",
+        "CONTRADICTION"
+      ]
+    }
+  },
+
+  "additionalProperties": false,
+  "properties": {
+    "record": { "$ref": "#/definitions/record" },
+    "lifecycle_event": { "$ref": "#/definitions/lifecycle_event" }
+  },
+  "oneOf": [
+    { "required": ["record"] },
+    { "required": ["lifecycle_event"] }
+  ],
+
+  "_validation": "Callers validate against a NAMED DEFINITION (#/definitions/record, #/definitions/lifecycle_event) — see lib/fluid/schema.js — following contracts/judgment-record.schema.json's per-definition pattern. The root is an envelope, and `oneOf` + `additionalProperties: false` exist so that an empty or unrelated payload is REJECTED by the machine rather than merely discouraged by this prose. A prose instruction with no machine effect is not a constraint."
+}