@nebulacomponents/citable 1.11.0 → 1.13.0

package/src/registries/index.js

@@ -23,6 +23,16 @@ export const REGISTRY_SPECS = [
   { file: 'review-items.yaml', kind: 'review_items', schema: 'review-item.schema.json', idField: 'review_item_id' },
   { file: 'sampling-plans.yaml', kind: 'sampling_plans', schema: 'sampling-plan.schema.json', idField: 'sampling_plan_id' },
   { file: 'schedules.yaml', kind: 'schedules', schema: 'schedule.schema.json', idField: 'schedule_id' },
+  // Executive reporting suite — governed inputs (Phase 1)
+  { file: 'kpis.yaml',              kind: 'kpis',              schema: 'kpi.schema.json',             idField: 'metric_id' },
+  { file: 'variances.yaml',         kind: 'variances',         schema: 'variance.schema.json',        idField: 'variance_id' },
+  { file: 'customer-outcomes.yaml', kind: 'customer-outcomes', schema: 'customer-outcome.schema.json', idField: 'outcome_id' },
+  { file: 'risks.yaml',             kind: 'risks',             schema: 'risk.schema.json',            idField: 'risk_id' },
+  // Executive reporting suite — decision support (Phase 2)
+  { file: 'decisions.yaml',    kind: 'decisions',   schema: 'decision.schema.json',   idField: 'decision_id' },
+  { file: 'assumptions.yaml',  kind: 'assumptions', schema: 'assumption.schema.json', idField: 'assumption_id' },
+  { file: 'scenarios.yaml',    kind: 'scenarios',   schema: 'scenario.schema.json',   idField: 'scenario_id' },
+  { file: 'initiatives.yaml',  kind: 'initiatives', schema: 'initiative.schema.json', idField: 'initiative_id' },
 ];
 
 export function contextDir(root) {
@@ -33,6 +43,31 @@ export function emptyRegistry(kind) {
   return { version: 1, kind, updated: nowIso(), entries: [] };
 }
 
+const LOAD_PROBLEMS = Symbol('registryLoadProblems');
+
+/** Read one registry without allowing malformed YAML to crash a command. */
+export function loadRegistryFile(file, kind) {
+  let data = emptyRegistry(kind);
+  const problems = [];
+  if (fs.existsSync(file)) {
+    try {
+      data = readYaml(file) ?? emptyRegistry(kind);
+      if (typeof data !== 'object' || data === null || !Array.isArray(data.entries)) {
+        problems.push(`${path.basename(file)}: YAML does not match expected registry shape`);
+        data = emptyRegistry(kind);
+      }
+    } catch (error) {
+      problems.push(`${path.basename(file)}: YAML parse failure: ${error.message}`);
+    }
+  }
+  Object.defineProperty(data, LOAD_PROBLEMS, { value: problems, enumerable: false });
+  return data;
+}
+
+export function registryLoadProblems(data) {
+  return data?.[LOAD_PROBLEMS] ?? [];
+}
+
 /** Load all registries under <root>/.citable. Missing files load as empty. */
 export function loadRegistries(root) {
   const dir = contextDir(root);
@@ -63,13 +98,21 @@ export function checkReferentialIntegrity(registries) {
   const problems = [];
   const ids = {};
   for (const spec of REGISTRY_SPECS) {
-    ids[spec.kind] = new Set((registries[spec.kind]?.entries || []).map((e) => e[spec.idField]));
-    const seen = new Set();
-    for (const e of registries[spec.kind]?.entries || []) {
-      const id = e[spec.idField];
-      if (seen.has(id)) problems.push(`${spec.kind}: duplicate id ${id}`);
-      seen.add(id);
+    const registry = registries[spec.kind] ?? emptyRegistry(spec.kind);
+    const schemaValid = (registry.entries || []).filter((entry) =>
+      validateAgainst(spec.schema, { ...registry, entries: [entry] }).valid);
+    const counts = new Map();
+    for (const entry of schemaValid) {
+      const id = entry[spec.idField];
+      counts.set(id, (counts.get(id) ?? 0) + 1);
     }
+    for (const [id, count] of counts) {
+      if (count > 1) problems.push(`${spec.kind}/${id}: duplicate id ${id}`);
+    }
+    // Only schema-valid, unambiguous records may satisfy references.
+    ids[spec.kind] = new Set(schemaValid
+      .map((entry) => entry[spec.idField])
+      .filter((id) => counts.get(id) === 1));
   }
   const refChecks = [
     ['claims', 'evidence', 'evidence', 'claim_id'],
@@ -131,6 +174,64 @@ export function checkReferentialIntegrity(registries) {
   }
   const reviewItemIds = ids.review_items || new Set();
   for (const plan of registries.sampling_plans?.entries || []) for (const ref of plan.selected_item_ids || []) if (!reviewItemIds.has(ref)) problems.push(`sampling_plans/${plan.sampling_plan_id}: references unknown review item id "${ref}"`);
+
+  // ── Executive reporting suite cross-registry checks ────────────────────────
+  const kpiIds        = ids.kpis            || new Set();
+  const outcomeIds    = ids['customer-outcomes'] || new Set();
+  const decisionIds   = ids.decisions       || new Set();
+  const assumptionIds = ids.assumptions     || new Set();
+  const riskIds       = ids.risks           || new Set();
+  const initiativeIds = ids.initiatives     || new Set();
+
+  // variances must reference a known KPI metric_id
+  for (const v of registries.variances?.entries || []) {
+    if (v.metric_id && !kpiIds.has(v.metric_id))
+      problems.push(`variances/${v.variance_id}: metric_id "${v.metric_id}" references unknown kpi`);
+  }
+
+  // decisions: supporting/contradicting evidence can reference outcome IDs
+  for (const d of registries.decisions?.entries || []) {
+    const prefix = `decisions/${d.decision_id}`;
+    for (const ref of d.supporting_evidence || []) {
+      if (typeof ref === 'string' && ref.startsWith('OUT-') && !outcomeIds.has(ref))
+        problems.push(`${prefix}: supporting_evidence references unknown customer-outcome "${ref}"`);
+    }
+    for (const ref of d.contradicting_evidence || []) {
+      if (typeof ref === 'string' && ref.startsWith('OUT-') && !outcomeIds.has(ref))
+        problems.push(`${prefix}: contradicting_evidence references unknown customer-outcome "${ref}"`);
+    }
+    for (const ref of d.assumptions || []) {
+      if (typeof ref === 'string' && ref.startsWith('ASMP-') && !assumptionIds.has(ref))
+        problems.push(`${prefix}: assumptions references unknown assumption "${ref}"`);
+    }
+  }
+
+  // initiatives: linked_kpis, linked_outcomes, linked_risks, linked_decisions
+  for (const i of registries.initiatives?.entries || []) {
+    const prefix = `initiatives/${i.initiative_id}`;
+    for (const ref of i.linked_kpis || [])
+      if (!kpiIds.has(ref)) problems.push(`${prefix}: linked_kpis references unknown kpi "${ref}"`);
+    for (const ref of i.linked_outcomes || [])
+      if (!outcomeIds.has(ref)) problems.push(`${prefix}: linked_outcomes references unknown customer-outcome "${ref}"`);
+    for (const ref of i.linked_risks || [])
+      if (!riskIds.has(ref)) problems.push(`${prefix}: linked_risks references unknown risk "${ref}"`);
+    for (const ref of i.linked_decisions || [])
+      if (!decisionIds.has(ref)) problems.push(`${prefix}: linked_decisions references unknown decision "${ref}"`);
+  }
+
+  // scenarios: variable_ids should reference known KPIs or risks
+  for (const s of registries.scenarios?.entries || []) {
+    const prefix = `scenarios/${s.scenario_id}`;
+    for (const v of s.variables || []) {
+      const ref = v.variable_id;
+      if (!ref) continue;
+      if (ref.startsWith('KPI-') && !kpiIds.has(ref))
+        problems.push(`${prefix}: variable "${ref}" references unknown kpi`);
+      if (ref.startsWith('RISK-') && !riskIds.has(ref))
+        problems.push(`${prefix}: variable "${ref}" references unknown risk`);
+    }
+  }
+
   return problems;
 }
 

package/src/release/governance.js

@@ -0,0 +1,331 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ALL_DETECTORS, detectorsByNamespace } from '../detectors/index.js';
+import { REGISTRY_SPECS } from '../registries/index.js';
+import { PROVIDERS } from '../installer/providers.js';
+import { sha256, writeJson } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const SOURCE_PROJECTIONS = [
+  ['package-json', 'package.json'],
+  ['package-lock', 'package-lock.json'],
+  ['skill-metadata', 'skill/SKILL.md'],
+  ['npm-readme', 'README.md'],
+  ['changelog', 'CHANGELOG.md'],
+  ['roadmap', 'docs/ROADMAP.md'],
+  ['controlled-surfaces', 'release/surfaces.json'],
+  ['distribution-manifest', 'dist/universal/manifest.json'],
+];
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function manifestHash(manifest) {
+  const { manifest_hash: ignored, ...unsigned } = manifest;
+  return sha256(canonicalJson(unsigned));
+}
+
+function projection(id, relativePath, content) {
+  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+  return { projection_id: id, path: relativePath, sha256: sha256(buffer), bytes: buffer.length, authority: 'control_plane' };
+}
+
+function currentCommit(root) {
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8' }).trim();
+}
+
+export function verifyRepositoryBinding(root, commit) {
+  try {
+    const head = currentCommit(root);
+    const trackedChanges = execFileSync('git', ['status', '--porcelain', '--untracked-files=no'], { cwd: root, encoding: 'utf8' }).trim();
+    const failures = [];
+    if (head !== commit) failures.push(`manifest commit ${commit} differs from HEAD ${head}`);
+    if (trackedChanges) failures.push('tracked working tree is not clean');
+    return { ok: failures.length === 0, failures };
+  } catch (error) {
+    return { ok: false, failures: [`repository binding unavailable: ${error.message}`] };
+  }
+}
+
+function distributionFileCount(root) {
+  const manifestFile = path.join(root, 'dist', 'universal', 'manifest.json');
+  if (!fs.existsSync(manifestFile)) return 0;
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  const first = Object.values(manifest.providers || {})[0];
+  if (Array.isArray(first)) return first.length;
+  if (Array.isArray(first?.files)) return first.files.length;
+  if (Number.isInteger(first?.files) && first.files >= 0) return first.files;
+  return 0;
+}
+
+export function releaseFacts(root) {
+  return {
+    detectors: ALL_DETECTORS.length,
+    namespaces: Object.keys(detectorsByNamespace()).length,
+    registries: REGISTRY_SPECS.length,
+    providers: Object.keys(PROVIDERS).length,
+    distribution_files_per_provider: distributionFileCount(root),
+  };
+}
+
+export function resourceProjection(version, facts, commit) {
+  return {
+    schema_version: 1,
+    product: 'Citable',
+    version,
+    commit,
+    facts,
+    boundary: 'Citable does not guarantee crawling, indexing, ranking, citation, recommendation, or conversion.',
+    canonical_repository: 'https://github.com/mikeholownych/citable',
+    npm_package: 'https://www.npmjs.com/package/@nebulacomponents/citable',
+  };
+}
+
+export function llmsProjection(version, facts, commit) {
+  return `# Citable\n\nCitable is the evidence and change-control layer for defensible search and AI citation readiness.\n\n- Version: ${version}\n- Release commit: ${commit}\n- Detectors: ${facts.detectors} across ${facts.namespaces} namespaces\n- Schema-validated registries: ${facts.registries}\n- Agent providers: ${facts.providers}\n- Canonical repository: https://github.com/mikeholownych/citable\n- npm: https://www.npmjs.com/package/@nebulacomponents/citable\n\nCitable does not guarantee crawling, indexing, ranking, citation, recommendation, or conversion.\n`;
+}
+
+export function generateReleaseManifest(root, { commit = currentCommit(root), generatedAt = new Date().toISOString(), outputDir } = {}) {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const version = packageJson.version;
+  const facts = releaseFacts(root);
+  const generated = {
+    'release/resource-data.json': `${JSON.stringify(resourceProjection(version, facts, commit), null, 2)}\n`,
+    'release/llms.txt': llmsProjection(version, facts, commit),
+  };
+  const projections = SOURCE_PROJECTIONS.map(([id, relativePath]) => {
+    const file = path.join(root, relativePath);
+    if (!fs.existsSync(file)) throw new Error(`required release projection is missing: ${relativePath}`);
+    return projection(id, relativePath, fs.readFileSync(file));
+  });
+  projections.push(projection('resource-data', 'release/resource-data.json', generated['release/resource-data.json']));
+  projections.push(projection('llms-txt', 'release/llms.txt', generated['release/llms.txt']));
+  const surfaceConfig = JSON.parse(fs.readFileSync(path.join(root, 'release', 'surfaces.json'), 'utf8'));
+  const manifest = {
+    schema_version: 1,
+    release_id: `RELEASE-v${version}`,
+    version,
+    commit,
+    generated_at: generatedAt,
+    toolchain: { node: process.version, citable: version },
+    facts,
+    projections,
+    controlled_surfaces: surfaceConfig.controlled_surfaces,
+  };
+  manifest.manifest_hash = manifestHash(manifest);
+  const check = validateAgainst('release-manifest.schema.json', manifest);
+  if (!check.valid) throw new Error(`release manifest violates contract: ${check.errors.join('; ')}`);
+  if (outputDir) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    for (const [relativePath, content] of Object.entries(generated)) {
+      const file = path.join(outputDir, path.basename(relativePath));
+      fs.writeFileSync(file, content);
+    }
+    writeJson(path.join(outputDir, 'release-manifest.json'), manifest);
+  }
+  return { manifest, generated };
+}
+
+function assertedCount(text, pattern, label) {
+  const match = pattern.exec(text);
+  return match ? { label, value: Number(match[1]) } : null;
+}
+
+export function validateReleaseManifest(root, manifest, generated = {}) {
+  const failures = [];
+  const check = validateAgainst('release-manifest.schema.json', manifest);
+  if (!check.valid) return { ok: false, failures: check.errors };
+  if (manifest.manifest_hash !== manifestHash(manifest)) failures.push('manifest hash is inconsistent');
+  const actual = generateReleaseManifest(root, { commit: manifest.commit, generatedAt: manifest.generated_at });
+  if (canonicalJson(actual.manifest.facts) !== canonicalJson(manifest.facts)) failures.push('release facts differ from executable sources');
+  const actualProjections = new Map(actual.manifest.projections.map((item) => [item.projection_id, item]));
+  for (const expected of manifest.projections) {
+    const observed = actualProjections.get(expected.projection_id);
+    if (!observed) failures.push(`${expected.projection_id}: projection is missing`);
+    else if (observed.sha256 !== expected.sha256 || observed.bytes !== expected.bytes) failures.push(`${expected.projection_id}: projection checksum differs`);
+  }
+  for (const [relativePath, content] of Object.entries(actual.generated)) {
+    if (generated[relativePath] != null && generated[relativePath] !== content) failures.push(`${relativePath}: generated projection differs`);
+  }
+  const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
+  const roadmap = fs.readFileSync(path.join(root, 'docs', 'ROADMAP.md'), 'utf8');
+  const assertions = [
+    assertedCount(readme, /\*\*(\d+) detectors\*\*/, 'README detector count'),
+    assertedCount(readme, /across (\d+) namespaces/, 'README namespace count'),
+    assertedCount(roadmap, /\| Detectors \| (\d+) across/, 'roadmap detector count'),
+    assertedCount(roadmap, /\| Registries \| (\d+) schema-validated/, 'roadmap registry count'),
+    assertedCount(roadmap, /\| Distribution \| (\d+) packaged files per provider/, 'roadmap distribution count'),
+  ].filter(Boolean);
+  const expected = { 'README detector count': manifest.facts.detectors, 'README namespace count': manifest.facts.namespaces, 'roadmap detector count': manifest.facts.detectors, 'roadmap registry count': manifest.facts.registries, 'roadmap distribution count': manifest.facts.distribution_files_per_provider };
+  for (const assertion of assertions) if (assertion.value !== expected[assertion.label]) failures.push(`${assertion.label} is ${assertion.value}; executable source is ${expected[assertion.label]}`);
+  return { ok: failures.length === 0, failures };
+}
+
+export function verifyManifestIntegrity(manifest) {
+  const failures = [];
+  const check = validateAgainst('release-manifest.schema.json', manifest);
+  if (!check.valid) failures.push(...check.errors);
+  if (manifest.manifest_hash !== manifestHash(manifest)) failures.push('manifest hash is inconsistent');
+  return { ok: failures.length === 0, failures };
+}
+
+export function createDeploymentReceipt(manifest, input) {
+  const surface = manifest.controlled_surfaces.find((item) => item.surface_id === input.surface_id);
+  if (!surface) throw new Error(`unknown controlled surface: ${input.surface_id}`);
+  if (input.url !== surface.url) throw new Error(`receipt URL does not match controlled surface ${surface.surface_id}`);
+  const expected = manifest.projections.find((item) => item.projection_id === surface.projection_id);
+  if (!expected) throw new Error(`manifest projection is missing for surface ${surface.surface_id}`);
+  const collectedAt = input.collected_at || new Date().toISOString();
+  const expiresAt = input.expires_at || new Date(new Date(collectedAt).getTime() + 24 * 60 * 60 * 1000).toISOString();
+  if (!(new Date(expiresAt) > new Date(collectedAt))) throw new Error('receipt expiry must be after collection');
+  const observedProjectionHash = surface.verification_method === 'exact_response_body'
+    ? input.response_hash
+    : input.http.headers?.[surface.verification_header] || null;
+  if (input.observed_projection_hash && input.observed_projection_hash !== observedProjectionHash) {
+    throw new Error('supplied projection hash conflicts with the manifest-declared verification method');
+  }
+  let verificationStatus = 'verified';
+  if (input.http.status < 200 || input.http.status >= 300) verificationStatus = 'failed';
+  else if (!observedProjectionHash) verificationStatus = 'insufficient_evidence';
+  else if (observedProjectionHash !== expected.sha256) verificationStatus = 'contradictory';
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `RECEIPT-${sha256(`${manifest.manifest_hash}:${surface.surface_id}:${collectedAt}`).slice(0, 20).toUpperCase()}`,
+    release_id: manifest.release_id,
+    manifest_hash: manifest.manifest_hash,
+    surface_id: surface.surface_id,
+    url: surface.url,
+    projection_id: expected.projection_id,
+    verification_method: surface.verification_method,
+    verification_header: surface.verification_header,
+    expected_projection_hash: expected.sha256,
+    observed_projection_hash: observedProjectionHash,
+    response_hash: input.response_hash,
+    http: input.http,
+    collector: input.collector,
+    collected_at: collectedAt,
+    expires_at: expiresAt,
+    authority: {
+      source_authority: 'owner_controlled',
+      collection_authority: 'synthetic_probe',
+      authenticity_status: 'checksum_protected_only',
+      representativeness: 'single_observation',
+      limitations: ['Publisher-collected execution evidence; not independent attestation.'],
+    },
+    verification_status: verificationStatus,
+    limitations: [...(input.limitations || []), 'Receipt verifies one publisher-controlled retrieval at one time and region.'],
+  };
+  receipt.receipt_hash = sha256(canonicalJson(receipt));
+  const check = validateAgainst('deployment-receipt.schema.json', receipt);
+  if (!check.valid) throw new Error(`deployment receipt violates contract: ${check.errors.join('; ')}`);
+  return receipt;
+}
+
+export function verifyDeploymentReceipt(manifest, receipt, { at = new Date() } = {}) {
+  const failures = [];
+  const check = validateAgainst('deployment-receipt.schema.json', receipt);
+  if (!check.valid) failures.push(...check.errors);
+  const { receipt_hash: ignored, ...unsigned } = receipt;
+  if (receipt.receipt_hash !== sha256(canonicalJson(unsigned))) failures.push('receipt hash is inconsistent');
+  if (receipt.release_id !== manifest.release_id) failures.push('receipt release differs from manifest');
+  if (receipt.manifest_hash !== manifest.manifest_hash) failures.push('receipt manifest hash differs');
+  const surface = manifest.controlled_surfaces.find((item) => item.surface_id === receipt.surface_id);
+  if (!surface) failures.push('receipt surface is not controlled by the manifest');
+  else {
+    if (receipt.url !== surface.url) failures.push('receipt URL differs from controlled surface');
+    if (receipt.projection_id !== surface.projection_id) failures.push('receipt projection differs from controlled surface');
+    if (receipt.verification_method !== surface.verification_method || receipt.verification_header !== surface.verification_header) failures.push('receipt verification method differs from controlled surface');
+  }
+  const expected = manifest.projections.find((item) => item.projection_id === receipt.projection_id);
+  if (!expected || expected.sha256 !== receipt.expected_projection_hash) failures.push('receipt expected projection is inconsistent');
+  if (receipt.verification_status !== 'verified') failures.push(`receipt status is ${receipt.verification_status}`);
+  if (receipt.authority?.source_authority !== 'owner_controlled' || receipt.authority?.collection_authority !== 'synthetic_probe' || receipt.authority?.representativeness !== 'single_observation') failures.push('receipt authority is not publisher-controlled single-observation execution evidence');
+  if (new Date(receipt.expires_at) <= at) failures.push('receipt is expired');
+  return { ok: failures.length === 0, failures };
+}
+
+function stateHash(value) {
+  const { state_hash: ignored, ...unsigned } = value;
+  return sha256(canonicalJson(unsigned));
+}
+
+function assertState(value) {
+  const check = validateAgainst('release-state.schema.json', value);
+  if (!check.valid) throw new Error(`release state violates contract: ${check.errors.join('; ')}`);
+  if (value.state_hash !== stateHash(value)) throw new Error('release state hash is inconsistent');
+}
+
+export function initializeReleaseState(manifest, { actor, at = new Date().toISOString(), maxDwellHours = 24, policyVersion = 'ADR-002' }) {
+  const integrity = verifyManifestIntegrity(manifest);
+  if (!integrity.ok) throw new Error(`cannot initialize state from invalid manifest: ${integrity.failures.join('; ')}`);
+  const state = {
+    schema_version: 1,
+    release_id: manifest.release_id,
+    manifest_hash: manifest.manifest_hash,
+    state: 'candidate',
+    max_dwell_hours: maxDwellHours,
+    created_at: at,
+    published_at: null,
+    finalized_at: null,
+    resolved_at: null,
+    resolution_reason: null,
+    superseding_release_id: null,
+    receipt_refs: [],
+    transitions: [{ from: null, to: 'candidate', actor, timestamp: at, reason: 'Release candidate created from validated manifest.', policy_version: policyVersion, evidence_refs: [manifest.manifest_hash] }],
+  };
+  state.state_hash = stateHash(state);
+  assertState(state);
+  return state;
+}
+
+export function releaseDwellStatus(state, at = new Date()) {
+  if (state.state !== 'published_unfinalized') return { expired: false, deadline: null };
+  const deadline = new Date(new Date(state.published_at).getTime() + state.max_dwell_hours * 60 * 60 * 1000);
+  return { expired: at >= deadline, deadline: deadline.toISOString() };
+}
+
+export function transitionRelease(state, to, { actor, reason, evidenceRefs = [], receipts = [], manifest, phaseOne, at = new Date().toISOString(), policyVersion = 'ADR-002', supersedingReleaseId = null } = {}) {
+  assertState(state);
+  if (['finalized', 'superseded', 'withdrawn'].includes(state.state)) throw new Error(`release state ${state.state} is terminal`);
+  const allowed = { candidate: ['published_unfinalized'], published_unfinalized: ['finalized', 'superseded', 'withdrawn'] };
+  if (!allowed[state.state]?.includes(to)) throw new Error(`invalid release transition: ${state.state} -> ${to}`);
+  if (!actor || !reason) throw new Error('release transition requires actor and reason');
+  if (state.state === 'candidate' && (!phaseOne?.ok || phaseOne.manifest_hash !== state.manifest_hash)) throw new Error('bound phase-one projection validation is required before publication');
+  const next = structuredClone(state);
+  if (to === 'published_unfinalized') next.published_at = at;
+  if (to === 'finalized') {
+    if (releaseDwellStatus(state, new Date(at)).expired) throw new Error('finalization deadline expired; resolve as withdrawn or superseded');
+    if (!manifest || manifest.manifest_hash !== state.manifest_hash) throw new Error('finalization requires the bound release manifest');
+    const required = manifest.controlled_surfaces.filter((surface) => surface.required_for_finalization);
+    const validReceiptIds = [];
+    for (const surface of required) {
+      const candidates = receipts.filter((receipt) => receipt.surface_id === surface.surface_id);
+      if (candidates.length !== 1) throw new Error(`${surface.surface_id}: exactly one required deployment receipt must be supplied`);
+      const result = verifyDeploymentReceipt(manifest, candidates[0], { at: new Date(at) });
+      if (!result.ok) throw new Error(`${surface.surface_id}: ${result.failures.join('; ')}`);
+      validReceiptIds.push(candidates[0].receipt_id);
+    }
+    next.receipt_refs = validReceiptIds;
+    next.finalized_at = at;
+  }
+  if (to === 'superseded' || to === 'withdrawn') {
+    if (!releaseDwellStatus(state, new Date(at)).expired) throw new Error(`${to} requires the published_unfinalized dwell deadline to expire`);
+    if (to === 'superseded' && !supersedingReleaseId) throw new Error('superseded resolution requires superseding release id');
+    next.resolved_at = at;
+    next.resolution_reason = reason;
+    next.superseding_release_id = supersedingReleaseId;
+  }
+  next.state = to;
+  next.transitions.push({ from: state.state, to, actor, timestamp: at, reason, policy_version: policyVersion, evidence_refs: [...evidenceRefs, ...next.receipt_refs] });
+  next.state_hash = stateHash(next);
+  assertState(next);
+  return next;
+}
+
+export { canonicalJson, manifestHash };

package/src/shared/asOf.js

@@ -0,0 +1,18 @@
+/** Strict, reproducible date parsing for temporal commands. */
+export function parseAsOf(args, fallback = new Date()) {
+  const i = args.indexOf('--as-of');
+  if (i < 0) return fallback;
+  const value = args[i + 1];
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value ?? '')) {
+    throw new Error(`--as-of must be a valid YYYY-MM-DD date, got: ${value ?? ''}`);
+  }
+  const date = new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+    throw new Error(`--as-of must be a valid YYYY-MM-DD date, got: ${value}`);
+  }
+  return date;
+}
+
+export function dateOnly(date) {
+  return date.toISOString().slice(0, 10);
+}