@etiquekit/etq 1.0.13 → 1.0.15

package/packages/control/src/supervision/session-open.ts

@@ -1,131 +0,0 @@
-import { existsSync } from 'node:fs';
-import { appendFile, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import type {
-  SupervisionDeps,
-  SupervisionSession,
-} from '../../../protocol/src/index';
-import { SupervisionRuntimeError } from './errors';
-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 { insertEventRow, insertSessionRow } from './store-rows';
-
-export interface SessionOpenArgs {
-  sessionId: string;
-  campaignRoot: string;
-  topic: string;
-  objective: string;
-  leadSeat: string;
-  responderSeat: string;
-  escalationOwner: string;
-  timeCapMinutes: number;
-  turnCap: number;
-  sourceRefs: string[];
-  seatManifestOverride?: string;
-}
-
-/**
- * Open a new supervision session.
- *
- * Per PHASE1.md canonical ordering: events.jsonl first (rebuild authority),
- * then SQLite mirror inside a single transaction, then artifacts
- * (latest-state.json + projection renders).
- */
-export async function openSupervisionSession(
-  args: SessionOpenArgs,
-  deps: SupervisionDeps,
-): Promise<SupervisionSession> {
-  // Validate seat manifest exists and is well-formed before any state lands.
-  await loadSeatManifest(args.seatManifestOverride);
-
-  const paths = supervisionRuntimePaths(args.campaignRoot);
-  await deps.mkdirp(paths.runtimeDir);
-  await maybeAddGitExclude(args.campaignRoot);
-
-  const db = deps.openSqlite(paths.sqlitePath);
-  try {
-    applySupervisionSchema(db);
-
-    const existing = db.get<{ session_id: string }>(
-      'SELECT session_id FROM sessions WHERE session_id = ?',
-      [args.sessionId],
-    );
-    if (existing) {
-      throw new SupervisionRuntimeError(
-        `session ${args.sessionId} already exists in ${paths.sqlitePath}`,
-        'SESSION_EXISTS',
-      );
-    }
-
-    const now = deps.now().toISOString();
-    const session: SupervisionSession = {
-      sessionId: args.sessionId,
-      campaignRoot: paths.campaignRoot,
-      topic: args.topic,
-      objective: args.objective,
-      status: 'running',
-      leadSeat: args.leadSeat,
-      responderSeat: args.responderSeat,
-      escalationOwner: args.escalationOwner,
-      timeCapMinutes: args.timeCapMinutes,
-      turnCap: args.turnCap,
-      currentTurnId: null,
-      nextOwnerHint: null,
-      approvedNextTurnJson: null,
-      lastBlockerJson: null,
-      sourceRefs: [...args.sourceRefs],
-      createdAt: now,
-      updatedAt: now,
-    };
-
-    // Canonical ordering: events.jsonl first (rebuild authority),
-    // then SQLite mirror inside a single transaction, then artifacts.
-    const event = buildEvent(deps, {
-      eventType: 'session.opened',
-      sessionId: session.sessionId,
-      turnId: null,
-      commandId: null,
-      actor: args.leadSeat,
-      audience: 'all',
-      at: now,
-      payload: session,
-    });
-    await appendSupervisionEvent(paths.eventsPath, event);
-
-    withSupervisionTransaction(db, () => {
-      insertSessionRow(db, session);
-      insertEventRow(db, event);
-    });
-
-    await writeLatestState(paths.latestStatePath, session, null);
-    await renderProjection(deps, paths, session, null, []);
-
-    return session;
-  } finally {
-    db.close();
-  }
-}
-
-/**
- * If the campaign root is a git worktree, add `.etiquette/runtime/`
- * to `.git/info/exclude` so the hot state never becomes an accidental
- * tracked change. Best-effort — unwritable excludes do not fail session-open.
- */
-async function maybeAddGitExclude(campaignRoot: string): Promise<void> {
-  const excludePath = join(campaignRoot, '.git', 'info', 'exclude');
-  if (!existsSync(excludePath)) return;
-  try {
-    const existing = await readFile(excludePath, 'utf-8');
-    const line = '.etiquette/runtime/';
-    if (!existing.split('\n').some((l) => l.trim() === line)) {
-      const newline = existing.endsWith('\n') ? '' : '\n';
-      await appendFile(excludePath, `${newline}${line}\n`);
-    }
-  } catch {
-    // Best-effort; if .git/info/exclude is unwritable we do not fail session-open.
-  }
-}

package/packages/control/src/supervision/session-read.ts

@@ -1,99 +0,0 @@
-import type {
-  SupervisionDeps,
-  SupervisionProjection,
-} from '../../../protocol/src/index';
-import { appendSupervisionEvent, buildEvent } from './events';
-import { supervisionRuntimePaths } from './paths';
-import { renderProjection } from './projection';
-import { applySupervisionSchema } from './sqlite';
-import { withSupervisionTransaction } from './sqlite-impl';
-import {
-  insertEventRow,
-  loadCurrentTurn,
-  loadPendingCommands,
-  loadSession,
-} from './store-rows';
-
-export interface SessionStatusArgs {
-  sessionId: string;
-  campaignRoot: string;
-}
-
-/**
- * Read the current session snapshot (pure read; no state change, no
- * projection render, no event emit). Used by `session-status` CLI and
- * conformance tests that need to observe state without triggering a
- * projection cycle.
- */
-export async function readSupervisionSession(
-  args: SessionStatusArgs,
-  deps: SupervisionDeps,
-): Promise<SupervisionProjection> {
-  const paths = supervisionRuntimePaths(args.campaignRoot);
-  const db = deps.openSqlite(paths.sqlitePath);
-  try {
-    applySupervisionSchema(db);
-    const session = loadSession(db, args.sessionId);
-    const currentTurn = loadCurrentTurn(db, session);
-    const pendingCommands = loadPendingCommands(db, args.sessionId);
-    return {
-      sessionId: session.sessionId,
-      renderedAt: deps.now().toISOString(),
-      sessionSnapshot: session,
-      currentTurn,
-      pendingCommands,
-    };
-  } finally {
-    db.close();
-  }
-}
-
-export interface SessionProjectArgs {
-  sessionId: string;
-  campaignRoot: string;
-}
-
-/**
- * Render the projection artifacts (STATUS_BOARD.md + seat channels +
- * latest-projection.json) from current SQLite state, and emit a
- * `projection.rendered` event so replay stays complete.
- *
- * Idempotent per PHASE1.md § Projection rules — rerunning does not duplicate
- * channel entries (meta-events like `projection.rendered` are filtered from
- * seat-channel output by the adapter).
- */
-export async function projectSupervisionSession(
-  args: SessionProjectArgs,
-  deps: SupervisionDeps,
-): Promise<SupervisionProjection> {
-  const paths = supervisionRuntimePaths(args.campaignRoot);
-  const db = deps.openSqlite(paths.sqlitePath);
-  try {
-    applySupervisionSchema(db);
-    const session = loadSession(db, args.sessionId);
-    const currentTurn = loadCurrentTurn(db, session);
-    const pendingCommands = loadPendingCommands(db, args.sessionId);
-    const projection = await renderProjection(deps, paths, session, currentTurn, pendingCommands);
-
-    // Emit projection.rendered event (after render so we know the render succeeded).
-    const renderedAt = projection.renderedAt;
-    const event = buildEvent(deps, {
-      eventType: 'projection.rendered',
-      sessionId: session.sessionId,
-      turnId: session.currentTurnId,
-      commandId: null,
-      actor: 'system',
-      audience: 'all',
-      at: renderedAt,
-      payload: { renderedAt },
-    });
-    await appendSupervisionEvent(paths.eventsPath, event);
-    withSupervisionTransaction(db, () => {
-      insertEventRow(db, event);
-    });
-
-    return projection;
-  } finally {
-    db.close();
-  }
-}

package/packages/control/src/supervision/sqlite-impl.ts

@@ -1,71 +0,0 @@
-import { Database } from 'bun:sqlite';
-import type { SupervisionSqliteHandle } from '../../../protocol/src/index';
-
-/**
- * Wrap a synchronous SQLite mutation bundle in a `BEGIN IMMEDIATE` /
- * `COMMIT` transaction. On throw, issue `ROLLBACK` best-effort and rethrow.
- *
- * Per PHASE1.md and the Phase D addendum: session row + event row +
- * command row updates should commit atomically on the SQLite side for
- * each logical command operation. Events in `events.jsonl` remain the
- * canonical rebuild authority; SQLite is a derived mirror.
- *
- * Do NOT wrap PRAGMA statements or DDL inside this helper — apply the
- * schema before opening a transaction.
- */
-export function withSupervisionTransaction<T>(
-  handle: SupervisionSqliteHandle,
-  fn: () => T,
-): T {
-  handle.run('BEGIN IMMEDIATE');
-  try {
-    const result = fn();
-    handle.run('COMMIT');
-    return result;
-  } catch (err) {
-    try {
-      handle.run('ROLLBACK');
-    } catch {
-      // Best-effort rollback; the real error is re-thrown below.
-    }
-    throw err;
-  }
-}
-
-/**
- * Open (or create) a SQLite database at `path` and wrap it as a
- * SupervisionSqliteHandle. Multi-statement DDL (schema init) goes through
- * `.exec()`; single-statement parameterized queries go through prepared
- * statements via `.query()`.
- *
- * Usage in tests: pass ":memory:" for an in-process DB without filesystem.
- */
-export function openSupervisionSqlite(path: string): SupervisionSqliteHandle {
-  const db = new Database(path);
-  return {
-    run(sql: string, params?: unknown[]): void {
-      if (!params || params.length === 0) {
-        db.exec(sql);
-        return;
-      }
-      db.query(sql).run(...(params as never[]));
-    },
-    all<T = unknown>(sql: string, params?: unknown[]): T[] {
-      const stmt = db.query(sql);
-      if (!params || params.length === 0) {
-        return stmt.all() as T[];
-      }
-      return stmt.all(...(params as never[])) as T[];
-    },
-    get<T = unknown>(sql: string, params?: unknown[]): T | undefined {
-      const stmt = db.query(sql);
-      const row = !params || params.length === 0
-        ? stmt.get()
-        : stmt.get(...(params as never[]));
-      return (row as T | null) ?? undefined;
-    },
-    close(): void {
-      db.close();
-    },
-  };
-}

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

@@ -1,121 +0,0 @@
-import type { SupervisionSqliteHandle } from '../../../protocol/src/index';
-
-/**
- * SQLite schema for Phase 1 supervision hot state. See
- * etiquette/internal/docs/supervision/PHASE1.md for column semantics.
- *
- * The schema is applied once on session-open. Re-applying is a no-op
- * (`CREATE TABLE IF NOT EXISTS`). WAL mode is enabled unconditionally.
- */
-export const SUPERVISION_SCHEMA_SQL = `
-PRAGMA journal_mode = WAL;
-
-CREATE TABLE IF NOT EXISTS sessions (
-  session_id TEXT PRIMARY KEY,
-  campaign_root TEXT NOT NULL,
-  topic TEXT NOT NULL,
-  objective TEXT NOT NULL,
-  status TEXT NOT NULL CHECK (status IN ('running','paused','blocked','awaiting_human','closed')),
-  lead_seat TEXT NOT NULL,
-  responder_seat TEXT NOT NULL,
-  escalation_owner TEXT NOT NULL,
-  time_cap_minutes INTEGER NOT NULL,
-  turn_cap INTEGER NOT NULL,
-  current_turn_id TEXT,
-  next_owner_hint TEXT,
-  approved_next_turn_json TEXT,
-  last_blocker_json TEXT,
-  source_refs_json TEXT NOT NULL,
-  created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS turns (
-  turn_id TEXT PRIMARY KEY,
-  session_id TEXT NOT NULL REFERENCES sessions(session_id),
-  sequence_no INTEGER NOT NULL,
-  status TEXT NOT NULL CHECK (status IN ('open','closed')),
-  owner_seat TEXT NOT NULL,
-  allowed_action_class TEXT NOT NULL CHECK (allowed_action_class IN (
-    'coordination_only','read_only_local','bounded_verification','bounded_product_mutation','human_only'
-  )),
-  max_duration_minutes INTEGER NOT NULL,
-  allowed_commands_json TEXT NOT NULL,
-  repo_roots_json TEXT NOT NULL,
-  owned_paths_json TEXT NOT NULL,
-  forbidden_paths_json TEXT NOT NULL,
-  verify_commands_json TEXT NOT NULL,
-  requires_human_approval INTEGER NOT NULL CHECK (requires_human_approval IN (0,1)),
-  projection_policy TEXT NOT NULL CHECK (projection_policy IN ('on_state_change','on_command_only')),
-  started_at TEXT NOT NULL,
-  ended_at TEXT,
-  result TEXT CHECK (result IS NULL OR result IN ('done','blocked','handed_off','stopped','timed_out')),
-  summary TEXT,
-  evidence_refs_json TEXT NOT NULL,
-  UNIQUE (session_id, sequence_no)
-);
-
-CREATE TABLE IF NOT EXISTS commands (
-  command_id TEXT PRIMARY KEY,
-  session_id TEXT NOT NULL REFERENCES sessions(session_id),
-  turn_id TEXT REFERENCES turns(turn_id),
-  issued_by TEXT NOT NULL,
-  command TEXT NOT NULL CHECK (command IN (
-    'status','pause','resume','stop','approve_next_turn','redirect_owner',
-    'request_summary','mark_blocked','escalate_to_human'
-  )),
-  payload_json TEXT NOT NULL,
-  status TEXT NOT NULL CHECK (status IN ('queued','applied','rejected','expired')),
-  issued_at TEXT NOT NULL,
-  applied_at TEXT,
-  rejection_reason TEXT
-);
-
-CREATE TABLE IF NOT EXISTS events (
-  seq INTEGER PRIMARY KEY AUTOINCREMENT,
-  event_id TEXT UNIQUE NOT NULL,
-  session_id TEXT NOT NULL,
-  turn_id TEXT,
-  command_id TEXT,
-  event_type TEXT NOT NULL CHECK (event_type IN (
-    'session.opened','session.status_changed','session.next_owner_changed',
-    'turn.opened','turn.closed',
-    'command.queued','command.applied','command.rejected',
-    'projection.rendered','rebuild.completed'
-  )),
-  actor TEXT NOT NULL,
-  audience TEXT NOT NULL,
-  at TEXT NOT NULL,
-  payload_json TEXT NOT NULL
-);
-
-CREATE VIEW IF NOT EXISTS latest_session_state AS
-SELECT
-  s.*,
-  t.turn_id AS current_turn_id_verified,
-  t.sequence_no AS current_turn_sequence_no,
-  t.status AS current_turn_status,
-  t.owner_seat AS current_turn_owner
-FROM sessions s
-LEFT JOIN turns t ON t.turn_id = s.current_turn_id;
-
-CREATE VIEW IF NOT EXISTS latest_turn_state AS
-SELECT * FROM turns
-WHERE status = 'open'
-ORDER BY started_at DESC;
-
-CREATE VIEW IF NOT EXISTS pending_commands AS
-SELECT * FROM commands
-WHERE status = 'queued'
-ORDER BY issued_at ASC;
-`;
-
-/**
- * Apply the schema to a SQLite handle. Idempotent; safe to call on every
- * session-open.
- */
-export function applySupervisionSchema(handle: SupervisionSqliteHandle): void {
-  // SQLite CLI wrappers generally accept multi-statement SQL on run(); this
-  // matches the shape used by bun:sqlite and better-sqlite3's .exec().
-  handle.run(SUPERVISION_SCHEMA_SQL);
-}