@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/maya-config.js

@@ -0,0 +1,53 @@
+/**
+ * maya-config.js — COMP-FOH FOH-6 S1
+ *
+ * Config readers for the Maya colleague coupling. Leaf module (no fetch, no
+ * state writes), mirroring lib/smartmemory-config.js: uncached direct reads of
+ * `.compose/compose.json`, try/catch → absent on missing/malformed.
+ *
+ * The feature switch is the PRESENCE of the `maya` block (design-foh-6.md
+ * §Config): absent means "not installed" (no chrome button), which is a
+ * different state from "installed but degraded" (a funnel).
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function readComposeJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The `maya` block, or null when the feature is not installed.
+ * @param {string} cwd
+ * @returns {{ baseUrl?: string, auth?: { mode?: 'provision'|'static' } } | null}
+ */
+export function getMayaConfig(cwd) {
+  const block = readComposeJson(cwd).maya;
+  return block && typeof block === 'object' ? block : null;
+}
+
+/**
+ * The fluid SmartMemory workspace id — the value the colleague identity's
+ * workspace claim must NOT equal (shallow-binding isolation, design §2).
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function getFluidWorkspaceId(cwd) {
+  const ws = readComposeJson(cwd).fluid?.smartmemory?.workspaceId;
+  return typeof ws === 'string' && ws ? ws : null;
+}
+
+/**
+ * Whether the fluid provider is SmartMemory-backed. The colleague never runs
+ * degraded (COLLEAGUE-ALL-IN): on the local floor the panel is a
+ * connect-SmartMemory funnel, not a plain chat.
+ * @param {string} cwd
+ */
+export function hasSmartmemoryFluidProvider(cwd) {
+  return readComposeJson(cwd).fluid?.provider === 'smartmemory';
+}

package/lib/maya-identity.js

@@ -0,0 +1,283 @@
+/**
+ * maya-identity.js — COMP-FOH FOH-6 S1
+ *
+ * The colleague identity store: `data/maya-identity.json` (covered by
+ * `.gitignore`'s blanket `data/` entry). One identity per project; it OWNS
+ * Maya's single standing conversation (session per JWT identity,
+ * session_registry.py:486-527), so nothing here re-provisions implicitly —
+ * minting a fresh identity destroys the thread AND the colleague-workspace
+ * memory, and is only ever an explicit user action (design §2).
+ *
+ * Provisioning uses smart-memory-service's sanctioned test surface, the same
+ * path the FOH-4/5/6 live-fires used:
+ *   POST /test/provision-user {email} → {user_id, tenant_id, team_id, access_token}
+ *     (409 on a repeated email — probed live 2026-08-11; there is no
+ *     token-refresh path on the test surface yet, upstream ask filed with the
+ *     channel_context issue)
+ *   POST /memory/beta/nda/accept {"version":"v1"}   (Bearer-authenticated)
+ *   DELETE /test/provision-user {email, user_id, tenant_id}
+ */
+
+import { readFileSync, writeFileSync, renameSync, rmSync, mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/** Provisioning/NDA failure. `kind` mirrors the relay's funnel taxonomy. */
+export class MayaIdentityError extends Error {
+  constructor(message, kind = 'auth') {
+    super(message);
+    this.name = 'MayaIdentityError';
+    this.kind = kind;
+  }
+}
+
+/** The colleague token's workspace claim equals the fluid workspace —
+ *  accepting it would silently enable the deferred deep-binding behaviour
+ *  (Maya's turn-ingestion writing into the fluid workspace). */
+export class MayaWorkspaceCollisionError extends Error {
+  constructor(claim) {
+    super(
+      `maya: the colleague token's workspace claim (${claim}) IS the fluid workspace — `
+      + 'refusing. Shallow binding requires a dedicated colleague workspace; '
+      + 'provision a separate identity or paste a token scoped elsewhere.',
+    );
+    this.name = 'MayaWorkspaceCollisionError';
+    this.claim = claim;
+  }
+}
+
+function identityPath(projectRoot) {
+  return join(projectRoot, 'data', 'maya-identity.json');
+}
+
+/** @returns {object|null} the stored identity, or null when none exists */
+export function loadIdentity(projectRoot) {
+  const path = identityPath(projectRoot);
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    // Enforce owner-only permissions on files created before the 0600 write
+    // path existed (Codex r1 P2). Best-effort — a read-only checkout must not
+    // break loading.
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Owner-only (0600) and ATOMIC: the file holds a bearer credential, so it must
+ * never be group/world-readable, and a crash mid-write must never truncate it
+ * — a truncated file loads as null and the next turn would silently provision
+ * a fresh identity, destroying the standing conversation (Codex r1 P2).
+ */
+export function saveIdentity(projectRoot, identity) {
+  mkdirSync(join(projectRoot, 'data'), { recursive: true });
+  const path = identityPath(projectRoot);
+  const tmp = `${path}.tmp.${randomBytes(6).toString('hex')}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(identity, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+export function clearIdentity(projectRoot) {
+  rmSync(identityPath(projectRoot), { force: true });
+}
+
+async function requestJson(url, { body, token, timeoutMs = 30000, fetchFn = fetch, method = 'POST' }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(url, {
+      method,
+      headers: {
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* tolerated; shape-checked below */ }
+    return { status: res.status, body: parsed };
+  } catch (err) {
+    throw new MayaIdentityError(`maya: ${method} ${url} failed: ${err?.message ?? 'unknown'}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Mint a fresh colleague identity. A RANDOM email per call — the provision
+ * surface refuses repeats (409), and a colleague identity is never shared
+ * across projects (documented-unsupported, design §2).
+ *
+ * Does NOT save: the caller decides persistence (ensureIdentity does both).
+ */
+export async function provisionIdentity({ smBaseUrl, fetchFn = fetch }) {
+  const email = `maya-colleague-${randomBytes(6).toString('hex')}@compose.invalid`;
+  const res = await requestJson(`${smBaseUrl}/test/provision-user`, { body: { email }, fetchFn });
+  if (res.status !== 200 || typeof res.body?.access_token !== 'string') {
+    throw new MayaIdentityError(
+      `maya: provisioning failed (HTTP ${res.status})`
+      + (res.body?.detail ? ` — ${String(res.body.detail).slice(0, 200)}` : ''),
+    );
+  }
+  const { user_id, tenant_id, team_id, access_token } = res.body;
+  return {
+    mode: 'provision', email, user_id, tenant_id, team_id, access_token,
+    ndaAccepted: false, provisionedAt: new Date().toISOString(),
+  };
+}
+
+/** Accept the beta NDA for a provisioned identity (403 `nda_required` gates
+ *  every memory route until this runs — FOH-4 ledger prereq 3). */
+export async function acceptNda({ smBaseUrl, token, fetchFn = fetch }) {
+  const res = await requestJson(`${smBaseUrl}/memory/beta/nda/accept`, {
+    body: { version: 'v1' }, token, fetchFn,
+  });
+  if (res.status < 200 || res.status >= 300) {
+    throw new MayaIdentityError(`maya: NDA accept failed (HTTP ${res.status})`);
+  }
+}
+
+/** Tear down a provisioned identity (explicit user action only). */
+export async function teardownIdentity(projectRoot, { smBaseUrl, fetchFn = fetch }) {
+  const identity = loadIdentity(projectRoot);
+  if (!identity) return { removed: false };
+  if (identity.mode === 'provision' && identity.email) {
+    await requestJson(`${smBaseUrl}/test/provision-user`, {
+      method: 'DELETE', fetchFn,
+      body: { email: identity.email, user_id: identity.user_id, tenant_id: identity.tenant_id },
+    });
+  }
+  clearIdentity(projectRoot);
+  return { removed: true };
+}
+
+/**
+ * The identity's workspace claim, or null when none is derivable. Provisioned
+ * identities carry `team_id` from the provision response (VERIFY-1: the JWT
+ * payload itself carries NO workspace claims — Maya resolves the workspace
+ * server-side from the verified user record). Static tokens fall back to
+ * decoding the JWT body for the claims Maya's `_extract_team_id` reads.
+ */
+export function workspaceClaimOf(identity) {
+  if (!identity) return null;
+  if (typeof identity.team_id === 'string' && identity.team_id) return identity.team_id;
+  const token = identity.access_token;
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return payload.workspace_id ?? payload.current_workspace_id
+      ?? payload.default_team_id ?? payload.team_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The shallow-binding invariant (design §2, VERIFY-3): refuse a colleague
+ * token whose workspace claim equals the fluid workspace. An underivable claim
+ * is ALLOWED here for STORED identities — provisioned identities always carry
+ * `team_id`, and static identities have their claim resolved and stored at
+ * paste time by `fetchVerifiedWorkspace` (which fails CLOSED — see below), so
+ * an underivable claim on a stored identity means only that this project has
+ * no fluid workspace to collide with. Cross-project token reuse remains
+ * documented-unsupported, not detected.
+ */
+export function validateWorkspaceIsolation(identity, fluidWorkspaceId) {
+  if (!fluidWorkspaceId) return;
+  const claim = workspaceClaimOf(identity);
+  if (claim && claim === fluidWorkspaceId) throw new MayaWorkspaceCollisionError(claim);
+}
+
+/**
+ * Resolve a token's VERIFIED workspace from smart-memory-service itself
+ * (`GET /auth/me` → `default_team_id` — the same user-record field Maya's
+ * `_extract_team_id` falls back to). Exists because the JWT-decode fallback is
+ * vacuous in practice: real tokens carry NO workspace claims (VERIFY-1), so a
+ * pasted static token could silently defeat the isolation check (Codex r1 P1).
+ *
+ * FAILS CLOSED: an unreachable service, a rejected token, or a user record
+ * without a resolvable team all throw — the paste flow refuses to store a
+ * token whose workspace it cannot verify.
+ */
+export async function fetchVerifiedWorkspace({ smBaseUrl, token, fetchFn = fetch }) {
+  if (!smBaseUrl) {
+    throw new MayaIdentityError('maya: cannot verify the token — smartmemory baseUrl is not configured');
+  }
+  const res = await requestJson(`${smBaseUrl}/auth/me`, { method: 'GET', token, fetchFn });
+  if (res.status !== 200 || !res.body || typeof res.body !== 'object') {
+    throw new MayaIdentityError(
+      `maya: could not verify the token against SmartMemory (HTTP ${res.status}) — not storing it`,
+    );
+  }
+  const team = res.body.default_team_id;
+  if (typeof team !== 'string' || !team) {
+    throw new MayaIdentityError(
+      'maya: the token verified but resolves no workspace (no default_team_id) — '
+      + 'refusing to store a token whose isolation cannot be checked',
+    );
+  }
+  return team;
+}
+
+/**
+ * Per-project serialization for ensureIdentity. Two concurrent first turns
+ * that both observe "no identity" would otherwise provision two competing
+ * users, overwrite each other's files, and fork the standing conversation
+ * (Codex r1 P2). The server is a single process, so an in-process promise
+ * chain is the whole fix: every caller re-loads at the head of its own turn
+ * in the chain and sees the winner's identity.
+ */
+const _ensureChain = new Map(); // projectRoot -> tail Promise
+
+async function ensureIdentityUnserialized(projectRoot, { smBaseUrl, mode, fetchFn = fetch }) {
+  let identity = loadIdentity(projectRoot);
+  if (!identity) {
+    if (mode !== 'provision') {
+      throw new MayaIdentityError('maya: no token configured — paste one in the panel', 'auth');
+    }
+    if (!smBaseUrl) {
+      throw new MayaIdentityError('maya: provisioning needs the smartmemory baseUrl', 'auth');
+    }
+    identity = await provisionIdentity({ smBaseUrl, fetchFn });
+    saveIdentity(projectRoot, identity);
+  }
+  // A saved-but-unaccepted NDA (crash between provision and accept) is retried
+  // on the SAME identity rather than minting a new one.
+  if (identity.mode === 'provision' && !identity.ndaAccepted) {
+    await acceptNda({ smBaseUrl, token: identity.access_token, fetchFn });
+    identity.ndaAccepted = true;
+    saveIdentity(projectRoot, identity);
+  }
+  return identity;
+}
+
+/**
+ * The relay's per-turn identity resolution: load, lazily provision on FIRST
+ * use (provision mode only — static mode with no pasted token is an auth
+ * funnel), and complete a pending NDA. Never called on a 401 — that funnel is
+ * explicit-action-only. Serialized per project (see `_ensureChain`).
+ */
+export async function ensureIdentity(projectRoot, opts) {
+  const tail = _ensureChain.get(projectRoot) ?? Promise.resolve();
+  const run = tail
+    .catch(() => {}) // a predecessor's failure must not poison the chain
+    .then(() => ensureIdentityUnserialized(projectRoot, opts));
+  _ensureChain.set(projectRoot, run);
+  try {
+    return await run;
+  } finally {
+    if (_ensureChain.get(projectRoot) === run) _ensureChain.delete(projectRoot);
+  }
+}

package/lib/mcp-enforcement.js

@@ -11,19 +11,20 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import {
+  isGuarded as registryIsGuarded,
+  toolsForPath as registryToolsForPath,
+  featureCodeForPath as registryFeatureCodeForPath,
+} from './canon-registry.js';
 
-const GUARDED_FILES = new Set(['ROADMAP.md', 'CHANGELOG.md']);
-
-const TOOLS_FOR_ROADMAP = ['add_roadmap_entry', 'set_feature_status', 'propose_followup'];
-const TOOLS_FOR_CHANGELOG = ['add_changelog_entry'];
-const TOOLS_FOR_FEATURE_JSON = [
-  'add_roadmap_entry',
-  'set_feature_status',
-  'link_artifact',
-  'link_features',
-  'record_completion',
-  'propose_followup',
-];
+// COMP-CANON-GUARD S1: the guarded-path/tool declarations that used to live here
+// as literal sets now live in lib/canon-registry.js — the single source of truth
+// shared with the write-time hook. This module is the 'ship' enforcement point;
+// it consumes ONLY the registry's ship subset, so its behavior is unchanged
+// (docs/judgment/** is a hook-only path and is invisible here, exactly as before
+// this refactor, when it was not declared at all). The contract test
+// (test/canon-registry-contract.test.js) pins that equivalence.
+const ENFORCEMENT_POINT = 'ship';
 
 /**
  * Read `enforcement.mcpForFeatureMgmt` and normalize to 'block' | 'log' | 'off'.
@@ -63,11 +64,7 @@ export function filterGuarded(dirtyFiles, featuresDir) {
  */
 export function isGuardedPath(path, featuresDir) {
   if (typeof path !== 'string') return false;
-  if (GUARDED_FILES.has(path)) return true;
-  // <featuresDir>/<CODE>/feature.json
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (!path.startsWith(prefix)) return false;
-  return path.endsWith('/feature.json');
+  return registryIsGuarded(path, { featuresDir, point: ENFORCEMENT_POINT });
 }
 
 /**
@@ -80,13 +77,7 @@ export function isGuardedPath(path, featuresDir) {
  * @returns {string[]}
  */
 export function expectedToolsForPath(path, featuresDir) {
-  if (path === 'ROADMAP.md') return [...TOOLS_FOR_ROADMAP];
-  if (path === 'CHANGELOG.md') return [...TOOLS_FOR_CHANGELOG];
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (path.startsWith(prefix) && path.endsWith('/feature.json')) {
-    return [...TOOLS_FOR_FEATURE_JSON];
-  }
-  return [];
+  return registryToolsForPath(path, { featuresDir, point: ENFORCEMENT_POINT });
 }
 
 /**
@@ -98,11 +89,7 @@ export function expectedToolsForPath(path, featuresDir) {
  * @returns {string|null}
  */
 export function featureCodeFromPath(path, featuresDir) {
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (!path.startsWith(prefix) || !path.endsWith('/feature.json')) return null;
-  const middle = path.slice(prefix.length, -'/feature.json'.length);
-  if (!middle || middle.includes('/')) return null;
-  return middle;
+  return registryFeatureCodeForPath(path, { featuresDir });
 }
 
 /**
@@ -165,9 +152,8 @@ export function enforcementError(violations) {
   return err;
 }
 
-export const _internals = {
-  GUARDED_FILES,
-  TOOLS_FOR_ROADMAP,
-  TOOLS_FOR_CHANGELOG,
-  TOOLS_FOR_FEATURE_JSON,
-};
+// NOTE: the `_internals` export (guarded-file set + tool sets) was removed in
+// COMP-CANON-GUARD S1. Those declarations now live in lib/canon-registry.js —
+// the single source of truth — with no in-repo consumer of the old shim. Import
+// from canon-registry.js if you need the raw sets, so there is exactly ONE
+// declaration, not a copy here that can drift.

package/lib/migrate-anon.js

@@ -181,6 +181,11 @@ export async function promoteAnonRow(cwd, row, { code, status = 'PLANNED', scaff
       status,
       complexity: 'S',
       position,
+      // COMP-COMPLETION-GATE: promoting an anonymous ROADMAP row transcribes a
+      // status that already exists in the roadmap — including COMPLETE for work
+      // finished long before the gate. That is history, not a new completion, so
+      // it takes the named migration exemption rather than the completion path.
+      _migration: { reason: `promoting anonymous ROADMAP row in phase ${row.phaseId}` },
     });
   } catch (err) {
     if (err && err.code === 'ROADMAP_PARTIAL_WRITE') throw err;

package/lib/migrate-roadmap.js

@@ -81,6 +81,21 @@ export function migrateRoadmap(cwd, opts = {}) {
       feature.created = new Date().toISOString().slice(0, 10);
     }
 
+    // COMP-COMPLETION-GATE slice 3 (AC-17, path 13): the migration legitimately
+    // copies historical COMPLETE rows into feature.json — it transcribes a
+    // completion that already happened, it does not mint one. The exemption is
+    // NAMED and LOGGED per write and covers BOTH branches: an existing file
+    // (`--overwrite`) and a missing one (created without it — §2.7 round 2
+    // finding 7: an exemption keyed on --overwrite alone would leave the
+    // create path as an unlogged bypass). `writeFeature` is the raw file
+    // primitive; this callsite is on the completion-write allowlist.
+    if (feature.status === 'COMPLETE') {
+      console.warn(
+        `[migrate-roadmap] migration exemption (${existing ? 'overwrite' : 'create'}): writing ` +
+        `${entry.code} as COMPLETE from its ROADMAP row without a completion record — ` +
+        `ROADMAP is the source of truth during migration.`,
+      );
+    }
     if (opts.dryRun) {
       console.log(`${existing ? 'update' : 'create'}: ${featuresDir}/${entry.code}/feature.json`);
     } else {

package/lib/new.js

@@ -13,6 +13,7 @@ import { promptGate } from './gate-prompt.js';
 import { VisionWriter } from './vision-writer.js';
 import { readFlowRound } from './flow-state.js';
 import { validateStep } from './step-validator.js';
+import { tsCompatibilityOf, quarantineMessage } from './pipeline-compat.js';
 
 const KICKOFF_VALIDATION = new Map([
   ['research', {
@@ -81,7 +82,18 @@ export async function runNew(intent, opts = {}) {
     throw new Error(`Kickoff spec not found: ${specPath}. Run 'compose init' to get default pipelines.`);
   }
 
-  const spec = YAML.parse(readFileSync(specPath, 'utf-8'));
+  // COMP-PIPELINE-QUARANTINE follow-up: `compose new` has its own runner and
+  // calls stratum.plan directly, so it never passed through runBuild's
+  // compatibility check. An existing workspace pinning an old new.stratum.yaml
+  // (init never overwrites one) still got the opaque engine rejection this check
+  // exists to replace.
+  const specText = readFileSync(specPath, 'utf-8');
+  const specCompat = tsCompatibilityOf(specText);
+  if (!specCompat.compatible) {
+    throw new Error(quarantineMessage(specPath, specCompat));
+  }
+
+  const spec = YAML.parse(specText);
   if (opts.skipResearch) {
     const research = spec.flows?.new?.steps?.find((step) => step.id === 'research');
     if (research) research.when = 'false';

package/lib/pipeline-compat.js

@@ -0,0 +1,104 @@
+/**
+ * TS-engine spec compatibility.
+ *
+ * COMP-PIPELINE-QUARANTINE: STRAT-PY-RETIRE converted only the two production
+ * pipelines (build, gsd) from the v0.3 dialect to TS v1 — see compose commit
+ * 9221548, "Both production pipelines (build, gsd) are re-authored as TS v1".
+ * Everything else in pipelines/ and presets/ stayed behind — most on v0.3,
+ * bug-fix on v0.1 — and the older execution paths were deleted, so those specs
+ * cannot run at all: the engine
+ * refuses them at `stratum_plan` with a bare `MCP error -32602: spec validation
+ * failed`, which tells the user nothing about why.
+ *
+ * This module is the single place that answers "can the TS engine run this
+ * spec". It reads the spec's OWN version stamp rather than consulting a list of
+ * pipeline names — so migrating a spec to `version: 1` lifts its quarantine
+ * automatically, with nothing here to remember to update.
+ */
+
+import { parse as parseYaml } from 'yaml';
+
+/** The only spec dialect the TS engine accepts. */
+export const TS_SPEC_VERSION = 1;
+
+/**
+ * The specs `compose init` seeds into a workspace's pipelines/ directory.
+ *
+ * Shared with resolveTemplatePath, which deliberately does NOT fall back to the
+ * bundled copy for these: their absence means the workspace was never
+ * initialized, and failing loudly with "Lifecycle spec not found" is the honest
+ * answer. Silently running Compose's own bundled build pipeline against an
+ * uninitialized project would be worse than the error. Every OTHER shipped
+ * pipeline (content, coverage-sweep, refactor, research, review-fix) is never
+ * copied by init, so the bundled copy is its only source and the fallback is the
+ * only way `--template research` can resolve at all.
+ */
+export const INIT_PROVISIONED_SPECS = Object.freeze([
+  'build',
+  'build-quick',
+  'bug-fix',
+  'new',
+  'plan',
+]);
+
+/**
+ * Classify a spec's engine compatibility.
+ *
+ * Deliberately shallow: a `version: 1` stamp means "authored for this engine",
+ * not "valid". Full validation belongs to the engine, which reports precise
+ * errors. This exists to turn the common, uninformative failure — a spec from
+ * the retired dialect — into a message that names the cause.
+ *
+ * @param {string} specText  Raw spec YAML
+ * @returns {{compatible: boolean, version: unknown, reason: string|null}}
+ */
+export function tsCompatibilityOf(specText) {
+  let parsed;
+  try {
+    parsed = parseYaml(specText);
+  } catch (err) {
+    return { compatible: false, version: null, reason: `spec is not parseable YAML: ${err.message}` };
+  }
+  const version = parsed?.version ?? null;
+  if (version === TS_SPEC_VERSION) return { compatible: true, version, reason: null };
+  if (version === null) {
+    return { compatible: false, version, reason: 'spec declares no `version`' };
+  }
+  return {
+    compatible: false,
+    version,
+    reason: `spec declares version ${JSON.stringify(version)}, but the TS engine only runs version ${TS_SPEC_VERSION}`,
+  };
+}
+
+/** True iff the TS engine will accept this spec's dialect. */
+export function isTsEngineSpec(specText) {
+  return tsCompatibilityOf(specText).compatible;
+}
+
+/**
+ * The message shown when a quarantined pipeline is invoked. Names the spec, the
+ * cause, and the only two ways forward — never a raw engine error code.
+ *
+ * @param {string} specPath  Absolute path of the offending spec
+ * @param {{reason: string|null}} compat  Result of tsCompatibilityOf
+ */
+export function quarantineMessage(specPath, compat) {
+  // Only a spec that declares an OLDER dialect gets the migration story. A
+  // malformed or version-less spec is far more likely to be a fresh typo, and
+  // telling its author it was "left behind by STRAT-PY-RETIRE" is a confident
+  // false history that sends them looking in the wrong place.
+  const isRetiredDialect = typeof compat.version === 'string' && /^0\./.test(compat.version);
+  const lines = [
+    `This pipeline cannot run: ${specPath}`,
+    `  ${compat.reason}.`,
+  ];
+  if (isRetiredDialect) {
+    lines.push(
+      '  It was left on a retired dialect when STRAT-PY-RETIRE cut the engine over to TS v1 and',
+      '  deleted the older execution path, so it has been unrunnable since that cutover.',
+    );
+  }
+  lines.push(`  The spec must declare \`version: ${TS_SPEC_VERSION}\` and use the TS v1 dialect.`);
+  return lines.join('\n');
+}