pi-daddy 0.22.0 → 0.23.0

package/src/work-ledger-snapshot.ts

@@ -0,0 +1,246 @@
+import { indexWorkLedgerText, workEventConflictSources, workRevisionConflictSources } from "./work-ledger-projection.ts";
+import { canonicalWorkJson, copyWorkJson, freezeWork } from "./work-ledger-json.ts";
+import { validateWorkSelection } from "./work-ledger-validation.ts";
+import {
+  WorkInputError, type EventRef, type Identity, type ObligationBinding, type RevisionRef,
+  type WorkConflict, type WorkDiagnostic, type WorkFrozen, type WorkProblem, type WorkReference,
+  type WorkResolutionCode, type WorkRevision, type WorkSnapshot,
+} from "./work-ledger-types.ts";
+
+type Ref = WorkFrozen<RevisionRef>;
+type Revision = WorkFrozen<WorkRevision>;
+type Problem = WorkFrozen<WorkProblem>;
+/** Internal shape of WorkProjectionContext.selectedSnapshot, not an authority context. */
+interface Selection { snapshot: Identity; event: EventRef }
+/** Internal structural result only. Never a substitute for WorkProjection/acceptance/runtime. */
+interface SnapshotResolution {
+  readonly scopeState: "unselected" | "valid" | "unresolved" | "invalid";
+  readonly selectedSnapshot: WorkFrozen<Identity> | null;
+  readonly snapshot: WorkFrozen<WorkSnapshot> | null;
+  readonly scope: Revision | null;
+  readonly revisions: readonly Revision[];
+  readonly obligations: ReadonlyArray<{
+    readonly binding: WorkFrozen<ObligationBinding>;
+    readonly revision: Revision;
+    readonly artifact: Revision | null;
+    readonly problems: readonly Problem[];
+  }>;
+  readonly problems: readonly Problem[];
+  readonly conflicts: ReadonlyArray<WorkFrozen<WorkConflict>>;
+  readonly errors: ReadonlyArray<WorkFrozen<WorkDiagnostic>>;
+}
+const key = canonicalWorkJson;
+const entity = (ref: Ref): string => `${ref.kind}:${ref.id}`;
+const reference = (ref: Ref): WorkFrozen<WorkReference> => ({ type: "revision", ref });
+function unique<T>(values: readonly T[]): T[] {
+  const rows = new Map(values.map(value => [key(value), value]));
+  return [...rows].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, value]) => value);
+}
+function diagnosticKey(row: Problem | WorkFrozen<WorkConflict>): string {
+  // Internally built output collections may exceed the wire array bound (e.g. 300 conflicting
+  // deliveries). Only their validated scalar/reference constituents use the wire canonicalizer.
+  const affected = key(row.affectedObligations);
+  return "code" in row
+    ? `{"affectedObligations":${affected},"code":${JSON.stringify(row.code)},"reference":${key(row.reference)}}`
+    : `{"affectedObligations":${affected},"digests":${JSON.stringify(row.digests)},"id":${JSON.stringify(row.id)},"kind":${JSON.stringify(row.kind)}}`;
+}
+function sortedDiagnostics<T extends Problem | WorkFrozen<WorkConflict>>(rows: T[]): T[] {
+  return rows.map(value => ({ value, key: diagnosticKey(value) }))
+    .sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0).map(row => row.value);
+}
+
+/** @internal Real builder/text/index/selector path. No unchecked parsed-object projection entry. */
+export function resolveWorkSnapshotText(text: string, requested: WorkFrozen<Selection> | null = null): SnapshotResolution {
+  const index = indexWorkLedgerText(text);
+  const errors: WorkFrozen<WorkDiagnostic>[] = [...index.ingestion.errors];
+  let selection: WorkFrozen<Selection> | null = null;
+  try {
+    const copied = copyWorkJson(requested);
+    validateWorkSelection(copied);
+    selection = copied as unknown as WorkFrozen<Selection> | null;
+  } catch (error) {
+    if (!(error instanceof WorkInputError)) throw error;
+    errors.push({ line: null, code: "WORK_CONTEXT_INVALID" });
+  }
+  const problems = new Map<string, Problem>();
+  const conflicts = new Map<string, { digests: string[]; affected: Ref[] }>();
+  for (const ref of index.conflictingEvents) {
+    const row = conflicts.get(ref.eventId) ?? { digests: [], affected: [] };
+    row.digests.push(ref.digest); conflicts.set(ref.eventId, row);
+  }
+  function problem(code: WorkResolutionCode, ref: WorkFrozen<WorkReference> | null, affected: readonly Ref[] = []) {
+    const id = `${code}:${key(ref)}`;
+    const old = problems.get(id);
+    problems.set(id, { code, reference: ref, affectedObligations: unique([...(old?.affectedObligations ?? []), ...affected]) });
+  }
+  function conflict(id: string, affected: readonly Ref[]) {
+    const row = conflicts.get(id);
+    if (!row) return;
+    row.affected = unique([...row.affected, ...affected]);
+    for (const digest of row.digests) problem("EVENT_CONFLICT", { type: "event", ref: { eventId: id, digest } }, affected);
+  }
+  function reports() {
+    return {
+      problems: sortedDiagnostics([...problems.values()]),
+      conflicts: sortedDiagnostics([...conflicts].map(([id, row]) => ({
+        kind: "event" as const, id, digests: [...row.digests].sort(), affectedObligations: unique(row.affected),
+      }))), errors,
+    };
+  }
+  function empty(scopeState: SnapshotResolution["scopeState"]): SnapshotResolution {
+    return freezeWork({ scopeState, selectedSnapshot: selection?.snapshot ?? null,
+      snapshot: null, scope: null, revisions: [], obligations: [], ...reports() });
+  }
+  if (errors.length) { problem("INPUT_INCOMPLETE", null); return empty("unresolved"); }
+  if (!selection) { problem("NO_SELECTION", null); return empty("unselected"); }
+
+  // Exact event AND nested snapshot identity: never elect a head from candidate order or time.
+  const nominated = index.candidates.find(event => event.eventId === selection!.event.eventId && event.digest === selection!.event.digest);
+  const exactSnapshot = nominated?.event === "work_snapshot" &&
+    nominated.payload.snapshot.snapshotId === selection.snapshot.id && nominated.payload.snapshot.digest === selection.snapshot.digest
+    ? nominated.payload.snapshot : null;
+  // A nominated inventory is diagnostic evidence only until ALL conflicting source IDs have been
+  // checked. Nested identity, not delivery ID/time, connects an alias to the selected closure.
+  const affected = exactSnapshot?.revisions.filter(ref => ref.kind === "obligation") ?? [];
+  const snapshotSources = workEventConflictSources(index, exactSnapshot ? nominated! : selection.event);
+  for (const source of snapshotSources) conflict(source.eventId, affected);
+  // An empty selected inventory is still quarantined: affected.length is not a validity test.
+  if (snapshotSources.length) return empty("unresolved");
+  if (!nominated) { problem("REFERENCE_MISSING", { type: "event", ref: selection.event }); return empty("unresolved"); }
+  if (!exactSnapshot) {
+    problem("SCOPE_INVALID", { type: "snapshot", ref: selection.snapshot }); return empty("invalid");
+  }
+  const snapshot = exactSnapshot;
+  const selected = new Map<string, Ref>();
+  let invalid = false, missing = false;
+  function reject(code: WorkResolutionCode, ref: Ref, affected: readonly Ref[] = []) {
+    invalid = true; problem(code, reference(ref), affected);
+  }
+  for (const ref of [snapshot.scope, ...snapshot.revisions]) {
+    if (selected.has(entity(ref))) reject("REVISION_INVALID", ref);
+    selected.set(entity(ref), ref); // Diagnostic lookup only if invalid; no rows will be exposed.
+  }
+  const obligationRefs = snapshot.revisions.filter(ref => ref.kind === "obligation");
+  const allAffected = unique(obligationRefs);
+  const records = new Map<string, Revision>();
+  const quarantineSources = new Map<string, readonly WorkFrozen<EventRef>[]>();
+  for (const event of index.candidates) if (event.event === "work_revision") {
+    const r = event.payload.revision;
+    const ref = { kind: r.kind, id: r.id, revision: r.revision, digest: r.digest };
+    if (!records.has(key(ref))) {
+      const sources = workRevisionConflictSources(index, ref);
+      if (sources.length) quarantineSources.set(key(ref), sources);
+    }
+    records.set(key(ref), r);
+  }
+  const isSelected = (ref: Ref) => key(selected.get(entity(ref)) ?? null) === key(ref);
+  function lookup(ref: Ref, affected: readonly Ref[], localArtifact = false): Revision | null {
+    // A scope revision's ID is its scopeId by the validated wire contract. This contradiction
+    // is already known from the reference; absent bytes must not downgrade it to a mere gap.
+    if (ref.kind === "scope" && ref.id !== snapshot.scope.id) reject("SCOPE_INVALID", ref, affected);
+    const sources = quarantineSources.get(key(ref));
+    if (sources) {
+      for (const source of sources) conflict(source.eventId, affected);
+      if (!localArtifact) missing = true;
+      return null;
+    }
+    const r = records.get(key(ref));
+    if (!r) {
+      problem("REFERENCE_MISSING", reference(ref), affected);
+      if (!localArtifact) missing = true;
+      return null;
+    }
+    if (r.scopeId !== snapshot.scope.id) reject("REVISION_INVALID", ref, affected);
+    return r;
+  }
+
+  function walk(root: Ref, affected: readonly Ref[], localArtifact = false) {
+    // Iterative traversal: the wire depth bound does not impose a limit on revision history length.
+    type Frame = { ref: Ref; current: boolean; exit?: boolean; local?: boolean };
+    const stack: Frame[] = [{ ref: root, current: true, local: localArtifact }];
+    const done = new Set<string>(), active = new Set<string>();
+    while (stack.length) {
+      const frame = stack.pop()!, id = `${frame.current}:${key(frame.ref)}`;
+      if (frame.exit) { active.delete(id); done.add(id); continue; }
+      if (active.has(id)) { reject("CYCLE", frame.ref, affected); continue; }
+      if (done.has(id)) continue;
+      if (frame.current && selected.has(entity(frame.ref)) && !isSelected(frame.ref)) reject("REVISION_INVALID", frame.ref, affected);
+      if (frame.current && frame.ref.kind === "scope" && key(frame.ref) !== key(snapshot.scope)) reject("SCOPE_INVALID", frame.ref, affected);
+      const r = lookup(frame.ref, affected, frame.local);
+      if (!r) continue;
+      active.add(id); stack.push({ ...frame, exit: true });
+      if (r.predecessor) {
+        const prior = lookup(r.predecessor, affected);
+        if (prior && (prior.kind !== r.kind || prior.id !== r.id || prior.scopeId !== r.scopeId || prior.revision + 1 !== r.revision)) {
+          reject("REVISION_INVALID", frame.ref, affected);
+        }
+        stack.push({ ref: r.predecessor, current: false });
+      }
+      if (r.parent) {
+        if (entity(r.parent) === entity(frame.ref)) reject("CYCLE", frame.ref, affected);
+        stack.push({ ref: r.parent, current: frame.current });
+      }
+      if (r.policy) {
+        if (frame.current && !isSelected(r.policy)) reject("REVISION_INVALID", r.policy, affected);
+        stack.push({ ref: r.policy, current: frame.current });
+      }
+      for (const dep of r.dependencies) {
+        if (entity(dep) === entity(frame.ref)) reject("CYCLE", frame.ref, affected);
+        if (frame.current && !isSelected(dep)) reject("DEPENDENCY_INVALID", dep, affected);
+        stack.push({ ref: dep, current: frame.current });
+      }
+    }
+  }
+  // Structural roots must be checked even when no obligation names them. Then walk each obligation
+  // independently to accumulate exact affected-obligation reachability, including shared ancestors.
+  walk(snapshot.scope, allAffected);
+  for (const ref of snapshot.revisions) {
+    const affected = ref.kind === "obligation" ? [ref] : snapshot.bindings.filter(binding =>
+      [binding.intent, binding.policy, binding.artifact].some(value => value && key(value) === key(ref)),
+    ).map(binding => binding.obligation).filter(isSelected);
+    walk(ref, affected, ref.kind === "artifact");
+  }
+  function ancestor(obligation: Ref, intent: Ref): boolean | null {
+    const seen = new Set<string>();
+    let cursor: Ref | null = obligation;
+    while (cursor) {
+      const id = key(cursor);
+      if (seen.has(id) || quarantineSources.has(id)) return null;
+      seen.add(id);
+      const r = records.get(id);
+      if (!r) return null;
+      cursor = r.parent;
+      if (cursor && key(cursor) === key(intent)) return true;
+    }
+    return false;
+  }
+  for (const ref of obligationRefs) {
+    if (snapshot.bindings.filter(binding => key(binding.obligation) === key(ref)).length !== 1) reject("SCOPE_INVALID", ref, [ref]);
+  }
+  for (const binding of snapshot.bindings) {
+    const affected = isSelected(binding.obligation) ? [binding.obligation] : [];
+    if (!isSelected(binding.obligation)) reject("SCOPE_INVALID", binding.obligation);
+    if (!isSelected(binding.intent)) reject("SCOPE_INVALID", binding.intent, affected);
+    if (!isSelected(binding.policy)) reject("REVISION_INVALID", binding.policy, affected);
+    const r = lookup(binding.obligation, affected);
+    if (r && key(r.policy) !== key(binding.policy)) reject("REVISION_INVALID", binding.policy, affected);
+    if (r && ancestor(binding.obligation, binding.intent) === false) reject("SCOPE_INVALID", binding.intent, affected);
+    if (binding.artifact && !isSelected(binding.artifact)) reject("ARTIFACT_UNSELECTED", binding.artifact, affected);
+  }
+  if (invalid) return empty("invalid");
+  if (missing) return empty("unresolved");
+  const diagnostics = reports();
+  return freezeWork({
+    scopeState: "valid", selectedSnapshot: selection.snapshot, snapshot,
+    scope: records.get(key(snapshot.scope))!,
+    revisions: unique(snapshot.revisions.flatMap(ref => {
+      const r = quarantineSources.has(key(ref)) ? undefined : records.get(key(ref));
+      return r ? [r] : [];
+    })),
+    obligations: snapshot.bindings.map(binding => ({
+      binding, revision: records.get(key(binding.obligation))!,
+      artifact: binding.artifact && !quarantineSources.has(key(binding.artifact)) ? records.get(key(binding.artifact)) ?? null : null,
+      problems: diagnostics.problems.filter(p => p.affectedObligations.some(ref => key(ref) === key(binding.obligation))),
+    })), ...diagnostics,
+  });
+}

package/src/work-ledger-types.ts

@@ -0,0 +1,229 @@
+/** 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

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