@aria_asi/cli 0.2.40 → 0.2.41

package/src/action-ledger-core.ts

@@ -0,0 +1,1054 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export type ActionLedgerSurface =
+  | 'codex'
+  | 'claude-code'
+  | 'opencode'
+  | 'shell'
+  | 'aria-task'
+  | 'atlas'
+  | 'sentinel'
+  | string;
+
+export type ActionLedgerPhase =
+  | 'session_bind'
+  | 'pre_prompt'
+  | 'pre_cognition'
+  | 'pre_tool'
+  | 'intra_tool'
+  | 'post_tool'
+  | 'post_cognition'
+  | 'stop'
+  | 'task_start'
+  | 'task_phase'
+  | 'task_qa'
+  | 'task_recovery'
+  | 'task_complete'
+  | string;
+
+export type ActionLedgerStatus =
+  | 'active'
+  | 'repaired'
+  | 'verified'
+  | 'blocked'
+  | 'needs_owner'
+  | 'failed'
+  | 'completed'
+  | string;
+
+export type JsonRecord = Record<string, unknown>;
+
+export type WorkIntentSource = 'chat_prompt' | 'airtable' | 'google_tasks' | 'google_sheets' | 'manual_cli';
+export type WorkIntentRequestedMode = 'capture_only' | 'plan' | 'execute';
+export type WorkIntentPriority = 'P0' | 'P1' | 'P2' | 'P3';
+export type ExternalBindingProvider = 'airtable' | 'google_tasks' | 'google_sheets' | 'chat' | 'cli';
+export type CompiledWorkUnitSourceTrust = 'direct_observed' | 'substrate_recorded' | 'evidence_attached' | 'unverified';
+export type CompiledWorkUnitStatus = 'candidate' | 'compiled' | 'approved' | 'running' | 'blocked' | 'verified' | 'synced' | 'rejected';
+export type KernelMutationType =
+  | 'constraint_added'
+  | 'option_changed'
+  | 'option_rejected'
+  | 'verification_added'
+  | 'learning_signal_added'
+  | 'uncertainty_recorded';
+
+export interface ExternalBinding {
+  provider: ExternalBindingProvider;
+  objectId: string;
+  url?: string;
+  writableStatus: boolean;
+  lastSyncAt?: string;
+}
+
+export interface WorkIntent {
+  schema: 'aria.work_intent.v1';
+  source: WorkIntentSource;
+  sourceId: string;
+  sourceUrl?: string;
+  projectKey: string;
+  rawText: string;
+  normalizedGoal: string;
+  requestedMode: WorkIntentRequestedMode;
+  priority: WorkIntentPriority;
+  acceptanceCriteria: string[];
+  externalBinding: ExternalBinding;
+}
+
+export interface KernelMutation {
+  stage: string;
+  mutationType: KernelMutationType;
+  before?: string;
+  after?: string;
+  reason: string;
+}
+
+export interface CompiledOption {
+  optionId: string;
+  action: string;
+  rank: number;
+  constraintsApplied: string[];
+  verificationPredicate: string;
+  maxAutonomyLevel: number;
+}
+
+export interface RejectedOption {
+  optionId: string;
+  rejectedBecause: string;
+  evidence: string;
+}
+
+export interface QiyasRow {
+  perspective: string;
+  verdict: 'accept' | 'requires_evidence' | 'downgrade' | 'reject';
+  finding: string;
+  remediation?: string;
+}
+
+export interface DirectorRoute {
+  role: 'director';
+  modelOrSurface: string;
+  responsibilities: string[];
+}
+
+export interface WorkerRoute {
+  role: 'worker';
+  modelOrSurface: string;
+  allowedFiles: string[];
+  forbiddenFiles: string[];
+  verificationCommand: string;
+  completionAuthority: 'parent_task_runner_only';
+}
+
+export interface CompiledWorkUnit {
+  schema: 'aria.compiled_work_unit.v1';
+  workUnitId: string;
+  sourceIntent: WorkIntent;
+  createdAt: string;
+  updatedAt: string;
+  atlas: {
+    snapshotId: string | number | null;
+    contextHash: string;
+    dossierTargets: string[];
+    riskGraphRefs: string[];
+    sentinelFindingRefs: string[];
+  };
+  kernel: {
+    compilationHash: string;
+    sourceTrust: CompiledWorkUnitSourceTrust;
+    classification: JsonRecord;
+    tadabbur12: {
+      ok: boolean;
+      stageCount: 12;
+      mutations: KernelMutation[];
+    };
+    qiyas15: {
+      ok: boolean;
+      perspectiveCount: 15;
+      rows: QiyasRow[];
+    };
+    rankedOptions: CompiledOption[];
+    rejectedOptions: RejectedOption[];
+  };
+  authority: {
+    maxAutonomyLevel: 0 | 1 | 2 | 3 | 4;
+    approvalRequired: boolean;
+    approvalReason?: string;
+    allowedRepos: string[];
+    allowedPaths: string[];
+    forbiddenPaths: string[];
+    forbiddenActions: string[];
+  };
+  execution: {
+    taskId: string;
+    phaseIds: string[];
+    director: DirectorRoute;
+    workers: WorkerRoute[];
+    verificationPredicates: string[];
+    qaCourtRequired: true;
+  };
+  ledgers: {
+    actionLedgerProjectId: string;
+    actionEventIds: string[];
+    hiveThreadId: string;
+    runtimeReceiptIds: string[];
+  };
+  externalBindings: ExternalBinding[];
+  status: CompiledWorkUnitStatus;
+}
+
+export interface ActionLedgerCompiledWorkUnitRef {
+  schema: 'aria.compiled_work_unit_ref.v1';
+  workUnitId: string;
+  status: CompiledWorkUnitStatus | string;
+  taskId: string | null;
+  authorityCap: number | null;
+  approvalRequired: boolean;
+  compilationHash: string | null;
+  mutationCount: number;
+  verificationPredicates: string[];
+  path?: string;
+  updatedAt?: string;
+}
+
+export interface CompiledWorkUnitValidationResult {
+  ok: boolean;
+  executable: boolean;
+  gaps: string[];
+  workUnitId: string | null;
+  authorityCap: number | null;
+  compilationHash: string | null;
+  mutationCount: number;
+}
+
+export interface ActionLedgerFileClaim {
+  path: string;
+  intent?: string;
+  status?: string;
+  note?: string;
+}
+
+export interface ActionLedgerEvidenceRef {
+  evidenceId?: string;
+  kind: string;
+  sha256?: string;
+  preview?: string;
+  path?: string;
+  at?: string;
+  metadata?: JsonRecord;
+}
+
+export interface ActionLedgerAtlasContext {
+  contextHash?: string | null;
+  snapshotId?: string | number | null;
+  status?: string | null;
+  target?: string | null;
+  dossierTargets?: string[];
+  doctrineRefs?: string[];
+  blastRadius?: JsonRecord | null;
+  verificationPredicates?: string[];
+}
+
+export interface ActionLedgerSentinelFinding {
+  id?: string | number | null;
+  severity?: string | null;
+  source?: string | null;
+  kind?: string | null;
+  title?: string | null;
+  status?: string | null;
+  target?: string | null;
+  reason?: string | null;
+  rescuePack?: string | null;
+}
+
+export interface ActionLedgerEventInput {
+  actionId?: string;
+  parentActionId?: string | null;
+  sessionId: string;
+  threadId?: string | null;
+  surface: ActionLedgerSurface;
+  projectId?: string | null;
+  taskId?: string | null;
+  phaseId?: string | null;
+  lifecyclePhase: ActionLedgerPhase;
+  status?: ActionLedgerStatus;
+  cwd?: string | null;
+  intent?: string | null;
+  toolName?: string | null;
+  fileClaims?: ActionLedgerFileClaim[];
+  evidenceRefs?: ActionLedgerEvidenceRef[];
+  skillReceipt?: JsonRecord | null;
+  runtimeReceipt?: JsonRecord | null;
+  qaReceipt?: JsonRecord | null;
+  correctionPlan?: JsonRecord | null;
+  learningDelta?: JsonRecord | null;
+  atlas?: ActionLedgerAtlasContext | null;
+  sentinelFindings?: ActionLedgerSentinelFinding[];
+  compiledWorkUnit?: CompiledWorkUnit | ActionLedgerCompiledWorkUnitRef | null;
+  metadata?: JsonRecord;
+  createdAt?: string;
+}
+
+export interface ActionLedgerEvent {
+  schema: 'aria.action_event.v1';
+  eventId: string;
+  actionId: string;
+  parentActionId: string | null;
+  sessionId: string;
+  threadId: string | null;
+  surface: ActionLedgerSurface;
+  projectId: string | null;
+  taskId: string | null;
+  phaseId: string | null;
+  lifecyclePhase: ActionLedgerPhase;
+  status: ActionLedgerStatus;
+  cwd: string | null;
+  intent: string | null;
+  toolName: string | null;
+  fileClaims: ActionLedgerFileClaim[];
+  evidenceRefs: ActionLedgerEvidenceRef[];
+  skillReceipt: JsonRecord | null;
+  runtimeReceipt: JsonRecord | null;
+  qaReceipt: JsonRecord | null;
+  correctionPlan: JsonRecord | null;
+  learningDelta: JsonRecord | null;
+  atlas: ActionLedgerAtlasContext | null;
+  sentinelFindings: ActionLedgerSentinelFinding[];
+  compiledWorkUnit: ActionLedgerCompiledWorkUnitRef | null;
+  metadata: JsonRecord;
+  createdAt: string;
+  eventHash: string;
+}
+
+export interface ActionLedgerPaths {
+  root: string;
+  eventsPath: string;
+  projectionPath: string;
+  publishOutboxPath: string;
+}
+
+export interface ActionLedgerProjection {
+  schema: 'aria.action_ledger_projection.v1';
+  generatedAt: string;
+  eventCount: number;
+  latestEvent: Pick<ActionLedgerEvent, 'eventId' | 'actionId' | 'surface' | 'lifecyclePhase' | 'status' | 'createdAt'> | null;
+  tasks: Record<string, JsonRecord>;
+  sessions: Record<string, JsonRecord>;
+  correctionRequired: boolean;
+  latestQa: JsonRecord | null;
+  latestLearningDelta: JsonRecord | null;
+  latestAtlas: ActionLedgerAtlasContext | null;
+  sentinelFindings: ActionLedgerSentinelFinding[];
+  compiledWorkUnits: Record<string, ActionLedgerCompiledWorkUnitRef>;
+  ownerAirtableSyncQueuedAt?: string;
+  ownerAirtableSyncQueuePath?: string;
+}
+
+export interface RecordActionEventResult {
+  ok: boolean;
+  event: ActionLedgerEvent;
+  paths: ActionLedgerPaths;
+  projection: ActionLedgerProjection;
+  publication?: JsonRecord;
+}
+
+export interface ActionLedgerPublishOutboxEntry {
+  schema: string;
+  at: string;
+  eventId?: string;
+  eventHash?: string;
+  actionId?: string;
+  projectId?: string | null;
+  taskId?: string | null;
+  phaseId?: string | null;
+  error?: string;
+  recovery?: string;
+  event?: ActionLedgerEvent;
+  replayAttempts?: number;
+  lastReplayAt?: string;
+  lastReplayError?: string;
+  metadata?: JsonRecord;
+}
+
+export interface ActionLedgerPublishReplayResult {
+  ok: boolean;
+  outboxPath: string;
+  attempted: number;
+  replayed: number;
+  remaining: number;
+  skipped: number;
+  failures: JsonRecord[];
+}
+
+export interface OwnerAirtableSyncQueueEntry {
+  schema: 'aria.owner_airtable_sync_needed.v1';
+  at: string;
+  reason: 'action_ledger_event_recorded';
+  eventId: string;
+  eventHash: string;
+  actionId: string;
+  projectId: string | null;
+  taskId: string | null;
+  phaseId: string | null;
+  sessionId: string;
+  threadId: string | null;
+  surface: ActionLedgerSurface;
+  lifecyclePhase: ActionLedgerPhase;
+  status: ActionLedgerStatus;
+}
+
+function defaultHome(): string {
+  return process.env.ARIA_HOME || process.env.HOME || homedir();
+}
+
+function safeSegment(value: string): string {
+  return String(value || 'global')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'global';
+}
+
+export function actionLedgerPaths(options: { home?: string; projectId?: string | null } = {}): ActionLedgerPaths {
+  const root = path.join(options.home || defaultHome(), '.aria', 'action-ledger', safeSegment(options.projectId || 'global'));
+  return {
+    root,
+    eventsPath: path.join(root, 'events.jsonl'),
+    projectionPath: path.join(root, 'projection.json'),
+    publishOutboxPath: path.join(root, 'publish-outbox.jsonl'),
+  };
+}
+
+export function compiledWorkUnitPath(options: { home?: string; projectId?: string | null; workUnitId: string }): string {
+  const paths = actionLedgerPaths({ home: options.home, projectId: options.projectId || null });
+  return path.join(paths.root, 'compiled-workunits', `${safeSegment(options.workUnitId)}.json`);
+}
+
+export function ownerAirtableSyncQueuePath(options: { home?: string } = {}): string {
+  return path.join(options.home || defaultHome(), '.aria', 'owner-airtable', 'sync-queue.jsonl');
+}
+
+function ownerAirtableSyncQueueEntry(event: ActionLedgerEvent): OwnerAirtableSyncQueueEntry {
+  return {
+    schema: 'aria.owner_airtable_sync_needed.v1',
+    at: new Date().toISOString(),
+    reason: 'action_ledger_event_recorded',
+    eventId: event.eventId,
+    eventHash: event.eventHash,
+    actionId: event.actionId,
+    projectId: event.projectId,
+    taskId: event.taskId,
+    phaseId: event.phaseId,
+    sessionId: event.sessionId,
+    threadId: event.threadId,
+    surface: event.surface,
+    lifecyclePhase: event.lifecyclePhase,
+    status: event.status,
+  };
+}
+
+export function enqueueOwnerAirtableSyncForEvent(event: ActionLedgerEvent, options: { home?: string } = {}): string {
+  const queuePath = ownerAirtableSyncQueuePath(options);
+  mkdirSync(path.dirname(queuePath), { recursive: true, mode: 0o700 });
+  appendFileSync(queuePath, `${JSON.stringify(ownerAirtableSyncQueueEntry(event))}\n`, { mode: 0o600 });
+  return queuePath;
+}
+
+function stableJson(value: unknown): string {
+  const seen = new WeakSet<object>();
+  const normalize = (input: unknown): unknown => {
+    if (!input || typeof input !== 'object') return input;
+    if (seen.has(input as object)) return '[Circular]';
+    seen.add(input as object);
+    if (Array.isArray(input)) return input.map((entry) => normalize(entry));
+    return Object.fromEntries(
+      Object.entries(input as JsonRecord)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entry]) => [key, normalize(entry)]),
+    );
+  };
+  return JSON.stringify(normalize(value));
+}
+
+export function actionLedgerSha256(value: unknown): string {
+  return createHash('sha256').update(typeof value === 'string' ? value : stableJson(value)).digest('hex');
+}
+
+function asRecord(value: unknown): JsonRecord | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as JsonRecord : null;
+}
+
+function asObject(value: unknown): JsonRecord {
+  return asRecord(value) || {};
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string' && entry.trim().length > 0).map((entry) => entry.trim())
+    : [];
+}
+
+function stringField(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeAuthorityCap(value: unknown): 0 | 1 | 2 | 3 | 4 | null {
+  const num = Number(value);
+  return num === 0 || num === 1 || num === 2 || num === 3 || num === 4 ? num : null;
+}
+
+export function compiledWorkUnitSummary(value: CompiledWorkUnit | ActionLedgerCompiledWorkUnitRef | null | undefined): ActionLedgerCompiledWorkUnitRef | null {
+  const record = asRecord(value);
+  if (!record) return null;
+  if (record.schema === 'aria.compiled_work_unit_ref.v1') {
+    const workUnitId = stringField(record.workUnitId);
+    if (!workUnitId) return null;
+    return {
+      schema: 'aria.compiled_work_unit_ref.v1',
+      workUnitId,
+      status: stringField(record.status) || 'candidate',
+      taskId: stringField(record.taskId) || null,
+      authorityCap: Number.isFinite(Number(record.authorityCap)) ? Number(record.authorityCap) : null,
+      approvalRequired: record.approvalRequired === true,
+      compilationHash: stringField(record.compilationHash) || null,
+      mutationCount: Number.isFinite(Number(record.mutationCount)) ? Number(record.mutationCount) : 0,
+      verificationPredicates: asStringArray(record.verificationPredicates),
+      path: stringField(record.path) || undefined,
+      updatedAt: stringField(record.updatedAt) || undefined,
+    };
+  }
+  if (record.schema !== 'aria.compiled_work_unit.v1') return null;
+  const unit = record as unknown as CompiledWorkUnit;
+  const authority = asObject(unit.authority);
+  const kernel = asObject(unit.kernel);
+  const tadabbur12 = asObject(kernel.tadabbur12);
+  const execution = asObject(unit.execution);
+  return {
+    schema: 'aria.compiled_work_unit_ref.v1',
+    workUnitId: stringField(unit.workUnitId),
+    status: stringField(unit.status) || 'candidate',
+    taskId: stringField(execution.taskId) || null,
+    authorityCap: Number.isFinite(Number(authority.maxAutonomyLevel)) ? Number(authority.maxAutonomyLevel) : null,
+    approvalRequired: authority.approvalRequired === true,
+    compilationHash: stringField(kernel.compilationHash) || null,
+    mutationCount: Array.isArray(tadabbur12.mutations) ? tadabbur12.mutations.length : 0,
+    verificationPredicates: asStringArray(execution.verificationPredicates),
+    updatedAt: stringField(unit.updatedAt) || undefined,
+  };
+}
+
+export function validateCompiledWorkUnitForExecution(unit: CompiledWorkUnit | null | undefined): CompiledWorkUnitValidationResult {
+  const gaps: string[] = [];
+  const record = asRecord(unit);
+  if (!record || record.schema !== 'aria.compiled_work_unit.v1') {
+    return {
+      ok: false,
+      executable: false,
+      gaps: ['compiled work unit schema missing or invalid'],
+      workUnitId: null,
+      authorityCap: null,
+      compilationHash: null,
+      mutationCount: 0,
+    };
+  }
+  const compiled = record as unknown as CompiledWorkUnit;
+  const kernel = asObject(compiled.kernel);
+  const tadabbur12 = asObject(kernel.tadabbur12);
+  const qiyas15 = asObject(kernel.qiyas15);
+  const authority = asObject(compiled.authority);
+  const execution = asObject(compiled.execution);
+  const compilationHash = stringField(kernel.compilationHash);
+  const mutations = Array.isArray(tadabbur12.mutations) ? tadabbur12.mutations : [];
+  const authorityCap = normalizeAuthorityCap(authority.maxAutonomyLevel);
+  if (!stringField(compiled.workUnitId)) gaps.push('compiled work unit id missing');
+  if (!compilationHash) gaps.push('kernel compilation hash missing');
+  if (mutations.length < 1) gaps.push('at least one kernel mutation is required before execution');
+  if (Number(tadabbur12.stageCount) !== 12 || tadabbur12.ok !== true) gaps.push('Tadabbur-12 receipt missing or not ok');
+  if (Number(qiyas15.perspectiveCount) !== 15 || qiyas15.ok !== true) gaps.push('Qiyas-15 receipt missing or not ok');
+  if (authorityCap === null) gaps.push('authority cap must be one of 0..4');
+  if (execution.qaCourtRequired !== true) gaps.push('QA court must be required');
+  if (!stringField(execution.taskId)) gaps.push('execution task id missing');
+  if (!asStringArray(execution.verificationPredicates).length) gaps.push('verification predicates missing');
+  return {
+    ok: gaps.length === 0,
+    executable: gaps.length === 0 && stringField(compiled.status) !== 'rejected',
+    gaps,
+    workUnitId: stringField(compiled.workUnitId) || null,
+    authorityCap,
+    compilationHash: compilationHash || null,
+    mutationCount: mutations.length,
+  };
+}
+
+export function assertCompiledWorkUnitExecutable(unit: CompiledWorkUnit): CompiledWorkUnitValidationResult {
+  const validation = validateCompiledWorkUnitForExecution(unit);
+  if (!validation.executable) {
+    throw new Error(`CompiledWorkUnit is not executable: ${validation.gaps.join('; ')}`);
+  }
+  return validation;
+}
+
+export function persistCompiledWorkUnit(
+  unit: CompiledWorkUnit,
+  options: { home?: string; projectId?: string | null } = {},
+): { ok: true; path: string; summary: ActionLedgerCompiledWorkUnitRef; validation: CompiledWorkUnitValidationResult } {
+  const validation = validateCompiledWorkUnitForExecution(unit);
+  if (!validation.ok) {
+    throw new Error(`Refusing to persist invalid CompiledWorkUnit: ${validation.gaps.join('; ')}`);
+  }
+  const filePath = compiledWorkUnitPath({ home: options.home, projectId: options.projectId || unit.ledgers.actionLedgerProjectId, workUnitId: unit.workUnitId });
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  writeFileSync(filePath, `${JSON.stringify(unit, null, 2)}\n`, { mode: 0o600 });
+  const summary = {
+    ...compiledWorkUnitSummary(unit)!,
+    path: filePath,
+  };
+  return { ok: true, path: filePath, summary, validation };
+}
+
+export function readCompiledWorkUnit(
+  workUnitId: string,
+  options: { home?: string; projectId?: string | null } = {},
+): CompiledWorkUnit | null {
+  const filePath = compiledWorkUnitPath({ home: options.home, projectId: options.projectId || null, workUnitId });
+  if (!existsSync(filePath)) return null;
+  const parsed = JSON.parse(readFileSync(filePath, 'utf8')) as CompiledWorkUnit;
+  return parsed.schema === 'aria.compiled_work_unit.v1' ? parsed : null;
+}
+
+function uniqueBy<T>(items: T[], key: (item: T) => string): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const item of items) {
+    const id = key(item);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(item);
+  }
+  return out;
+}
+
+export function buildActionEvent(input: ActionLedgerEventInput): ActionLedgerEvent {
+  const createdAt = input.createdAt || new Date().toISOString();
+  const actionId = input.actionId || `act_${randomUUID()}`;
+  const base = {
+    schema: 'aria.action_event.v1' as const,
+    eventId: '',
+    actionId,
+    parentActionId: input.parentActionId || null,
+    sessionId: input.sessionId,
+    threadId: input.threadId || null,
+    surface: input.surface,
+    projectId: input.projectId || null,
+    taskId: input.taskId || null,
+    phaseId: input.phaseId || null,
+    lifecyclePhase: input.lifecyclePhase,
+    status: input.status || 'active',
+    cwd: input.cwd || null,
+    intent: input.intent || null,
+    toolName: input.toolName || null,
+    fileClaims: uniqueBy(input.fileClaims || [], (claim) => claim.path),
+    evidenceRefs: input.evidenceRefs || [],
+    skillReceipt: asRecord(input.skillReceipt),
+    runtimeReceipt: asRecord(input.runtimeReceipt),
+    qaReceipt: asRecord(input.qaReceipt),
+    correctionPlan: asRecord(input.correctionPlan),
+    learningDelta: asRecord(input.learningDelta),
+    atlas: input.atlas || null,
+    sentinelFindings: uniqueBy(input.sentinelFindings || [], (finding) => String(finding.id || `${finding.source}:${finding.kind}:${finding.target}`)),
+    compiledWorkUnit: compiledWorkUnitSummary(input.compiledWorkUnit),
+    metadata: input.metadata || {},
+    createdAt,
+  };
+  const eventHash = actionLedgerSha256(base);
+  return {
+    ...base,
+    eventId: `ev_${eventHash.slice(0, 24)}`,
+    eventHash,
+  };
+}
+
+export function readActionLedgerEvents(options: { home?: string; projectId?: string | null; taskId?: string | null; sessionId?: string | null } = {}): ActionLedgerEvent[] {
+  const paths = actionLedgerPaths(options);
+  if (!existsSync(paths.eventsPath)) return [];
+  return readFileSync(paths.eventsPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as ActionLedgerEvent)
+    .filter((event) => !options.taskId || event.taskId === options.taskId)
+    .filter((event) => !options.sessionId || event.sessionId === options.sessionId);
+}
+
+function readJsonlFile<T = JsonRecord>(filePath: string): T[] {
+  if (!existsSync(filePath)) return [];
+  return readFileSync(filePath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line) as T; } catch { return null; }
+    })
+    .filter((entry): entry is T => Boolean(entry));
+}
+
+export function readActionLedgerPublishOutbox(options: { home?: string; projectId?: string | null; taskId?: string | null; sessionId?: string | null } = {}): ActionLedgerPublishOutboxEntry[] {
+  const paths = actionLedgerPaths(options);
+  return readJsonlFile<ActionLedgerPublishOutboxEntry>(paths.publishOutboxPath)
+    .filter((entry) => !options.taskId || entry.taskId === options.taskId || entry.event?.taskId === options.taskId)
+    .filter((entry) => !options.sessionId || entry.event?.sessionId === options.sessionId);
+}
+
+export function writeActionLedgerPublishOutbox(
+  entries: ActionLedgerPublishOutboxEntry[],
+  options: { home?: string; projectId?: string | null } = {},
+): string {
+  const paths = actionLedgerPaths(options);
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  const body = entries.map((entry) => JSON.stringify(entry)).join('\n');
+  writeFileSync(paths.publishOutboxPath, body ? `${body}\n` : '', { mode: 0o600 });
+  return paths.publishOutboxPath;
+}
+
+function eventForOutboxEntry(
+  entry: ActionLedgerPublishOutboxEntry,
+  eventsById: Map<string, ActionLedgerEvent>,
+): ActionLedgerEvent | null {
+  if (entry.event?.schema === 'aria.action_event.v1') return entry.event;
+  if (entry.eventId && eventsById.has(entry.eventId)) return eventsById.get(entry.eventId) || null;
+  return null;
+}
+
+function taskStatusFromEvent(event: ActionLedgerEvent): string {
+  if (event.status === 'blocked' || event.status === 'failed' || event.status === 'needs_owner') return event.status;
+  if (event.lifecyclePhase === 'task_complete' || event.status === 'completed' || event.status === 'verified') return 'completed';
+  return 'active';
+}
+
+export function projectActionLedger(events: ActionLedgerEvent[]): ActionLedgerProjection {
+  const tasks: Record<string, JsonRecord> = {};
+  const sessions: Record<string, JsonRecord> = {};
+  let latestQa: JsonRecord | null = null;
+  let latestLearningDelta: JsonRecord | null = null;
+  let latestAtlas: ActionLedgerAtlasContext | null = null;
+  let correctionRequired = false;
+  const sentinelFindings: ActionLedgerSentinelFinding[] = [];
+  const compiledWorkUnits: Record<string, ActionLedgerCompiledWorkUnitRef> = {};
+
+  const sorted = [...events].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+  for (const event of sorted) {
+    sessions[event.sessionId] = {
+      sessionId: event.sessionId,
+      threadId: event.threadId,
+      surface: event.surface,
+      latestEventId: event.eventId,
+      latestPhase: event.lifecyclePhase,
+      latestStatus: event.status,
+      updatedAt: event.createdAt,
+    };
+
+    if (event.qaReceipt) {
+      latestQa = event.qaReceipt;
+      if (event.qaReceipt.ok === false || event.qaReceipt.passed === false) correctionRequired = true;
+    }
+    if (event.correctionPlan && event.correctionPlan.required === true) correctionRequired = true;
+    if (event.learningDelta) latestLearningDelta = event.learningDelta;
+    if (event.atlas) latestAtlas = event.atlas;
+    sentinelFindings.push(...event.sentinelFindings);
+    if (event.compiledWorkUnit?.workUnitId) {
+      compiledWorkUnits[event.compiledWorkUnit.workUnitId] = event.compiledWorkUnit;
+    }
+
+    if (!event.taskId) continue;
+    const prior = tasks[event.taskId] || {
+      taskId: event.taskId,
+      projectId: event.projectId,
+      threadId: event.threadId,
+      status: 'active',
+      activePhase: null,
+      phases: {},
+      fileClaims: [],
+      evidenceRefs: [],
+      latestEventId: null,
+      latestQa: null,
+      latestLearningDelta: null,
+      latestAtlas: null,
+      compiledWorkUnitId: null,
+      compiledWorkUnitStatus: null,
+      authorityCap: null,
+      approvalRequired: false,
+      sentinelFindingCount: 0,
+      updatedAt: null,
+    };
+    const phases = asRecord(prior.phases) || {};
+    if (event.phaseId) {
+      phases[event.phaseId] = {
+        phaseId: event.phaseId,
+        status: event.status,
+        latestLifecyclePhase: event.lifecyclePhase,
+        latestEventId: event.eventId,
+        updatedAt: event.createdAt,
+      };
+    }
+    tasks[event.taskId] = {
+      ...prior,
+      status: taskStatusFromEvent(event),
+      activePhase: event.phaseId || prior.activePhase,
+      phases,
+      fileClaims: uniqueBy([...(Array.isArray(prior.fileClaims) ? prior.fileClaims as ActionLedgerFileClaim[] : []), ...event.fileClaims], (claim) => claim.path).slice(-100),
+      evidenceRefs: [...(Array.isArray(prior.evidenceRefs) ? prior.evidenceRefs : []), ...event.evidenceRefs].slice(-100),
+      latestEventId: event.eventId,
+      latestQa: event.qaReceipt || prior.latestQa || null,
+      latestLearningDelta: event.learningDelta || prior.latestLearningDelta || null,
+      latestAtlas: event.atlas || prior.latestAtlas || null,
+      compiledWorkUnitId: event.compiledWorkUnit?.workUnitId || prior.compiledWorkUnitId || null,
+      compiledWorkUnitStatus: event.compiledWorkUnit?.status || prior.compiledWorkUnitStatus || null,
+      authorityCap: event.compiledWorkUnit?.authorityCap ?? prior.authorityCap ?? null,
+      approvalRequired: event.compiledWorkUnit?.approvalRequired ?? prior.approvalRequired ?? false,
+      sentinelFindingCount: Number(prior.sentinelFindingCount || 0) + event.sentinelFindings.length,
+      correctionRequired,
+      updatedAt: event.createdAt,
+    };
+  }
+
+  const latest = sorted[sorted.length - 1] || null;
+  return {
+    schema: 'aria.action_ledger_projection.v1',
+    generatedAt: new Date().toISOString(),
+    eventCount: sorted.length,
+    latestEvent: latest ? {
+      eventId: latest.eventId,
+      actionId: latest.actionId,
+      surface: latest.surface,
+      lifecyclePhase: latest.lifecyclePhase,
+      status: latest.status,
+      createdAt: latest.createdAt,
+    } : null,
+    tasks,
+    sessions,
+    correctionRequired,
+    latestQa,
+    latestLearningDelta,
+    latestAtlas,
+    sentinelFindings: uniqueBy(sentinelFindings, (finding) => String(finding.id || `${finding.source}:${finding.kind}:${finding.target}`)).slice(-50),
+    compiledWorkUnits,
+  };
+}
+
+export function recordActionEventLocal(input: ActionLedgerEventInput, options: { home?: string; projectId?: string | null } = {}): RecordActionEventResult {
+  const event = buildActionEvent(input);
+  const paths = actionLedgerPaths({ home: options.home, projectId: input.projectId || options.projectId || null });
+  mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+  appendFileSync(paths.eventsPath, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+  const projection = projectActionLedger(readActionLedgerEvents({ home: options.home, projectId: input.projectId || options.projectId || null }));
+  writeFileSync(paths.projectionPath, `${JSON.stringify(projection, null, 2)}\n`, { mode: 0o600 });
+  const queuePath = enqueueOwnerAirtableSyncForEvent(event, { home: options.home });
+  projection.ownerAirtableSyncQueuedAt = new Date().toISOString();
+  projection.ownerAirtableSyncQueuePath = queuePath;
+  writeFileSync(paths.projectionPath, `${JSON.stringify(projection, null, 2)}\n`, { mode: 0o600 });
+  return { ok: true, event, paths, projection };
+}
+
+async function defaultPostJson(runtimeUrl: string, route: string, body: JsonRecord): Promise<JsonRecord> {
+  const response = await fetch(`${runtimeUrl.replace(/\/+$/, '')}${route}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed: JsonRecord = {};
+  try { parsed = text ? JSON.parse(text) as JsonRecord : {}; } catch { parsed = { raw: text.slice(0, 1000) }; }
+  if (!response.ok) {
+    throw Object.assign(new Error(`runtime ${route} failed (${response.status}): ${text.slice(0, 1000)}`), { route, status: response.status, body: parsed });
+  }
+  return parsed;
+}
+
+export async function publishActionEventToRuntime(
+  event: ActionLedgerEvent,
+  options: {
+    runtimeUrl?: string;
+    postJson?: (route: string, body: JsonRecord) => Promise<JsonRecord>;
+  } = {},
+): Promise<JsonRecord> {
+  const runtimeUrl = options.runtimeUrl || process.env.ARIA_RUNTIME_URL || 'http://127.0.0.1:4319';
+  const post = options.postJson || ((route: string, body: JsonRecord) => defaultPostJson(runtimeUrl, route, body));
+  const results: JsonRecord[] = [];
+
+  results.push(await post('/api/hive/session-lifecycle', {
+    session_id: event.sessionId,
+    thread_id: event.threadId,
+    event: event.lifecyclePhase,
+    status: event.status,
+    intent_summary: event.intent || `${event.surface} ${event.lifecyclePhase}`,
+    file_claims: event.fileClaims,
+    source: 'action-ledger-core',
+    body: { action_event: event },
+  }));
+
+  if (event.projectId) {
+    results.push(await post('/api/hive/project-context', {
+      project_id: event.projectId,
+      session_id: event.sessionId,
+      thread_id: event.threadId,
+      active_phase: event.phaseId,
+      event: event.lifecyclePhase,
+      source: 'action-ledger-core',
+      capsule: {
+        latest_action_event: {
+          event_id: event.eventId,
+          action_id: event.actionId,
+          event_hash: event.eventHash,
+          surface: event.surface,
+          lifecycle_phase: event.lifecyclePhase,
+          status: event.status,
+        },
+        active_task_id: event.taskId,
+        active_phase: event.phaseId,
+        latest_qa: event.qaReceipt,
+        latest_learning_delta: event.learningDelta,
+        latest_atlas: event.atlas,
+        sentinel_findings: event.sentinelFindings,
+        compiled_work_unit: event.compiledWorkUnit,
+      },
+    }));
+  }
+
+  if (event.taskId) {
+    results.push(await post('/task-project-ledger/event', {
+      platform: event.surface,
+      phase: event.lifecyclePhase,
+      source: 'action-ledger-core',
+      event: {
+        taskId: event.taskId,
+        phaseId: event.phaseId,
+        sessionId: event.sessionId,
+        actionId: event.actionId,
+        eventId: event.eventId,
+        intent: event.intent,
+      },
+      evidence: {
+        actionEventHash: event.eventHash,
+        evidenceRefs: event.evidenceRefs,
+        qaReceipt: event.qaReceipt,
+        correctionPlan: event.correctionPlan,
+        learningDelta: event.learningDelta,
+        atlas: event.atlas,
+        sentinelFindings: event.sentinelFindings,
+        compiledWorkUnit: event.compiledWorkUnit,
+      },
+    }));
+  }
+
+  return {
+    ok: true,
+    routeCount: results.length,
+    routes: [
+      '/api/hive/session-lifecycle',
+      ...(event.projectId ? ['/api/hive/project-context'] : []),
+      ...(event.taskId ? ['/task-project-ledger/event'] : []),
+    ],
+    results,
+  };
+}
+
+export async function recordActionEvent(
+  input: ActionLedgerEventInput,
+  options: {
+    home?: string;
+    projectId?: string | null;
+    publish?: boolean;
+    runtimeUrl?: string;
+    postJson?: (route: string, body: JsonRecord) => Promise<JsonRecord>;
+  } = {},
+): Promise<RecordActionEventResult> {
+  const local = recordActionEventLocal(input, options);
+  if (options.publish === false) return local;
+  try {
+    const publication = await publishActionEventToRuntime(local.event, {
+      runtimeUrl: options.runtimeUrl,
+      postJson: options.postJson,
+    });
+    return { ...local, publication };
+  } catch (error) {
+    const failure = {
+      schema: 'aria.action_event_publish_failure.v1',
+      at: new Date().toISOString(),
+      eventId: local.event.eventId,
+      eventHash: local.event.eventHash,
+      error: error instanceof Error ? error.message : String(error),
+      recovery: 'queued_for_action_event_publish_replay',
+      event: local.event,
+    };
+    appendFileSync(local.paths.publishOutboxPath, `${JSON.stringify(failure)}\n`, { mode: 0o600 });
+    return {
+      ...local,
+      ok: false,
+      publication: {
+        ok: false,
+        queued: true,
+        publishOutboxPath: local.paths.publishOutboxPath,
+        error: failure.error,
+      },
+    };
+  }
+}
+
+export async function replayActionLedgerPublishOutbox(
+  options: {
+    home?: string;
+    projectId?: string | null;
+    taskId?: string | null;
+    sessionId?: string | null;
+    limit?: number;
+    runtimeUrl?: string;
+    postJson?: (route: string, body: JsonRecord) => Promise<JsonRecord>;
+  } = {},
+): Promise<ActionLedgerPublishReplayResult> {
+  const paths = actionLedgerPaths(options);
+  const outbox = readActionLedgerPublishOutbox(options);
+  const eventsById = new Map(readActionLedgerEvents({
+    home: options.home,
+    projectId: options.projectId || null,
+    taskId: options.taskId || null,
+    sessionId: options.sessionId || null,
+  }).map((event) => [event.eventId, event]));
+  const limit = Math.max(0, Number(options.limit || outbox.length || 0));
+  const remaining: ActionLedgerPublishOutboxEntry[] = [];
+  const failures: JsonRecord[] = [];
+  let attempted = 0;
+  let replayed = 0;
+  let skipped = 0;
+
+  for (const entry of outbox) {
+    if (attempted >= limit) {
+      remaining.push(entry);
+      continue;
+    }
+    const event = eventForOutboxEntry(entry, eventsById);
+    if (!event) {
+      skipped += 1;
+      remaining.push({
+        ...entry,
+        lastReplayAt: new Date().toISOString(),
+        lastReplayError: 'missing_action_event',
+      });
+      continue;
+    }
+    attempted += 1;
+    try {
+      await publishActionEventToRuntime(event, {
+        runtimeUrl: options.runtimeUrl,
+        postJson: options.postJson,
+      });
+      replayed += 1;
+    } catch (error) {
+      const failure = {
+        ...entry,
+        event,
+        replayAttempts: Number(entry.replayAttempts || 0) + 1,
+        lastReplayAt: new Date().toISOString(),
+        lastReplayError: error instanceof Error ? error.message : String(error),
+      };
+      remaining.push(failure);
+      failures.push({
+        eventId: event.eventId,
+        projectId: event.projectId,
+        taskId: event.taskId,
+        error: failure.lastReplayError,
+      });
+    }
+  }
+
+  writeActionLedgerPublishOutbox(remaining, options);
+  return {
+    ok: failures.length === 0 && skipped === 0,
+    outboxPath: paths.publishOutboxPath,
+    attempted,
+    replayed,
+    remaining: remaining.length,
+    skipped,
+    failures,
+  };
+}