@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/parity/surfaces.ts

@@ -0,0 +1,748 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  buildHarnessInventoryReportFile,
+  validateHarnessPruneReceiptFile,
+  type HarnessDisposition,
+} from '../harness/pruning';
+import { assertSharedMemoryScopeId, assertSharedMemoryText, detectMemoryRiskFlags } from '../memory/sanitize';
+import { buildAgentOwnerCardProjection, type AgentOwnerCardProjection } from '../seat/owner-card';
+
+type JsonRecord = Record<string, unknown>;
+
+const RUNTIME_PROFILE_TIERS = ['local', 'remote', 'self_hosted'] as const;
+const PERIMETER_MODES = ['local_process', 'self_hosted_sandbox', 'managed_sandbox'] as const;
+
+export type RuntimeProfileTier = typeof RUNTIME_PROFILE_TIERS[number];
+export type RuntimePerimeterMode = typeof PERIMETER_MODES[number];
+
+export interface ModelFingerprint {
+  seat?: string;
+  model_id?: string;
+  model_tier?: string;
+  adapter_backend?: string;
+  execution_surface?: string;
+  runtime_tier?: string;
+}
+
+export interface ModelDriftReceipt {
+  schema: 'model-drift-receipt.v0';
+  receipt_id: string;
+  created_at: string;
+  previous_ref: string;
+  current_ref: string;
+  previous: ModelFingerprint;
+  current: ModelFingerprint;
+  drift_detected: boolean;
+  invalidates_social_calibration: boolean;
+  drift: Array<{ field: keyof ModelFingerprint; previous: string | null; current: string | null }>;
+  authority_boundary: {
+    can_authorize: false;
+    can_attach_grant: false;
+    mutates_roster: false;
+  };
+}
+
+export interface RuntimeProfile {
+  schema: 'runtime-profile.v0';
+  profile_id: string;
+  runtime_tier: RuntimeProfileTier;
+  perimeter_mode: RuntimePerimeterMode;
+  adapter_backend: string;
+  target_ref: string;
+  supports_verifier: boolean;
+  network_egress?: {
+    allowlist: boolean;
+    allowed_hosts: string[];
+  };
+  authority_boundary: {
+    can_execute_verifier: boolean;
+    can_write: false;
+    can_merge: false;
+    can_close: false;
+    can_grant: false;
+    mutates_canonical_truth: false;
+  };
+}
+
+export interface RuntimeProfileValidation {
+  schema: 'runtime-profile-validation.v0';
+  profile_id: string;
+  validated_at: string;
+  verdict: 'accepted';
+  runtime_tier: RuntimeProfileTier;
+  perimeter_mode: RuntimePerimeterMode;
+  adapter_backend: string;
+  supported_modes: ['verifier'];
+  authority_boundary: RuntimeProfile['authority_boundary'];
+}
+
+export interface VaultReferenceReceipt {
+  schema: 'vault-reference-receipt.v0';
+  receipt_id: string;
+  created_at: string;
+  provider: string;
+  vault_ref: string;
+  purpose: string;
+  requested_by: string;
+  raw_secret_stored: false;
+  content_boundary: {
+    stores_secret_value: false;
+    stores_provider_token: false;
+    stores_raw_identity_document: false;
+  };
+  authority_boundary: {
+    can_read_secret: false;
+    can_inject_secret: false;
+    can_grant_secret_access: false;
+  };
+}
+
+export interface SchedulerWakeProposal {
+  schema: 'scheduler-wake-proposal.v0';
+  proposal_id: string;
+  created_at: string;
+  created_by: string;
+  task_ref: string;
+  wake_at: string;
+  reason: string;
+  status: 'proposed';
+  authority_boundary: {
+    scheduler_can_authorize: false;
+    scheduler_can_merge: false;
+    scheduler_can_grant: false;
+    scheduler_can_execute: false;
+  };
+}
+
+export interface McpWriteProposal {
+  schema: 'mcp-write-proposal.v0';
+  proposal_id: string;
+  created_at: string;
+  proposed_by: string;
+  task_ref: string;
+  summary: string;
+  evidence_ref?: string;
+  outbox_ref: string;
+  content_boundary: {
+    raw_prompt_included: false;
+    raw_tool_output_included: false;
+    source_snippets_included: false;
+    local_paths_included: false;
+  };
+  authority_boundary: {
+    can_authorize: false;
+    can_merge: false;
+    can_close: false;
+    can_grant: false;
+    mutates_ledger: false;
+  };
+}
+
+export interface ConsoleProvisioningEvent {
+  event_id: string;
+  created_at: string;
+  event_kind: string;
+  plan_ref: string;
+  terraform_ref: string;
+  target: {
+    provider: string;
+    substrate: string;
+    cluster_name: string;
+    region: string;
+    namespace: string;
+  };
+  summary: string;
+}
+
+export interface ConsoleHarnessMaintenanceProjection {
+  schema: 'harness-maintenance-console-projection.v0';
+  counts: Record<HarnessDisposition, number> & {
+    inventory_items: number;
+    pruning_receipts: number;
+    validation_errors: number;
+  };
+  inventory_reports: Array<{
+    manifest_ref: string;
+    item_count: number;
+    counts: Record<HarnessDisposition, number>;
+  }>;
+  pruning_receipts: Array<{
+    receipt_ref: string;
+    object_id: string;
+    proposed_disposition: HarnessDisposition;
+    canary_verdict: 'pass' | 'blocked';
+    human_disposition_required: true;
+  }>;
+  validation_errors: Array<{
+    ref: string;
+    reason: string;
+  }>;
+  authority_boundary: {
+    read_only: true;
+    can_prune: false;
+    can_delete: false;
+    can_grant: false;
+    can_close_lane: false;
+  };
+}
+
+export interface ConsoleReadModel {
+  schema: 'console-read-model.v0';
+  generated_at: string;
+  project_ref: '.';
+  counts: {
+    ledger_entries: number;
+    receipts: number;
+    tasks: number;
+    outbox_items: number;
+    provisioning_events: number;
+    owner_cards: number;
+  };
+  seat_readiness: JsonRecord | null;
+  owner_cards: AgentOwnerCardProjection;
+  provisioning_events: ConsoleProvisioningEvent[];
+  harness_maintenance: ConsoleHarnessMaintenanceProjection;
+  recent_ledger: string[];
+  authority_boundary: {
+    read_only: true;
+    can_emit_events: false;
+    can_attach_grants: false;
+    can_merge: false;
+    can_close: false;
+  };
+}
+
+function isoNow(at?: string): string {
+  const value = at ?? new Date().toISOString();
+  if (!Number.isFinite(Date.parse(value))) throw new Error('--at must be an ISO-8601 timestamp');
+  return new Date(value).toISOString();
+}
+
+function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 12);
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function stringValue(record: JsonRecord, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function nestedString(record: JsonRecord, objectKey: string, key: string): string | undefined {
+  const nested = record[objectKey];
+  if (!isRecord(nested)) return undefined;
+  return stringValue(nested, key);
+}
+
+async function readStructured(path: string): Promise<unknown> {
+  const raw = await readFile(path, 'utf-8');
+  if (extname(path).toLowerCase() === '.json') return JSON.parse(raw) as unknown;
+  return parseYaml(raw) as unknown;
+}
+
+function safeLabel(path: string, label?: string): string {
+  if (label) {
+    assertSharedMemoryText(label, 'label');
+    return label;
+  }
+  return `input:${stableHash(path)}`;
+}
+
+function assertOpaque(value: string, field: string): void {
+  assertSharedMemoryScopeId(value, field);
+}
+
+function assertSharedText(value: string, field: string): void {
+  if (value.trim().length === 0) throw new Error(`${field} must not be empty`);
+  assertSharedMemoryText(value, field);
+}
+
+function assertArtifactRef(value: string, field: string): void {
+  if (value.length === 0 || value.length > 256) throw new Error(`${field} must be 1-256 chars`);
+  if (value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value)) {
+    throw new Error(`${field} must not be an absolute path`);
+  }
+  assertSharedMemoryText(value, field);
+}
+
+function assertVaultRef(value: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,159}$/.test(value)) {
+    throw new Error('--vault-ref must be an opaque provider reference');
+  }
+  if (value.includes('=') || /sk-[A-Za-z0-9_-]{12,}/.test(value)) {
+    throw new Error('--vault-ref must not contain a secret value');
+  }
+  const restricted = detectMemoryRiskFlags(value).filter((flag) => flag !== 'contains_credential');
+  if (restricted.length > 0) {
+    throw new Error(`--vault-ref contains restricted shared content: ${restricted.join(', ')}`);
+  }
+}
+
+function assertEnum<T extends readonly string[]>(values: T, value: string, field: string): asserts value is T[number] {
+  if (!(values as readonly string[]).includes(value)) {
+    throw new Error(`${field} must be one of: ${values.join(', ')}`);
+  }
+}
+
+function fingerprint(value: unknown): ModelFingerprint {
+  if (!isRecord(value)) throw new Error('model posture input must be an object');
+  return {
+    seat: stringValue(value, 'seat') ?? stringValue(value, 'seat_id'),
+    model_id: stringValue(value, 'model_id') ?? stringValue(value, 'model') ?? nestedString(value, 'model_config', 'model'),
+    model_tier: stringValue(value, 'model_tier') ?? stringValue(value, 'tier'),
+    adapter_backend: stringValue(value, 'adapter_backend') ?? stringValue(value, 'provider'),
+    execution_surface: stringValue(value, 'execution_surface') ?? stringValue(value, 'surface'),
+    runtime_tier: stringValue(value, 'runtime_tier') ?? stringValue(value, 'hosting_tier'),
+  };
+}
+
+export async function createModelDriftReceipt(options: {
+  previousPath: string;
+  currentPath: string;
+  previousLabel?: string;
+  currentLabel?: string;
+  receiptPath?: string;
+  at?: string;
+}): Promise<ModelDriftReceipt> {
+  const createdAt = isoNow(options.at);
+  const previous = fingerprint(await readStructured(options.previousPath));
+  const current = fingerprint(await readStructured(options.currentPath));
+  const fields: Array<keyof ModelFingerprint> = [
+    'seat',
+    'model_id',
+    'model_tier',
+    'adapter_backend',
+    'execution_surface',
+    'runtime_tier',
+  ];
+  const drift = fields
+    .filter((field) => (previous[field] ?? null) !== (current[field] ?? null))
+    .map((field) => ({
+      field,
+      previous: previous[field] ?? null,
+      current: current[field] ?? null,
+    }));
+  const invalidates = drift.some((entry) => (
+    entry.field === 'model_id' ||
+    entry.field === 'model_tier' ||
+    entry.field === 'adapter_backend' ||
+    entry.field === 'runtime_tier'
+  ));
+  const receipt: ModelDriftReceipt = {
+    schema: 'model-drift-receipt.v0',
+    receipt_id: `model-drift:${stableHash({ previous, current, createdAt })}`,
+    created_at: createdAt,
+    previous_ref: safeLabel(options.previousPath, options.previousLabel),
+    current_ref: safeLabel(options.currentPath, options.currentLabel),
+    previous,
+    current,
+    drift_detected: drift.length > 0,
+    invalidates_social_calibration: invalidates,
+    drift,
+    authority_boundary: {
+      can_authorize: false,
+      can_attach_grant: false,
+      mutates_roster: false,
+    },
+  };
+  if (options.receiptPath) await writeYaml(options.receiptPath, receipt);
+  return receipt;
+}
+
+export async function validateRuntimeProfileFile(path: string, at?: string): Promise<RuntimeProfileValidation> {
+  const raw = await readStructured(path);
+  if (!isRecord(raw)) throw new Error('runtime profile must be an object');
+  if (raw.schema !== 'runtime-profile.v0') throw new Error('runtime profile schema must be runtime-profile.v0');
+
+  const profileId = stringValue(raw, 'profile_id');
+  const runtimeTier = stringValue(raw, 'runtime_tier');
+  const perimeterMode = stringValue(raw, 'perimeter_mode');
+  const adapterBackend = stringValue(raw, 'adapter_backend');
+  const targetRef = stringValue(raw, 'target_ref');
+  if (!profileId) throw new Error('profile_id is required');
+  if (!runtimeTier) throw new Error('runtime_tier is required');
+  if (!perimeterMode) throw new Error('perimeter_mode is required');
+  if (!adapterBackend) throw new Error('adapter_backend is required');
+  if (!targetRef) throw new Error('target_ref is required');
+  assertOpaque(profileId, 'profile_id');
+  assertEnum(RUNTIME_PROFILE_TIERS, runtimeTier, 'runtime_tier');
+  assertEnum(PERIMETER_MODES, perimeterMode, 'perimeter_mode');
+  assertOpaque(adapterBackend, 'adapter_backend');
+  assertArtifactRef(targetRef, 'target_ref');
+  if (raw.supports_verifier !== true) throw new Error('supports_verifier must be true');
+
+  const boundary = raw.authority_boundary;
+  if (!isRecord(boundary)) throw new Error('authority_boundary is required');
+  const expectedFalse = ['can_write', 'can_merge', 'can_close', 'can_grant', 'mutates_canonical_truth'];
+  for (const key of expectedFalse) {
+    if (boundary[key] !== false) throw new Error(`authority_boundary.${key} must be false`);
+  }
+
+  return {
+    schema: 'runtime-profile-validation.v0',
+    profile_id: profileId,
+    validated_at: isoNow(at),
+    verdict: 'accepted',
+    runtime_tier: runtimeTier,
+    perimeter_mode: perimeterMode,
+    adapter_backend: adapterBackend,
+    supported_modes: ['verifier'],
+    authority_boundary: {
+      can_execute_verifier: true,
+      can_write: false,
+      can_merge: false,
+      can_close: false,
+      can_grant: false,
+      mutates_canonical_truth: false,
+    },
+  };
+}
+
+export async function createVaultReferenceReceipt(options: {
+  provider: string;
+  vaultRef: string;
+  purpose: string;
+  requestedBy: string;
+  receiptPath?: string;
+  at?: string;
+}): Promise<VaultReferenceReceipt> {
+  assertOpaque(options.provider, '--provider');
+  assertVaultRef(options.vaultRef);
+  assertSharedText(options.purpose, '--purpose');
+  assertOpaque(options.requestedBy, '--requested-by');
+  const createdAt = isoNow(options.at);
+  const receipt: VaultReferenceReceipt = {
+    schema: 'vault-reference-receipt.v0',
+    receipt_id: `vault-ref:${stableHash({ provider: options.provider, vaultRef: options.vaultRef, purpose: options.purpose, createdAt })}`,
+    created_at: createdAt,
+    provider: options.provider,
+    vault_ref: options.vaultRef,
+    purpose: options.purpose,
+    requested_by: options.requestedBy,
+    raw_secret_stored: false,
+    content_boundary: {
+      stores_secret_value: false,
+      stores_provider_token: false,
+      stores_raw_identity_document: false,
+    },
+    authority_boundary: {
+      can_read_secret: false,
+      can_inject_secret: false,
+      can_grant_secret_access: false,
+    },
+  };
+  if (options.receiptPath) await writeYaml(options.receiptPath, receipt);
+  return receipt;
+}
+
+export async function createSchedulerWakeProposal(options: {
+  projectRoot: string;
+  taskRef: string;
+  wakeAt: string;
+  reason: string;
+  createdBy: string;
+  proposalPath?: string;
+  at?: string;
+}): Promise<SchedulerWakeProposal> {
+  assertArtifactRef(options.taskRef, '--task');
+  assertSharedText(options.reason, '--reason');
+  assertOpaque(options.createdBy, '--created-by');
+  const wakeAt = isoNow(options.wakeAt);
+  const createdAt = isoNow(options.at);
+  const proposal: SchedulerWakeProposal = {
+    schema: 'scheduler-wake-proposal.v0',
+    proposal_id: `scheduler-wake:${stableHash({ taskRef: options.taskRef, wakeAt, reason: options.reason })}`,
+    created_at: createdAt,
+    created_by: options.createdBy,
+    task_ref: options.taskRef,
+    wake_at: wakeAt,
+    reason: options.reason,
+    status: 'proposed',
+    authority_boundary: {
+      scheduler_can_authorize: false,
+      scheduler_can_merge: false,
+      scheduler_can_grant: false,
+      scheduler_can_execute: false,
+    },
+  };
+  const path = options.proposalPath ?? join(resolve(options.projectRoot), '.etiquette', 'outbox', 'scheduler', `${proposal.proposal_id.replace(/[^A-Za-z0-9_-]+/g, '-')}.yaml`);
+  await writeYaml(path, proposal);
+  return proposal;
+}
+
+export async function stageMcpWriteProposal(options: {
+  projectRoot: string;
+  taskRef: string;
+  summary: string;
+  proposedBy?: string;
+  evidenceRef?: string;
+  at?: string;
+}): Promise<McpWriteProposal> {
+  assertArtifactRef(options.taskRef, 'task_ref');
+  assertSharedText(options.summary, 'summary');
+  if (options.evidenceRef) assertArtifactRef(options.evidenceRef, 'evidence_ref');
+  const proposedBy = options.proposedBy ?? 'mcp-client';
+  assertOpaque(proposedBy, 'proposed_by');
+  const createdAt = isoNow(options.at);
+  const proposalId = `mcp-proposal:${stableHash({
+    taskRef: options.taskRef,
+    summary: options.summary,
+    evidenceRef: options.evidenceRef,
+    proposedBy,
+    createdAt,
+  })}`;
+  const outPath = join(resolve(options.projectRoot), '.etiquette', 'outbox', 'mcp-proposals', `${proposalId.replace(/[^A-Za-z0-9_-]+/g, '-')}.json`);
+  const outboxRef = projectRelative(options.projectRoot, outPath);
+  const proposal: McpWriteProposal = {
+    schema: 'mcp-write-proposal.v0',
+    proposal_id: proposalId,
+    created_at: createdAt,
+    proposed_by: proposedBy,
+    task_ref: options.taskRef,
+    summary: options.summary,
+    ...(options.evidenceRef ? { evidence_ref: options.evidenceRef } : {}),
+    outbox_ref: outboxRef,
+    content_boundary: {
+      raw_prompt_included: false,
+      raw_tool_output_included: false,
+      source_snippets_included: false,
+      local_paths_included: false,
+    },
+    authority_boundary: {
+      can_authorize: false,
+      can_merge: false,
+      can_close: false,
+      can_grant: false,
+      mutates_ledger: false,
+    },
+  };
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, `${JSON.stringify(proposal, null, 2)}\n`);
+  return proposal;
+}
+
+export async function buildConsoleReadModel(projectRoot: string, at?: string): Promise<ConsoleReadModel> {
+  const root = resolve(projectRoot);
+  const ledgerPath = join(root, 'docs', 'work', 'ledger', 'LEDGER.md');
+  const ledgerRaw = await readTextIfExists(ledgerPath);
+  const ledgerLines = ledgerRaw
+    ? ledgerRaw.split('\n').map((line) => line.trim()).filter((line) => line.startsWith('- '))
+    : [];
+  const receipts = await countFiles(join(root, 'docs', 'work', 'receipts'));
+  const tasks = await countFiles(join(root, 'docs', 'work', 'tasks'));
+  const outbox = await countFiles(join(root, '.etiquette', 'outbox'));
+  const provisioningEvents = await readProvisioningEvents(join(root, '.etiquette', 'provisioning', 'events'));
+  const harnessMaintenance = await readHarnessMaintenanceProjection(root);
+  const ownerCards = await buildAgentOwnerCardProjection({ projectRoot: root, at });
+  const readinessRaw = await readTextIfExists(join(root, '.etiquette', 'state', 'seat-readiness.json'));
+  const readiness = readinessRaw ? JSON.parse(readinessRaw) as JsonRecord : null;
+
+  return {
+    schema: 'console-read-model.v0',
+    generated_at: isoNow(at),
+    project_ref: '.',
+    counts: {
+      ledger_entries: ledgerLines.length,
+      receipts,
+      tasks,
+      outbox_items: outbox,
+      provisioning_events: provisioningEvents.length,
+      owner_cards: ownerCards.cards.length,
+    },
+    seat_readiness: readiness,
+    owner_cards: ownerCards,
+    provisioning_events: provisioningEvents.slice(-8),
+    harness_maintenance: harnessMaintenance,
+    recent_ledger: ledgerLines.slice(-8),
+    authority_boundary: {
+      read_only: true,
+      can_emit_events: false,
+      can_attach_grants: false,
+      can_merge: false,
+      can_close: false,
+    },
+  };
+}
+
+async function readTextIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function countFiles(dir: string): Promise<number> {
+  if (!existsSync(dir)) return 0;
+  const entries = await readdir(dir, { withFileTypes: true });
+  const counts = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return countFiles(path);
+    return entry.isFile() ? 1 : 0;
+  }));
+  return counts.reduce((sum, count) => sum + count, 0);
+}
+
+async function collectFiles(dir: string): Promise<string[]> {
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(entries.map(async (entry) => {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) return collectFiles(path);
+    return entry.isFile() ? [path] : [];
+  }));
+  return nested.flat().sort();
+}
+
+async function readProvisioningEvents(dir: string): Promise<ConsoleProvisioningEvent[]> {
+  const files = (await collectFiles(dir)).filter((file) => ['.yaml', '.yml', '.json'].includes(extname(file).toLowerCase()));
+  const events = await Promise.all(files.map(async (file) => {
+    const raw = await readStructured(file);
+    if (!isRecord(raw) || raw.schema !== 'provisioning-event.v0') return null;
+    const target = raw.target;
+    if (!isRecord(target)) return null;
+    const eventId = stringValue(raw, 'event_id');
+    const createdAt = stringValue(raw, 'created_at');
+    const eventKind = stringValue(raw, 'event_kind');
+    const planRef = stringValue(raw, 'plan_ref');
+    const terraformRef = stringValue(raw, 'terraform_ref');
+    const summary = stringValue(raw, 'summary');
+    const provider = stringValue(target, 'provider');
+    const substrate = stringValue(target, 'substrate');
+    const clusterName = stringValue(target, 'cluster_name');
+    const region = stringValue(target, 'region');
+    const namespace = stringValue(target, 'namespace');
+    if (!eventId || !createdAt || !eventKind || !planRef || !terraformRef || !summary || !provider || !substrate || !clusterName || !region || !namespace) {
+      return null;
+    }
+    return {
+      event_id: eventId,
+      created_at: createdAt,
+      event_kind: eventKind,
+      plan_ref: planRef,
+      terraform_ref: terraformRef,
+      target: {
+        provider,
+        substrate,
+        cluster_name: clusterName,
+        region,
+        namespace,
+      },
+      summary,
+    };
+  }));
+  return events
+    .filter((event): event is ConsoleProvisioningEvent => event !== null)
+    .sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+
+async function readHarnessMaintenanceProjection(root: string): Promise<ConsoleHarnessMaintenanceProjection> {
+  const counts: ConsoleHarnessMaintenanceProjection['counts'] = {
+    keep: 0,
+    consolidate: 0,
+    quarantine: 0,
+    'delete-ready': 0,
+    blocked: 0,
+    inventory_items: 0,
+    pruning_receipts: 0,
+    validation_errors: 0,
+  };
+  const inventoryReports: ConsoleHarnessMaintenanceProjection['inventory_reports'] = [];
+  const pruningReceipts: ConsoleHarnessMaintenanceProjection['pruning_receipts'] = [];
+  const validationErrors: ConsoleHarnessMaintenanceProjection['validation_errors'] = [];
+
+  const inventoryCandidates = [
+    join(root, '.etiquette', 'harness', 'inventory.yaml'),
+    join(root, '.etiquette', 'harness', 'inventory.yml'),
+    join(root, 'docs', 'work', 'harness-inventory.yaml'),
+    join(root, 'docs', 'work', 'harness-inventory.yml'),
+    join(root, 'docs', 'work', 'harness', 'inventory.yaml'),
+    join(root, 'docs', 'work', 'harness', 'inventory.yml'),
+  ].filter((path, index, all) => existsSync(path) && all.indexOf(path) === index);
+
+  for (const path of inventoryCandidates) {
+    const ref = projectRelative(root, path);
+    try {
+      const report = await buildHarnessInventoryReportFile(path);
+      inventoryReports.push({
+        manifest_ref: ref,
+        item_count: report.item_count,
+        counts: report.counts,
+      });
+      counts.inventory_items += report.item_count;
+      for (const disposition of Object.keys(report.counts) as HarnessDisposition[]) {
+        counts[disposition] += report.counts[disposition];
+      }
+    } catch (err) {
+      validationErrors.push({ ref, reason: errorMessage(err) });
+    }
+  }
+
+  const receiptDirs = [
+    join(root, '.etiquette', 'harness', 'receipts'),
+    join(root, 'docs', 'work', 'harness', 'receipts'),
+    join(root, 'docs', 'work', 'receipts'),
+  ];
+  const receiptFiles = [...new Set((await Promise.all(receiptDirs.map(collectFiles))).flat())]
+    .filter((file) => ['.yaml', '.yml', '.json'].includes(extname(file).toLowerCase()));
+
+  for (const path of receiptFiles) {
+    const raw = await readTextIfExists(path);
+    if (!raw?.includes('harness-prune-receipt.v0')) continue;
+    const ref = projectRelative(root, path);
+    try {
+      const receipt = await validateHarnessPruneReceiptFile(path);
+      pruningReceipts.push({
+        receipt_ref: ref,
+        object_id: receipt.object_id,
+        proposed_disposition: receipt.proposed_disposition,
+        canary_verdict: receipt.canary.verdict,
+        human_disposition_required: true,
+      });
+      counts.pruning_receipts += 1;
+    } catch (err) {
+      validationErrors.push({ ref, reason: errorMessage(err) });
+    }
+  }
+
+  counts.validation_errors = validationErrors.length;
+  return {
+    schema: 'harness-maintenance-console-projection.v0',
+    counts,
+    inventory_reports: inventoryReports,
+    pruning_receipts: pruningReceipts,
+    validation_errors: validationErrors,
+    authority_boundary: {
+      read_only: true,
+      can_prune: false,
+      can_delete: false,
+      can_grant: false,
+      can_close_lane: false,
+    },
+  };
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function projectRelative(projectRoot: string, path: string): string {
+  const rel = relative(resolve(projectRoot), resolve(path));
+  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
+    throw new Error(`path must stay inside project root: ${path}`);
+  }
+  return rel;
+}
+
+async function writeYaml(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, stringifyYaml(value));
+}