@smartmemory/compose 0.3.5-beta → 0.3.7

package/lib/judgment-verify.js

@@ -0,0 +1,153 @@
+/**
+ * Combined drift verification for the judgment canon.
+ *
+ * The inventory, projection roundtrip, and record attestation are evaluated
+ * under the writer's advisory lock so a legitimate write cannot expose a
+ * partially-published canon to the verifier.
+ */
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+} from 'node:fs';
+import { join, posix } from 'node:path';
+
+import { readManifest, recordFileSet, verifyRecords } from './judgment-attest.js';
+import {
+  checkProjectionRoundtrip,
+  generateFromRecords,
+  loadSnapshot,
+} from './judgment-gen.js';
+import { withJudgmentLock } from './judgment-writer.js';
+
+const JUDGMENT_REL = 'docs/judgment';
+const MANIFEST_REL = `${JUDGMENT_REL}/.attest.json`;
+const RECORDS_REL = `${JUDGMENT_REL}/records`;
+const STRUCTURAL_DIRS = [
+  RECORDS_REL,
+  `${JUDGMENT_REL}/people`,
+  `${JUDGMENT_REL}/positions`,
+];
+// The legitimate depth-1 dirs under records/. Anything else there (e.g. a
+// Bash-created `records/garbage/`) is drift. Deeper legitimate dirs — such as
+// `records/positions/<slug>/` — are admitted by expectedTree's parent-walk over
+// the real record files, so this list stays exact rather than blanket-exempting
+// every nested path.
+const RECORD_STRUCTURAL_DIRS = [
+  'goal', 'intents', 'joints', 'people', 'positions', 'predictions', 'situation',
+].map((name) => `${RECORDS_REL}/${name}`);
+
+function expectedTree(cwd) {
+  // Derive the expected projection set from the SAME snapshot builder that
+  // checkProjectionRoundtrip uses (loadSnapshot, exported from judgment-gen).
+  // Reconstructing it here would be a mirror that silently diverges into false
+  // tree drift the moment loadSnapshot changes.
+  const projections = Object.keys(generateFromRecords(loadSnapshot(cwd)));
+  const records = recordFileSet(cwd);
+  // The manifest is NOT in this set: it lives at .compose/judgment-attest.json,
+  // outside the tree being inventoried.
+  const files = new Set([...projections, ...records]);
+  const directories = new Set([JUDGMENT_REL, ...STRUCTURAL_DIRS, ...RECORD_STRUCTURAL_DIRS]);
+
+  for (const relPath of files) {
+    let parent = posix.dirname(relPath);
+    while (parent.startsWith(`${JUDGMENT_REL}/`)) {
+      directories.add(parent);
+      parent = posix.dirname(parent);
+    }
+  }
+
+  return { files, directories };
+}
+
+function inventoryTree(cwd, expected) {
+  const root = join(cwd, ...JUDGMENT_REL.split('/'));
+  if (!existsSync(root)) return [];
+
+  const rootStat = lstatSync(root);
+  if (rootStat.isSymbolicLink()) {
+    return [{ path: JUDGMENT_REL, kind: 'symlink' }];
+  }
+  if (!rootStat.isDirectory()) {
+    return [{ path: JUDGMENT_REL, kind: 'unexpected' }];
+  }
+
+  const drift = [];
+
+  function walk(absDir, relDir) {
+    const entries = readdirSync(absDir)
+      .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+
+    for (const name of entries) {
+      const absPath = join(absDir, name);
+      const relPath = `${relDir}/${name}`;
+      const stat = lstatSync(absPath);
+
+      if (stat.isSymbolicLink()) {
+        drift.push({ path: relPath, kind: 'symlink' });
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        // An EMPTY unexpected dir is not reported: it holds no canon, and
+        // UndoLog.restore unlinks files without removing their directories, so a
+        // rolled-back op legitimately leaves e.g. an empty positions/<slug>/.
+        // Flagging those would false-RED on correct behaviour. A non-empty stray
+        // dir is still caught — every file inside it fails the file rule below.
+        if (!expected.directories.has(relPath) && readdirSync(absPath).length > 0) {
+          drift.push({ path: relPath, kind: 'unexpected' });
+        }
+        walk(absPath, relPath);
+        continue;
+      }
+
+      if (!stat.isFile() || !expected.files.has(relPath)) {
+        drift.push({ path: relPath, kind: 'unexpected' });
+      }
+    }
+  }
+
+  walk(root, JUDGMENT_REL);
+  drift.sort((a, b) => {
+    if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+    return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+  });
+  return drift;
+}
+
+/**
+ * True when this project has no judgment canon at all — no `docs/judgment/`
+ * tree and no attestation baseline. There is nothing to verify, so verification
+ * must pass: most Compose projects never adopt the judgment layer, and a
+ * gate that fails them would break every pre-push and ship in those repos.
+ *
+ * This is NOT the same as a deleted canon. The baseline lives outside
+ * `docs/judgment/**` (at `.compose/judgment-attest.json`), so wiping the canon
+ * leaves the manifest behind — `hasNoCanon` is false and every record it
+ * remembers surfaces as `removed` drift.
+ */
+function hasNoCanon(cwd) {
+  return !existsSync(join(cwd, ...JUDGMENT_REL.split('/')))
+    && readManifest(cwd) === null;
+}
+
+export async function verifyJudgmentCanon(cwd) {
+  return withJudgmentLock(cwd, async () => {
+    if (hasNoCanon(cwd)) {
+      return { ok: true, treeDrift: [], projectionDrift: [], recordDrift: [] };
+    }
+
+    const treeDrift = inventoryTree(cwd, expectedTree(cwd));
+    const projection = checkProjectionRoundtrip(cwd);
+    const records = verifyRecords(cwd);
+    const projectionDrift = projection.diffs;
+    const recordDrift = records.drift;
+
+    return {
+      ok: treeDrift.length === 0 && projection.fixedPoint && records.ok,
+      treeDrift,
+      projectionDrift,
+      recordDrift,
+    };
+  });
+}

package/lib/judgment-write-guard.js

@@ -0,0 +1,230 @@
+/**
+ * lib/judgment-write-guard.js — write-time judgment-record validation (S03).
+ *
+ * Pure leaf validator in the feature-write-guard shape: schema conformance,
+ * grounding/elicitation rules, the design's edge→artifact table, and the
+ * method gates. The writer (lib/judgment-writer.js) and MCP surface call
+ * into this module; it never imports them — imports are restricted to the
+ * Ajv SchemaValidator and the judgment schema loader so the graph stays
+ * acyclic (the feature-write-guard.js:20-23 discipline).
+ *
+ * Rules enforced here (design.md rev 5):
+ *  - every record validates against contracts/judgment-record.schema.json
+ *    (MCP inputSchema is advisory, never the enforcement)
+ *  - grounding: ASSERT requires a structured elicitation block
+ *  - [owner-locked] is unrepresentable through tools — import or the epic's
+ *    future override only
+ *  - every transition edge carries its bound artifact or is refused; there
+ *    is no free under_test→open edge; dissolution is its own artifact
+ *  - EXT needs sharpened-or-judgment-dispatch before under_test; STRADDLE
+ *    needs signal+kill-criteria; a SILENT ext result may only yield the
+ *    joint outcome `inconclusive`
+ */
+import { getJudgmentValidator } from './judgment/schema.js';
+
+export class JudgmentWriteValidationError extends Error {
+  /**
+   * @param {'JUDGMENT_SCHEMA_VIOLATION'|'JUDGMENT_GROUNDING_VIOLATION'|'JUDGMENT_ILLEGAL_EDGE'|'JUDGMENT_METHOD_GATE'} kind
+   * @param {string[]} violations
+   */
+  constructor(kind, violations) {
+    super(`${kind}: ${violations.join('; ')}`);
+    this.name = 'JudgmentWriteValidationError';
+    this.code = kind;
+    this.kind = kind;
+    this.violations = violations;
+  }
+}
+
+function refuse(kind, violations) {
+  throw new JudgmentWriteValidationError(kind, violations);
+}
+
+/**
+ * Validate a record against its contract definition. Throws
+ * JUDGMENT_SCHEMA_VIOLATION with ajv error paths on mismatch.
+ *
+ * @param {'position_revision'|'joint'|'prediction'|'ledger_event'|'pending_intent'} defName
+ * @param {object} record
+ */
+export function assertValidRecord(defName, record) {
+  const { valid, errors } = getJudgmentValidator().validate(defName, record);
+  if (valid) return;
+  refuse(
+    'JUDGMENT_SCHEMA_VIOLATION',
+    (errors || []).map((e) => `${defName}${e.instancePath || ''}: ${e.message}`),
+  );
+}
+
+/**
+ * Grounding rules over a record's claims (position revisions; any record
+ * carrying `claims[]`). `via: 'import'` — taken from opts or the record's own
+ * provenance — is the only sanctioned owner-tag path in v1.
+ *
+ * @param {object} record
+ * @param {{ via?: 'import' }} [opts]
+ */
+export function assertGrounding(record, opts = {}) {
+  const via = opts.via ?? record?.provenance?.via;
+  const violations = [];
+  for (const claim of (Array.isArray(record?.claims) ? record.claims : [])) {
+    if (claim.grounding === 'ASSERT' && !claim.elicitation) {
+      violations.push(
+        `claim ${claim.id}: grounding ASSERT requires an elicitation block { asked, answered_at, answer_ref } (assert-elicitation-amendment)`,
+      );
+    }
+    if (claim.owner_locked === true && via !== 'import') {
+      violations.push(
+        `claim ${claim.id}: [owner-locked] is unrepresentable through tools — use the importer (via: 'import') or the epic's future override`,
+      );
+    }
+  }
+  if (violations.length > 0) refuse('JUDGMENT_GROUNDING_VIOLATION', violations);
+}
+
+/**
+ * The design's edge→artifact table, verbatim. Each legal edge names the
+ * exactly-one artifact the transition input must carry; anything else is
+ * refused. Keys are `${from}→${to}`.
+ *
+ * @type {Record<string, (input: object) => string|null>}
+ *   returns a violation string or null when satisfied
+ */
+const EDGE_TABLE = {
+  'open→under_test': () => null, // method gate enforced by assertMethodGate
+  'under_test→resolved': (input) =>
+    input?.resolution?.outcome === 'resolved'
+      ? null
+      : 'requires resolution { outcome: resolved, evidence }',
+  'under_test→inconclusive': (input) =>
+    input?.resolution?.outcome === 'inconclusive'
+      ? null
+      : 'requires resolution { outcome: inconclusive, learned, would_have_settled }',
+  'under_test→open': (input) =>
+    input?.resolution?.outcome === 'failed_to_run'
+      ? null
+      : 'a free under_test→open edge does not exist — requires resolution { outcome: failed_to_run, reason }',
+  'open→superseded': (input) =>
+    input?.resolution?.outcome === 'superseded'
+      ? null
+      : 'requires resolution { outcome: superseded, why }',
+  'under_test→superseded': (input) =>
+    input?.resolution?.outcome === 'superseded'
+      ? null
+      : 'requires resolution { outcome: superseded, why }',
+  'open→dissolved': (input) =>
+    input?.dissolution && !input?.resolution
+      ? null
+      : 'requires dissolution { decomposed_into[] } — its own artifact, not a resolution',
+  'under_test→dissolved': (input) =>
+    input?.dissolution && !input?.resolution
+      ? null
+      : 'requires dissolution { decomposed_into[] } — its own artifact, not a resolution',
+  'resolved→open': (input) =>
+    input?.reopen?.shaken_evidence_ref
+      ? null
+      : 'reopen requires { shaken_evidence_ref } (P6)',
+  'inconclusive→under_test': (input) => redisposeViolation(input),
+  'inconclusive→open': (input) => redisposeViolation(input),
+};
+
+/**
+ * Re-dispose carries `{ new_resolve_by, new method package }` for BOTH target
+ * states (the table is explicit): a gated method may not be re-disposed
+ * without its package even when the joint returns to open.
+ */
+function redisposeViolation(input) {
+  const redispose = input?.redispose;
+  if (!redispose?.new_resolve_by) {
+    return 're-dispose requires { new_resolve_by, new method package } (P3 retry-with-different-method)';
+  }
+  if (redispose.new_resolve_by === 'EXT' && !redispose.ext) {
+    return 're-dispose to EXT requires its ext package (sharpened or judgment-dispatch)';
+  }
+  if (redispose.new_resolve_by === 'STRADDLE' && !redispose.straddle) {
+    return 're-dispose to STRADDLE requires straddle { discriminating_signal, kill_criteria }';
+  }
+  return null;
+}
+
+/**
+ * The legal edge set, exported for the graph-parity contract test (the
+ * judgment lifecycle mode and this table must agree edge-for-edge).
+ */
+export const LEGAL_EDGES = Object.freeze(Object.keys(EDGE_TABLE));
+
+/**
+ * Assert a transition edge is legal and carries its bound artifact.
+ *
+ * @param {string} from current joint state
+ * @param {string} to target joint state
+ * @param {object} input transition input ({ resolution?, dissolution?, reopen?, redispose? })
+ */
+export function assertEdgeArtifact(from, to, input = {}) {
+  const edge = `${from}→${to}`;
+  const rule = EDGE_TABLE[edge];
+  if (!rule) {
+    refuse('JUDGMENT_ILLEGAL_EDGE', [`edge ${edge} is not in the edge→artifact table — refused`]);
+  }
+  const violation = rule(input);
+  if (violation) refuse('JUDGMENT_ILLEGAL_EDGE', [`edge ${edge}: ${violation}`]);
+}
+
+/**
+ * Method gates (P3 / external-signal contract), applied to the joint as it
+ * would stand AFTER the transition (i.e. with any re-disposed method/package
+ * already merged by the caller):
+ *  - EXT → under_test needs `ext` (sharpened package or judgment-dispatch)
+ *  - STRADDLE → under_test needs `straddle { discriminating_signal, kill_criteria }`
+ *  - an ext_result of SILENT may only accompany the joint outcome `inconclusive`
+ *
+ * @param {object} joint the joint record (post-merge view)
+ * @param {string} to target state
+ * @param {object} [input] transition input (for resolution inspection)
+ */
+export function assertMethodGate(joint, to, input = {}) {
+  const violations = [];
+  if (to === 'under_test') {
+    if (joint.resolve_by === 'EXT' && !joint.ext) {
+      violations.push(
+        'EXT joint cannot enter under_test without ext { sharpened_question, bar, falsifier } or ext { judgment_dispatch: true, reason } (BAR-OR-JUDGMENT)',
+      );
+    }
+    if (joint.resolve_by === 'STRADDLE' && !joint.straddle) {
+      violations.push(
+        'STRADDLE joint cannot enter under_test without straddle { discriminating_signal, kill_criteria } (STRADDLE-NEEDS-SIGNAL, KILL-CRITERIA-FIRST)',
+      );
+    }
+  }
+  // EXT resolutions MUST carry the ruled result package. Since only the
+  // Answerer slice can produce evidence packages, this is also what makes
+  // "no EXT resolution can occur before the Answerer exists" structural.
+  if (joint.resolve_by === 'EXT' && (to === 'resolved' || to === 'inconclusive')) {
+    const extResult = input?.resolution?.ext_result;
+    if (!extResult) {
+      violations.push(
+        'an EXT resolution requires the ruled ext_result package { outcome, sources, search_record, found_or_provoked, judgment_not_evidence }',
+      );
+    } else {
+      if (['FOUND', 'CONTRARY'].includes(extResult.outcome)) {
+        const sources = Array.isArray(extResult.sources) ? extResult.sources : [];
+        if (sources.length === 0) {
+          violations.push(`ext_result ${extResult.outcome} requires at least one source address`);
+        }
+        for (const source of sources) {
+          if (!String(source).startsWith('records/evidence/')) {
+            violations.push(`ext_result source "${source}" must address an immutable records/evidence/ package`);
+          }
+        }
+      }
+      if (joint.ext?.judgment_dispatch === true && extResult.judgment_dispatch !== true) {
+        violations.push('the judgment-dispatch stamp propagates permanently: ext_result.judgment_dispatch must be true on a BAR-OR-JUDGMENT joint');
+      }
+    }
+  }
+  const extOutcome = input?.resolution?.ext_result?.outcome;
+  if (extOutcome === 'SILENT' && to !== 'inconclusive') {
+    violations.push('a SILENT external-signal result may only yield the joint outcome inconclusive');
+  }
+  if (violations.length > 0) refuse('JUDGMENT_METHOD_GATE', violations);
+}