@smartmemory/compose 0.3.5-beta → 0.3.7

package/lib/hooks-status.js

@@ -24,6 +24,14 @@ export const HOOK_MARKERS = {
   'pre-push': '# Compose pre-push hook —',
 };
 
+/**
+ * Current baked versions for hooks whose content contract is versioned.
+ * Post-commit remains unversioned until its template changes.
+ */
+export const HOOK_VERSIONS = {
+  'pre-push': '1',
+};
+
 /** The hook types Compose manages, in display order. */
 export const HOOK_TYPE_LIST = Object.keys(HOOK_MARKERS);
 
@@ -33,6 +41,12 @@ export function extractBakedWorkspaceId(content) {
   return m ? m[1] : null;
 }
 
+/** Pull the baked HOOK_VERSION="..." value out of hook content, or null. */
+export function extractBakedHookVersion(content) {
+  const m = content.match(/^HOOK_VERSION="([^"]*)"$/m);
+  return m ? m[1] : null;
+}
+
 /**
  * Compute the raw status facts for every managed hook type.
  *
@@ -55,15 +69,19 @@ export function computeHooksStatus({ projectRoot, expectedWsId = null, composeNo
 
 function computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin }) {
   const marker = HOOK_MARKERS[type];
+  const expectedVersion = HOOK_VERSIONS[type] ?? null;
   const dest = join(hooksDir, type);
 
   const empty = {
     reason: null,
     bakedWorkspace: null,
+    bakedVersion: null,
+    expectedVersion,
     expectedWorkspace: expectedWsId ?? null,
     wsVerified: false,
     nodeMatch: false,
     binMatch: false,
+    versionMatch: false,
   };
 
   if (!existsSync(dest)) return { state: 'absent', ...empty };
@@ -75,26 +93,33 @@ function computeOne({ type, hooksDir, expectedWsId, composeNode, composeBin }) {
   const binMatch = content.includes(`COMPOSE_BIN="${composeBin}"`);
   const hasRawToken = content.includes('__COMPOSE_WORKSPACE_ID__');
   const bakedWorkspace = extractBakedWorkspaceId(content);
+  const bakedVersion = extractBakedHookVersion(content);
+  const versionMatch = expectedVersion == null || bakedVersion === expectedVersion;
   // Mirror of statusOne: raw token never matches; a known expected id must match
   // the baked value; an unknown (null) expected id is treated leniently as a match.
   const wsMatch = hasRawToken ? false : expectedWsId ? content.includes(`COMPOSE_WORKSPACE_ID="${expectedWsId}"`) : true;
 
   const base = {
     bakedWorkspace,
+    bakedVersion,
+    expectedVersion,
     expectedWorkspace: expectedWsId ?? null,
     wsVerified: expectedWsId != null,
     nodeMatch,
     binMatch,
+    versionMatch,
   };
 
-  if (nodeMatch && binMatch && wsMatch && !hasRawToken) {
+  if (nodeMatch && binMatch && wsMatch && !hasRawToken && versionMatch) {
     return { state: 'installed-current', reason: null, ...base };
   }
   const reason = hasRawToken
     ? 'MISSING_WORKSPACE_ID'
     : expectedWsId && !wsMatch
       ? 'STALE_WORKSPACE_ID'
-      : 'stale paths';
+      : !nodeMatch || !binMatch
+        ? 'stale paths'
+        : 'HOOK_VERSION_DRIFT';
   return { state: 'installed-stale', reason, ...base };
 }
 
@@ -118,6 +143,7 @@ export function formatHookStatusLines(type, s, { composeNode, composeBin }) {
   // installed-stale
   const lines = [`${type}: installed (${s.reason} — re-run install)`];
   if (s.reason === 'STALE_WORKSPACE_ID') lines.push(`  expected COMPOSE_WORKSPACE_ID="${s.expectedWorkspace}"`);
+  if (s.reason === 'HOOK_VERSION_DRIFT') lines.push(`  expected HOOK_VERSION="${s.expectedVersion}"`);
   if (!s.nodeMatch) lines.push(`  expected COMPOSE_NODE="${composeNode}"`);
   if (!s.binMatch) lines.push(`  expected COMPOSE_BIN="${composeBin}"`);
   return lines;
@@ -126,10 +152,13 @@ export function formatHookStatusLines(type, s, { composeNode, composeBin }) {
 /**
  * @typedef {object} HookStatusRaw
  * @property {'absent'|'foreign'|'installed-current'|'installed-stale'} state
- * @property {null|'MISSING_WORKSPACE_ID'|'STALE_WORKSPACE_ID'|'stale paths'} reason
+ * @property {null|'MISSING_WORKSPACE_ID'|'STALE_WORKSPACE_ID'|'stale paths'|'HOOK_VERSION_DRIFT'} reason
  * @property {string|null} bakedWorkspace
+ * @property {string|null} bakedVersion
+ * @property {string|null} expectedVersion
  * @property {string|null} expectedWorkspace
  * @property {boolean} wsVerified
  * @property {boolean} nodeMatch
  * @property {boolean} binMatch
+ * @property {boolean} versionMatch
  */

package/lib/idempotency.js

@@ -18,7 +18,13 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
 import { join, dirname } from 'path';
 
 const MAX_ENTRIES = 1000;
-const LOCK_TIMEOUT_MS = 5000;
+const LOCK_TIMEOUT_MS = 5000; // acquisition wait
+// Steal threshold — deliberately larger than the wait: the heartbeat (1s,
+// event-loop-scheduled) can be silenced by a SYNCHRONOUS computeFn, so a
+// live lock is only stealable after a sync block longer than this. 20s of
+// contiguous sync blocking is the documented bound; a fresh crash costs
+// waiters up to 20s of retryable lock-timeout errors before recovery.
+const LOCK_STALE_MS = 20000;
 const LOCK_RETRY_MS = 25;
 
 function cacheFile(cwd) {
@@ -35,28 +41,47 @@ function ensureDir(file) {
 
 /**
  * Acquire an advisory lock by creating a directory (atomic on POSIX). Caller
- * is responsible for releasing via the returned function. Stale locks older
- * than LOCK_TIMEOUT_MS are forcibly cleared so a crashed prior holder can't
- * deadlock the next caller.
+ * is responsible for releasing via the returned function.
+ *
+ * The lock is HEARTBEATED (COMP-JUDGMENT-WRITER hardening): the holder
+ * refreshes the dir mtime every second, so only a lock whose holder has died
+ * (heartbeat silent for LOCK_TIMEOUT_MS) is ever stealable — a live compute
+ * that legitimately outlasts the stale threshold (e.g. a judgment transition
+ * spanning a 10s Stratum guard call) keeps its lock. An owner token makes
+ * release safe after a post-crash steal: a holder never removes a lock it no
+ * longer owns. (A steal requires LOCK_TIMEOUT_MS of MISSED heartbeats, which
+ * a live holder cannot produce — so token-check-then-remove races only exist
+ * against already-dead holders, where there is no releaser to race.)
  */
 async function acquireLock(cwd) {
   const path = lockFile(cwd);
   ensureDir(path);
+  const { statSync, utimesSync } = await import('fs');
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const ownerFile = join(path, 'owner');
 
   const start = Date.now();
   // eslint-disable-next-line no-constant-condition
   while (true) {
     try {
       mkdirSync(path);
+      writeFileSync(ownerFile, token);
+      const heartbeat = setInterval(() => {
+        try { utimesSync(path, new Date(), new Date()); } catch { /* lock gone — release will no-op */ }
+      }, 1000);
+      heartbeat.unref?.();
       return () => {
-        try { rmSync(path, { recursive: true, force: true }); } catch { /* best-effort */ }
+        clearInterval(heartbeat);
+        try {
+          if (readFileSync(ownerFile, 'utf-8') === token) rmSync(path, { recursive: true, force: true });
+        } catch { /* not ours anymore — leave it */ }
       };
     } catch (err) {
       if (err.code !== 'EEXIST') throw err;
-      // Stale lock recovery: if older than timeout, clear and retry.
+      // Stale lock recovery: heartbeat silent longer than the stale bound → holder died.
       try {
-        const { mtimeMs } = (await import('fs')).statSync(path);
-        if (Date.now() - mtimeMs > LOCK_TIMEOUT_MS) {
+        const { mtimeMs } = statSync(path);
+        if (Date.now() - mtimeMs > LOCK_STALE_MS) {
           rmSync(path, { recursive: true, force: true });
           continue;
         }

package/lib/judgment/schema.js

@@ -0,0 +1,23 @@
+/**
+ * lib/judgment/schema.js — judgment-record contract loader (S01).
+ *
+ * Exposes the contract path and a memoized SchemaValidator instance. The
+ * schema carries an $id, which the definitions path of SchemaValidator
+ * requires (server/schema-validator.js:52). Callers validate per-kind via
+ * `getJudgmentValidator().validate('<definition>', obj)`.
+ */
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SchemaValidator } from '../../server/schema-validator.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const JUDGMENT_SCHEMA_PATH = resolve(__dirname, '../../contracts/judgment-record.schema.json');
+
+// Memoized — the contract is static for the life of the process.
+let _validator = null;
+
+export function getJudgmentValidator() {
+  if (!_validator) _validator = new SchemaValidator(JUDGMENT_SCHEMA_PATH);
+  return _validator;
+}

package/lib/judgment/store/index.js

@@ -0,0 +1,207 @@
+/**
+ * lib/judgment/store/index.js — judgment canon provider registry (S02).
+ *
+ * Exactly one configured canon provider (design Decision 1/5): selection is
+ * read from `.compose/compose.json#judgment.provider`, default 'records'
+ * (the tracked floor). 'smartmemory' is the checkpoint-store-precedent seam:
+ * it throws NOT_IMPLEMENTED AT SELECTION — no stub object is ever returned.
+ * W4's SmartMemory integration is an enrichment emitter behind the SEPARATE
+ * `judgment.enrichment.smartmemory` key, never a canon provider.
+ *
+ * `capabilities()` lives on each backend (records ⇒ empty set), not here.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { RecordsStore } from './records.js';
+
+const EFFECTIVE_STORES = new WeakSet();
+
+function configuredProvider(cwd) {
+  try {
+    const config = JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf8'));
+    return config?.judgment?.provider ?? 'records';
+  } catch {
+    return 'records';
+  }
+}
+
+/**
+ * Construct the configured judgment canon store for a project root.
+ * @param {string} cwd project root
+ * @returns {RecordsStore}
+ */
+export function createJudgmentStore(cwd) {
+  const provider = configuredProvider(cwd);
+  switch (provider) {
+    case 'records':
+      return new RecordsStore(cwd);
+
+    case 'smartmemory':
+      // A SmartMemory CANON provider would need the full store contract plus
+      // an owner-ruled one-time import (Decision 1). Not built; selection
+      // fails loudly rather than returning a partial stub.
+      throw Object.assign(
+        new Error("SmartMemory judgment canon provider not implemented — v1 canon is 'records'; SmartMemory ships as enrichment (judgment.enrichment.smartmemory) in W4"),
+        { code: 'NOT_IMPLEMENTED' },
+      );
+
+    default:
+      throw new Error(`Unknown judgment provider '${provider}'. Valid ids: records, smartmemory.`);
+  }
+}
+
+/**
+ * Construct a read-only view that excludes whole artifacts attributed to an
+ * intent which was pending when the view was created.
+ *
+ * The intent set is deliberately snapshotted once. Record files and ledger
+ * lines are filtered only by top-level provenance; nested intent attribution
+ * belongs to the containing record and is not recursively hidden.
+ *
+ * @param {RecordsStore} rawStore
+ */
+export function effectiveStore(rawStore) {
+  if (EFFECTIVE_STORES.has(rawStore)) return rawStore;
+
+  const pendingIntents = rawStore.readIntents();
+  const pendingIds = new Set(pendingIntents.map((intent) => intent.id));
+  const isVisible = (record) => (
+    record != null && !pendingIds.has(record.provenance?.intent_id)
+  );
+  const visibleOrNull = (record) => (isVisible(record) ? record : null);
+
+  const adapter = {
+    capabilities() {
+      return rawStore.capabilities();
+    },
+
+    readPositionRevision(slug, rev) {
+      return visibleOrNull(rawStore.readPositionRevision(slug, rev));
+    },
+
+    readPositionChain(slug) {
+      return rawStore.readPositionChain(slug)
+        .map((record) => adapter.readPositionRevision(slug, record.rev))
+        .filter(Boolean);
+    },
+
+    latestPositionRevision(slug) {
+      const chain = adapter.readPositionChain(slug);
+      return chain.length === 0 ? null : chain[chain.length - 1];
+    },
+
+    listPositionSlugs() {
+      return rawStore.listPositionSlugs()
+        .filter((slug) => adapter.readPositionChain(slug).length > 0);
+    },
+
+    derivePositionStatus(slug) {
+      const latest = adapter.latestPositionRevision(slug);
+      if (!latest) return null;
+      if (latest.retracted === true) return 'retracted';
+      for (const other of adapter.listPositionSlugs()) {
+        if (other === slug) continue;
+        const otherLatest = adapter.latestPositionRevision(other);
+        if (!otherLatest || otherLatest.retracted === true) continue;
+        const ref = otherLatest.supersedes;
+        if (typeof ref === 'string' && ref.startsWith(`${slug}#r`)) {
+          return 'superseded';
+        }
+      }
+      return 'live';
+    },
+
+    readJoint(slug) {
+      return visibleOrNull(rawStore.readJoint(slug));
+    },
+
+    listJoints() {
+      return rawStore.listJoints()
+        .map((record) => adapter.readJoint(record.slug))
+        .filter(Boolean);
+    },
+
+    readPrediction(id) {
+      return visibleOrNull(rawStore.readPrediction(id));
+    },
+
+    listPredictions({ status } = {}) {
+      return rawStore.listPredictions()
+        .map((record) => adapter.readPrediction(record.id))
+        .filter(Boolean)
+        .filter((record) => (status ? record.status === status : true));
+    },
+
+    readLedgerEvents() {
+      return rawStore.readLedgerEvents().filter(isVisible);
+    },
+
+    readPerson(slug) {
+      return visibleOrNull(rawStore.readPerson(slug));
+    },
+
+    listPeople() {
+      return rawStore.listPeople()
+        .map((record) => adapter.readPerson(record.slug))
+        .filter(Boolean);
+    },
+
+    readSituationEntity(slug) {
+      return visibleOrNull(rawStore.readSituationEntity(slug));
+    },
+
+    listSituationEntities() {
+      return rawStore.listSituationEntities()
+        .map((record) => adapter.readSituationEntity(record.slug))
+        .filter(Boolean);
+    },
+
+    readGoalVersion(version) {
+      return visibleOrNull(rawStore.readGoalVersion(version));
+    },
+
+    readGoalChain() {
+      return rawStore.readGoalChain()
+        .map((record) => adapter.readGoalVersion(record.version))
+        .filter(Boolean);
+    },
+
+    latestGoalVersion() {
+      const chain = adapter.readGoalChain();
+      return chain.length === 0 ? null : chain[chain.length - 1];
+    },
+
+    readGoalState() {
+      const raw = rawStore.readGoalState();
+      // Records-atomic guarantee (C3): while a goal migration is pending, a
+      // state.json the migration already wrote (attributed to that intent)
+      // must read back as the captured PREIMAGE, not as absence. Every other
+      // family hides an attributed record as null; goal state instead
+      // substitutes the pre-migration bytes the intent carries.
+      const migration = pendingIntents.find((intent) => intent.kind === 'goal_migration');
+      if (migration && raw?.provenance?.intent_id === migration.id) {
+        return migration.payload?.goal_state_preimage?.record ?? null;
+      }
+      return visibleOrNull(raw);
+    },
+
+    hasPendingIntentKind(kind) {
+      return pendingIntents.some((intent) => intent.kind === kind);
+    },
+  };
+
+  EFFECTIVE_STORES.add(adapter);
+  return Object.freeze(adapter);
+}
+
+/**
+ * True once a published goal chain exists and no goal migration is pending.
+ * Accepts either a raw RecordsStore or an already-effective view.
+ */
+export function goalCutoverComplete(store) {
+  const effective = EFFECTIVE_STORES.has(store) ? store : effectiveStore(store);
+  return (
+    effective.readGoalChain().length > 0
+    && !effective.hasPendingIntentKind('goal_migration')
+  );
+}