@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/supervision/command-apply.ts

@@ -0,0 +1,378 @@
+import type {
+  ApprovedNextTurnPayload,
+  BlockerPayload,
+  SessionStatus,
+  SupervisionCommand,
+  SupervisionCommandRecord,
+  SupervisionDeps,
+  SupervisionSession,
+} from '../../../protocol/src/index';
+import { appendSupervisionEvent, buildEvent } from './events';
+import { loadSeatManifest } from './manifest';
+import { supervisionRuntimePaths } from './paths';
+import { renderProjection, writeLatestState } from './projection';
+import { applySupervisionSchema } from './sqlite';
+import { withSupervisionTransaction } from './sqlite-impl';
+import {
+  insertCommandRow,
+  insertEventRow,
+  loadCurrentTurn,
+  loadPendingCommands,
+  loadSession,
+  updateCommandApplied,
+  updateCommandRejected,
+  updateSessionApproval,
+  updateSessionBlocker,
+  updateSessionNextOwner,
+  updateSessionStatus,
+} from './store-rows';
+
+// ---------------------------------------------------------------------------
+// Supervision command — public entrypoint
+// ---------------------------------------------------------------------------
+
+export interface SessionCommandArgs {
+  sessionId: string;
+  campaignRoot: string;
+  command: SupervisionCommand;
+  actor: string;
+  payloadJson: string;
+  seatManifestOverride?: string;
+}
+
+export async function issueSupervisionCommand(
+  args: SessionCommandArgs,
+  deps: SupervisionDeps,
+): Promise<SupervisionCommandRecord> {
+  // Seat manifest load is a sanity check; per-command authorization beyond
+  // existence is currently a Phase 2 concern (no seat-gated commands yet).
+  await loadSeatManifest(args.seatManifestOverride);
+
+  const paths = supervisionRuntimePaths(args.campaignRoot);
+  const db = deps.openSqlite(paths.sqlitePath);
+  try {
+    applySupervisionSchema(db);
+    const session = loadSession(db, args.sessionId);
+    const now = deps.now().toISOString();
+
+    const commandId = deps.randomId();
+    const commandRecord: SupervisionCommandRecord = {
+      commandId,
+      sessionId: args.sessionId,
+      turnId: session.currentTurnId,
+      issuedBy: args.actor,
+      command: args.command,
+      payloadJson: args.payloadJson,
+      status: 'queued',
+      issuedAt: now,
+      appliedAt: null,
+      rejectionReason: null,
+    };
+
+    const queuedEvent = buildEvent(deps, {
+      eventType: 'command.queued',
+      sessionId: args.sessionId,
+      turnId: session.currentTurnId,
+      commandId,
+      actor: args.actor,
+      audience: 'all',
+      at: now,
+      payload: {
+        command: args.command,
+        issuedBy: args.actor,
+        turnId: session.currentTurnId,
+        payloadJson: args.payloadJson,
+        issuedAt: now,
+      },
+    });
+
+    // Apply is a pure function of the pre-command session state.
+    const outcome = applyCommand(session, args.command, args.payloadJson, now);
+
+    if (outcome.status === 'rejected') {
+      const reason = outcome.reason ?? 'unknown';
+      const rejectedEvent = buildEvent(deps, {
+        eventType: 'command.rejected',
+        sessionId: args.sessionId,
+        turnId: session.currentTurnId,
+        commandId,
+        actor: 'system',
+        audience: 'all',
+        at: now,
+        payload: { command: args.command, rejectedAt: now, reason },
+      });
+
+      // Events first (canonical), then SQLite mirror in a single transaction.
+      await appendSupervisionEvent(paths.eventsPath, queuedEvent);
+      await appendSupervisionEvent(paths.eventsPath, rejectedEvent);
+
+      withSupervisionTransaction(db, () => {
+        insertCommandRow(db, commandRecord);
+        insertEventRow(db, queuedEvent);
+        updateCommandRejected(db, commandId, now, reason);
+        insertEventRow(db, rejectedEvent);
+      });
+
+      // Per the Phase D addendum rule #4 (projection only on state change):
+      // rejection leaves session state unchanged — no projection re-render.
+      return {
+        ...commandRecord,
+        status: 'rejected',
+        appliedAt: now,
+        rejectionReason: reason,
+      };
+    }
+
+    // Applied path — pre-compute all events, append in order, then one txn.
+    const appliedEvent = buildEvent(deps, {
+      eventType: 'command.applied',
+      sessionId: args.sessionId,
+      turnId: session.currentTurnId,
+      commandId,
+      actor: 'system',
+      audience: 'all',
+      at: now,
+      payload: {
+        command: args.command,
+        appliedAt: now,
+        resultingState: outcome.resultingState ?? {},
+      },
+    });
+
+    const statusChanged = !!(outcome.statusTo && outcome.statusTo !== session.status);
+    const nextOwnerChanged =
+      outcome.nextOwnerTo !== undefined && outcome.nextOwnerTo !== session.nextOwnerHint;
+
+    const statusEvent = statusChanged
+      ? buildEvent(deps, {
+          eventType: 'session.status_changed',
+          sessionId: args.sessionId,
+          turnId: null,
+          commandId,
+          actor: 'system',
+          audience: 'all',
+          at: now,
+          payload: {
+            from: session.status,
+            to: outcome.statusTo,
+            reason: `command:${args.command}`,
+          },
+        })
+      : null;
+    const nextOwnerEvent = nextOwnerChanged
+      ? buildEvent(deps, {
+          eventType: 'session.next_owner_changed',
+          sessionId: args.sessionId,
+          turnId: null,
+          commandId,
+          actor: 'system',
+          audience: 'all',
+          at: now,
+          payload: { from: session.nextOwnerHint, to: outcome.nextOwnerTo },
+        })
+      : null;
+
+    // Events first (canonical) in declared order, then one SQLite txn.
+    await appendSupervisionEvent(paths.eventsPath, queuedEvent);
+    await appendSupervisionEvent(paths.eventsPath, appliedEvent);
+    if (statusEvent) await appendSupervisionEvent(paths.eventsPath, statusEvent);
+    if (nextOwnerEvent) await appendSupervisionEvent(paths.eventsPath, nextOwnerEvent);
+
+    withSupervisionTransaction(db, () => {
+      insertCommandRow(db, commandRecord);
+      insertEventRow(db, queuedEvent);
+      updateCommandApplied(db, commandId, now);
+      insertEventRow(db, appliedEvent);
+      if (statusEvent && outcome.statusTo) {
+        updateSessionStatus(db, args.sessionId, outcome.statusTo, now);
+        insertEventRow(db, statusEvent);
+      }
+      if (nextOwnerEvent) {
+        updateSessionNextOwner(db, args.sessionId, outcome.nextOwnerTo ?? null, now);
+        insertEventRow(db, nextOwnerEvent);
+      }
+      if (outcome.resultingState?.approvedNextTurnJson !== undefined) {
+        updateSessionApproval(db, args.sessionId, outcome.resultingState.approvedNextTurnJson, now);
+      }
+      if (outcome.resultingState?.lastBlockerJson !== undefined) {
+        updateSessionBlocker(db, args.sessionId, outcome.resultingState.lastBlockerJson, now);
+      }
+    });
+
+    const sessionNow = loadSession(db, args.sessionId);
+    const applied: SupervisionCommandRecord = {
+      ...commandRecord,
+      status: 'applied',
+      appliedAt: now,
+    };
+    await writeLatestState(paths.latestStatePath, sessionNow, loadCurrentTurn(db, sessionNow));
+    await renderProjection(
+      deps,
+      paths,
+      sessionNow,
+      loadCurrentTurn(db, sessionNow),
+      loadPendingCommands(db, args.sessionId),
+    );
+    return applied;
+  } finally {
+    db.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command application (pure) — switch on `command`, validate payload,
+// produce an outcome. No I/O, no state mutation beyond the returned plan.
+// ---------------------------------------------------------------------------
+
+interface CommandApplyOutcome {
+  status: 'applied' | 'rejected';
+  reason?: string;
+  statusTo?: SessionStatus;
+  nextOwnerTo?: string | null;
+  resultingState?: {
+    approvedNextTurnJson?: string | null;
+    lastBlockerJson?: string | null;
+  };
+}
+
+function applyCommand(
+  session: SupervisionSession,
+  command: SupervisionCommand,
+  payloadJson: string,
+  now: string,
+): CommandApplyOutcome {
+  switch (command) {
+    case 'status':
+      return { status: 'applied' };
+
+    case 'pause':
+      if (session.status !== 'running') {
+        return {
+          status: 'rejected',
+          reason: `pause requires status=running (current=${session.status})`,
+        };
+      }
+      return { status: 'applied', statusTo: 'paused' };
+
+    case 'resume':
+      if (session.status === 'paused') {
+        return { status: 'applied', statusTo: 'running' };
+      }
+      if (session.status === 'awaiting_human' && session.approvedNextTurnJson) {
+        return { status: 'applied', statusTo: 'running' };
+      }
+      return {
+        status: 'rejected',
+        reason:
+          session.status === 'awaiting_human'
+            ? 'resume from awaiting_human requires prior approve_next_turn'
+            : `resume requires status=paused or awaiting_human+approval (current=${session.status})`,
+      };
+
+    case 'stop':
+      if (session.status === 'closed') {
+        return { status: 'rejected', reason: 'cannot stop a closed session' };
+      }
+      return {
+        status: 'applied',
+        statusTo: 'awaiting_human',
+        resultingState: { approvedNextTurnJson: null },
+      };
+
+    case 'mark_blocked': {
+      const parsed = tryParse(payloadJson);
+      if (!parsed || typeof parsed !== 'object') {
+        return { status: 'rejected', reason: 'mark_blocked requires a JSON object payload' };
+      }
+      const obj = parsed as Partial<BlockerPayload>;
+      if (!obj.reason || typeof obj.reason !== 'string') {
+        return { status: 'rejected', reason: 'mark_blocked payload requires "reason" string' };
+      }
+      const blocker: BlockerPayload = {
+        reason: obj.reason,
+        raisedBy: typeof obj.raisedBy === 'string' ? obj.raisedBy : 'unknown',
+        raisedAt: typeof obj.raisedAt === 'string' ? obj.raisedAt : now,
+        escalationOwner:
+          typeof obj.escalationOwner === 'string' ? obj.escalationOwner : session.escalationOwner,
+        evidenceRefs: Array.isArray(obj.evidenceRefs)
+          ? obj.evidenceRefs.filter((v): v is string => typeof v === 'string')
+          : [],
+      };
+      return {
+        status: 'applied',
+        statusTo: 'blocked',
+        resultingState: { lastBlockerJson: JSON.stringify(blocker) },
+      };
+    }
+
+    case 'request_summary':
+      return { status: 'applied' };
+
+    case 'redirect_owner': {
+      const parsed = tryParse(payloadJson);
+      const next = parsed && typeof parsed === 'object'
+        ? (parsed as { nextOwnerHint?: unknown }).nextOwnerHint
+        : undefined;
+      if (next !== null && typeof next !== 'string') {
+        return {
+          status: 'rejected',
+          reason: 'redirect_owner requires { nextOwnerHint: string | null }',
+        };
+      }
+      return { status: 'applied', nextOwnerTo: next as string | null };
+    }
+
+    case 'approve_next_turn': {
+      const parsed = tryParse(payloadJson);
+      if (!parsed || typeof parsed !== 'object') {
+        return { status: 'rejected', reason: 'approve_next_turn requires a JSON object payload' };
+      }
+      const p = parsed as Partial<ApprovedNextTurnPayload>;
+      const requiredStrings: Array<keyof ApprovedNextTurnPayload> = [
+        'ownerSeat',
+        'allowedActionClass',
+        'projectionPolicy',
+        'issuedBy',
+        'issuedAt',
+      ];
+      for (const key of requiredStrings) {
+        if (typeof p[key] !== 'string') {
+          return { status: 'rejected', reason: `approve_next_turn payload missing "${key}"` };
+        }
+      }
+      if (typeof p.maxDurationMinutes !== 'number') {
+        return { status: 'rejected', reason: 'approve_next_turn payload "maxDurationMinutes" must be a number' };
+      }
+      if (typeof p.requiresHumanApproval !== 'boolean') {
+        return { status: 'rejected', reason: 'approve_next_turn payload "requiresHumanApproval" must be a boolean' };
+      }
+      for (const listKey of ['allowedCommands', 'repoRoots', 'ownedPaths', 'forbiddenPaths', 'verifyCommands'] as const) {
+        if (!Array.isArray(p[listKey])) {
+          return { status: 'rejected', reason: `approve_next_turn payload "${listKey}" must be an array` };
+        }
+      }
+
+      const nextStatus: SessionStatus | undefined =
+        session.status === 'awaiting_human' ? 'running' : undefined;
+      return {
+        status: 'applied',
+        statusTo: nextStatus,
+        resultingState: { approvedNextTurnJson: payloadJson },
+      };
+    }
+
+    case 'escalate_to_human':
+      return { status: 'applied', statusTo: 'awaiting_human' };
+
+    default:
+      return { status: 'rejected', reason: `unknown command: ${String(command)}` };
+  }
+}
+
+function tryParse(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}

package/packages/control/src/supervision/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Supervision runtime errors. Every thrown error from the runtime path uses
+ * this class plus a stable string code; callers (CLI, conformance tests)
+ * dispatch on the code.
+ */
+export class SupervisionRuntimeError extends Error {
+  constructor(
+    message: string,
+    readonly code: string,
+  ) {
+    super(message);
+    this.name = 'SupervisionRuntimeError';
+  }
+}

package/packages/control/src/supervision/event-replay.ts

@@ -0,0 +1,155 @@
+import type {
+  SessionStatus,
+  SupervisionCommand,
+  SupervisionDeps,
+  SupervisionEvent,
+  SupervisionSession,
+  SupervisionTurn,
+  TurnResult,
+} from '../../../protocol/src/index';
+import {
+  clearSessionCurrentTurn,
+  insertCommandRow,
+  insertEventRow,
+  insertSessionRow,
+  insertTurnRow,
+  updateCommandApplied,
+  updateCommandRejected,
+  updateSessionApproval,
+  updateSessionBlocker,
+  updateSessionCurrentTurn,
+  updateSessionNextOwner,
+  updateSessionStatus,
+  updateTurnOnClose,
+} from './store-rows';
+
+/**
+ * Replay a single supervision event against the SQLite mirror.
+ *
+ * Used by `rebuild.ts` when reconstructing SQLite from `events.jsonl` after
+ * a drop/rebuild cycle. Every event type recognized by the runtime must have
+ * a case here; unrecognized types are silently skipped (permissive read).
+ *
+ * After the switch, the event itself is inserted into the `events` table so
+ * the replayed database carries full event provenance.
+ */
+export function replayEvent(
+  db: ReturnType<SupervisionDeps['openSqlite']>,
+  event: SupervisionEvent,
+): void {
+  switch (event.eventType) {
+    case 'session.opened': {
+      const s = event.payload as SupervisionSession;
+      insertSessionRow(db, s);
+      break;
+    }
+    case 'session.status_changed': {
+      const p = event.payload as { from: SessionStatus; to: SessionStatus };
+      updateSessionStatus(db, event.sessionId, p.to, event.at);
+      break;
+    }
+    case 'session.next_owner_changed': {
+      const p = event.payload as { from: string | null; to: string | null };
+      updateSessionNextOwner(db, event.sessionId, p.to, event.at);
+      break;
+    }
+    case 'turn.opened': {
+      const t = event.payload as SupervisionTurn;
+      insertTurnRow(db, t);
+      updateSessionCurrentTurn(db, event.sessionId, t.turnId, event.at);
+      break;
+    }
+    case 'turn.closed': {
+      const p = event.payload as {
+        endedAt: string;
+        result: TurnResult;
+        summary: string;
+        evidenceRefs: string[];
+      };
+      updateTurnOnClose(db, {
+        turnId: event.turnId ?? '',
+        sessionId: event.sessionId,
+        sequenceNo: 0, // unused on close update
+        status: 'closed',
+        ownerSeat: '', // unused on close update
+        allowedActionClass: 'coordination_only', // unused on close update
+        maxDurationMinutes: 0,
+        allowedCommands: [],
+        repoRoots: [],
+        ownedPaths: [],
+        forbiddenPaths: [],
+        verifyCommands: [],
+        requiresHumanApproval: false,
+        projectionPolicy: 'on_state_change',
+        startedAt: event.at,
+        endedAt: p.endedAt,
+        result: p.result,
+        summary: p.summary,
+        evidenceRefs: [...p.evidenceRefs],
+      });
+      clearSessionCurrentTurn(db, event.sessionId, event.at);
+      break;
+    }
+    case 'command.queued': {
+      const p = event.payload as {
+        command: SupervisionCommand;
+        issuedBy: string;
+        turnId: string | null;
+        payloadJson: string;
+        issuedAt: string;
+      };
+      insertCommandRow(db, {
+        commandId: event.commandId ?? '',
+        sessionId: event.sessionId,
+        turnId: p.turnId,
+        issuedBy: p.issuedBy,
+        command: p.command,
+        payloadJson: p.payloadJson,
+        status: 'queued',
+        issuedAt: p.issuedAt,
+        appliedAt: null,
+        rejectionReason: null,
+      });
+      break;
+    }
+    case 'command.applied': {
+      const p = event.payload as {
+        command: SupervisionCommand;
+        appliedAt: string;
+        resultingState?: {
+          approvedNextTurnJson?: string | null;
+          lastBlockerJson?: string | null;
+        };
+      };
+      updateCommandApplied(db, event.commandId ?? '', p.appliedAt);
+      if (p.resultingState?.approvedNextTurnJson !== undefined) {
+        updateSessionApproval(
+          db,
+          event.sessionId,
+          p.resultingState.approvedNextTurnJson,
+          p.appliedAt,
+        );
+      }
+      if (p.resultingState?.lastBlockerJson !== undefined) {
+        updateSessionBlocker(
+          db,
+          event.sessionId,
+          p.resultingState.lastBlockerJson,
+          p.appliedAt,
+        );
+      }
+      break;
+    }
+    case 'command.rejected': {
+      const p = event.payload as { rejectedAt: string; reason: string };
+      updateCommandRejected(db, event.commandId ?? '', p.rejectedAt, p.reason);
+      break;
+    }
+    case 'projection.rendered':
+    case 'rebuild.completed':
+      // No DB state change.
+      break;
+  }
+
+  insertEventRow(db, event);
+}

package/packages/control/src/supervision/events.ts

@@ -0,0 +1,109 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type {
+  SupervisionDeps,
+  SupervisionEvent,
+  SupervisionEventType,
+} from '../../../protocol/src/index';
+
+/**
+ * Canonical JSON serialization for event lines. Keys are emitted in a fixed
+ * order so two runs over the same event produce byte-identical output (this
+ * matters for rebuild determinism).
+ */
+export function serializeEventLine(event: SupervisionEvent): string {
+  const canonical = {
+    event_id: event.eventId,
+    session_id: event.sessionId,
+    turn_id: event.turnId,
+    command_id: event.commandId,
+    event_type: event.eventType,
+    actor: event.actor,
+    audience: event.audience,
+    at: event.at,
+    payload: event.payload ?? null,
+  };
+  return `${JSON.stringify(canonical)}\n`;
+}
+
+/**
+ * Append an event to the JSONL log. Creates the parent directory if missing.
+ * This is the authoritative write path for all supervision state changes
+ * per PHASE1.md; SQLite state is derived from these events and must be
+ * rebuildable from them alone.
+ */
+export async function appendSupervisionEvent(
+  eventsPath: string,
+  event: SupervisionEvent,
+): Promise<void> {
+  await mkdir(dirname(eventsPath), { recursive: true });
+  await appendFile(eventsPath, serializeEventLine(event), 'utf-8');
+}
+
+/**
+ * Read all events from the JSONL log, in file order. Used by session-rebuild
+ * and for test-side correctness checks.
+ */
+export async function readAllSupervisionEvents(eventsPath: string): Promise<SupervisionEvent[]> {
+  let raw: string;
+  try {
+    raw = await readFile(eventsPath, 'utf-8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw err;
+  }
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  return lines.map((line, idx) => {
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } catch (err) {
+      throw new Error(`events.jsonl line ${idx + 1} is not valid JSON: ${String(err)}`);
+    }
+    return {
+      eventId: String(obj.event_id),
+      sessionId: String(obj.session_id),
+      turnId: obj.turn_id === null || obj.turn_id === undefined ? null : String(obj.turn_id),
+      commandId: obj.command_id === null || obj.command_id === undefined ? null : String(obj.command_id),
+      eventType: obj.event_type as SupervisionEvent['eventType'],
+      actor: String(obj.actor),
+      audience: obj.audience as SupervisionEvent['audience'],
+      at: String(obj.at),
+      payload: obj.payload,
+    } satisfies SupervisionEvent;
+  });
+}
+
+/**
+ * Build a `SupervisionEvent` envelope from the caller-supplied fields plus a
+ * fresh `eventId` from `deps.randomId()`. Pure factory — no I/O.
+ *
+ * Used by every runtime writer (session-open, turn-open/close, command-apply,
+ * rebuild, session-read's `projection.rendered` emission) to construct events
+ * with a consistent shape before appending to `events.jsonl`.
+ */
+export function buildEvent(
+  deps: SupervisionDeps,
+  fields: {
+    eventType: SupervisionEventType;
+    sessionId: string;
+    turnId: string | null;
+    commandId: string | null;
+    actor: string;
+    audience: SupervisionEvent['audience'];
+    at: string;
+    payload: unknown;
+  },
+): SupervisionEvent {
+  return {
+    eventId: deps.randomId(),
+    sessionId: fields.sessionId,
+    turnId: fields.turnId,
+    commandId: fields.commandId,
+    eventType: fields.eventType,
+    actor: fields.actor,
+    audience: fields.audience,
+    at: fields.at,
+    payload: fields.payload,
+  };
+}

package/packages/control/src/supervision/index.ts

@@ -0,0 +1,16 @@
+export * from './paths';
+export * from './manifest';
+export * from './action-classes';
+export * from './events';
+export * from './sqlite';
+export * from './sqlite-impl';
+// Split of the former monolithic `session.ts` per the Phase D.7 surgical
+// refactor. Each of these exports the same public surface it previously
+// shared via `./session`; barrel re-exports preserve caller imports.
+export * from './errors';
+export * from './session-open';
+export * from './session-read';
+export * from './turn-open';
+export * from './turn-close';
+export * from './command-apply';
+export * from './rebuild';