@etiquekit/etq 1.0.13 → 1.0.15

package/packages/control/src/project.ts

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

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

@@ -1,48 +0,0 @@
-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,
-  };
-}