@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/index.ts

@@ -0,0 +1,384 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import {
+  aggregateSliceStatus,
+  type ControlDeps,
+  type ProjectManifest,
+  type SecretarySummary,
+  type Slice,
+  type SliceTask,
+  type Surface,
+} from '../../protocol/src/index';
+import { writeJson, now, sanitize } from './fs';
+import { buildSlice, loadSlice, resolveWorktreePath, sliceStatePath } from './project';
+
+export * from './authority/lease';
+export * from './authority/node-delegation';
+export * from './authority/rig-conductor';
+export {
+  CODEX_PERMISSIONS_ADAPTER_SCHEMA,
+  CODEX_PERMISSION_ACCESS,
+  SEAT_PREFLIGHT_RESULT_SCHEMA,
+  SEAT_PREFLIGHT_SCHEMA,
+  SEAT_PREFLIGHT_REQUIRED_CHECKS,
+  SEAT_PROFILE_ROLES,
+  SEAT_PROFILE_SCHEMA,
+  SEAT_MONITOR_MODES,
+  codexFilesystemAccessForPath,
+  createDefaultSeatProfile,
+  evaluateSeatPreflight,
+  normalizeCodexPermissionsAdapter,
+  normalizeSeatProfile,
+  type CodexFilesystemPermissionRule,
+  type CodexNetworkPermissionRule,
+  type CodexPermissionAccess,
+  type CodexPermissionsAdapter,
+  type SeatMonitorMode,
+  type SeatPreflight,
+  type SeatPreflightRequiredCheck,
+  type SeatPreflightResult,
+  type SeatProfile,
+  type SeatProfileRole,
+} from './seat/readiness';
+
+async function persistSlice(project: ProjectManifest, slice: Slice): Promise<void> {
+  slice.updatedAt = now();
+  await writeJson(sliceStatePath(project, slice.sliceId), slice);
+}
+
+type CheckResult = {
+  command: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+export async function startSlice(project: ProjectManifest, sliceId: string, deps: ControlDeps, surfaces: Surface[]): Promise<Slice> {
+  await deps.handshake.ensureStore(project);
+  const existing = await loadSlice(project, sliceId);
+  if (existing) {
+    await deps.scrutiny.openOrLinkSlice(project, existing);
+    return existing;
+  }
+  const slice = buildSlice(project, sliceId, surfaces);
+  await deps.scrutiny.openOrLinkSlice(project, slice);
+  await persistSlice(project, slice);
+  return slice;
+}
+
+export async function splitSlice(project: ProjectManifest, sliceId: string, deps: ControlDeps): Promise<Slice> {
+  const slice = await loadSlice(project, sliceId);
+  if (!slice) {
+    throw new Error(`slice not started: ${sliceId}`);
+  }
+  for (const task of slice.tasks) {
+    task.packetId = `slice-${sanitize(sliceId)}-${task.surface}`;
+    await deps.handshake.newPacket({ packetId: task.packetId, sliceId, task, project });
+  }
+  slice.state = 'split';
+  slice.transitions.push({ state: 'split', actorId: 'etiquette', at: now(), note: 'packets and incoming tasks created' });
+  await persistSlice(project, slice);
+  return slice;
+}
+
+export async function assignSlice(project: ProjectManifest, sliceId: string, deps: ControlDeps): Promise<Slice> {
+  const slice = await loadSlice(project, sliceId);
+  if (!slice) {
+    throw new Error(`slice not started: ${sliceId}`);
+  }
+  for (const task of slice.tasks) {
+    task.worktreePath = resolveWorktreePath(project, sliceId, task);
+    task.branchName = `codex/${sanitize(sliceId)}-${task.surface}`;
+    await deps.agent.spawnWorker(project, task);
+    await deps.agent.bindWorktree(project, task, task.worktreePath, task.owner ?? 'unassigned');
+    await deps.handshake.claimTask(project, task.taskId, task.owner ?? 'unassigned');
+    task.state = 'claimed';
+    task.transitions.push({ state: 'claimed', actorId: task.owner ?? 'unassigned', at: now(), note: `bound ${task.worktreePath}` });
+  }
+  slice.state = 'assigned';
+  slice.transitions.push({ state: 'assigned', actorId: 'etiquette', at: now(), note: 'workers claimed bounded tasks' });
+  await persistSlice(project, slice);
+  return slice;
+}
+
+export async function statusSlice(project: ProjectManifest, sliceId: string, deps: ControlDeps) {
+  const slice = await loadSlice(project, sliceId);
+  if (!slice) {
+    throw new Error(`slice not started: ${sliceId}`);
+  }
+  const scrutiny = await deps.scrutiny.readSliceState(project, slice.scrutinyId);
+  const packetStates = await deps.handshake.readPacketStates(project);
+  const ledgerTaskStates = await deps.handshake.readTaskStates(project);
+  for (const task of slice.tasks) {
+    const ledgerState = ledgerTaskStates[task.taskId];
+    if (ledgerState) {
+      task.state = ledgerState;
+    }
+  }
+  const snapshot = aggregateSliceStatus(slice, scrutiny.state, packetStates);
+  return { slice, scrutiny, snapshot };
+}
+
+function resolveTaskBySurface(slice: Slice, surface: Surface): SliceTask {
+  const task = slice.tasks.find((candidate) => candidate.surface === surface);
+  if (!task) {
+    throw new Error(`slice ${slice.sliceId} missing task for surface ${surface}`);
+  }
+  return task;
+}
+
+function ensureTaskNotResolved(task: SliceTask): void {
+  if (task.state === 'resolved') {
+    throw new Error(`task ${task.taskId} is already resolved`);
+  }
+}
+
+function runCheck(project: ProjectManifest, command: string): CheckResult {
+  const result = spawnSync('zsh', ['-lc', command], {
+    cwd: project.projectRoot,
+    encoding: 'utf-8',
+  });
+  return {
+    command,
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function renderEvidenceReport(task: SliceTask, actor: string, note: string, results: CheckResult[]): string {
+  const lines = [
+    `# Discipline Evidence: ${task.taskId}`,
+    '',
+    `- Surface: \`${task.surface}\``,
+    `- Actor: \`${actor}\``,
+    `- Summary: ${note}`,
+    `- Captured At: ${now()}`,
+    '',
+    '## Checks',
+    '',
+  ];
+  for (const result of results) {
+    lines.push(`### \`${result.command}\``);
+    lines.push('');
+    lines.push(`- Exit code: \`${result.exitCode}\``);
+    lines.push('');
+    if (result.stdout.trim()) {
+      lines.push('#### stdout');
+      lines.push('');
+      lines.push('```text');
+      lines.push(result.stdout.trimEnd());
+      lines.push('```');
+      lines.push('');
+    }
+    if (result.stderr.trim()) {
+      lines.push('#### stderr');
+      lines.push('');
+      lines.push('```text');
+      lines.push(result.stderr.trimEnd());
+      lines.push('```');
+      lines.push('');
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function writeEvidenceFiles(project: ProjectManifest, task: SliceTask, actor: string, note: string, results: CheckResult[]): Promise<string[]> {
+  const content = renderEvidenceReport(task, actor, note, results);
+  const written: string[] = [];
+  for (const relative of task.bounds.evidenceFiles) {
+    const target = resolve(project.projectRoot, relative);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content, 'utf-8');
+    written.push(relative);
+  }
+  return written;
+}
+
+export async function completeTask(
+  project: ProjectManifest,
+  sliceId: string,
+  surface: Surface,
+  deps: ControlDeps,
+  actor: string,
+  note: string,
+  evidencePaths: string[] = [],
+): Promise<SliceTask> {
+  const slice = await loadSlice(project, sliceId);
+  if (!slice) {
+    throw new Error(`slice not started: ${sliceId}`);
+  }
+  const task = resolveTaskBySurface(slice, surface);
+  ensureTaskNotResolved(task);
+  if (!task.packetId) {
+    throw new Error(`task ${task.taskId} has no packet`);
+  }
+  const files = evidencePaths.length > 0 ? evidencePaths : task.bounds.evidenceFiles;
+  await deps.agent.captureReceipt(project, task.taskId, note, files);
+  await deps.agent.reportTaskState(project, task.taskId, 'evidence_ready', note);
+  await deps.handshake.resolveTask(project, task.taskId, actor, note);
+  await deps.handshake.respondPacket(project, task.packetId, 'ACCEPTED');
+  await deps.handshake.lockPacket(project, task.packetId);
+  await deps.handshake.provisionPacket(project, task.packetId);
+  await deps.agent.reportTaskState(project, task.taskId, 'resolved', note);
+  task.state = 'resolved';
+  task.transitions.push({
+    state: 'resolved',
+    actorId: actor,
+    at: now(),
+    note,
+  });
+  if (slice.tasks.every((candidate) => candidate.state === 'resolved')) {
+    slice.state = 'validated';
+    slice.transitions.push({
+      state: 'validated',
+      actorId: actor,
+      at: now(),
+      note: 'all bounded tasks resolved through discipline complete',
+    });
+  }
+  await persistSlice(project, slice);
+  return task;
+}
+
+export async function runTask(
+  project: ProjectManifest,
+  sliceId: string,
+  surface: Surface,
+  deps: ControlDeps,
+  actor: string,
+  note: string,
+): Promise<SliceTask> {
+  const slice = await loadSlice(project, sliceId);
+  if (!slice) {
+    throw new Error(`slice not started: ${sliceId}`);
+  }
+  const task = resolveTaskBySurface(slice, surface);
+  ensureTaskNotResolved(task);
+  await deps.agent.reportTaskState(project, task.taskId, 'in_progress', `running checks for ${task.taskId}`);
+  const results: CheckResult[] = [];
+  for (const command of task.bounds.checks) {
+    const result = runCheck(project, command);
+    results.push(result);
+    if (result.exitCode !== 0) {
+      const failureNote = `${note} (failed check: ${command})`;
+      const evidence = await writeEvidenceFiles(project, task, actor, failureNote, results);
+      await deps.agent.captureReceipt(project, task.taskId, failureNote, evidence);
+      await deps.agent.reportTaskState(project, task.taskId, 'blocked', failureNote);
+      throw new Error(result.stderr.trim() || result.stdout.trim() || `${command} failed`);
+    }
+  }
+  const evidence = await writeEvidenceFiles(project, task, actor, note, results);
+  return completeTask(project, sliceId, surface, deps, actor, note, evidence);
+}
+
+export async function secretarySummary(project: ProjectManifest, sliceId: string, deps: ControlDeps): Promise<SecretarySummary> {
+  const { slice, snapshot } = await statusSlice(project, sliceId, deps);
+  const actions: SecretarySummary['actions'] = [];
+  for (const task of slice.tasks) {
+    if (task.state === 'blocked' || task.state === 'countered') {
+      actions.push({
+        level: 'blocked',
+        taskId: task.taskId,
+        surface: task.surface,
+        summary: `${task.taskId} needs escalation before work can continue`,
+      });
+      continue;
+    }
+    if (task.state === 'incoming') {
+      actions.push({
+        level: 'action',
+        taskId: task.taskId,
+        surface: task.surface,
+        summary: `${task.taskId} has not been claimed`,
+      });
+      continue;
+    }
+    if (task.state === 'claimed') {
+      actions.push({
+        level: 'action',
+        taskId: task.taskId,
+        surface: task.surface,
+        summary: `${task.taskId} is claimed and waiting for worker evidence`,
+      });
+      continue;
+    }
+    if (task.state === 'resolved') {
+      actions.push({
+        level: 'info',
+        taskId: task.taskId,
+        surface: task.surface,
+        summary: `${task.taskId} is resolved and packet lifecycle is complete`,
+      });
+    }
+  }
+  if (snapshot.readyToClose) {
+    actions.push({
+      level: 'action',
+      summary: `slice ${slice.sliceId} is ready to close`,
+    });
+  } else if (actions.length === 0) {
+    actions.push({
+      level: 'info',
+      summary: `slice ${slice.sliceId} has no immediate secretary actions`,
+    });
+  }
+  return { sliceId: slice.sliceId, actions };
+}
+
+export async function closeSlice(project: ProjectManifest, sliceId: string, deps: ControlDeps, renderArtifacts = false): Promise<Slice> {
+  const { slice, snapshot } = await statusSlice(project, sliceId, deps);
+  if (!snapshot.readyToClose) {
+    throw new Error(`slice ${sliceId} is not ready to close: ${snapshot.blockers.join(', ') || snapshot.unresolvedTasks.join(', ')}`);
+  }
+  const contextId = await deps.logix.createDecisionContext(project, slice);
+  await deps.logix.requestVerdict(project, slice, contextId);
+  if (renderArtifacts) {
+    await deps.scrutiny.renderArtifacts(project);
+  }
+  slice.state = 'closed';
+  slice.transitions.push({ state: 'closed', actorId: 'etiquette', at: now(), note: `context=${contextId}` });
+  await persistSlice(project, slice);
+  return slice;
+}
+
+export function formatStatus(result: Awaited<ReturnType<typeof statusSlice>>): string {
+  const { slice, scrutiny, snapshot } = result;
+  const lines = [
+    `slice=${slice.sliceId}`,
+    `title=${slice.title}`,
+    `slice_state=${slice.state}`,
+    `scrutiny=${scrutiny.scrutinyId}:${scrutiny.state}`,
+    `tasks=${slice.tasks.length}`,
+    `ready_to_close=${snapshot.readyToClose}`,
+  ];
+  for (const [state, count] of Object.entries(snapshot.taskStates)) {
+    if (count > 0) lines.push(`task_${state}=${count}`);
+  }
+  for (const [state, count] of Object.entries(snapshot.packetStates)) {
+    if (count > 0) lines.push(`packet_${state}=${count}`);
+  }
+  if (scrutiny.kind) lines.push(`scrutiny_kind=${scrutiny.kind}`);
+  if (scrutiny.blockedBy && scrutiny.blockedBy.length > 0) lines.push(`scrutiny_blocked_by=${scrutiny.blockedBy.join(',')}`);
+  if (scrutiny.dependsOn && scrutiny.dependsOn.length > 0) lines.push(`scrutiny_depends_on=${scrutiny.dependsOn.join(',')}`);
+  if (scrutiny.readinessQuestion) lines.push(`scrutiny_readiness_question=${scrutiny.readinessQuestion}`);
+  if (scrutiny.readyForRevisit) lines.push(`scrutiny_ready_for_revisit=true`);
+  if (snapshot.blockers.length > 0) {
+    lines.push(`blockers=${snapshot.blockers.join(',')}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatSecretarySummary(summary: SecretarySummary): string {
+  const lines = [`slice=${summary.sliceId}`];
+  for (const action of summary.actions) {
+    const prefix = action.level.toUpperCase();
+    if (action.taskId && action.surface) {
+      lines.push(`${prefix} ${action.taskId} [${action.surface}] ${action.summary}`);
+    } else {
+      lines.push(`${prefix} ${action.summary}`);
+    }
+  }
+  return lines.join('\n');
+}

package/packages/control/src/ledger/entry.ts

@@ -0,0 +1,303 @@
+export const LEDGER_ENTRY_TYPES = [
+  'decision',
+  'review',
+  'receipt',
+  'audit',
+  'event',
+  'heartbeat',
+  'capability',
+  'incident',
+  'doctrine',
+  'task',
+  'closeout',
+  'retroactive_import',
+] as const;
+
+export const LEDGER_AUTHORITY_CLASSES = [
+  'advisory',
+  'grant',
+  'receipt',
+  'audit',
+  'status',
+] as const;
+
+export const LEDGER_EXPORT_CLASSES = [
+  'local_private',
+  'workspace_shared',
+  'org_projected',
+  'public_safe',
+] as const;
+
+export const LEDGER_STATUS_EFFECTS = [
+  'none',
+  'observed',
+  'changed',
+  'gap_found',
+  'reserved',
+  'closed',
+  'proved',
+] as const;
+
+export type LedgerEntryType = typeof LEDGER_ENTRY_TYPES[number];
+export type LedgerAuthorityClass = typeof LEDGER_AUTHORITY_CLASSES[number];
+export type LedgerExportClass = typeof LEDGER_EXPORT_CLASSES[number];
+export type LedgerStatusEffect = typeof LEDGER_STATUS_EFFECTS[number];
+
+export interface LedgerEntryRefs {
+  lanes?: string[];
+  commits?: string[];
+  prs?: string[];
+  bus?: string[];
+  artifacts?: string[];
+  receipts?: string[];
+}
+
+export interface LedgerEntryV0 {
+  schema: 'ledger-entry.v0';
+  entry_id: string;
+  created_at: string;
+  entry_type: LedgerEntryType;
+  spine_eligible: boolean;
+  authority: {
+    class: LedgerAuthorityClass;
+    grants_execution: boolean;
+  };
+  refs: LedgerEntryRefs;
+  export_class: LedgerExportClass;
+  summary: string;
+  legacy?: {
+    pre_v0?: boolean;
+    low_authority?: boolean;
+  };
+}
+
+export interface LedgerEntryV01 extends Omit<LedgerEntryV0, 'schema'> {
+  schema: 'ledger-entry.v0.1';
+  topic_hints?: string[];
+  status_effect?: LedgerStatusEffect;
+}
+
+export interface LedgerEntryV02 extends Omit<LedgerEntryV01, 'schema'> {
+  schema: 'ledger-entry.v0.2';
+  valid_time?: string;
+  valid_time_end?: string;
+}
+
+export type LedgerEntry = LedgerEntryV0 | LedgerEntryV01 | LedgerEntryV02;
+
+export type LedgerLineClassification =
+  | { kind: 'ignored' }
+  | { kind: 'legacy'; pre_v0: true; spine_eligible: false; low_authority: true }
+  | { kind: 'v0'; pre_v0: false; spine_eligible: boolean };
+
+function assertIsoTimestamp(value: string): void {
+  if (!Number.isFinite(Date.parse(value))) {
+    throw new Error('ledger entry created_at must be an ISO-8601 timestamp');
+  }
+}
+
+function assertOpaqueRef(value: string, field: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9:._/@-]{0,255}$/.test(value)) {
+    throw new Error(`${field} must be a compact opaque or repo-relative ref`);
+  }
+}
+
+function assertSummary(value: string): void {
+  if (value.length === 0 || value.length > 240 || /\s{2,}/.test(value)) {
+    throw new Error('ledger entry summary must be compact and single-spaced');
+  }
+}
+
+export function assertLedgerTopicHints(value: string[] | undefined): void {
+  if (value === undefined) return;
+  if (value.length > 8) {
+    throw new Error('ledger entry topic_hints may contain at most 8 items');
+  }
+  const seen = new Set<string>();
+  for (const topic of value) {
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(topic)) {
+      throw new Error('ledger entry topic_hints must be kebab-case slugs');
+    }
+    if (seen.has(topic)) {
+      throw new Error('ledger entry topic_hints must not contain duplicates');
+    }
+    seen.add(topic);
+  }
+}
+
+function refsCount(refs: LedgerEntryRefs): number {
+  return Object.values(refs).reduce((total, values) => total + (values?.length ?? 0), 0);
+}
+
+function compactRefs(refs: LedgerEntryRefs): string {
+  const parts: string[] = [];
+  for (const key of ['lanes', 'commits', 'prs', 'bus', 'artifacts', 'receipts'] as const) {
+    for (const value of refs[key] ?? []) {
+      assertOpaqueRef(value, `refs.${key}`);
+      parts.push(`${key}:${value}`);
+    }
+  }
+  return parts.join(',') || 'none';
+}
+
+function assertLedgerEntryBase(entry: LedgerEntry): void {
+  assertIsoTimestamp(entry.created_at);
+  assertOpaqueRef(entry.entry_id, 'entry_id');
+  assertSummary(entry.summary);
+
+  if (entry.authority.grants_execution && entry.authority.class !== 'grant') {
+    throw new Error('only grant authority entries may set grants_execution=true');
+  }
+
+  if (entry.authority.class !== 'advisory' && refsCount(entry.refs) === 0) {
+    throw new Error('non-advisory ledger entries require at least one durable ref');
+  }
+}
+
+export function assertLedgerEntryV0(entry: LedgerEntryV0): void {
+  assertLedgerEntryBase(entry);
+  if (entry.entry_type === 'retroactive_import') {
+    throw new Error('retroactive_import entries require schema ledger-entry.v0.2');
+  }
+}
+
+export function assertLedgerEntryV01(entry: LedgerEntryV01): void {
+  assertLedgerEntryBase(entry);
+  assertLedgerTopicHints(entry.topic_hints);
+  if (entry.status_effect !== undefined && !LEDGER_STATUS_EFFECTS.includes(entry.status_effect)) {
+    throw new Error('ledger entry status_effect is not supported');
+  }
+  if (entry.entry_type === 'retroactive_import') {
+    throw new Error('retroactive_import entries require schema ledger-entry.v0.2');
+  }
+}
+
+export function assertLedgerEntryV02(entry: LedgerEntryV02): void {
+  assertLedgerEntryBase(entry);
+  assertLedgerTopicHints(entry.topic_hints);
+  if (entry.status_effect !== undefined && !LEDGER_STATUS_EFFECTS.includes(entry.status_effect)) {
+    throw new Error('ledger entry status_effect is not supported');
+  }
+
+  // Bitemporal honesty: created_at is the recording (transaction) time and is
+  // never backdated; valid_time (+ optional end) is when the covered work
+  // actually happened.
+  if (entry.valid_time !== undefined) {
+    if (!Number.isFinite(Date.parse(entry.valid_time))) {
+      throw new Error('ledger entry valid_time must be an ISO-8601 timestamp');
+    }
+    if (Date.parse(entry.valid_time) > Date.parse(entry.created_at)) {
+      throw new Error('ledger entry valid_time must not be after created_at (no future coverage, no backdated recording)');
+    }
+  }
+  if (entry.valid_time_end !== undefined) {
+    if (entry.valid_time === undefined) {
+      throw new Error('ledger entry valid_time_end requires valid_time');
+    }
+    if (!Number.isFinite(Date.parse(entry.valid_time_end))) {
+      throw new Error('ledger entry valid_time_end must be an ISO-8601 timestamp');
+    }
+    if (Date.parse(entry.valid_time_end) < Date.parse(entry.valid_time)) {
+      throw new Error('ledger entry valid_time_end must not precede valid_time');
+    }
+    if (Date.parse(entry.valid_time_end) > Date.parse(entry.created_at)) {
+      throw new Error('ledger entry valid_time_end must not be after created_at');
+    }
+  }
+
+  if (entry.entry_type === 'retroactive_import') {
+    if (entry.valid_time === undefined) {
+      throw new Error('retroactive_import entries must declare valid_time');
+    }
+    const evidence =
+      (entry.refs.commits?.length ?? 0) +
+      (entry.refs.receipts?.length ?? 0) +
+      (entry.refs.artifacts?.length ?? 0);
+    if (evidence === 0) {
+      throw new Error('retroactive_import entries require contemporaneous evidence refs (commits, receipts, or artifacts)');
+    }
+    if (entry.authority.class !== 'advisory' && entry.authority.class !== 'audit') {
+      throw new Error('retroactive_import entries must carry advisory or audit authority; late entries never mint grants');
+    }
+  }
+}
+
+export function assertLedgerEntry(entry: LedgerEntry): void {
+  if (entry.schema === 'ledger-entry.v0.2') {
+    assertLedgerEntryV02(entry);
+    return;
+  }
+  if (entry.schema === 'ledger-entry.v0.1') {
+    assertLedgerEntryV01(entry);
+    return;
+  }
+  assertLedgerEntryV0(entry);
+}
+
+export function normalizeLedgerEntryV01(entry: LedgerEntryV01): LedgerEntryV01 {
+  assertLedgerEntryV01(entry);
+  return {
+    ...entry,
+    topic_hints: entry.topic_hints ?? [],
+    status_effect: entry.status_effect ?? 'none',
+  };
+}
+
+export function formatLedgerEntryLine(entry: LedgerEntry, extra: Record<string, string> = {}): string {
+  assertLedgerEntry(entry);
+  const parts = [
+    `- ${entry.created_at}`,
+    `schema=${entry.schema}`,
+    `entry_id=${entry.entry_id}`,
+    `entry_type=${entry.entry_type}`,
+    `spine_eligible=${entry.spine_eligible}`,
+    `authority_class=${entry.authority.class}`,
+    `grants_execution=${entry.authority.grants_execution}`,
+    `export_class=${entry.export_class}`,
+    `refs=${compactRefs(entry.refs)}`,
+  ];
+
+  if (entry.schema === 'ledger-entry.v0.1' || entry.schema === 'ledger-entry.v0.2') {
+    const topicHints = entry.topic_hints ?? [];
+    const statusEffect = entry.status_effect ?? 'none';
+    if (topicHints.length > 0) {
+      parts.push(`topic_hints=${topicHints.join(',')}`);
+    }
+    if (statusEffect !== 'none') {
+      parts.push(`status_effect=${statusEffect}`);
+    }
+  }
+
+  if (entry.schema === 'ledger-entry.v0.2') {
+    if (entry.valid_time !== undefined) {
+      parts.push(`valid_time=${entry.valid_time}`);
+    }
+    if (entry.valid_time_end !== undefined) {
+      parts.push(`valid_time_end=${entry.valid_time_end}`);
+    }
+  }
+
+  for (const [key, value] of Object.entries(extra)) {
+    parts.push(`${key}=${value}`);
+  }
+
+  return parts.join(' ');
+}
+
+export function classifyLedgerLine(line: string): LedgerLineClassification {
+  const trimmed = line.trim();
+  if (trimmed.length === 0 || trimmed.startsWith('#')) {
+    return { kind: 'ignored' };
+  }
+  if (!trimmed.startsWith('- ')) {
+    return { kind: 'ignored' };
+  }
+  if (!/\bschema=ledger-entry\.v0(?:\.[12])?\b/.test(trimmed)) {
+    return { kind: 'legacy', pre_v0: true, spine_eligible: false, low_authority: true };
+  }
+  return {
+    kind: 'v0',
+    pre_v0: false,
+    spine_eligible: /\bspine_eligible=true\b/.test(trimmed),
+  };
+}