sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/runtime-projection-p0.ts

@@ -1,292 +1,314 @@
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-
-import type { RuntimeProjectionEnvelope, RuntimeProjectionStaleness, RuntimeRef } from './contracts.js';
-import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
-import { hashDocumentContent } from './sdd-docs/document-hashes.js';
-import { listRuntimeProjections, readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, type RuntimeProjectionEnvelopeWriteResult } from './storage/runtime-store.js';
-import {
-  NEXT_INTENT_PROJECTION_TYPE,
-  TASK_ORCHESTRATION_PROJECTION_TYPE,
-  VALIDATION_UNIT_PROJECTION_TYPE,
-  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE
-} from './workflow-state/runtime-projections.js';
-
-export const RUNTIME_PROJECTION_P0_CONTRACT_VERSION = 'phase9.19-runtime-sqlite-contract-projection-p0-v1' as const;
-export const RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE = 'phase9_19_ref_hash_registry';
-export const RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION = 'phase9.19-ref-hash-registry-v1';
-export const STAGE_ROUTE_BINDING_PROJECTION_TYPE = 'phase9_18_stage_route_binding';
-export const STAGE_ROUTE_BINDING_PRODUCER_VERSION = 'phase9.18-stage-route-binding-v1';
-export const TRUTH_RECONCILIATION_PROJECTION_TYPE = 'phase9_21_truth_reconciliation';
-
-export type RuntimeProjectionP0Key =
-  | 'lifecycleDecisions'
-  | 'riskSignals'
-  | 'stageRuns'
-  | 'stageHandoffs'
-  | 'gates'
-  | 'gapBlockers'
-  | 'evidenceItems'
-  | 'evidenceSets'
-  | 'selectionPointers'
-  | 'workflowCurrentState'
-  | 'taskOrchestration'
-  | 'validationUnits'
-  | 'truthAlignment'
-  | 'truthReconciliation'
-  | 'stageRouteBindings'
-  | 'nextIntent'
-  | 'auditEvents';
-
-export type RuntimeProjectionP0Storage = 'sqlite' | 'sqlite-ref-hash-only' | 'sqlite-projection';
-export type RuntimeProjectionP0HealthStatus = 'pass' | 'warn' | 'blocked';
-export type RuntimeRefFreshnessStatus = 'fresh' | 'stale' | 'missing' | 'unhashed' | 'unsafe' | 'not_file_backed';
-
-export interface RuntimeProjectionP0InventoryItem {
-  key: RuntimeProjectionP0Key;
-  storage: RuntimeProjectionP0Storage;
-  primitive: string;
-  writer: 'runtime';
-  responsibility: string;
-  consumers: string[];
-  markdownBodyAuthority: false;
-}
-
-export interface RuntimeRefFreshness {
-  ref: RuntimeRef;
-  normalizedRef: string;
-  expectedHash: string | null;
-  currentHash: string | null;
-  status: RuntimeRefFreshnessStatus;
-  reason: string;
-}
-
-export interface RuntimeRefHashRegistryProjection {
-  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
-  branch: string;
-  refs: RuntimeRefFreshness[];
-  status: 'fresh' | 'blocked';
-  staleRefs: RuntimeRef[];
-  reasons: string[];
-}
-
-export interface RuntimeProjectionP0Diagnostic {
-  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
-  branch: string;
-  status: RuntimeProjectionP0HealthStatus;
-  inventory: RuntimeProjectionP0InventoryItem[];
-  projectionCounts: Record<string, number>;
-  refHashRegistry: {
-    projectionType: typeof RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE;
-    envelopeStaleness: RuntimeProjectionStaleness;
-    status: RuntimeRefHashRegistryProjection['status'] | 'missing';
-    staleRefs: RuntimeRef[];
-    reasons: string[];
-  };
-  reasons: string[];
-}
-
-export const RUNTIME_PROJECTION_P0_INVENTORY: readonly RuntimeProjectionP0InventoryItem[] = [
-  inventoryItem('lifecycleDecisions', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Lifecycle/risk authority created only by /sdd or /sdd:spec.', ['router', 'stage-close', 'status', 'doctor']),
-  inventoryItem('riskSignals', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Risk signal snapshot and lifecycle policy output for routing and gates.', ['router', 'workflow-gate', 'status']),
-  inventoryItem('stageRuns', 'sqlite', 'projections:phase8_stage_run', 'Runtime-owned stage run state and terminal health.', ['status', 'stage-close', 'ship']),
-  inventoryItem('stageHandoffs', 'sqlite', 'projections:phase8_workflow_handoff', 'Runtime handoff packet between completed stages and next runtime stage.', ['status', 'stage-close']),
-  inventoryItem('gates', 'sqlite', 'workflow_gate_decisions', 'Hard gate decisions and policy outcomes.', ['workflow-gate', 'status', 'ship']),
-  inventoryItem('gapBlockers', 'sqlite', 'durable_gaps', 'Mutable gap/blocker lifecycle with runtime status authority.', ['doctor', 'status', 'stage-close']),
-  inventoryItem('evidenceItems', 'sqlite-ref-hash-only', 'stage_artifacts/artifact_payloads', 'Agent-authored Markdown evidence registered by ref, hash, contract, producer, and status.', ['workflow-gate', 'stage-close', 'doctor']),
-  inventoryItem('evidenceSets', 'sqlite-ref-hash-only', 'evidence_sets/evidence_set_items', 'Accepted evidence sets selected by refs and digests, not Markdown bodies.', ['workflow-gate', 'ship', 'status']),
-  inventoryItem('selectionPointers', 'sqlite', 'selection_pointers', 'Active accepted evidence pointer for downstream consumers.', ['workflow-gate', 'latest-eligible-run', 'ship']),
-  inventoryItem('workflowCurrentState', 'sqlite-projection', `projections:${WORKFLOW_CURRENT_STATE_PROJECTION_TYPE}`, 'Runtime-owned lifecycle, task, and validation-unit current state projection.', ['status', 'router', 'ai-tool-entry']),
-  inventoryItem('taskOrchestration', 'sqlite-projection', `projections:${TASK_ORCHESTRATION_PROJECTION_TYPE}`, 'Parsed task orchestration read model with task-level hashes, dependencies, validation unit binding, and capability signals.', ['status', 'do-manager', 'tasks-manager']),
-  inventoryItem('validationUnits', 'sqlite-projection', `projections:${VALIDATION_UNIT_PROJECTION_TYPE}`, 'Runtime validation-unit read model derived from verify contracts and task orchestration.', ['status', 'test-manager', 'workflow-gate']),
-  inventoryItem('truthAlignment', 'sqlite', 'projections:phase9_12_truth_alignment', 'Goal-verify truth alignment projection for ship readiness.', ['ship', 'status']),
-  inventoryItem('truthReconciliation', 'sqlite', `projections:${TRUTH_RECONCILIATION_PROJECTION_TYPE}`, 'Owner-stage reconciliation decision slot for minimal rerun frontier.', ['orchestrator', 'status', 'ship']),
-  inventoryItem('stageRouteBindings', 'sqlite', `projections:${STAGE_ROUTE_BINDING_PROJECTION_TYPE}`, 'Stage-local command input binding to an accepted runtime target.', ['router', 'status']),
-  inventoryItem('nextIntent', 'sqlite-projection', `projections:${NEXT_INTENT_PROJECTION_TYPE}`, 'Advisory runtime next-action read model; execution still checks readiness and gates.', ['status', 'ai-tool-entry']),
-  inventoryItem('auditEvents', 'sqlite', 'events/activities', 'Append-only runtime events and activity records for auditability.', ['doctor', 'run-inspect'])
-];
-
-export const RUNTIME_PROJECTION_P0_PROJECTION_TYPES = [
-  'phase8_lifecycle_risk_decision',
-  'phase8_stage_run',
-  'phase8_workflow_handoff',
-  'phase9_12_truth_alignment',
-  TRUTH_RECONCILIATION_PROJECTION_TYPE,
-  STAGE_ROUTE_BINDING_PROJECTION_TYPE,
-  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE,
-  TASK_ORCHESTRATION_PROJECTION_TYPE,
-  VALIDATION_UNIT_PROJECTION_TYPE,
-  NEXT_INTENT_PROJECTION_TYPE,
-  RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE
-] as const;
-
-export async function inspectRuntimeProjectionP0(projectRoot: string, branch: string): Promise<RuntimeProjectionP0Diagnostic> {
-  const partition = branchToSafePartition(branch);
-  const projections = await listRuntimeProjections(projectRoot, [...RUNTIME_PROJECTION_P0_PROJECTION_TYPES]);
-  const projectionCounts = Object.fromEntries(RUNTIME_PROJECTION_P0_PROJECTION_TYPES.map((projectionType) => [projectionType, projections.filter((projection) => projection.projectionType === projectionType).length]));
-  const envelope = await readRuntimeRefHashRegistryProjection(projectRoot, partition);
-  const refHashRegistry = await inspectRefHashRegistry(projectRoot, partition, envelope);
-  const status: RuntimeProjectionP0HealthStatus = refHashRegistry.status === 'blocked' ? 'blocked' : envelope ? 'pass' : 'warn';
-  const reasons = runtimeProjectionP0Reasons(status, refHashRegistry.reasons);
-  return {
-    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
-    branch: partition,
-    status,
-    inventory: [...RUNTIME_PROJECTION_P0_INVENTORY],
-    projectionCounts,
-    refHashRegistry,
-    reasons
-  };
-}
-
-export async function recordRuntimeRefHashRegistryProjection(projectRoot: string, input: { branch: string; refs: RuntimeRef[]; generatedAt?: string }): Promise<RuntimeProjectionEnvelopeWriteResult<RuntimeRefHashRegistryProjection>> {
-  const branch = branchToSafePartition(input.branch);
-  const refs = await inspectRuntimeRefFreshness(projectRoot, input.refs);
-  const staleRefs = refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
-  const projection: RuntimeRefHashRegistryProjection = {
-    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
-    branch,
-    refs,
-    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
-    staleRefs,
-    reasons: refHashRegistryReasons(staleRefs, refs)
-  };
-  return recordRuntimeProjectionEnvelope(projectRoot, {
-    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
-    scopeKey: runtimeRefHashRegistryScopeKey(branch),
-    inputHash: runtimeProjectionStableHash(projection),
-    producer: 'phase9.19-runtime-projection-p0',
-    producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION,
-    generatedAt: input.generatedAt,
-    payload: projection
-  });
-}
-
-export async function readRuntimeRefHashRegistryProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null> {
-  return readRuntimeProjectionEnvelope(projectRoot, RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE, runtimeRefHashRegistryScopeKey(branchToSafePartition(branch)));
-}
-
-export async function inspectRuntimeRefFreshness(projectRoot: string, refs: RuntimeRef[]): Promise<RuntimeRefFreshness[]> {
-  return Promise.all(refs.map((ref) => inspectRuntimeRef(projectRoot, ref)));
-}
-
-export function runtimeRefHashRegistryScopeKey(branch: string): string {
-  return [branchToSafePartition(branch), 'ref-hash-registry'].join(':');
-}
-
-export function runtimeProjectionStableHash(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
-}
-
-async function inspectRefHashRegistry(projectRoot: string, branch: string, envelope: RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null): Promise<RuntimeProjectionP0Diagnostic['refHashRegistry']> {
-  if (!envelope) {
-    return {
-      projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
-      envelopeStaleness: 'unknown',
-      status: 'missing',
-      staleRefs: [],
-      reasons: ['Runtime ref/hash registry projection is missing; register accepted Markdown refs before relying on freshness diagnostics.']
-    };
-  }
-  const currentRefs = await inspectRuntimeRefFreshness(projectRoot, envelope.payload.refs.map((entry) => entry.ref));
-  const staleRefs = currentRefs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
-  const currentProjection: RuntimeRefHashRegistryProjection = {
-    ...envelope.payload,
-    refs: currentRefs,
-    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
-    staleRefs,
-    reasons: refHashRegistryReasons(staleRefs, currentRefs)
-  };
-  return {
-    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
-    envelopeStaleness: runtimeProjectionStaleness(envelope, {
-      inputHash: runtimeProjectionStableHash(currentProjection),
-      producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION
-    }),
-    status: currentProjection.status,
-    staleRefs,
-    reasons: currentProjection.reasons
-  };
-}
-
-async function inspectRuntimeRef(projectRoot: string, ref: RuntimeRef): Promise<RuntimeRefFreshness> {
-  const normalizedRef = normalizePortablePath(ref.ref);
-  if (!isFileBackedRef(ref)) {
-    return freshness(ref, normalizedRef, null, null, 'not_file_backed', `Runtime ref kind ${ref.kind} is not file-backed.`);
-  }
-  if (!ref.hash) {
-    return freshness(ref, normalizedRef, null, null, 'unhashed', `File-backed ref ${ref.ref} has no expected hash.`);
-  }
-  const safePath = safeProjectRelativePath(projectRoot, normalizedRef);
-  if (!safePath) {
-    return freshness(ref, normalizedRef, ref.hash, null, 'unsafe', `File-backed ref ${ref.ref} is not a safe project-relative path.`);
-  }
-  try {
-    const currentHash = hashDocumentContent(await readFile(safePath, 'utf8'));
-    return hashMatches(ref.hash, currentHash)
-      ? freshness(ref, normalizedRef, ref.hash, currentHash, 'fresh', `File-backed ref ${normalizedRef} is fresh.`)
-      : freshness(ref, normalizedRef, ref.hash, currentHash, 'stale', `File-backed ref ${normalizedRef} hash is stale: expected ${ref.hash}, actual ${currentHash}.`);
-  } catch (error) {
-    if (isMissingFileError(error)) {
-      return freshness(ref, normalizedRef, ref.hash, null, 'missing', `File-backed ref ${normalizedRef} is missing.`);
-    }
-    throw error;
-  }
-}
-
-function inventoryItem(key: RuntimeProjectionP0Key, storage: RuntimeProjectionP0Storage, primitive: string, responsibility: string, consumers: string[]): RuntimeProjectionP0InventoryItem {
-  return { key, storage, primitive, writer: 'runtime', responsibility, consumers, markdownBodyAuthority: false };
-}
-
-function runtimeProjectionP0Reasons(status: RuntimeProjectionP0HealthStatus, refHashReasons: string[]): string[] {
-  if (status === 'blocked') {
-    return refHashReasons;
-  }
-  if (status === 'warn') {
-    return ['Runtime projection P0 inventory is available; ref/hash freshness registry has not been recorded yet.'];
-  }
-  return ['Runtime projection P0 inventory is available and registered file-backed refs are fresh.'];
-}
-
-function refHashRegistryReasons(staleRefs: RuntimeRef[], refs: RuntimeRefFreshness[]): string[] {
-  if (staleRefs.length === 0) {
-    return ['Registered file-backed refs are fresh; non-file-backed refs remain metadata-only.'];
-  }
-  return refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.reason);
-}
-
-function blocksRefHashRegistry(status: RuntimeRefFreshnessStatus): boolean {
-  return status === 'stale' || status === 'missing' || status === 'unhashed' || status === 'unsafe';
-}
-
-function isFileBackedRef(ref: RuntimeRef): boolean {
-  if (ref.kind === 'document' || ref.kind === 'artifact' || ref.kind === 'evidence') {
-    return true;
-  }
-  return /^(specs|runs)\//.test(normalizePortablePath(ref.ref));
-}
-
-function safeProjectRelativePath(projectRoot: string, normalizedRef: string): string | null {
-  if (path.isAbsolute(normalizedRef) || normalizedRef.startsWith('../') || normalizedRef === '..') {
-    return null;
-  }
-  const projectPath = path.resolve(projectRoot);
-  const absolutePath = path.resolve(projectPath, normalizedRef);
-  return absolutePath === projectPath || absolutePath.startsWith(`${projectPath}${path.sep}`) ? absolutePath : null;
-}
-
-function freshness(ref: RuntimeRef, normalizedRef: string, expectedHash: string | null, currentHash: string | null, status: RuntimeRefFreshnessStatus, reason: string): RuntimeRefFreshness {
-  return { ref: { ...ref, ref: normalizedRef }, normalizedRef, expectedHash, currentHash, status, reason };
-}
-
-function hashMatches(expected: string, actual: string): boolean {
-  return expected.replace(/^sha256:/, '') === actual.replace(/^sha256:/, '');
-}
-
-function isMissingFileError(error: unknown): boolean {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  return 'code' in error && (error as { code?: unknown }).code === 'ENOENT';
-}
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { RuntimeProjectionEnvelope, RuntimeProjectionStaleness, RuntimeRef } from './contracts.js';
+import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import { hashDocumentContent } from './sdd-docs/document-hashes.js';
+import { listRuntimeProjections, readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, type RuntimeProjectionEnvelopeWriteResult } from './storage/runtime-store.js';
+import {
+  NEXT_INTENT_PROJECTION_TYPE,
+  TASK_ORCHESTRATION_PROJECTION_TYPE,
+  VALIDATION_UNIT_PROJECTION_TYPE,
+  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE
+} from './workflow-state/runtime-projections.js';
+import {
+  DIAGNOSTIC_PROJECTION_TYPE,
+  EVIDENCE_SELECTION_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+  LIFECYCLE_ROUTE_PROJECTION_TYPE,
+  STAGE_WORK_ORDER_PROJECTION_TYPE
+} from './lifecycle-graph.js';
+
+export const RUNTIME_PROJECTION_P0_CONTRACT_VERSION = 'phase9.19-runtime-sqlite-contract-projection-p0-v1' as const;
+export const RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE = 'phase9_19_ref_hash_registry';
+export const RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION = 'phase9.19-ref-hash-registry-v1';
+export const STAGE_ROUTE_BINDING_PROJECTION_TYPE = 'phase9_18_stage_route_binding';
+export const STAGE_ROUTE_BINDING_PRODUCER_VERSION = 'phase9.18-stage-route-binding-v1';
+export const TRUTH_RECONCILIATION_PROJECTION_TYPE = 'phase9_21_truth_reconciliation';
+
+export type RuntimeProjectionP0Key =
+  | 'lifecycleDecisions'
+  | 'riskSignals'
+  | 'stageRuns'
+  | 'stageHandoffs'
+  | 'gates'
+  | 'gapBlockers'
+  | 'evidenceItems'
+  | 'evidenceSets'
+  | 'selectionPointers'
+  | 'workflowCurrentState'
+  | 'taskOrchestration'
+  | 'validationUnits'
+  | 'truthAlignment'
+  | 'truthReconciliation'
+  | 'stageRouteBindings'
+  | 'nextIntent'
+  | 'lifecycleGraphInstances'
+  | 'lifecycleRoutes'
+  | 'stageWorkOrders'
+  | 'evidenceSelections'
+  | 'diagnosticProjections'
+  | 'auditEvents';
+
+export type RuntimeProjectionP0Storage = 'sqlite' | 'sqlite-ref-hash-only' | 'sqlite-projection';
+export type RuntimeProjectionP0HealthStatus = 'pass' | 'warn' | 'blocked';
+export type RuntimeRefFreshnessStatus = 'fresh' | 'stale' | 'missing' | 'unhashed' | 'unsafe' | 'not_file_backed';
+
+export interface RuntimeProjectionP0InventoryItem {
+  key: RuntimeProjectionP0Key;
+  storage: RuntimeProjectionP0Storage;
+  primitive: string;
+  writer: 'runtime';
+  responsibility: string;
+  consumers: string[];
+  markdownBodyAuthority: false;
+}
+
+export interface RuntimeRefFreshness {
+  ref: RuntimeRef;
+  normalizedRef: string;
+  expectedHash: string | null;
+  currentHash: string | null;
+  status: RuntimeRefFreshnessStatus;
+  reason: string;
+}
+
+export interface RuntimeRefHashRegistryProjection {
+  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
+  branch: string;
+  refs: RuntimeRefFreshness[];
+  status: 'fresh' | 'blocked';
+  staleRefs: RuntimeRef[];
+  reasons: string[];
+}
+
+export interface RuntimeProjectionP0Diagnostic {
+  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
+  branch: string;
+  status: RuntimeProjectionP0HealthStatus;
+  inventory: RuntimeProjectionP0InventoryItem[];
+  projectionCounts: Record<string, number>;
+  refHashRegistry: {
+    projectionType: typeof RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE;
+    envelopeStaleness: RuntimeProjectionStaleness;
+    status: RuntimeRefHashRegistryProjection['status'] | 'missing';
+    staleRefs: RuntimeRef[];
+    reasons: string[];
+  };
+  reasons: string[];
+}
+
+export const RUNTIME_PROJECTION_P0_INVENTORY: readonly RuntimeProjectionP0InventoryItem[] = [
+  inventoryItem('lifecycleDecisions', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Lifecycle/risk authority created only by /sdd or /sdd:spec.', ['router', 'stage-close', 'status', 'doctor']),
+  inventoryItem('riskSignals', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Risk signal snapshot and lifecycle policy output for routing and gates.', ['router', 'workflow-gate', 'status']),
+  inventoryItem('stageRuns', 'sqlite', 'projections:phase8_stage_run', 'Runtime-owned stage run state and terminal health.', ['status', 'stage-close', 'ship']),
+  inventoryItem('stageHandoffs', 'sqlite', 'projections:phase8_workflow_handoff', 'Runtime handoff packet between completed stages and next runtime stage.', ['status', 'stage-close']),
+  inventoryItem('gates', 'sqlite', 'workflow_gate_decisions', 'Hard gate decisions and policy outcomes.', ['workflow-gate', 'status', 'ship']),
+  inventoryItem('gapBlockers', 'sqlite', 'durable_gaps', 'Mutable gap/blocker lifecycle with runtime status authority.', ['doctor', 'status', 'stage-close']),
+  inventoryItem('evidenceItems', 'sqlite-ref-hash-only', 'stage_artifacts/artifact_payloads', 'Agent-authored Markdown evidence registered by ref, hash, contract, producer, and status.', ['workflow-gate', 'stage-close', 'doctor']),
+  inventoryItem('evidenceSets', 'sqlite-ref-hash-only', 'evidence_sets/evidence_set_items', 'Accepted evidence sets selected by refs and digests, not Markdown bodies.', ['workflow-gate', 'ship', 'status']),
+  inventoryItem('selectionPointers', 'sqlite', 'selection_pointers', 'Active accepted evidence pointer for downstream consumers.', ['workflow-gate', 'latest-eligible-run', 'ship']),
+  inventoryItem('workflowCurrentState', 'sqlite-projection', `projections:${WORKFLOW_CURRENT_STATE_PROJECTION_TYPE}`, 'Runtime-owned lifecycle, task, and validation-unit current state projection.', ['status', 'router', 'ai-tool-entry']),
+  inventoryItem('taskOrchestration', 'sqlite-projection', `projections:${TASK_ORCHESTRATION_PROJECTION_TYPE}`, 'Parsed task orchestration read model with task-level hashes, dependencies, validation unit binding, and capability signals.', ['status', 'do-manager', 'tasks-manager']),
+  inventoryItem('validationUnits', 'sqlite-projection', `projections:${VALIDATION_UNIT_PROJECTION_TYPE}`, 'Runtime validation-unit read model derived from verify contracts and task orchestration.', ['status', 'test-manager', 'workflow-gate']),
+  inventoryItem('truthAlignment', 'sqlite', 'projections:phase9_12_truth_alignment', 'Goal-verify truth alignment projection for ship readiness.', ['ship', 'status']),
+  inventoryItem('truthReconciliation', 'sqlite', `projections:${TRUTH_RECONCILIATION_PROJECTION_TYPE}`, 'Owner-stage reconciliation decision slot for minimal rerun frontier.', ['orchestrator', 'status', 'ship']),
+  inventoryItem('stageRouteBindings', 'sqlite', `projections:${STAGE_ROUTE_BINDING_PROJECTION_TYPE}`, 'Stage-local command input binding to an accepted runtime target.', ['router', 'status']),
+  inventoryItem('nextIntent', 'sqlite-projection', `projections:${NEXT_INTENT_PROJECTION_TYPE}`, 'Advisory runtime next-action read model; execution still checks readiness and gates.', ['status', 'ai-tool-entry']),
+  inventoryItem('lifecycleGraphInstances', 'sqlite-projection', `projections:${LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE}`, 'Runtime-owned lifecycle graph instance derived from active lifecycle risk authority.', ['status', 'instructions', 'doctor', 'router', 'stage-close']),
+  inventoryItem('lifecycleRoutes', 'sqlite-projection', `projections:${LIFECYCLE_ROUTE_PROJECTION_TYPE}`, 'Graph-owned legal next action and blocker route projection.', ['status', 'instructions', 'doctor', 'router']),
+  inventoryItem('stageWorkOrders', 'sqlite-projection', `projections:${STAGE_WORK_ORDER_PROJECTION_TYPE}`, 'Stage-local work order schemas, required refs, and closure commands.', ['instructions', 'stage-close', 'do-manager', 'test-manager']),
+  inventoryItem('evidenceSelections', 'sqlite-projection', `projections:${EVIDENCE_SELECTION_PROJECTION_TYPE}`, 'Runtime-selected evidence obligations and selected accepted refs.', ['status', 'stage-close', 'workflow-gate', 'doctor']),
+  inventoryItem('diagnosticProjections', 'sqlite-projection', `projections:${DIAGNOSTIC_PROJECTION_TYPE}`, 'Blocker-specific diagnostics and recovery commands for lifecycle graph consumers.', ['doctor', 'status', 'instructions', 'router']),
+  inventoryItem('auditEvents', 'sqlite', 'events/activities', 'Append-only runtime events and activity records for auditability.', ['doctor', 'run-inspect'])
+];
+
+export const RUNTIME_PROJECTION_P0_PROJECTION_TYPES = [
+  'phase8_lifecycle_risk_decision',
+  'phase8_stage_run',
+  'phase8_workflow_handoff',
+  'phase9_12_truth_alignment',
+  TRUTH_RECONCILIATION_PROJECTION_TYPE,
+  STAGE_ROUTE_BINDING_PROJECTION_TYPE,
+  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE,
+  TASK_ORCHESTRATION_PROJECTION_TYPE,
+  VALIDATION_UNIT_PROJECTION_TYPE,
+  NEXT_INTENT_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+  LIFECYCLE_ROUTE_PROJECTION_TYPE,
+  STAGE_WORK_ORDER_PROJECTION_TYPE,
+  EVIDENCE_SELECTION_PROJECTION_TYPE,
+  DIAGNOSTIC_PROJECTION_TYPE,
+  RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE
+] as const;
+
+export async function inspectRuntimeProjectionP0(projectRoot: string, branch: string): Promise<RuntimeProjectionP0Diagnostic> {
+  const partition = branchToSafePartition(branch);
+  const projections = await listRuntimeProjections(projectRoot, [...RUNTIME_PROJECTION_P0_PROJECTION_TYPES]);
+  const projectionCounts = Object.fromEntries(RUNTIME_PROJECTION_P0_PROJECTION_TYPES.map((projectionType) => [projectionType, projections.filter((projection) => projection.projectionType === projectionType).length]));
+  const envelope = await readRuntimeRefHashRegistryProjection(projectRoot, partition);
+  const refHashRegistry = await inspectRefHashRegistry(projectRoot, partition, envelope);
+  const status: RuntimeProjectionP0HealthStatus = refHashRegistry.status === 'blocked' ? 'blocked' : envelope ? 'pass' : 'warn';
+  const reasons = runtimeProjectionP0Reasons(status, refHashRegistry.reasons);
+  return {
+    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
+    branch: partition,
+    status,
+    inventory: [...RUNTIME_PROJECTION_P0_INVENTORY],
+    projectionCounts,
+    refHashRegistry,
+    reasons
+  };
+}
+
+export async function recordRuntimeRefHashRegistryProjection(projectRoot: string, input: { branch: string; refs: RuntimeRef[]; generatedAt?: string }): Promise<RuntimeProjectionEnvelopeWriteResult<RuntimeRefHashRegistryProjection>> {
+  const branch = branchToSafePartition(input.branch);
+  const refs = await inspectRuntimeRefFreshness(projectRoot, input.refs);
+  const staleRefs = refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
+  const projection: RuntimeRefHashRegistryProjection = {
+    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
+    branch,
+    refs,
+    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
+    staleRefs,
+    reasons: refHashRegistryReasons(staleRefs, refs)
+  };
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+    scopeKey: runtimeRefHashRegistryScopeKey(branch),
+    inputHash: runtimeProjectionStableHash(projection),
+    producer: 'phase9.19-runtime-projection-p0',
+    producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION,
+    generatedAt: input.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readRuntimeRefHashRegistryProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE, runtimeRefHashRegistryScopeKey(branchToSafePartition(branch)));
+}
+
+export async function inspectRuntimeRefFreshness(projectRoot: string, refs: RuntimeRef[]): Promise<RuntimeRefFreshness[]> {
+  return Promise.all(refs.map((ref) => inspectRuntimeRef(projectRoot, ref)));
+}
+
+export function runtimeRefHashRegistryScopeKey(branch: string): string {
+  return [branchToSafePartition(branch), 'ref-hash-registry'].join(':');
+}
+
+export function runtimeProjectionStableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+async function inspectRefHashRegistry(projectRoot: string, branch: string, envelope: RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null): Promise<RuntimeProjectionP0Diagnostic['refHashRegistry']> {
+  if (!envelope) {
+    return {
+      projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+      envelopeStaleness: 'unknown',
+      status: 'missing',
+      staleRefs: [],
+      reasons: ['Runtime ref/hash registry projection is missing; register accepted Markdown refs before relying on freshness diagnostics.']
+    };
+  }
+  const currentRefs = await inspectRuntimeRefFreshness(projectRoot, envelope.payload.refs.map((entry) => entry.ref));
+  const staleRefs = currentRefs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
+  const currentProjection: RuntimeRefHashRegistryProjection = {
+    ...envelope.payload,
+    refs: currentRefs,
+    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
+    staleRefs,
+    reasons: refHashRegistryReasons(staleRefs, currentRefs)
+  };
+  return {
+    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+    envelopeStaleness: runtimeProjectionStaleness(envelope, {
+      inputHash: runtimeProjectionStableHash(currentProjection),
+      producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION
+    }),
+    status: currentProjection.status,
+    staleRefs,
+    reasons: currentProjection.reasons
+  };
+}
+
+async function inspectRuntimeRef(projectRoot: string, ref: RuntimeRef): Promise<RuntimeRefFreshness> {
+  const normalizedRef = normalizePortablePath(ref.ref);
+  if (!isFileBackedRef(ref)) {
+    return freshness(ref, normalizedRef, null, null, 'not_file_backed', `Runtime ref kind ${ref.kind} is not file-backed.`);
+  }
+  if (!ref.hash) {
+    return freshness(ref, normalizedRef, null, null, 'unhashed', `File-backed ref ${ref.ref} has no expected hash.`);
+  }
+  const safePath = safeProjectRelativePath(projectRoot, normalizedRef);
+  if (!safePath) {
+    return freshness(ref, normalizedRef, ref.hash, null, 'unsafe', `File-backed ref ${ref.ref} is not a safe project-relative path.`);
+  }
+  try {
+    const currentHash = hashDocumentContent(await readFile(safePath, 'utf8'));
+    return hashMatches(ref.hash, currentHash)
+      ? freshness(ref, normalizedRef, ref.hash, currentHash, 'fresh', `File-backed ref ${normalizedRef} is fresh.`)
+      : freshness(ref, normalizedRef, ref.hash, currentHash, 'stale', `File-backed ref ${normalizedRef} hash is stale: expected ${ref.hash}, actual ${currentHash}.`);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return freshness(ref, normalizedRef, ref.hash, null, 'missing', `File-backed ref ${normalizedRef} is missing.`);
+    }
+    throw error;
+  }
+}
+
+function inventoryItem(key: RuntimeProjectionP0Key, storage: RuntimeProjectionP0Storage, primitive: string, responsibility: string, consumers: string[]): RuntimeProjectionP0InventoryItem {
+  return { key, storage, primitive, writer: 'runtime', responsibility, consumers, markdownBodyAuthority: false };
+}
+
+function runtimeProjectionP0Reasons(status: RuntimeProjectionP0HealthStatus, refHashReasons: string[]): string[] {
+  if (status === 'blocked') {
+    return refHashReasons;
+  }
+  if (status === 'warn') {
+    return ['Runtime projection P0 inventory is available; ref/hash freshness registry has not been recorded yet.'];
+  }
+  return ['Runtime projection P0 inventory is available and registered file-backed refs are fresh.'];
+}
+
+function refHashRegistryReasons(staleRefs: RuntimeRef[], refs: RuntimeRefFreshness[]): string[] {
+  if (staleRefs.length === 0) {
+    return ['Registered file-backed refs are fresh; non-file-backed refs remain metadata-only.'];
+  }
+  return refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.reason);
+}
+
+function blocksRefHashRegistry(status: RuntimeRefFreshnessStatus): boolean {
+  return status === 'stale' || status === 'missing' || status === 'unhashed' || status === 'unsafe';
+}
+
+function isFileBackedRef(ref: RuntimeRef): boolean {
+  if (ref.kind === 'document' || ref.kind === 'artifact' || ref.kind === 'evidence') {
+    return true;
+  }
+  return /^(specs|runs)\//.test(normalizePortablePath(ref.ref));
+}
+
+function safeProjectRelativePath(projectRoot: string, normalizedRef: string): string | null {
+  if (path.isAbsolute(normalizedRef) || normalizedRef.startsWith('../') || normalizedRef === '..') {
+    return null;
+  }
+  const projectPath = path.resolve(projectRoot);
+  const absolutePath = path.resolve(projectPath, normalizedRef);
+  return absolutePath === projectPath || absolutePath.startsWith(`${projectPath}${path.sep}`) ? absolutePath : null;
+}
+
+function freshness(ref: RuntimeRef, normalizedRef: string, expectedHash: string | null, currentHash: string | null, status: RuntimeRefFreshnessStatus, reason: string): RuntimeRefFreshness {
+  return { ref: { ...ref, ref: normalizedRef }, normalizedRef, expectedHash, currentHash, status, reason };
+}
+
+function hashMatches(expected: string, actual: string): boolean {
+  return expected.replace(/^sha256:/, '') === actual.replace(/^sha256:/, '');
+}
+
+function isMissingFileError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  return 'code' in error && (error as { code?: unknown }).code === 'ENOENT';
+}