@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/cli/commands/dispatch.ts

@@ -0,0 +1,279 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import { evaluateOperationalDispatch } from '../../dispatch/decision';
+import {
+  loadOperationalDispatchRecord,
+  projectDispatchRecordToHostedReceipt,
+} from '../../dispatch/projection';
+import { recordOperationalDispatch } from '../../dispatch/record';
+import { loadSandboxReceipt } from '../../rubric/loader';
+import { evaluateSeatReadiness, readSeatReadiness } from '../../seat/readiness';
+import { evaluateWorkflowCheck } from '../../workflow/evaluator';
+import { loadWorkflowEnvelope, loadWorkflowMode } from '../../workflow/loader';
+
+const DISPATCH_VERBS = new Set(['check', 'record', 'projection', 'scaffold']);
+
+export function isDispatchCommand(command: string): boolean {
+  return command === 'dispatch';
+}
+
+function renderDecision(result: ReturnType<typeof evaluateOperationalDispatch>): string {
+  return [
+    'operational_dispatch_decision:',
+    `  task_ref: ${result.task_ref}`,
+    `  seat: ${result.seat}`,
+    `  decision: ${result.decision}`,
+    `  reasons: ${result.reasons.join(', ') || 'none'}`,
+    `  warnings: ${result.warnings.join(', ') || 'none'}`,
+    `  profile_hint: ${result.profile_hint ?? 'none'}`,
+    `  seat_routing: ${result.inputs.seat_readiness.routing_recommendation}`,
+    `  workflow_recommendation: ${result.inputs.workflow_check.recommendation}`,
+    `  rubric_receipt_accepted: ${String(result.inputs.rubric_receipt.accepted)}`,
+    `  can_dispatch: ${String(result.authority_boundary.can_dispatch)}`,
+    `  can_authorize: ${String(result.authority_boundary.can_authorize)}`,
+    `  consumer_is_engine: ${String(result.authority_boundary.consumer_is_engine)}`,
+  ].join('\n');
+}
+
+function renderRecord(result: Awaited<ReturnType<typeof recordOperationalDispatch>>): string {
+  return [
+    'operational_dispatch_record:',
+    `  record_id: ${result.record.record_id}`,
+    `  task_ref: ${result.record.task_ref}`,
+    `  seat: ${result.record.seat}`,
+    `  decision: ${result.record.decision}`,
+    `  reasons: ${result.record.reasons.join(', ') || 'none'}`,
+    `  warnings: ${result.record.warnings.join(', ') || 'none'}`,
+    `  receipt_ref: ${result.record.receipt_ref}`,
+    `  ledger_ref: ${result.record.ledger_ref}`,
+    `  can_execute: ${String(result.record.authority_boundary.can_execute)}`,
+  ].join('\n');
+}
+
+function renderProjection(result: ReturnType<typeof projectDispatchRecordToHostedReceipt>): string {
+  const payload = result.hosted_payload;
+  return [
+    'hosted_receipt_metadata_projection:',
+    `  projection_id: ${result.projection_id}`,
+    `  source_record_id: ${result.source_record_id}`,
+    `  task_id: ${payload.task_id}`,
+    `  seat_id: ${payload.seat_id}`,
+    `  status: ${payload.status}`,
+    `  artifact_ref: ${payload.artifact_ref ?? 'none'}`,
+    `  receipt_ref: ${payload.receipt_ref}`,
+    `  validation_summary: ${payload.validation_summary}`,
+    '  boundary: metadata-only; hosted plane cannot execute, authorize, attach grants, or mutate the local ledger',
+  ].join('\n');
+}
+
+function addHours(at: string, hours: number): string {
+  const date = new Date(at);
+  if (Number.isNaN(date.getTime())) throw new Error('--at must be an ISO-8601 timestamp');
+  date.setUTCHours(date.getUTCHours() + hours);
+  return date.toISOString();
+}
+
+function rel(root: string, path: string): string {
+  const value = relative(root, path);
+  return value && !value.startsWith('..') ? value : path;
+}
+
+function renderScaffold(result: Awaited<ReturnType<typeof scaffoldDispatch>>): string {
+  return [
+    'dispatch_scaffold:',
+    `  out: ${result.out_ref}`,
+    `  mode: ${result.files.mode_ref}`,
+    `  task: ${result.files.task_ref}`,
+    `  sandbox_receipt: ${result.files.sandbox_receipt_ref}`,
+    `  state: ${result.files.state_ref}`,
+    `  check_command: ${result.check_command}`,
+    '  boundary: scaffold only; does not record dispatch, authorize, grant, merge, close, or execute',
+  ].join('\n');
+}
+
+async function scaffoldDispatch(flags: Record<string, string | boolean>) {
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const taskId = optionalString(flags, 'task-id') ?? optionalString(flags, 'task') ?? 'APP-001';
+  const seat = optionalString(flags, 'seat') ?? 'codex-seat';
+  const modeId = optionalString(flags, 'mode-id') ?? 'dispatch-mixed-mode-v0';
+  const strategy = optionalString(flags, 'strategy') ?? 'local_adversarial_tango';
+  const at = optionalString(flags, 'at') ?? new Date().toISOString();
+  const outDir = resolve(optionalString(flags, 'out') ?? join(projectRoot, 'docs', 'work', 'dispatch', taskId));
+  const modePath = join(outDir, 'mode.yaml');
+  const taskPath = join(outDir, 'task.yaml');
+  const receiptPath = join(outDir, 'receipt.yaml');
+  const statePath = join(outDir, 'seat-readiness.json');
+  const receiptId = `sandbox-run:${taskId}`;
+
+  const modeYaml = `mode_id: ${modeId}
+mode_version: 0.1.0
+mode_type: mixed
+drafting:
+  surface: coordination-ledger
+  requires_review: true
+  min_reviewers: 1
+  amendment_rounds_allowed: true
+  adversarial_review_required: false
+  compact_reason_required: false
+grant:
+  required: true
+  preauthorization_allowed: false
+  granted_by: operator_principal
+  advisory_consensus_can_authorize: false
+execution:
+  surface: local-etiquette
+  dispatch: immediate_after_grant
+  strategy_policy: executor_selected
+  rubric_required: true
+proof:
+  receipt_required: true
+  validation_required: true
+  closeout_requires_receipt: true
+audit:
+  event_log_required: true
+  dissent_capture_required: true
+authority_status: policy_preset_only
+`;
+  const taskYaml = `task_ref: task:${taskId}
+workflow_mode_ref: workflow-mode:${modeId}
+requested_mode_type: mixed
+mutates_state: true
+grant_ref: grant:${taskId}
+consensus_ref: consensus:${taskId}
+receipt_ref: receipt:${taskId}
+validation_refs:
+  - ${receiptId}
+bounded: true
+preauthorized: false
+advisory_consensus_claims_authority: false
+risk: medium
+`;
+  const receiptYaml = `schema: sandbox-run-receipt.v0
+receipt_id: ${receiptId}
+rubric_id: ${taskId}
+rubric_version: 0.1.0
+fixture_set_ref: fixture-set:${taskId}
+results:
+  - fixture_id: ready
+    expected: pass
+    actual: pass
+    reason: scaffolded receipt example
+summary:
+  total_fixtures: 1
+  known_bad_rejected: 0
+  known_good_accepted: 1
+  unexpected_outcomes: 0
+run_at: ${at}
+run_by: ${seat}
+run_environment: local
+`;
+  const seatState = {
+    schema_version: 'seat-readiness.v0.1',
+    seat,
+    seat_type: 'control_seat',
+    execution_surface: 'local-etiquette',
+    declared_by: 'config',
+    capability_source: 'local_validation',
+    capability_trusted: true,
+    operational_status: 'operational',
+    model_tier: 'local_unknown',
+    model_id: 'local-session',
+    active_workers: 0,
+    max_recommended_workers: 1,
+    supports_parallel: false,
+    supported_strategies: [strategy],
+    unsupported_strategies: [],
+    constraints: ['scaffold-example'],
+    last_checked_at: at,
+    last_heartbeat_at: at,
+    ttl_seconds: 86400,
+    stale_after: addHours(at, 24),
+  };
+
+  await mkdir(outDir, { recursive: true });
+  await writeFile(modePath, modeYaml);
+  await writeFile(taskPath, taskYaml);
+  await writeFile(receiptPath, receiptYaml);
+  await writeFile(statePath, `${JSON.stringify(seatState, null, 2)}\n`);
+
+  const files = {
+    mode_ref: rel(projectRoot, modePath),
+    task_ref: rel(projectRoot, taskPath),
+    sandbox_receipt_ref: rel(projectRoot, receiptPath),
+    state_ref: rel(projectRoot, statePath),
+  };
+  return {
+    schema: 'dispatch-scaffold.v0',
+    out_ref: rel(projectRoot, outDir),
+    task_id: taskId,
+    seat,
+    files,
+    check_command: `etiquette dispatch check --project . --mode ${files.mode_ref} --task ${files.task_ref} --sandbox-receipt ${files.sandbox_receipt_ref} --state ${files.state_ref} --strategy ${strategy}`,
+    authority_boundary: {
+      scaffold_only: true,
+      can_record_dispatch: false,
+      can_authorize: false,
+      can_attach_grant: false,
+      can_execute: false,
+      can_merge: false,
+      can_close: false,
+    },
+  };
+}
+
+export async function dispatchDispatch(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !DISPATCH_VERBS.has(verb)) {
+    throw new Error(`dispatch verb must be one of: ${[...DISPATCH_VERBS].join(', ')}`);
+  }
+  const json = Boolean(flags.json);
+  if (verb === 'scaffold') {
+    const scaffold = await scaffoldDispatch(flags);
+    console.log(json ? JSON.stringify(scaffold, null, 2) : renderScaffold(scaffold));
+    return;
+  }
+  if (verb === 'projection') {
+    const record = await loadOperationalDispatchRecord(resolve(requireString(flags, 'record')));
+    const projected = projectDispatchRecordToHostedReceipt({
+      record,
+      artifactRef: optionalString(flags, 'artifact-ref'),
+      receiptRef: optionalString(flags, 'receipt-ref'),
+      status: optionalString(flags, 'status'),
+      validationSummary: optionalString(flags, 'validation-summary'),
+    });
+    console.log(json ? JSON.stringify(projected, null, 2) : renderProjection(projected));
+    return;
+  }
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const mode = await loadWorkflowMode(resolve(requireString(flags, 'mode')));
+  const envelope = await loadWorkflowEnvelope(resolve(requireString(flags, 'task')));
+  const readiness = evaluateSeatReadiness(
+    await readSeatReadiness(projectRoot, optionalString(flags, 'state')),
+    optionalString(flags, 'at'),
+  );
+  const receiptPath = optionalString(flags, 'sandbox-receipt');
+  const sandboxReceipt = receiptPath ? await loadSandboxReceipt(resolve(receiptPath)) : null;
+  const result = evaluateOperationalDispatch({
+    seat: readiness,
+    mode,
+    envelope,
+    workflow: evaluateWorkflowCheck(mode, envelope),
+    sandboxReceipt,
+    requestedStrategy: optionalString(flags, 'strategy'),
+  });
+  if (verb === 'record') {
+    const recorded = await recordOperationalDispatch({
+      projectRoot,
+      decision: result,
+      recordedBy: optionalString(flags, 'recorded-by'),
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(recorded.record, null, 2) : renderRecord(recorded));
+    return;
+  }
+  console.log(json ? JSON.stringify(result, null, 2) : renderDecision(result));
+}

package/packages/control/src/cli/commands/harness.ts

@@ -0,0 +1,89 @@
+import { resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import {
+  buildHarnessInventoryReportFile,
+  loadHarnessPruneReceipt,
+  evaluateHarnessCanary,
+  validateHarnessPruneReceiptFile,
+  type HarnessCanaryResult,
+  type HarnessInventoryReport,
+  type HarnessReceiptValidation,
+} from '../../harness/pruning';
+
+const HARNESS_VERBS = new Set(['receipt', 'inventory', 'canary']);
+
+export function isHarnessCommand(command: string): boolean {
+  return command === 'harness';
+}
+
+function renderReceipt(result: HarnessReceiptValidation): string {
+  return [
+    'harness_prune_receipt:',
+    `  receipt_id: ${result.receipt_id}`,
+    `  object_id: ${result.object_id}`,
+    `  verdict: ${result.verdict}`,
+    `  proposed_disposition: ${result.proposed_disposition}`,
+    `  canary_verdict: ${result.canary.verdict}`,
+    `  can_authorize_pruning: ${String(result.authority_boundary.receipt_can_authorize_pruning)}`,
+    `  human_disposition_required: ${String(result.authority_boundary.human_disposition_required)}`,
+  ].join('\n');
+}
+
+function renderCanary(result: HarnessCanaryResult): string {
+  return [
+    'harness_canary:',
+    `  object_id: ${result.object_id}`,
+    `  verdict: ${result.verdict}`,
+    `  required: ${result.required_canaries.join(', ')}`,
+    `  observed: ${result.observed_canaries.join(', ')}`,
+    `  missing: ${result.missing_canaries.join(', ') || 'none'}`,
+  ].join('\n');
+}
+
+function renderInventory(result: HarnessInventoryReport): string {
+  return [
+    'harness_inventory:',
+    `  item_count: ${result.item_count}`,
+    `  keep: ${result.counts.keep}`,
+    `  consolidate: ${result.counts.consolidate}`,
+    `  quarantine: ${result.counts.quarantine}`,
+    `  delete_ready: ${result.counts['delete-ready']}`,
+    `  blocked: ${result.counts.blocked}`,
+    `  can_delete: ${String(result.authority_boundary.inventory_can_delete)}`,
+    `  pruning_receipt_required: ${String(result.authority_boundary.pruning_receipt_required)}`,
+    ...result.items.map((item) => (
+      `  - ${item.object_id}: ${item.suggested_disposition} (${item.reason})`
+    )),
+  ].join('\n');
+}
+
+export async function dispatchHarness(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !HARNESS_VERBS.has(verb)) {
+    throw new Error(`harness verb must be one of: ${[...HARNESS_VERBS].join(', ')}`);
+  }
+  const json = Boolean(flags.json);
+
+  if (verb === 'receipt') {
+    const result = await validateHarnessPruneReceiptFile(resolve(requireString(flags, 'receipt')));
+    console.log(json ? JSON.stringify(result, null, 2) : renderReceipt(result));
+    return;
+  }
+
+  if (verb === 'canary') {
+    const receipt = await loadHarnessPruneReceipt(resolve(requireString(flags, 'receipt')));
+    const result = evaluateHarnessCanary(receipt);
+    console.log(json ? JSON.stringify(result, null, 2) : renderCanary(result));
+    return;
+  }
+
+  const result = await buildHarnessInventoryReportFile(resolve(requireString(flags, 'manifest')));
+  if (optionalString(flags, 'project')) {
+    // Parsed intentionally as a harmless compatibility flag for callers that
+    // consistently pass --project to read-only Etiquette commands.
+  }
+  console.log(json ? JSON.stringify(result, null, 2) : renderInventory(result));
+}

package/packages/control/src/cli/commands/hook.ts

@@ -0,0 +1,50 @@
+import { dispatchHook } from '../../hooks/dispatcher';
+import { HOOK_STAGES, type HookStage } from '../../hooks/types';
+import { optionalString } from '../argv';
+
+export function isHookCommand(command: string): boolean {
+  return command === 'hook';
+}
+
+export async function dispatchHookCli(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const stage = positionals[1];
+  if (!stage) {
+    console.error(`hook: missing stage (one of: ${HOOK_STAGES.join(', ')})`);
+    process.exit(2);
+  }
+  if (!(HOOK_STAGES as readonly string[]).includes(stage)) {
+    console.error(`hook: unknown stage "${stage}"; expected one of: ${HOOK_STAGES.join(', ')}`);
+    process.exit(2);
+  }
+
+  const workspace_id = optionalString(flags, 'workspace');
+  const payloadRaw = optionalString(flags, 'payload');
+  let payload: Record<string, unknown> = {};
+  if (payloadRaw) {
+    try {
+      const parsed = JSON.parse(payloadRaw);
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('payload must be a JSON object');
+      }
+      payload = parsed as Record<string, unknown>;
+    } catch (err) {
+      console.error(`hook: --payload must be valid JSON object: ${(err as Error).message}`);
+      process.exit(2);
+    }
+  }
+
+  const result = dispatchHook({
+    stage: stage as HookStage,
+    workspace_id: workspace_id ?? undefined,
+    payload,
+  });
+
+  // Always exit 0 — operational results (disabled / written / skipped) are
+  // non-error states per the V0.1 envelope. Only argv-parse failures above
+  // exit non-zero. Hooks must NEVER block the operator's runtime.
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}

package/packages/control/src/cli/commands/ledger.ts

@@ -0,0 +1,91 @@
+import { resolve } from 'node:path';
+import { optionalString, parseInt32 } from '../argv';
+import {
+  defaultLedgerIndexDbPath,
+  ledgerIndexNeedsRebuild,
+  rebuildLedgerIndex,
+  searchLedgerIndex,
+  showLedgerIndexEntry,
+  type CompactLedgerSearchResult,
+} from '../../ledger/indexer';
+
+const LEDGER_VERBS = new Set(['index', 'search', 'show']);
+
+export function isLedgerCommand(command: string): boolean {
+  return command === 'ledger';
+}
+
+function asLimit(raw: string | boolean | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const parsed = parseInt32(raw, 'limit');
+  if (parsed < 1 || parsed > 50) {
+    throw new Error('--limit must be between 1 and 50');
+  }
+  return parsed;
+}
+
+function renderCompact(items: CompactLedgerSearchResult[]): string {
+  if (items.length === 0) return 'ledger: no matching entries\n';
+  return `${items.map((item) => [
+    `entry: ${item.entry_id}`,
+    `type: ${item.type}`,
+    `topic_hints: ${item.topic_hints.join(', ') || 'none'}`,
+    `status_effect: ${item.status_effect}`,
+    `refs: ${item.refs.join(', ') || 'none'}`,
+    `confidence: ${item.confidence}`,
+    `is_canonical: ${item.is_canonical}`,
+    `regenerable: ${item.regenerable}`,
+    `can_authorize: ${item.can_authorize}`,
+  ].join('\n')).join('\n---\n')}\n`;
+}
+
+async function ensureFresh(projectRoot: string, dbPath: string): Promise<void> {
+  if (await ledgerIndexNeedsRebuild({ projectRoot, dbPath })) {
+    throw new Error('ledger index is missing or stale; run `etiquette ledger index` first');
+  }
+}
+
+export async function dispatchLedger(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !LEDGER_VERBS.has(verb)) {
+    throw new Error(`ledger verb must be one of: ${[...LEDGER_VERBS].join(', ')}`);
+  }
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const dbPath = optionalString(flags, 'db') ?? defaultLedgerIndexDbPath(projectRoot);
+  const json = Boolean(flags.json);
+
+  if (verb === 'index') {
+    const result = await rebuildLedgerIndex({ projectRoot, dbPath });
+    console.log(json ? JSON.stringify(result, null, 2) : [
+      'ledger_index:',
+      `  db: ${result.dbPath}`,
+      `  ledger_entries: ${result.ledger_entries}`,
+      `  refs: ${result.refs}`,
+      `  topics: ${result.topics}`,
+      `  documents: ${result.documents}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (verb === 'search') {
+    const topic = optionalString(flags, 'topic');
+    const query = topic ?? positionals.slice(2).join(' ').trim();
+    if (!query) throw new Error('<query> or --topic is required');
+    await ensureFresh(projectRoot, dbPath);
+    const items = searchLedgerIndex({ dbPath, query, limit: asLimit(flags.limit, 10) });
+    console.log(json ? JSON.stringify(items, null, 2) : renderCompact(items));
+    return;
+  }
+
+  if (verb === 'show') {
+    const id = positionals[2];
+    if (!id) throw new Error('<entry_or_ref_id> is required');
+    await ensureFresh(projectRoot, dbPath);
+    const entry = showLedgerIndexEntry({ dbPath, entryIdOrRef: id });
+    if (!entry) throw new Error(`unknown ledger entry or ref: ${id}`);
+    console.log(JSON.stringify(entry, null, 2));
+  }
+}