@etiquekit/etq 1.0.14 → 1.0.15

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

@@ -1,378 +0,0 @@
-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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,155 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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';