pi-daddy 0.28.0 → 0.32.0

package/src/work-ledger-types.ts

@@ -1,229 +0,0 @@
-/** Opt-in work-v4 wire identities; none of these declarations grants authority. */
-export type WorkFrozen<T> = T extends ReadonlyArray<infer E>
-  ? ReadonlyArray<WorkFrozen<E>>
-  : T extends object ? { readonly [K in keyof T]: WorkFrozen<T[K]> } : T;
-export type WorkInputCode =
-  | "WORK_JSON_INVALID" | "WORK_DUPLICATE_MEMBER" | "WORK_LIMIT_EXCEEDED"
-  | "WORK_VERSION_UNSUPPORTED" | "WORK_SCHEMA_INVALID"
-  | "WORK_DIGEST_MISMATCH" | "WORK_CONTEXT_INVALID";
-
-export class WorkInputError extends TypeError {
-  readonly code: WorkInputCode;
-  constructor(code: WorkInputCode) {
-    super(code);
-    this.name = "WorkInputError";
-    this.code = code;
-  }
-}
-
-export type WorkWriteCode = "WORK_DESTINATION_INVALID" | "WORK_DESTINATION_ALIAS" | "WORK_LEDGER_WRITE_FAILED";
-export class WorkLedgerWriteError extends Error {
-  readonly code: WorkWriteCode;
-  constructor(code: WorkWriteCode) { super(code); this.name = "WorkLedgerWriteError"; this.code = code; }
-}
-export type WorkInspectionCode = "WORK_INSPECTION_PATH_INVALID" | "WORK_INSPECTION_NOT_REGULAR" | "WORK_INSPECTION_READ_FAILED";
-export interface WorkInspectionDiagnostic { readonly line: null; readonly code: WorkInputCode | WorkInspectionCode }
-export interface WorkLedgerInspection {
-  readonly version: 4;
-  readonly status: "read" | "missing" | "error";
-  readonly exists: boolean | null;
-  readonly ingestion: WorkIngestion | null;
-  readonly projection: WorkProjection | null;
-  readonly errors: ReadonlyArray<WorkInspectionDiagnostic>;
-}
-
-export type RevisionKind = "scope" | "goal" | "node" | "obligation" | "artifact" | "policy";
-export type WorkEventKind = "work_revision" | "work_snapshot" | "work_occurrence" | "work_acceptance";
-export interface RevisionRef { kind: RevisionKind; id: string; revision: number; digest: string }
-export interface EventRef { eventId: string; digest: string }
-export interface Identity { id: string; digest: string }
-export interface WorkRevision {
-  kind: RevisionKind;
-  id: string;
-  revision: number;
-  scopeId: string;
-  predecessor: RevisionRef | null;
-  contentDigest: string;
-  parent: RevisionRef | null;
-  dependencies: RevisionRef[];
-  ownerId: string;
-  permittedEffects: string[];
-  policy: RevisionRef | null;
-  digest: string;
-}
-export interface ObligationBinding {
-  intent: RevisionRef;
-  obligation: RevisionRef;
-  artifact: RevisionRef | null;
-  policy: RevisionRef;
-}
-export interface WorkSnapshot {
-  snapshotId: string;
-  scope: RevisionRef;
-  revisions: RevisionRef[];
-  bindings: ObligationBinding[];
-  digest: string;
-}
-export interface WorkOccurrencePayload {
-  scope: RevisionRef;
-  obligation: RevisionRef;
-  executionId: string;
-  parentExecutionId: string | null;
-  childId: string | null;
-  variantId: string | null;
-  artifact: RevisionRef | null;
-  provenance: "declared" | "observed";
-  state: "unknown" | "starting" | "running" | "completed" | "failed";
-  labels: {
-    sessionId: string | null;
-    branchLeafId: string | null;
-    toolCallId: string | null;
-    taskId: string | null;
-    workspaceId: string | null;
-    definitionDigest: string | null;
-    configurationDigest: string | null;
-    modelId: string | null;
-    effortId: string | null;
-  };
-}
-export interface EvidenceRef { id: string; digest: string; event: EventRef | null }
-export interface AcceptanceBinding {
-  snapshot: Identity;
-  scope: RevisionRef;
-  intent: RevisionRef;
-  obligation: RevisionRef;
-  artifact: RevisionRef;
-  artifactDigest: string;
-  policy: RevisionRef;
-  evidence: EvidenceRef[];
-}
-export interface WorkAcceptancePayload { authorityId: string; binding: AcceptanceBinding }
-interface WorkEvent<K extends WorkEventKind, P> {
-  ledgerVersion: 4;
-  event: K;
-  eventId: string;
-  ts: string;
-  payload: P;
-  digest: string;
-}
-export type WorkRevisionEvent = WorkEvent<"work_revision", { revision: WorkRevision }>;
-export type WorkSnapshotEvent = WorkEvent<"work_snapshot", { snapshot: WorkSnapshot }>;
-export type WorkOccurrenceEvent = WorkEvent<"work_occurrence", WorkOccurrencePayload>;
-export type WorkAcceptanceEvent = WorkEvent<"work_acceptance", WorkAcceptancePayload>;
-export type WorkLedgerEvent = WorkRevisionEvent | WorkSnapshotEvent | WorkOccurrenceEvent | WorkAcceptanceEvent;
-export interface WorkDiagnostic { readonly line: number | null; readonly code: WorkInputCode }
-export interface WorkIngestion {
-  readonly events: ReadonlyArray<WorkLedgerEvent>;
-  readonly errors: ReadonlyArray<WorkDiagnostic>;
-  readonly complete: boolean;
-}
-
-export type WorkResolutionCode =
-  | "INPUT_INCOMPLETE" | "NO_SELECTION" | "REFERENCE_MISSING"
-  | "SCOPE_INVALID" | "REVISION_INVALID" | "CYCLE" | "DEPENDENCY_INVALID"
-  | "EVENT_CONFLICT" | "ARTIFACT_UNSELECTED" | "ARTIFACT_DIGEST_MISMATCH"
-  | "NO_CLAIM" | "SUPERSEDED_BINDING" | "AUTHORITY_MISSING"
-  | "RECEIPT_MISSING" | "RECEIPT_MISMATCH" | "RECEIPT_CONFLICT" | "DECISION_CONFLICT"
-  | "TRUSTED_REJECTION" | "AVAILABILITY_MISSING" | "BYTES_UNAVAILABLE"
-  | "AVAILABILITY_CONFLICT" | "OCCURRENCE_CONFLICT"
-  | "PARENT_MISSING" | "PARENT_CYCLE" | "OBSERVATION_CONFLICT" | "BRANCH_UNKNOWN";
-export type WorkReference =
-  | { readonly type: "revision"; readonly ref: RevisionRef }
-  | { readonly type: "event"; readonly ref: EventRef }
-  | { readonly type: "snapshot" | "authority" | "artifact-bytes" | "evidence-bytes"; readonly ref: Identity }
-  | { readonly type: "execution"; readonly id: string };
-export interface WorkProblem {
-  readonly code: WorkResolutionCode;
-  readonly reference: WorkReference | null;
-  readonly affectedObligations: ReadonlyArray<RevisionRef>;
-}
-export interface WorkConflict {
-  readonly kind: "event" | "receipt";
-  readonly id: string;
-  readonly digests: ReadonlyArray<string>;
-  readonly affectedObligations: ReadonlyArray<RevisionRef>;
-}
-
-/** Explicit trusted-host declarations, never constructed from wire evidence by production code. */
-export interface WorkProjectionContext {
-  selectedSnapshot: { snapshot: Identity; event: EventRef } | null;
-  authority: {
-    snapshot: Identity;
-    decisions: Array<{
-      receiptId: string;
-      authorityId: string;
-      claim: EventRef;
-      binding: AcceptanceBinding;
-      decision: "accept" | "reject";
-    }>;
-    availability: Array<{ kind: "artifact" | "evidence"; id: string; digest: string; available: boolean }>;
-  } | null;
-}
-export type WorkAvailability = "available" | "unavailable" | "unknown" | "conflicted";
-export interface WorkCoverageItem {
-  readonly kind: "artifact" | "evidence";
-  readonly identity: Identity;
-  readonly state: WorkAvailability;
-}
-export interface WorkCoverage {
-  readonly state: WorkAvailability | "unselected";
-  readonly items: ReadonlyArray<WorkCoverageItem>;
-}
-export type WorkAcceptanceState = "accepted-under-supplied-authority" | "unaccepted" | "unresolved";
-export interface WorkClaimResult {
-  readonly claim: EventRef;
-  readonly obligation: RevisionRef;
-  readonly applicability: WorkAcceptanceState | "superseded";
-  readonly matchedReceiptIds: ReadonlyArray<string>;
-  readonly problems: ReadonlyArray<WorkProblem>;
-}
-export interface WorkObligationResult {
-  readonly binding: ObligationBinding;
-  readonly acceptance: WorkAcceptanceState;
-  readonly artifactCoverage: WorkCoverage;
-  readonly evidenceCoverage: WorkCoverage;
-  readonly claims: ReadonlyArray<EventRef>;
-  readonly problems: ReadonlyArray<WorkProblem>;
-}
-export interface WorkOccurrenceView { readonly event: EventRef; readonly payload: WorkOccurrencePayload }
-export interface WorkAttemptBinding {
-  readonly scope: RevisionRef;
-  readonly obligation: RevisionRef;
-  readonly variantIds: ReadonlyArray<string>;
-  readonly artifacts: ReadonlyArray<RevisionRef>;
-}
-export interface WorkAttempt {
-  readonly executionId: string;
-  readonly bindings: ReadonlyArray<WorkAttemptBinding>;
-  readonly parentExecutionId: string | null;
-  readonly childId: string | null;
-  readonly declaredLabels: ReadonlyArray<WorkOccurrencePayload["labels"]>;
-  readonly observedLabels: ReadonlyArray<WorkOccurrencePayload["labels"]>;
-  readonly effectiveLabels: WorkOccurrencePayload["labels"];
-  readonly state: WorkOccurrencePayload["state"] | "conflicted";
-  readonly resolution: "resolved" | "unresolved";
-  readonly problems: ReadonlyArray<WorkProblem>;
-}
-export interface WorkRuntimeCounts {
-  readonly attempts: number;
-  readonly variants: number;
-  readonly observedCompletedAttempts: number;
-}
-export interface WorkRuntime {
-  readonly counts: WorkRuntimeCounts;
-  readonly occurrences: ReadonlyArray<WorkOccurrenceView>;
-  readonly attempts: ReadonlyArray<WorkAttempt>;
-}
-export interface WorkProjection {
-  readonly selectedSnapshot: Identity | null;
-  readonly authoritySnapshot: Identity | null;
-  readonly scopeState: "unselected" | "valid" | "unresolved" | "invalid";
-  readonly progress: Readonly<{ accepted: number; total: number }> | null;
-  readonly obligations: ReadonlyArray<WorkObligationResult>;
-  readonly claims: ReadonlyArray<WorkClaimResult>;
-  readonly supersededClaims: number;
-  readonly conflicts: ReadonlyArray<WorkConflict>;
-  readonly problems: ReadonlyArray<WorkProblem>;
-  readonly errors: ReadonlyArray<WorkDiagnostic>;
-  readonly runtime: WorkRuntime | null;
-}

package/src/work-ledger-validation.ts

@@ -1,174 +0,0 @@
-import { isExecutionId } from "./execution-id.ts";
-import { canonicalWorkJson, workDigest, type WorkJson } from "./work-ledger-json.ts";
-import { WorkInputError, type WorkLedgerEvent } from "./work-ledger-types.ts";
-
-type ObjectValue = { [key: string]: WorkJson };
-const kinds = ["scope", "goal", "node", "obligation", "artifact", "policy"];
-const fail = (): never => { throw new WorkInputError("WORK_SCHEMA_INVALID"); };
-function require(value: boolean): asserts value { if (!value) fail(); }
-export function workObject(value: WorkJson): ObjectValue {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return fail();
-  return value;
-}
-function closed(value: WorkJson, keys: string[]): ObjectValue {
-  const object = workObject(value);
-  require(Object.keys(object).length === keys.length && keys.every(key => Object.hasOwn(object, key)));
-  return object;
-}
-function id(value: WorkJson): void { require(typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,127}$/.test(value)); }
-function digest(value: WorkJson): void { require(typeof value === "string" && /^[0-9a-f]{64}$/.test(value)); }
-function integer(value: WorkJson): void { require(typeof value === "number" && Number.isSafeInteger(value) && value >= 1); }
-function member(value: WorkJson, values: string[]): void { require(typeof value === "string" && values.includes(value)); }
-function nullable(value: WorkJson, validate: (value: WorkJson) => void): void { if (value !== null) validate(value); }
-function reference(value: WorkJson, allowed = kinds): void {
-  const ref = closed(value, ["kind", "id", "revision", "digest"]);
-  member(ref.kind, allowed); id(ref.id); integer(ref.revision); digest(ref.digest);
-}
-function identity(value: WorkJson): void {
-  const ref = closed(value, ["id", "digest"]); id(ref.id); digest(ref.digest);
-}
-function eventRef(value: WorkJson): void {
-  const ref = closed(value, ["eventId", "digest"]); id(ref.eventId); digest(ref.digest);
-}
-/** Internal validation for the exact out-of-band selectedSnapshot shape; no authority is constructed. */
-export function validateWorkSelection(value: WorkJson): void {
-  if (value === null) return;
-  const selected = closed(value, ["snapshot", "event"]);
-  identity(selected.snapshot); eventRef(selected.event);
-}
-
-function timestamp(value: WorkJson): void {
-  require(typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value));
-  require(!value.startsWith("0000") && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value);
-}
-
-/** Builder sorts detached copies; reader refuses noncanonical sets instead of repairing them. */
-function set(value: WorkJson, validate: (item: WorkJson) => void, building: boolean,
-  key: (item: WorkJson) => string = canonicalWorkJson): void {
-  require(Array.isArray(value));
-  value.forEach(validate);
-  const keyed = value.map(item => ({ item, key: key(item) }));
-  const sorted = [...keyed].sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
-  for (let i = 1; i < sorted.length; i++) require(sorted[i - 1].key !== sorted[i].key);
-  if (building) value.splice(0, value.length, ...sorted.map(entry => entry.item));
-  else require(keyed.every((entry, i) => entry.key === sorted[i].key));
-}
-function ownKeys(keys: string[], building: boolean): string[] { return building ? keys : [...keys, "digest"]; }
-
-function revision(value: WorkJson, building: boolean): void {
-  const r = closed(value, ownKeys(["kind", "id", "revision", "scopeId", "predecessor", "contentDigest",
-    "parent", "dependencies", "ownerId", "permittedEffects", "policy"], building));
-  member(r.kind, kinds); id(r.id); integer(r.revision); id(r.scopeId); id(r.ownerId); digest(r.contentDigest);
-  nullable(r.predecessor, v => reference(v));
-  nullable(r.parent, v => reference(v));
-  nullable(r.policy, v => reference(v, ["policy"]));
-  set(r.dependencies, v => reference(v, ["obligation"]), building);
-  set(r.permittedEffects, id, building, v => v as string);
-  if (r.revision === 1) require(r.predecessor === null);
-  else {
-    require(r.predecessor !== null);
-    const predecessor = workObject(r.predecessor);
-    require(predecessor.kind === r.kind && predecessor.id === r.id &&
-      (predecessor.revision as number) === (r.revision as number) - 1);
-  }
-  const noDependencies = (r.dependencies as WorkJson[]).length === 0;
-  if (r.kind === "scope") require(r.scopeId === r.id && r.parent === null && noDependencies && r.policy === null);
-  if (r.kind === "artifact" || r.kind === "policy") {
-    require(r.parent === null && noDependencies && r.policy === null && (r.permittedEffects as WorkJson[]).length === 0);
-  }
-  if (r.kind === "goal" || r.kind === "node" || r.kind === "obligation") {
-    reference(r.parent, r.kind === "goal" ? ["scope", "goal"] : ["goal", "node"]);
-    if (r.kind === "obligation") reference(r.policy, ["policy"]);
-    else require(noDependencies && r.policy === null);
-  }
-  if (!building) digest(r.digest);
-}
-function obligationBinding(value: WorkJson): void {
-  const b = closed(value, ["intent", "obligation", "artifact", "policy"]);
-  reference(b.intent, ["goal", "node"]); reference(b.obligation, ["obligation"]);
-  nullable(b.artifact, v => reference(v, ["artifact"])); reference(b.policy, ["policy"]);
-}
-function snapshot(value: WorkJson, building: boolean): void {
-  const s = closed(value, ownKeys(["snapshotId", "scope", "revisions", "bindings"], building));
-  id(s.snapshotId); reference(s.scope, ["scope"]);
-  set(s.revisions, v => reference(v, kinds.filter(k => k !== "scope")), building);
-  set(s.bindings, obligationBinding, building, v => canonicalWorkJson(workObject(v).obligation));
-  if (!building) digest(s.digest);
-  // Inventory/ancestor/predecessor resolution requires the complete event snapshot, not a guessed head.
-}
-function occurrence(value: WorkJson): void {
-  const p = closed(value, ["scope", "obligation", "executionId", "parentExecutionId", "childId", "variantId",
-    "artifact", "provenance", "state", "labels"]);
-  reference(p.scope, ["scope"]); reference(p.obligation, ["obligation"]);
-  require(isExecutionId(p.executionId));
-  require(p.parentExecutionId === null || isExecutionId(p.parentExecutionId));
-  require(p.executionId !== p.parentExecutionId);
-  nullable(p.childId, id); nullable(p.variantId, id); nullable(p.artifact, v => reference(v, ["artifact"]));
-  member(p.provenance, ["declared", "observed"]);
-  member(p.state, ["unknown", "starting", "running", "completed", "failed"]);
-  const labels = closed(p.labels, ["sessionId", "branchLeafId", "toolCallId", "taskId", "workspaceId",
-    "definitionDigest", "configurationDigest", "modelId", "effortId"]);
-  for (const [key, value] of Object.entries(labels)) nullable(value, key.endsWith("Digest") ? digest : id);
-}
-function evidence(value: WorkJson): void {
-  const e = closed(value, ["id", "digest", "event"]);
-  id(e.id); digest(e.digest); nullable(e.event, eventRef);
-}
-function acceptance(value: WorkJson, building: boolean): void {
-  const p = closed(value, ["authorityId", "binding"]); id(p.authorityId);
-  acceptanceBinding(p.binding, building);
-}
-function acceptanceBinding(value: WorkJson, building: boolean): void {
-  const b = closed(value, ["snapshot", "scope", "intent", "obligation", "artifact", "artifactDigest", "policy", "evidence"]);
-  identity(b.snapshot); reference(b.scope, ["scope"]); reference(b.intent, ["goal", "node"]);
-  reference(b.obligation, ["obligation"]); reference(b.artifact, ["artifact"]);
-  digest(b.artifactDigest); reference(b.policy, ["policy"]);
-  set(b.evidence, evidence, building); require((b.evidence as WorkJson[]).length > 0);
-}
-
-/** Validate a detached host context. Receipt/availability order and duplicate deliveries have no priority. */
-export function validateWorkContext(value: WorkJson): void {
-  const c = closed(value, ["selectedSnapshot", "authority"]);
-  validateWorkSelection(c.selectedSnapshot);
-  if (c.authority === null) return;
-  const a = closed(c.authority, ["snapshot", "decisions", "availability"]);
-  identity(a.snapshot);
-  require(Array.isArray(a.decisions)); require(Array.isArray(a.availability));
-  for (const value of a.decisions) {
-    const d = closed(value, ["receiptId", "authorityId", "claim", "binding", "decision"]);
-    id(d.receiptId); id(d.authorityId); eventRef(d.claim); acceptanceBinding(d.binding, false);
-    member(d.decision, ["accept", "reject"]);
-  }
-  for (const value of a.availability) {
-    const row = closed(value, ["kind", "id", "digest", "available"]);
-    member(row.kind, ["artifact", "evidence"]); id(row.id); digest(row.digest);
-    require(typeof row.available === "boolean");
-  }
-}
-
-function ownDigest(object: ObjectValue, building: boolean): void {
-  const { digest: supplied, ...body } = object;
-  const computed = workDigest(body);
-  if (building) object.digest = computed;
-  else if (supplied !== computed) throw new WorkInputError("WORK_DIGEST_MISMATCH");
-}
-
-/** All closed shapes/domain checks finish before any own digest is computed or verified. */
-export function validateWorkEvent(value: WorkJson, building = false): WorkLedgerEvent {
-  const e = workObject(value);
-  if (e.ledgerVersion !== 4) throw new WorkInputError("WORK_VERSION_UNSUPPORTED");
-  closed(e, ownKeys(["ledgerVersion", "event", "eventId", "ts", "payload"], building));
-  member(e.event, ["work_revision", "work_snapshot", "work_occurrence", "work_acceptance"]);
-  id(e.eventId); timestamp(e.ts);
-  let nested: ObjectValue | undefined;
-  if (e.event === "work_revision") {
-    nested = workObject(closed(e.payload, ["revision"]).revision); revision(nested, building);
-  } else if (e.event === "work_snapshot") {
-    nested = workObject(closed(e.payload, ["snapshot"]).snapshot); snapshot(nested, building);
-  } else if (e.event === "work_occurrence") occurrence(e.payload);
-  else acceptance(e.payload, building);
-  if (!building) digest(e.digest);
-  if (nested) ownDigest(nested, building);
-  ownDigest(e, building);
-  return e as unknown as WorkLedgerEvent;
-}

package/src/work-ledger.ts

@@ -1,186 +0,0 @@
-/** Opt-in work-v4 evidence. No default emission or built-in acceptance authority. */
-import { isDate } from "node:util/types";
-import { open, stat } from "node:fs/promises";
-import { constants } from "node:fs";
-import { appendLedgerLine, readWorkBytes, closeWorkHandle } from "./ledger-append.ts";
-import { workDestination, workFsError, validWorkPath } from "./work-ledger-destination.ts";
-import { LockTimeoutError } from "./file-lock.ts";
-import {
-  canonicalWorkJson, copyWorkJson, freezeWork, ownWorkFields, parseWorkJson,
-  WORK_EVENT_BYTES, WORK_TEXT_BYTES, WORK_RECORDS, mergeWorkConflicts,
-} from "./work-ledger-json.ts";
-import { validateWorkEvent, validateWorkContext } from "./work-ledger-validation.ts";
-import { indexWorkLedgerText, indexWorkReceipts, projectWorkAcceptance } from "./work-ledger-projection.ts";
-import { resolveWorkSnapshotText } from "./work-ledger-snapshot.ts";
-import { foldWorkOccurrences } from "./work-ledger-occurrences.ts";
-import {
-  WorkInputError, type WorkAcceptanceEvent, type WorkAcceptancePayload, type WorkDiagnostic,
-  type WorkFrozen, type WorkIngestion, type WorkLedgerEvent, type WorkOccurrenceEvent,
-  type WorkOccurrencePayload, type WorkRevision, type WorkRevisionEvent, type WorkSnapshot,
-  type WorkSnapshotEvent, type WorkEventKind, type WorkProjectionContext, type WorkProjection,
-  type WorkProblem, type WorkConflict, WorkLedgerWriteError, type WorkLedgerInspection, type WorkInspectionDiagnostic,
-} from "./work-ledger-types.ts";
-export * from "./work-ledger-types.ts";
-
-function build(args: unknown, kind: WorkEventKind, field: "revision" | "snapshot" | "payload"): WorkFrozen<WorkLedgerEvent> {
-  const fields = ownWorkFields(args);
-  const required = ["eventId", "now", field];
-  if (Object.keys(fields).length !== required.length || required.some(key => !Object.hasOwn(fields, key))) {
-    throw new WorkInputError("WORK_SCHEMA_INVALID");
-  }
-  const now = fields.now.value;
-  if (!isDate(now) || Object.getPrototypeOf(now) !== Date.prototype || Reflect.ownKeys(now).length !== 0 ||
-      !Number.isFinite(Date.prototype.getTime.call(now))) throw new WorkInputError("WORK_SCHEMA_INVALID");
-  const content = copyWorkJson(fields[field].value);
-  const candidate = copyWorkJson({ ledgerVersion: 4, event: kind, eventId: fields.eventId.value,
-    ts: Date.prototype.toISOString.call(now), payload: field === "payload" ? content : { [field]: content } });
-  const event = validateWorkEvent(candidate, true);
-  if (Buffer.byteLength(canonicalWorkJson(event), "utf8") > WORK_EVENT_BYTES) throw new WorkInputError("WORK_LIMIT_EXCEEDED");
-  return freezeWork(event);
-}
-
-export function buildWorkRevisionEvent(args: { eventId: string; now: Date; revision: Omit<WorkRevision, "digest"> }): WorkFrozen<WorkRevisionEvent> {
-  return build(args, "work_revision", "revision") as WorkFrozen<WorkRevisionEvent>;
-}
-export function buildWorkSnapshotEvent(args: { eventId: string; now: Date; snapshot: Omit<WorkSnapshot, "digest"> }): WorkFrozen<WorkSnapshotEvent> {
-  return build(args, "work_snapshot", "snapshot") as WorkFrozen<WorkSnapshotEvent>;
-}
-export function buildWorkOccurrenceEvent(args: { eventId: string; now: Date; payload: WorkOccurrencePayload }): WorkFrozen<WorkOccurrenceEvent> {
-  return build(args, "work_occurrence", "payload") as WorkFrozen<WorkOccurrenceEvent>;
-}
-export function buildWorkAcceptanceEvent(args: { eventId: string; now: Date; payload: WorkAcceptancePayload }): WorkFrozen<WorkAcceptanceEvent> {
-  return build(args, "work_acceptance", "payload") as WorkFrozen<WorkAcceptanceEvent>;
-}
-
-function* lines(text: string): Generator<{ text: string; line: number }> {
-  let start = 0, line = 1;
-  while (start < text.length) {
-    const end = text.indexOf("\n", start);
-    yield { text: text.slice(start, end === -1 ? text.length : end), line: line++ };
-    if (end === -1) return;
-    start = end + 1;
-  }
-}
-const blank = (text: string): boolean => /^[ \t\r]*$/.test(text);
-
-/** Diagnostic boundary: retain physical valid deliveries, never rewrite, deduplicate or elect a winner. */
-export function parseWorkLedgerText(text: string): WorkFrozen<WorkIngestion> {
-  const wholeError = (code: WorkDiagnostic["code"]) => freezeWork({ events: [], errors: [{ line: null, code }], complete: false });
-  if (typeof text !== "string") return wholeError("WORK_SCHEMA_INVALID");
-  if (Buffer.byteLength(text, "utf8") > WORK_TEXT_BYTES) return wholeError("WORK_LIMIT_EXCEEDED");
-  let records = 0;
-  for (const row of lines(text)) if (!blank(row.text) && ++records > WORK_RECORDS) return wholeError("WORK_LIMIT_EXCEEDED");
-  const events: WorkLedgerEvent[] = [], errors: WorkDiagnostic[] = [];
-  for (const row of lines(text)) {
-    if (blank(row.text)) continue;
-    try { events.push(validateWorkEvent(parseWorkJson(row.text))); }
-    catch (error) {
-      if (!(error instanceof WorkInputError)) throw error;
-      errors.push({ line: row.line, code: error.code });
-    }
-  }
-  return freezeWork({ events, errors, complete: errors.length === 0 });
-}
-
-/** Public opt-in projection: strict text, detached host context, exact selection, actual runtime,
- * then conditional authority binding. No I/O, authenticator, ambient trust or acceptance callback. */
-export function projectWorkLedger(text: string, context: WorkFrozen<WorkProjectionContext> = { selectedSnapshot: null, authority: null }): WorkFrozen<WorkProjection> {
-  const index = indexWorkLedgerText(text);
-  const errors: WorkFrozen<WorkDiagnostic>[] = [...index.ingestion.errors];
-  let copied: WorkFrozen<WorkProjectionContext> | null = null;
-  try {
-    const value = copyWorkJson(context);
-    validateWorkContext(value);
-    copied = JSON.parse(canonicalWorkJson(value)) as WorkProjectionContext;
-  } catch (error) {
-    if (!(error instanceof WorkInputError)) throw error;
-    errors.push({ line: null, code: "WORK_CONTEXT_INVALID" });
-  }
-  errors.sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity) || (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
-  const conflicts = mergeWorkConflicts([
-    ...index.conflictingEvents.map(ref => ({ kind: "event" as const, id: ref.eventId, digests: [ref.digest], affectedObligations: [] })),
-    ...indexWorkReceipts(copied?.authority ?? null).conflicts,
-  ]);
-  const identities = { selectedSnapshot: copied?.selectedSnapshot?.snapshot ?? null, authoritySnapshot: copied?.authority?.snapshot ?? null };
-  function empty(scopeState: WorkProjection["scopeState"], problems: readonly WorkFrozen<WorkProblem>[], retained: readonly WorkFrozen<WorkConflict>[] = conflicts) {
-    return freezeWork({ ...identities, scopeState, progress: null, obligations: [], claims: [], supersededClaims: 0,
-      conflicts: mergeWorkConflicts([...retained, ...conflicts]), problems, errors, runtime: null });
-  }
-  if (errors.length) return empty("unresolved", [{ code: "INPUT_INCOMPLETE", reference: null, affectedObligations: [] }]);
-  const structure = resolveWorkSnapshotText(text, copied!.selectedSnapshot);
-  if (structure.scopeState !== "valid") return empty(structure.scopeState, structure.problems, structure.conflicts);
-  const runtime = foldWorkOccurrences(index, structure.snapshot!);
-  const acceptance = projectWorkAcceptance(index, structure, copied!.authority, runtime);
-  return freezeWork({ ...identities, scopeState: "valid", ...acceptance, errors, runtime: runtime.runtime });
-}
-
-/** Always opt-in, strict, and detached before the first filesystem await. No environment defaults. */
-export function appendWorkLedgerEvent(options: { path: string; grantLedgerPath: string | null }, event: WorkFrozen<WorkLedgerEvent>): Promise<void> {
-  return appendWorkEvent(options, event, false);
-}
-/** Explicit controller application seam: exact ID/digest redelivery does not append a second event. */
-export function appendWorkLedgerEventOnce(options: { path: string; grantLedgerPath: string | null }, event: WorkFrozen<WorkLedgerEvent>): Promise<void> {
-  return appendWorkEvent(options, event, true);
-}
-async function appendWorkEvent(options: { path: string; grantLedgerPath: string | null }, event: WorkFrozen<WorkLedgerEvent>, once: boolean): Promise<void> {
-  const fields = ownWorkFields(options);
-  if (Object.keys(fields).length !== 2 || !Object.hasOwn(fields, "path") || !Object.hasOwn(fields, "grantLedgerPath") || typeof fields.path.value !== "string" ||
-      (fields.grantLedgerPath.value !== null && typeof fields.grantLedgerPath.value !== "string")) throw new WorkInputError("WORK_SCHEMA_INVALID");
-  const path: string = fields.path.value, grant: string | null = fields.grantLedgerPath.value;
-  const candidate = validateWorkEvent(copyWorkJson(event));
-  const canonical = canonicalWorkJson(candidate);
-  if (Buffer.byteLength(canonical, "utf8") > WORK_EVENT_BYTES) throw new WorkInputError("WORK_LIMIT_EXCEEDED");
-  try {
-    const destination = await workDestination(path, grant);
-    await appendLedgerLine({ path: destination.path }, canonical + "\n", destination, once ? { eventId: candidate.eventId, digest: candidate.digest } : undefined);
-  } catch (error) {
-    if (error instanceof LockTimeoutError || workFsError(error)) throw new WorkLedgerWriteError("WORK_LEDGER_WRITE_FAILED");
-    throw error;
-  }
-}
-
-/** Read-only regular-file inspection; a successful read is not a content-validity or acceptance claim. */
-export async function inspectWorkLedger(options: { version: 4; path: string },
-  context: WorkFrozen<WorkProjectionContext> = { selectedSnapshot: null, authority: null }): Promise<WorkFrozen<WorkLedgerInspection>> {
-  let exists: boolean | null = null;
-  const failure = (code: WorkInspectionDiagnostic["code"]): WorkFrozen<WorkLedgerInspection> => freezeWork({
-    version: 4, status: "error", exists, ingestion: null, projection: null, errors: [{ line: null, code }],
-  });
-  const missing = (): WorkFrozen<WorkLedgerInspection> => freezeWork({ version: 4, status: "missing", exists: false,
-    ingestion: null, projection: null, errors: [] });
-  let path: string, copied: WorkFrozen<WorkProjectionContext>;
-  try {
-    const fields = ownWorkFields(options);
-    if (Object.keys(fields).length !== 2 || !Object.hasOwn(fields, "path") || !Object.hasOwn(fields, "version") || typeof fields.path.value !== "string") throw new WorkInputError("WORK_SCHEMA_INVALID");
-    if (fields.version.value !== 4) throw new WorkInputError("WORK_VERSION_UNSUPPORTED");
-    path = fields.path.value;
-    try { const value = copyWorkJson(context); validateWorkContext(value); copied = value as unknown as WorkFrozen<WorkProjectionContext>; }
-    catch (error) { if (error instanceof WorkInputError) throw new WorkInputError("WORK_CONTEXT_INVALID"); throw error; }
-  } catch (error) { if (error instanceof WorkInputError) return failure(error.code); throw error; }
-  if (!validWorkPath(path)) return failure("WORK_INSPECTION_PATH_INVALID");
-  try {
-    let info;
-    try { info = await stat(path); }
-    catch (error) {
-      if (workFsError(error) && error.code === "ENOENT") return missing();
-      throw error;
-    }
-    exists = true;
-    if (!info.isFile()) return failure("WORK_INSPECTION_NOT_REGULAR");
-    let handle: Awaited<ReturnType<typeof open>>;
-    try { handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK); }
-    catch (error) { if (workFsError(error) && error.code === "ENOENT") return missing(); throw error; }
-    let failed = false, bytes: Buffer;
-    try {
-      if (!(await handle.stat()).isFile()) return failure("WORK_INSPECTION_NOT_REGULAR");
-      bytes = await readWorkBytes(handle);
-    } catch (error) { failed = true; throw error; }
-    finally { await closeWorkHandle(handle, failed); }
-    const text = bytes.toString("utf8");
-    return freezeWork({ version: 4, status: "read", exists: true, ingestion: parseWorkLedgerText(text), projection: projectWorkLedger(text, copied), errors: [] });
-  } catch (error) {
-    if (error instanceof WorkInputError) return failure(error.code);
-    if (workFsError(error)) return failure("WORK_INSPECTION_READ_FAILED");
-    throw error;
-  }
-}