@etiquekit/etq 1.0.12 → 1.0.13

package/packages/control/src/project.ts

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { validateProjectManifest } from '../../protocol/src/index';
+import type {
+  Dependency,
+  ProjectManifest,
+  Slice,
+  SliceBlueprint,
+  SliceTask,
+  SliceTaskBlueprint,
+  Surface,
+} from '../../protocol/src/types';
+import { now, readJson, sanitize } from './fs';
+
+export async function loadProjectManifest(path?: string): Promise<ProjectManifest> {
+  const target = resolve(path ?? 'discipline.project.json');
+  const manifest = await readJson<ProjectManifest>(target);
+  const manifestDir = dirname(target);
+  const resolvePath = (value?: string): string | undefined => {
+    if (!value) return value;
+    return isAbsolute(value) ? value : resolve(manifestDir, value);
+  };
+  manifest.projectRoot = resolvePath(manifest.projectRoot)!;
+  manifest.handshakeStorePath = resolvePath(manifest.handshakeStorePath)!;
+  manifest.defaultWorktreeRoot = resolvePath(manifest.defaultWorktreeRoot)!;
+  if (manifest.logixRepoRoot) {
+    manifest.logixRepoRoot = resolvePath(manifest.logixRepoRoot);
+  }
+  for (const surface of Object.values(manifest.surfaces)) {
+    surface.repoRoots = surface.repoRoots.map((root) => resolvePath(root)!);
+  }
+  for (const slice of Object.values(manifest.slices)) {
+    if (slice.repoRoots) {
+      slice.repoRoots = slice.repoRoots.map((root) => resolvePath(root)!);
+    }
+    for (const task of Object.values(slice.tasks)) {
+      if (!task?.repoRoots) continue;
+      task.repoRoots = task.repoRoots.map((root) => resolvePath(root)!);
+    }
+  }
+  validateProjectManifest(manifest);
+  return manifest;
+}
+
+export function sliceStatePath(project: ProjectManifest, sliceId: string): string {
+  return join(project.handshakeStorePath, '.discipline', 'slices', `${sliceId}.json`);
+}
+
+export async function loadSlice(project: ProjectManifest, sliceId: string): Promise<Slice | null> {
+  const path = sliceStatePath(project, sliceId);
+  if (!existsSync(path)) return null;
+  return readJson<Slice>(path);
+}
+
+function resolveBlueprint(project: ProjectManifest, sliceId: string): SliceBlueprint {
+  const blueprint = project.slices[sliceId];
+  if (!blueprint) {
+    throw new Error(`unknown slice: ${sliceId}`);
+  }
+  return blueprint;
+}
+
+function buildTask(project: ProjectManifest, sliceId: string, scrutinyId: string, surface: Surface, task: SliceTaskBlueprint): SliceTask {
+  const defaults = project.surfaces[surface];
+  const taskId = `${sanitize(sliceId)}-${surface}`;
+  const ownedPaths = task.ownedPaths ?? defaults.ownedPaths;
+  const forbiddenPaths = task.forbiddenPaths ?? defaults.forbiddenPaths;
+  const checks = task.checks ?? defaults.checks;
+  const evidenceFiles = task.evidenceFiles ?? defaults.evidenceFiles;
+  const repoRoots = task.repoRoots ?? defaults.repoRoots;
+  const owner = task.owner ?? defaults.owner;
+  const workerRole = task.workerRole ?? defaults.workerRole;
+  return {
+    taskId,
+    surface,
+    title: task.title,
+    summary: task.summary,
+    scrutinyId,
+    state: 'incoming',
+    owner,
+    workerRole,
+    bounds: {
+      repoRoots,
+      ownedPaths,
+      forbiddenPaths,
+      checks,
+      evidenceFiles,
+    },
+    dependencies: task.dependencies ?? ([] as Dependency[]),
+    transitions: [
+      {
+        state: 'incoming',
+        actorId: owner,
+        at: now(),
+        note: 'task created from slice blueprint',
+      },
+    ],
+  };
+}
+
+export function buildSlice(project: ProjectManifest, sliceId: string, surfaces: Surface[]): Slice {
+  const blueprint = resolveBlueprint(project, sliceId);
+  const tasks = surfaces.map((surface) => {
+    const taskBlueprint = blueprint.tasks[surface];
+    if (!taskBlueprint) {
+      throw new Error(`slice ${sliceId} missing task blueprint for surface ${surface}`);
+    }
+    return buildTask(project, sliceId, blueprint.scrutinyId, surface, taskBlueprint);
+  });
+
+  return {
+    schemaVersion: 'discipline-slice.v1',
+    sliceId,
+    projectId: project.projectId,
+    title: blueprint.title,
+    objective: blueprint.objective,
+    scrutinyId: blueprint.scrutinyId,
+    state: 'planned',
+    repoRoots: blueprint.repoRoots ?? [project.projectRoot],
+    handshakeStorePath: project.handshakeStorePath,
+    tasks,
+    transitions: [
+      {
+        state: 'planned',
+        actorId: 'etiquette',
+        at: now(),
+        note: 'slice initialized',
+      },
+    ],
+    createdAt: now(),
+    updatedAt: now(),
+  };
+}
+
+export function resolveWorktreePath(project: ProjectManifest, sliceId: string, task: SliceTask): string {
+  const template = project.surfaces[task.surface].worktreeTemplate;
+  return template
+    .replace('{root}', project.defaultWorktreeRoot)
+    .replace('{sliceId}', sanitize(sliceId))
+    .replace('{surface}', task.surface);
+}

package/packages/control/src/projection/local-ledger-view.ts

@@ -0,0 +1,373 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+type JsonRecord = Record<string, unknown>;
+
+export interface LocalEvent extends JsonRecord {
+  seq: number;
+  schema: 'local-event.v0';
+  event_ref: string;
+  created_at: string;
+  type: string;
+}
+
+export type LocalLedgerViewKind = 'all' | 'events' | 'packets';
+
+export interface LocalLedgerViewOptions {
+  since?: string | number | null;
+  until?: string | number | null;
+  lane?: string | null;
+  seat?: string | null;
+  from?: string | null;
+  to?: string | null;
+  role?: string | null;
+  action?: string | null;
+  match?: string | null;
+  kind?: LocalLedgerViewKind;
+  limit?: number;
+  computedAt?: string;
+}
+
+export interface LocalLedgerViewRow {
+  kind: 'event' | 'packet';
+  seq: number | null;
+  event_ref: string | null;
+  created_at: string | null;
+  type: string | null;
+  role: string | null;
+  lane: string | null;
+  from: string | null;
+  to: string | null;
+  next_owner: string | null;
+  packet_ref: string | null;
+  requires_ack: boolean | null;
+  verdict: string | null;
+  status_effect: string | null;
+  topic_hints: string[];
+  in_reply_to: string | null;
+  parent_event_ref: string | null;
+  parent_event_seq: number | null;
+  mode: string | null;
+  packet_tier: string | null;
+  text: string;
+}
+
+export interface LocalLedgerView {
+  schema: 'local-ledger-view.v0';
+  watermark: {
+    latest_event_ref: string;
+    latest_seq: number;
+    commit_sha: string;
+    event_log_hash: string;
+    computed_at: string;
+  };
+  filters: JsonRecord;
+  boundary: string;
+  events_matched: number;
+  packets_matched: number;
+  events: LocalLedgerViewRow[];
+  packets: LocalLedgerViewRow[];
+  authority_boundary: {
+    stdout_only: true;
+    rebuildable_projection: true;
+    can_authorize: false;
+    can_assign: false;
+    can_close: false;
+    can_merge: false;
+    can_mutate_bus: false;
+    can_write_global_ledger: false;
+  };
+}
+
+function eventPath(root: string): string {
+  return join(root, '.etiquette', 'events', 'local.ndjson');
+}
+
+function relativeRef(root: string, path: string): string {
+  const rel = relative(root, resolve(path));
+  if (rel.length === 0 || rel.startsWith('..') || rel.includes('\\')) {
+    throw new Error(`path must stay inside project root: ${path}`);
+  }
+  return rel;
+}
+
+function asRecord(value: unknown, label: string): JsonRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as JsonRecord;
+}
+
+function stringField(record: JsonRecord, field: string): string | undefined {
+  const value = record[field];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function boolField(record: JsonRecord, field: string): boolean | undefined {
+  const value = record[field];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function numberField(record: JsonRecord, field: string): number | undefined {
+  const value = record[field];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function stringListField(record: JsonRecord, field: string): string[] {
+  const value = record[field];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0).map((item) => item.trim());
+}
+
+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 listJsonFiles(dir: string): Promise<string[]> {
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.json')).map((entry) => join(dir, entry.name));
+}
+
+async function readJsonIfExists<T>(path: string, fallback: T): Promise<T> {
+  const raw = await readTextIfExists(path);
+  return raw ? JSON.parse(raw) as T : fallback;
+}
+
+async function readEventsIfInitialized(root: string): Promise<LocalEvent[]> {
+  const raw = await readTextIfExists(eventPath(root));
+  if (!raw) return [];
+  return raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as LocalEvent);
+}
+
+function parseBusSeqBound(raw: string | number | null | undefined, key: string): number | null {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw === 'number') {
+    if (!Number.isFinite(raw) || raw < 0) throw new Error(`--${key} must be a non-negative event sequence`);
+    return raw;
+  }
+  const normalized = raw.startsWith('local://event/') ? raw.slice('local://event/'.length) : raw;
+  const n = Number.parseInt(normalized, 10);
+  if (!Number.isFinite(n) || n < 0) throw new Error(`--${key} must be a non-negative event sequence`);
+  return n;
+}
+
+function eventLogHash(raw: string | null): string {
+  return `sha256:${createHash('sha256').update(raw ?? '').digest('hex')}`;
+}
+
+function currentGitCommit(root: string): string {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf-8' });
+  if (result.status !== 0) return 'unavailable';
+  return result.stdout.trim() || 'unavailable';
+}
+
+function rowText(row: LocalLedgerViewRow): string {
+  const parts = [
+    row.event_ref ?? row.packet_ref ?? row.kind,
+    row.type,
+    row.role ? `role=${row.role}` : null,
+    row.lane ? `lane=${row.lane}` : null,
+    row.from ? `from=${row.from}` : null,
+    row.to ? `to=${row.to}` : null,
+    row.next_owner ? `next_owner=${row.next_owner}` : null,
+    row.requires_ack === true ? 'requires_ack=true' : null,
+    row.packet_ref ? `packet_ref=${row.packet_ref}` : null,
+    row.verdict ? `verdict=${row.verdict}` : null,
+    row.status_effect && row.status_effect !== 'none' ? `status_effect=${row.status_effect}` : null,
+    row.topic_hints.length > 0 ? `topic_hints=${row.topic_hints.join(',')}` : null,
+    row.in_reply_to ? `in_reply_to=${row.in_reply_to}` : null,
+  ].filter((value): value is string => value !== null && value !== undefined && value.length > 0);
+  return parts.join(' ');
+}
+
+function eventToBusViewRow(event: LocalEvent): LocalLedgerViewRow {
+  const actor = typeof event.actor === 'string' ? event.actor : null;
+  const row: LocalLedgerViewRow = {
+    kind: 'event',
+    seq: event.seq,
+    event_ref: event.event_ref,
+    created_at: event.created_at,
+    type: event.type,
+    role: typeof event.role === 'string' ? event.role : null,
+    lane: typeof event.lane === 'string' ? event.lane : null,
+    from: typeof event.from === 'string' ? event.from : actor,
+    to: typeof event.to === 'string' ? event.to : null,
+    next_owner: typeof event.next_owner === 'string' ? event.next_owner : null,
+    packet_ref: typeof event.packet_ref === 'string' ? event.packet_ref : null,
+    requires_ack: typeof event.requires_ack === 'boolean' ? event.requires_ack : null,
+    verdict: typeof event.verdict === 'string' ? event.verdict : null,
+    status_effect: typeof event.status_effect === 'string' ? event.status_effect : null,
+    topic_hints: stringListField(event, 'topic_hints'),
+    in_reply_to: typeof event.in_reply_to === 'string' ? event.in_reply_to : null,
+    parent_event_ref: typeof event.parent_event_ref === 'string' ? event.parent_event_ref : null,
+    parent_event_seq: numberField(event, 'parent_event_seq') ?? null,
+    mode: typeof event.mode === 'string' ? event.mode : null,
+    packet_tier: typeof event.packet_tier === 'string' ? event.packet_tier : null,
+    text: '',
+  };
+  return { ...row, text: rowText(row) };
+}
+
+function packetToBusViewRow(packet: JsonRecord, packetRef: string, eventSeq: number | null): LocalLedgerViewRow {
+  const row: LocalLedgerViewRow = {
+    kind: 'packet',
+    seq: eventSeq,
+    event_ref: null,
+    created_at: stringField(packet, 'created_at') ?? null,
+    type: stringField(packet, 'action') ?? stringField(packet, 'type') ?? null,
+    role: stringField(packet, 'role') ?? null,
+    lane: stringField(packet, 'lane') ?? null,
+    from: stringField(packet, 'from') ?? null,
+    to: stringField(packet, 'to') ?? null,
+    next_owner: stringField(packet, 'next_owner') ?? null,
+    packet_ref: packetRef,
+    requires_ack: boolField(packet, 'requires_ack') ?? null,
+    verdict: stringField(packet, 'verdict') ?? null,
+    status_effect: stringField(packet, 'status_effect') ?? null,
+    topic_hints: stringListField(packet, 'topic_hints'),
+    in_reply_to: stringField(packet, 'in_reply_to') ?? null,
+    parent_event_ref: stringField(packet, 'parent_event_ref') ?? null,
+    parent_event_seq: numberField(packet, 'parent_event_seq') ?? null,
+    mode: stringField(packet, 'mode') ?? null,
+    packet_tier: stringField(packet, 'packet_tier') ?? null,
+    text: '',
+  };
+  return { ...row, text: rowText(row) };
+}
+
+async function readPacketRows(root: string, events: LocalEvent[]): Promise<LocalLedgerViewRow[]> {
+  const packetDir = join(root, 'docs', 'work', 'packets');
+  if (!existsSync(packetDir)) return [];
+  const files = await listJsonFiles(packetDir);
+  const eventSeqByPacketRef = new Map(
+    events
+      .filter((event) => typeof event.packet_ref === 'string')
+      .map((event) => [String(event.packet_ref), event.seq] as const),
+  );
+  const rows: LocalLedgerViewRow[] = [];
+  for (const path of files.sort()) {
+    const packetRef = relativeRef(root, path);
+    const packet = asRecord(await readJsonIfExists<JsonRecord>(path, {}), 'local packet');
+    rows.push(packetToBusViewRow(packet, packetRef, eventSeqByPacketRef.get(packetRef) ?? null));
+  }
+  return rows;
+}
+
+function rowMatchesBusView(row: LocalLedgerViewRow, options: LocalLedgerViewOptions): boolean {
+  const since = parseBusSeqBound(options.since, 'since');
+  const until = parseBusSeqBound(options.until, 'until');
+  if (since !== null && (row.seq === null || row.seq < since)) return false;
+  if (until !== null && (row.seq === null || row.seq > until)) return false;
+
+  if (options.lane && row.lane !== options.lane) return false;
+  if (options.role && row.role !== options.role) return false;
+  if (options.action && row.type !== options.action) return false;
+  if (options.from && row.from !== options.from) return false;
+  if (options.to && row.to !== options.to && row.next_owner !== options.to) return false;
+  if (options.seat && row.from !== options.seat && row.to !== options.seat && row.next_owner !== options.seat && !row.text.includes(options.seat)) return false;
+  if (options.match && !row.text.toLowerCase().includes(options.match.toLowerCase())) return false;
+
+  return true;
+}
+
+export async function buildLocalLedgerView(root: string, options: LocalLedgerViewOptions = {}): Promise<LocalLedgerView> {
+  const rawEventLog = await readTextIfExists(eventPath(root));
+  const events = await readEventsIfInitialized(root);
+  const packetRows = await readPacketRows(root, events);
+  const limit = options.limit ?? 20;
+  const kind = options.kind ?? 'all';
+  if (limit < 0) throw new Error('--limit must be a non-negative integer');
+  const eventRows = events.map(eventToBusViewRow).filter((row) => rowMatchesBusView(row, options));
+  const filteredPacketRows = packetRows.filter((row) => rowMatchesBusView(row, options));
+  const latestSeq = events.reduce((max, event) => Math.max(max, event.seq), 0);
+  const latestEventRef = latestSeq > 0 ? `local://event/${latestSeq}` : 'local://event/0';
+  const takeLast = <T>(rows: T[]): T[] => (limit === 0 ? [] : rows.slice(-limit));
+  return {
+    schema: 'local-ledger-view.v0',
+    watermark: {
+      latest_event_ref: latestEventRef,
+      latest_seq: latestSeq,
+      commit_sha: currentGitCommit(root),
+      event_log_hash: eventLogHash(rawEventLog),
+      computed_at: options.computedAt ?? new Date().toISOString(),
+    },
+    filters: {
+      since: options.since ?? null,
+      until: options.until ?? null,
+      lane: options.lane ?? null,
+      seat: options.seat ?? null,
+      from: options.from ?? null,
+      to: options.to ?? null,
+      role: options.role ?? null,
+      action: options.action ?? null,
+      match: options.match ?? null,
+      kind,
+      limit,
+    },
+    boundary: 'authority-false stdout-only rebuildable local projection; cannot authorize, assign, close, merge, mutate local events, write global ledger, or read external buses',
+    events_matched: eventRows.length,
+    packets_matched: filteredPacketRows.length,
+    events: kind === 'packets' ? [] : takeLast(eventRows),
+    packets: kind === 'events' ? [] : takeLast(filteredPacketRows),
+    authority_boundary: {
+      stdout_only: true,
+      rebuildable_projection: true,
+      can_authorize: false,
+      can_assign: false,
+      can_close: false,
+      can_merge: false,
+      can_mutate_bus: false,
+      can_write_global_ledger: false,
+    },
+  };
+}
+
+export function renderLocalLedgerViewText(view: LocalLedgerView): string {
+  return [
+    `schema: ${view.schema}`,
+    `watermark: ${view.watermark.latest_event_ref} commit_sha=${view.watermark.commit_sha}`,
+    `event_log_hash: ${view.watermark.event_log_hash}`,
+    `computed_at: ${view.watermark.computed_at}`,
+    `filters: ${Object.entries(view.filters).filter(([, value]) => value !== null).map(([key, value]) => `${key}=${String(value)}`).join(', ') || 'none'}`,
+    `boundary: ${view.boundary}`,
+    `events_matched: ${view.events_matched} showing: ${view.events.length}`,
+    ...view.events.map((row) => `  - ${row.text}`),
+    `packets_matched: ${view.packets_matched} showing: ${view.packets.length}`,
+    ...view.packets.map((row) => `  - ${row.text}`),
+  ].join('\n');
+}
+
+export function renderLocalLedgerViewMarkdown(view: LocalLedgerView): string {
+  return [
+    '# Local Etiquette Bus View',
+    '',
+    `- Schema: \`${view.schema}\``,
+    `- Watermark: \`${view.watermark.latest_event_ref}\``,
+    `- Commit: \`${view.watermark.commit_sha}\``,
+    `- Event log hash: \`${view.watermark.event_log_hash}\``,
+    `- Computed at: \`${view.watermark.computed_at}\``,
+    `- Boundary: ${view.boundary}`,
+    '',
+    `## Events (${view.events_matched} matched, ${view.events.length} shown)`,
+    '',
+    ...(view.events.length === 0 ? ['_No events._'] : view.events.map((row) => `- ${row.text}`)),
+    '',
+    `## Packets (${view.packets_matched} matched, ${view.packets.length} shown)`,
+    '',
+    ...(view.packets.length === 0 ? ['_No packets._'] : view.packets.map((row) => `- ${row.text}`)),
+    '',
+  ].join('\n');
+}

package/packages/control/src/projection/return-enforcement.ts

@@ -0,0 +1,48 @@
+import type { LocalLedgerView, LocalLedgerViewRow } from './local-ledger-view';
+
+export type ReturnRole = 'implementation-return' | 'review-return';
+export type ReturnCheckVerdict = 'pass' | 'missing_return' | 'unposted_return';
+
+export interface ReturnDetection {
+  task: string;
+  seat: string;
+  expected_roles: ReturnRole[];
+  verdict: ReturnCheckVerdict;
+  matched_return_packets: LocalLedgerViewRow[];
+  posted_return_packets: LocalLedgerViewRow[];
+  latest_event_ref: string;
+  event_log_hash: string;
+}
+
+export function detectReturnPackets(
+  projection: Pick<LocalLedgerView, 'packets' | 'watermark'>,
+  options: {
+    task: string;
+    seat: string;
+    expectedRoles: ReturnRole[];
+  },
+): ReturnDetection {
+  const matchedReturnPackets = projection.packets.filter((row) => (
+    row.kind === 'packet' &&
+    row.lane === options.task &&
+    row.from === options.seat &&
+    options.expectedRoles.includes(row.role as ReturnRole)
+  ));
+  const postedReturnPackets = matchedReturnPackets.filter((row) => row.seq !== null);
+  const verdict: ReturnCheckVerdict = postedReturnPackets.length > 0
+    ? 'pass'
+    : matchedReturnPackets.length > 0
+      ? 'unposted_return'
+      : 'missing_return';
+
+  return {
+    task: options.task,
+    seat: options.seat,
+    expected_roles: options.expectedRoles,
+    verdict,
+    matched_return_packets: matchedReturnPackets,
+    posted_return_packets: postedReturnPackets,
+    latest_event_ref: projection.watermark.latest_event_ref,
+    event_log_hash: projection.watermark.event_log_hash,
+  };
+}