@akagilnc/pi-workflow-roles 0.1.1751

package/src/navigator-invocation-identity.ts

@@ -0,0 +1,446 @@
+/**
+ * Exact current-invocation principal for Navigator attendance correlation.
+ * Shared role lifecycle owns one opaque uuidv7 per Role invocation and persists
+ * it on the role session via Pi's guaranteed `pi.appendEntry` boundary.
+ *
+ * session_start is process/session activation, not a new Role invocation:
+ * unfinished exact-session resume reuses the latest valid marker only when its
+ * role/phase/subjectKey still match the expected identity; a packaged role
+ * terminal completing that marker starts the next invocation (fresh mint).
+ * Terminal settlement binds the nearest independent marker strictly before the
+ * current durable packaged role terminal and compares equality — never attendance
+ * self-shape, markers after the terminal, or stale older markers behind a
+ * malformed nearest. Non-UUIDv7 principals are never accepted.
+ *
+ * One shared typed terminal classifier owns durable completion for lifecycle,
+ * publicNavigatorSettlement, and every public CLI Receipt extractor:
+ *   - accepted/human: isError exactly false and no infrastructure-failure fact
+ *   - infrastructure: isError exactly true plus exact closed infrastructure fact
+ *   - retryable/missing/nonboolean/contradictory/malformed: nonterminal
+ *
+ * One truth table also owns marker↔terminal cardinality:
+ *   - a marker binds exactly one durable packaged role terminal
+ *   - multiple durable terminals after the same marker → ambiguous / fail-closed
+ *   - marker role/phase/subjectKey must match the terminal + independent expected
+ */
+
+import { PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
+import { isUuidV7, uuidv7 } from "./uuidv7.ts";
+import { workSubjectKeysEqual } from "./work-subject-identity.ts";
+
+export const NAVIGATOR_INVOCATION_ENTRY = "ak-navigator-invocation" as const;
+
+/** Typed durable infrastructure-failure fact on a packaged role output toolResult. */
+export const NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND = "role_infrastructure_failure" as const;
+
+/** Closed fact keys — extras/missing/wrong keys fail closed. */
+const NAVIGATOR_INFRASTRUCTURE_FAILURE_KEYS = [
+  "kind",
+  "source",
+  "reasonCode",
+] as const;
+
+export type NavigatorInfrastructureFailureFact = {
+  kind: typeof NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND;
+  source: "shared-role-lifecycle";
+  reasonCode: "host_failure";
+};
+
+export function buildNavigatorInfrastructureFailureFact(): NavigatorInfrastructureFailureFact {
+  return {
+    kind: NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND,
+    source: "shared-role-lifecycle",
+    reasonCode: "host_failure",
+  };
+}
+
+/**
+ * Exact closed infrastructure-failure fact.
+ * Rejects extras, missing keys, wrong values/types, and non-objects.
+ */
+export function isNavigatorInfrastructureFailureFact(
+  value: unknown,
+): value is NavigatorInfrastructureFailureFact {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record);
+  if (keys.length !== NAVIGATOR_INFRASTRUCTURE_FAILURE_KEYS.length) return false;
+  for (const key of NAVIGATOR_INFRASTRUCTURE_FAILURE_KEYS) {
+    if (!Object.hasOwn(record, key)) return false;
+  }
+  return (
+    record.kind === NAVIGATOR_INFRASTRUCTURE_FAILURE_KIND &&
+    record.source === "shared-role-lifecycle" &&
+    record.reasonCode === "host_failure"
+  );
+}
+
+const PACKAGED_ROLE_OUTPUT_TOOLS: ReadonlyMap<string, string> = new Map(
+  PACKAGED_ROLE_REGISTRY.map((entry) => [entry.outputTool, entry.role]),
+);
+
+export type NavigatorInvocationEntryLike = {
+  readonly type?: string;
+  readonly customType?: string;
+  readonly data?: unknown;
+  readonly message?: {
+    readonly role?: unknown;
+    readonly toolName?: unknown;
+    readonly isError?: unknown;
+    readonly details?: unknown;
+  };
+};
+
+/** Mint one globally unique opaque invocation principal. */
+export function mintNavigatorInvocationId(): string {
+  return uuidv7();
+}
+
+/** Phase carried on the durable invocation marker / expected identity. */
+export type InvocationPhase = "plan" | "apply" | null;
+
+/** Full exact-invocation marker identity persisted on the role session. */
+export type InvocationMarkerIdentity = {
+  readonly invocationId: string;
+  readonly role: string;
+  readonly phase: InvocationPhase;
+  readonly subjectKey: string;
+};
+
+/** Independently admitted / registry / cwd expected identity for resume and correlation. */
+export type ExpectedInvocationIdentity = {
+  readonly role: string;
+  readonly phase?: InvocationPhase;
+  readonly allowedPhases?: readonly InvocationPhase[];
+  readonly subjectKey?: string;
+};
+
+function invocationPhaseFromUnknown(value: unknown): InvocationPhase | undefined {
+  if (value === null || value === "plan" || value === "apply") return value;
+  return undefined;
+}
+
+/**
+ * Parse a full invocation marker payload. All identity fields are required;
+ * non-UUIDv7 principals and partial shapes fail closed.
+ */
+export function parseInvocationMarkerIdentity(
+  data: unknown,
+): InvocationMarkerIdentity | undefined {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return undefined;
+  const record = data as Record<string, unknown>;
+  const invocationId = record.invocationId;
+  if (typeof invocationId !== "string") return undefined;
+  const trimmedId = invocationId.trim();
+  if (!isUuidV7(trimmedId)) return undefined;
+  if (typeof record.role !== "string" || record.role.trim() === "") return undefined;
+  const phase = invocationPhaseFromUnknown(record.phase);
+  if (phase === undefined) return undefined;
+  if (typeof record.subjectKey !== "string" || record.subjectKey.trim() === "") return undefined;
+  return {
+    invocationId: trimmedId,
+    role: record.role,
+    phase,
+    subjectKey: record.subjectKey,
+  };
+}
+
+/**
+ * Marker identity agrees with independently expected role/phase/subject.
+ * Role is mandatory. Phase and subject apply when the expected side knows them.
+ */
+export function markerMatchesExpectedIdentity(
+  marker: InvocationMarkerIdentity,
+  expected: ExpectedInvocationIdentity,
+): boolean {
+  if (marker.role !== expected.role) return false;
+  if (expected.phase !== undefined) {
+    if (marker.phase !== expected.phase) return false;
+  } else if (expected.allowedPhases !== undefined) {
+    if (!expected.allowedPhases.includes(marker.phase)) return false;
+  }
+  if (expected.subjectKey !== undefined) {
+    if (!workSubjectKeysEqual(marker.subjectKey, expected.subjectKey)) return false;
+  }
+  return true;
+}
+
+/** Shared terminal discriminant owned by one classifier. */
+export type PackagedRoleTerminalClassification =
+  | { readonly kind: "accepted" }
+  | {
+      readonly kind: "infrastructure";
+      readonly fact: NavigatorInfrastructureFailureFact;
+    }
+  | { readonly kind: "nonterminal" };
+
+export type PackagedRoleTerminalMessage = {
+  readonly toolName?: unknown;
+  readonly isError?: unknown;
+  readonly details?: unknown;
+};
+
+/**
+ * One shared typed terminal classifier for packaged role output toolResults.
+ * Consumed by lifecycle principal completion, publicNavigatorSettlement, and
+ * every public CLI role Receipt extractor. No second classifier.
+ */
+export function classifyPackagedRoleTerminalResult(
+  message: PackagedRoleTerminalMessage,
+): PackagedRoleTerminalClassification {
+  if (typeof message.toolName !== "string") return { kind: "nonterminal" };
+  if (!PACKAGED_ROLE_OUTPUT_TOOLS.has(message.toolName)) return { kind: "nonterminal" };
+
+  const infraFact = isNavigatorInfrastructureFailureFact(message.details)
+    ? message.details
+    : undefined;
+
+  // Infrastructure completion: exact isError === true + exact closed infra fact.
+  if (message.isError === true) {
+    if (infraFact === undefined) return { kind: "nonterminal" };
+    return { kind: "infrastructure", fact: infraFact };
+  }
+  // Accepted/human completion: exact isError === false and must not carry infra fact.
+  if (message.isError === false) {
+    if (infraFact !== undefined) return { kind: "nonterminal" };
+    return { kind: "accepted" };
+  }
+  // Missing, non-boolean, contradictory, or malformed shapes fail closed.
+  return { kind: "nonterminal" };
+}
+
+/**
+ * Durable-completion boolean over the shared classifier
+ * (accepted/human or infrastructure terminal).
+ */
+export function isDurablePackagedRoleTerminalResult(
+  message: PackagedRoleTerminalMessage,
+): boolean {
+  const classification = classifyPackagedRoleTerminalResult(message);
+  return classification.kind === "accepted" || classification.kind === "infrastructure";
+}
+
+/** Receipt extractors admit only exact accepted/human terminals. */
+export function isAcceptedPackagedRoleTerminalResult(
+  message: PackagedRoleTerminalMessage,
+): boolean {
+  return classifyPackagedRoleTerminalResult(message).kind === "accepted";
+}
+
+export type DurablePackagedRoleTerminalRef = {
+  readonly index: number;
+  readonly role: string;
+  readonly toolName: string;
+  readonly classification: "accepted" | "infrastructure";
+  readonly message: PackagedRoleTerminalMessage;
+};
+
+function durableTerminalAt(
+  entries: readonly NavigatorInvocationEntryLike[],
+  index: number,
+): DurablePackagedRoleTerminalRef | undefined {
+  const entry = entries[index];
+  if (entry?.type !== "message") return undefined;
+  const message = entry.message;
+  if (message?.role !== "toolResult") return undefined;
+  if (typeof message.toolName !== "string") return undefined;
+  const role = PACKAGED_ROLE_OUTPUT_TOOLS.get(message.toolName);
+  if (role === undefined) return undefined;
+  const classification = classifyPackagedRoleTerminalResult(message);
+  if (classification.kind !== "accepted" && classification.kind !== "infrastructure") {
+    return undefined;
+  }
+  return {
+    index,
+    role,
+    toolName: message.toolName,
+    classification: classification.kind,
+    message,
+  };
+}
+
+function isPackagedRoleTerminalEntry(entry: NavigatorInvocationEntryLike | undefined): boolean {
+  if (entry?.type !== "message") return false;
+  const message = entry.message;
+  if (message?.role !== "toolResult") return false;
+  return isDurablePackagedRoleTerminalResult(message);
+}
+
+function isInvocationMarkerEntry(entry: NavigatorInvocationEntryLike | undefined): boolean {
+  return entry?.type === "custom" && entry.customType === NAVIGATOR_INVOCATION_ENTRY;
+}
+
+function latestInvocationMarkerIndex(
+  entries: readonly NavigatorInvocationEntryLike[],
+): number {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    if (isInvocationMarkerEntry(entries[i])) return i;
+  }
+  return -1;
+}
+
+/** Latest durable packaged role terminal in session order. */
+export function findLatestDurablePackagedRoleTerminal(
+  entries: readonly NavigatorInvocationEntryLike[],
+): DurablePackagedRoleTerminalRef | undefined {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const terminal = durableTerminalAt(entries, i);
+    if (terminal !== undefined) return terminal;
+  }
+  return undefined;
+}
+
+/**
+ * Truth-table binding of the current durable packaged role terminal to its
+ * owning invocation marker. Singleton cardinality: multiple durable terminals
+ * after the same marker are ambiguous and fail closed.
+ */
+export type DurableTerminalMarkerBinding =
+  | {
+      readonly kind: "bound";
+      readonly terminal: DurablePackagedRoleTerminalRef;
+      readonly marker: InvocationMarkerIdentity & { readonly index: number };
+    }
+  | {
+      readonly kind: "unbound";
+      readonly terminal: DurablePackagedRoleTerminalRef;
+    }
+  | { readonly kind: "absent" }
+  | { readonly kind: "ambiguous" };
+
+export function bindCurrentDurableTerminalToMarker(
+  entries: readonly NavigatorInvocationEntryLike[],
+): DurableTerminalMarkerBinding {
+  const terminal = findLatestDurablePackagedRoleTerminal(entries);
+  if (terminal === undefined) return { kind: "absent" };
+
+  let markerIndex = -1;
+  for (let i = terminal.index - 1; i >= 0; i -= 1) {
+    if (isInvocationMarkerEntry(entries[i])) {
+      markerIndex = i;
+      break;
+    }
+  }
+  if (markerIndex < 0) {
+    return { kind: "unbound", terminal };
+  }
+
+  const marker = parseInvocationMarkerIdentity(entries[markerIndex]?.data);
+  if (marker === undefined) {
+    // Malformed nearest marker: no stale fallback; terminal exists but is unbound.
+    return { kind: "unbound", terminal };
+  }
+
+  let windowEnd = entries.length;
+  for (let i = markerIndex + 1; i < entries.length; i += 1) {
+    if (isInvocationMarkerEntry(entries[i])) {
+      windowEnd = i;
+      break;
+    }
+  }
+
+  let durableCount = 0;
+  for (let i = markerIndex + 1; i < windowEnd; i += 1) {
+    if (durableTerminalAt(entries, i) !== undefined) durableCount += 1;
+  }
+  if (durableCount !== 1) return { kind: "ambiguous" };
+  // Current terminal must be the singleton inside this marker window.
+  if (terminal.index <= markerIndex || terminal.index >= windowEnd) {
+    return { kind: "ambiguous" };
+  }
+
+  return {
+    kind: "bound",
+    terminal,
+    marker: { ...marker, index: markerIndex },
+  };
+}
+
+/**
+ * Whether public Receipt settlement may proceed for the current durable terminal.
+ * Only ambiguous multi-terminal bindings fail closed; attendance mismatch does not
+ * pollute an otherwise legal single Receipt.
+ */
+export function isReceiptSettlementBindingClear(
+  entries: readonly NavigatorInvocationEntryLike[],
+): boolean {
+  return bindCurrentDurableTerminalToMarker(entries).kind !== "ambiguous";
+}
+
+export type LifecycleInvocationPrincipal = {
+  readonly invocationId: string;
+  /** True when the principal is already on the admitted session (resume; do not re-append). */
+  readonly resume: boolean;
+};
+
+/**
+ * Resolve the exact-invocation principal at shared role lifecycle start from the
+ * admitted session's typed entries only.
+ *
+ * - Latest marker is valid full identity, matches expected (when supplied), and no
+ *   packaged role terminal follows it → resume.
+ * - Contradictory marker role/phase/subjectKey vs expected → mint (do not resume).
+ * - Latest marker is valid and a packaged role terminal already completed it → mint.
+ * - Missing or malformed latest marker → mint; never fall back to a stale older marker.
+ */
+export function resolveLifecycleInvocationPrincipal(
+  entries: readonly NavigatorInvocationEntryLike[],
+  expected?: ExpectedInvocationIdentity,
+): LifecycleInvocationPrincipal {
+  const markerIndex = latestInvocationMarkerIndex(entries);
+  if (markerIndex < 0) {
+    return { invocationId: mintNavigatorInvocationId(), resume: false };
+  }
+
+  const marker = parseInvocationMarkerIdentity(entries[markerIndex]?.data);
+  if (marker === undefined) {
+    // Malformed nearest marker: honest new principal, no stale fallback.
+    return { invocationId: mintNavigatorInvocationId(), resume: false };
+  }
+
+  if (expected !== undefined && !markerMatchesExpectedIdentity(marker, expected)) {
+    // Contradictory marker must not resume a different role/phase/subject invocation.
+    return { invocationId: mintNavigatorInvocationId(), resume: false };
+  }
+
+  for (let i = markerIndex + 1; i < entries.length; i += 1) {
+    if (isPackagedRoleTerminalEntry(entries[i])) {
+      return { invocationId: mintNavigatorInvocationId(), resume: false };
+    }
+  }
+
+  return { invocationId: marker.invocationId, resume: true };
+}
+
+/**
+ * Exact current invocation principal already present on the role session.
+ * `beforeIndex` is the current packaged role terminal index: only the nearest
+ * marker strictly before that bound is applicable. A malformed nearest marker
+ * fails closed (undefined) — never falls back to a stale older valid marker.
+ * Markers at/after the terminal (future prepare/event) are never considered.
+ * Non-UUIDv7 values are rejected.
+ */
+export function currentInvocationPrincipalFromSession(
+  entries: readonly NavigatorInvocationEntryLike[],
+  beforeIndex: number = entries.length,
+): string | undefined {
+  return currentInvocationMarkerFromSession(entries, beforeIndex)?.invocationId;
+}
+
+/**
+ * Full marker identity nearest before `beforeIndex` (current durable terminal).
+ * Malformed nearest fails closed — no stale older fallback.
+ */
+export function currentInvocationMarkerFromSession(
+  entries: readonly NavigatorInvocationEntryLike[],
+  beforeIndex: number = entries.length,
+): InvocationMarkerIdentity | undefined {
+  const limit = Math.min(Math.max(beforeIndex, 0), entries.length);
+  for (let i = limit - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (!isInvocationMarkerEntry(entry)) continue;
+    // Nearest marker only — parse full identity or fail closed.
+    return parseInvocationMarkerIdentity(entry?.data);
+  }
+  return undefined;
+}

package/src/open-tool-schema.ts

@@ -0,0 +1,46 @@
+import { Type, type TSchema } from "typebox";
+
+type UnionSchema = TSchema & { anyOf: Array<TSchema & { properties?: Record<string, TSchema> }> };
+
+function described(name: string, schema: TSchema): TSchema {
+  if (typeof (schema as { description?: unknown }).description === "string") return schema;
+  throw new Error(`Tool field ${name} has no semantic description at its schema owner`);
+}
+
+function declarationIdentity(schema: TSchema): string {
+  const { description: _description, ...semantic } = schema as TSchema & { description?: string };
+  return JSON.stringify(semantic);
+}
+
+/** Collapse transport variants into one provider-compatible, zero-required open object. */
+export function openToolObjectFromUnion(schema: UnionSchema): TSchema {
+  const declarations = new Map<string, TSchema[]>();
+  for (const variant of schema.anyOf) {
+    for (const [name, declaration] of Object.entries(variant.properties ?? {})) {
+      const entries = declarations.get(name) ?? [];
+      const identity = declarationIdentity(declaration);
+      if (!entries.some((entry) => declarationIdentity(entry) === identity)) entries.push(declaration);
+      declarations.set(name, entries);
+    }
+  }
+  const properties = Object.fromEntries([...declarations].map(([name, entries]) => {
+    const descriptions = [...new Set(entries.map((entry) => (entry as { description?: unknown }).description).filter((value): value is string => typeof value === "string"))].join(" ");
+    const declaration = entries.length === 1
+      ? entries[0]!
+      : Type.Union(entries, descriptions === "" ? {} : { description: descriptions });
+    return [name, Type.Optional(described(name, declaration))];
+  }));
+  const object = Type.Object(properties, { additionalProperties: true });
+  (object as unknown as { required: string[] }).required = [];
+  return object;
+}
+
+/** Open a pre-existing object transport schema without changing declarations. */
+export function openToolObject(schema: TSchema & { properties: Record<string, TSchema> }): TSchema {
+  const object = Type.Object(
+    Object.fromEntries(Object.entries(schema.properties).map(([name, declaration]) => [name, Type.Optional(described(name, declaration))])),
+    { additionalProperties: true },
+  );
+  (object as unknown as { required: string[] }).required = [];
+  return object;
+}

package/src/package-contracts/collector-output.ts

@@ -0,0 +1,109 @@
+/** Package-owned Collector receipt leaf — no role registration surface. */
+
+export const COLLECTOR_OUTPUT_TOOL = "ak_collector_output";
+export const COLLECTOR_ACCEPTED_TEXT = "Collector receipt accepted";
+export const COLLECTOR_HOST = "github.com";
+
+export type CollectorIdentityGroup = {
+  identity: Record<string, unknown> | null;
+  displayLogin?: string;
+  attendance: true;
+  materials: Array<Record<string, unknown>>;
+  findings: Array<Record<string, unknown>>;
+};
+
+export type CollectorRequestAttempt = {
+  attemptId: string;
+  requestId: string;
+  observedHead: string;
+  snapshotId: string;
+  marker: string;
+  body: string;
+  startedAt: string;
+  status: "started" | "succeeded" | "rejected" | "ambiguous_loss" | "recovered";
+  responseDiagnostics?: string;
+  commentEvidenceId?: string;
+  recoverySnapshotId?: string;
+};
+
+export type CollectorSnapshot = {
+  snapshotId: string;
+  observedAt: string;
+  completedAt: string;
+  completedMono: number;
+  host: "github.com";
+  repository: string;
+  prNumber: number;
+  prState: string;
+  headOid: string;
+  complete: boolean;
+  evidenceIds: string[];
+  pageDiagnostics: Array<Record<string, unknown>>;
+  normalizedByteLength: number;
+};
+
+export type CollectorEvidenceRecord = {
+  evidenceId: string;
+  kind: string;
+  versionId: string;
+  contentDigest: string;
+  firstObservedAt: string;
+  raw: unknown;
+};
+
+export type CollectorReceipt = {
+  host: "github.com";
+  repository: string;
+  prNumber: number;
+  manifestDigest: string;
+  activationTime: string;
+  deadlineTime: string;
+  finalObservationTime: string;
+  finalSnapshotId: string;
+  targetHead: string;
+  groups: CollectorIdentityGroup[];
+  requestAttempts: CollectorRequestAttempt[];
+  snapshots: CollectorSnapshot[];
+  evidenceRecords: CollectorEvidenceRecord[];
+};
+
+function safeGet(value: unknown, key: string): unknown {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return undefined;
+  try { return (value as Record<string, unknown>)[key]; } catch { return undefined; }
+}
+function records(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value) ? value.filter((item): item is Record<string, unknown> => item !== null && typeof item === "object") : [];
+}
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+/** Settlement projection. Presence of the canonical groups array is the one Collector terminal discriminator. */
+export function validateAcceptedCollectorReceipt(value: unknown): CollectorReceipt {
+  const rawGroups = safeGet(value, "groups");
+  if (!Array.isArray(rawGroups)) throw new Error("Collector receipt has no typed groups terminal discriminator");
+  const groups = records(rawGroups).map((group) => ({
+    identity: (safeGet(group, "identity") ?? null) as Record<string, unknown> | null,
+    ...(typeof safeGet(group, "displayLogin") === "string" ? { displayLogin: safeGet(group, "displayLogin") as string } : {}),
+    attendance: true as const,
+    materials: records(safeGet(group, "materials")),
+    findings: records(safeGet(group, "findings")),
+  }));
+  return {
+    host: safeGet(value, "host") as "github.com",
+    repository: safeGet(value, "repository") as string,
+    prNumber: safeGet(value, "prNumber") as number,
+    manifestDigest: safeGet(value, "manifestDigest") as string,
+    activationTime: safeGet(value, "activationTime") as string,
+    deadlineTime: safeGet(value, "deadlineTime") as string,
+    finalObservationTime: safeGet(value, "finalObservationTime") as string,
+    finalSnapshotId: safeGet(value, "finalSnapshotId") as string,
+    targetHead: safeGet(value, "targetHead") as string,
+    groups,
+    requestAttempts: records(safeGet(value, "requestAttempts")) as unknown as CollectorRequestAttempt[],
+    snapshots: records(safeGet(value, "snapshots")).map((snapshot) => ({
+      snapshotId: safeGet(snapshot, "snapshotId"), observedAt: safeGet(snapshot, "observedAt"), completedAt: safeGet(snapshot, "completedAt"), completedMono: safeGet(snapshot, "completedMono"), host: safeGet(snapshot, "host"), repository: safeGet(snapshot, "repository"), prNumber: safeGet(snapshot, "prNumber"), prState: safeGet(snapshot, "prState"), headOid: safeGet(snapshot, "headOid"), complete: safeGet(snapshot, "complete"), evidenceIds: strings(safeGet(snapshot, "evidenceIds")), pageDiagnostics: records(safeGet(snapshot, "pageDiagnostics")), normalizedByteLength: safeGet(snapshot, "normalizedByteLength"),
+    } as CollectorSnapshot)),
+    evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), raw: safeGet(record, "raw") } as CollectorEvidenceRecord)),
+  };
+}

package/src/package-contracts/fixer-output.ts

@@ -0,0 +1,81 @@
+import { Type, type Static } from "typebox";
+import { FIXER_PREREQUISITE_ID_PATTERN, type FixerInvocationInput } from "./fixer-packet.ts";
+import { openToolObjectFromUnion } from "../open-tool-schema.ts";
+
+export const FIXER_OUTPUT_TOOL_NAME = "ak_fixer_output";
+export const FIXER_ACCEPTED_TEXT = "Fixer report accepted";
+
+const nonblankTransportString = Type.String({ minLength: 1 });
+const authorityBlockerSchema = Type.Object({ cause: Type.Literal("authority_violation"), evidence: nonblankTransportString });
+const prerequisiteBlockerSchema = Type.Object({ cause: Type.Literal("prerequisite_unmet"), prerequisiteId: Type.String({ pattern: FIXER_PREREQUISITE_ID_PATTERN }), evidence: nonblankTransportString });
+const blockerSchema = Type.Union([authorityBlockerSchema, prerequisiteBlockerSchema]);
+const exceptionSchema = Type.Object({ where: nonblankTransportString, reason: nonblankTransportString });
+/** ⑥ test evidence slip — require submit when diff has test changes; machine does not check existence/completeness/coverage. */
+const testEvidenceSchema = Type.Object({
+  contract: Type.String({ minLength: 1, description: "Contract the test change proves." }),
+  minimumNecessaryCost: Type.String({ minLength: 1, description: "One-line minimum necessary cost of the test change." }),
+  measuredDuration: Type.String({ minLength: 1, description: "Measured duration of the focused verification run." }),
+}, { description: "Test evidence slip (submit when diff includes test changes; machine does not verify)." });
+const completedClassResultSchema = Type.Object({
+  name: nonblankTransportString,
+  disposition: Type.Literal("completed"),
+  searchScope: nonblankTransportString,
+  exceptions: Type.Array(exceptionSchema),
+  commitSha: nonblankTransportString,
+});
+const refusedClassResultSchema = Type.Object({
+  name: nonblankTransportString,
+  disposition: Type.Literal("refused"),
+  remainingScope: nonblankTransportString,
+  blocker: blockerSchema,
+});
+const classResultSchema = Type.Union([completedClassResultSchema, refusedClassResultSchema]);
+const completedClassResultsSchema = Type.Array(completedClassResultSchema, { minItems: 1 });
+
+const fixerOutputVariants = Type.Union([
+  Type.Object({ status: Type.Literal("planned", { description: "Plan-phase proposal outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }) }),
+  Type.Object({ status: Type.Literal("refused", { description: "Lawfully refused outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work that cannot lawfully be performed." }), blocker: Type.Unsafe({ ...blockerSchema, description: "Lawful blocker preventing completion." }) }),
+  Type.Object({ status: Type.Literal("unfinished", { description: "Honest unfinished apply outcome." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), remainingScope: Type.String({ minLength: 1, description: "Work remaining after this invocation." }), classResults: Type.Optional(Type.Unsafe({ ...completedClassResultsSchema, description: "Completed class settlements from this invocation." })), testEvidence: Type.Optional(testEvidenceSchema) }),
+  Type.Object({ status: Type.Literal("completed", { description: "All assigned classes completed." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Completed class settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),
+  Type.Object({ status: Type.Literal("refused", { description: "All assigned classes lawfully refused." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class refusal settlements." }) }),
+  Type.Object({ status: Type.Literal("partially_completed", { description: "Assigned classes include completions and lawful refusals." }), report: Type.String({ minLength: 1, description: "Truthful Fixer outcome report." }), classResults: Type.Array(classResultSchema, { minItems: 1, description: "Per-class completion or refusal settlements." }), testEvidence: Type.Optional(testEvidenceSchema) }),
+]);
+export const fixerOutputSchema = openToolObjectFromUnion(fixerOutputVariants);
+
+export type FixerBlocker = Static<typeof blockerSchema>;
+export type FixerClassResult = Static<typeof classResultSchema>;
+export type FixerTestEvidence = Static<typeof testEvidenceSchema>;
+export type FixerOutput = Static<typeof fixerOutputVariants>;
+export type FixerPhase = "plan" | "apply";
+
+export function validateFixerOutput(value: unknown, _phase?: FixerPhase): FixerOutput {
+  return value as FixerOutput;
+}
+
+function safeProperty(value: unknown, property: string): unknown {
+  if (value === null || typeof value !== "object") return undefined;
+  try {
+    return (value as Record<string, unknown>)[property];
+  } catch {
+    return undefined;
+  }
+}
+
+/** Bind recognizable prerequisite blockers to the packet declaration. */
+export function validateFixerOutputForPacket(value: unknown, phase: FixerPhase, packet: FixerInvocationInput): FixerOutput {
+  const output = validateFixerOutput(value, phase);
+  const declaredIds = new Set(packet.prerequisites.map((entry) => entry.id));
+  const topLevelBlocker = safeProperty(output, "blocker");
+  const classResults = safeProperty(output, "classResults");
+  const blockers = topLevelBlocker === undefined
+    ? (Array.isArray(classResults) ? classResults.map((entry) => safeProperty(entry, "blocker")) : [])
+    : [topLevelBlocker];
+  for (const blocker of blockers) {
+    if (safeProperty(blocker, "cause") !== "prerequisite_unmet") continue;
+    const prerequisiteId = safeProperty(blocker, "prerequisiteId");
+    if (typeof prerequisiteId === "string" && !declaredIds.has(prerequisiteId)) {
+      throw new Error("Fixer output violates blocker.prerequisiteId declared-prerequisite constraint");
+    }
+  }
+  return output;
+}