@piagent/platform 1.3.1 → 1.4.0

package/packages/piagent-core/runtime/inspection/mutation-provenance-contract.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const MUTATION_PROVENANCE_VERSION = "piagent-mutation-provenance-v1" as const;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const TREE = /^wt-content-v2:[a-f0-9]{64}$/;
+const PUBLIC_ID = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+export type MutationProvenanceChange = {
+  pathDigest: string;
+  repoPathBase64: string;
+  beforeCarrierDigest: string | null;
+  afterCarrierDigest: string | null;
+  afterContentDigest: string | null;
+  proofMode: "full-content" | "exact-replacement" | null;
+  effect: "exact-content" | "content-preserved" | "content-changed" | "unknown";
+};
+
+export type MutationProvenanceRecord = {
+  schemaVersion: 1;
+  version: typeof MUTATION_PROVENANCE_VERSION;
+  recordId: string;
+  evidenceRef: string;
+  taskId: string;
+  taskRunId: string;
+  sessionIdentityHash: string;
+  toolCallIdentityHash: string;
+  toolName: "edit" | "write" | "apply_patch" | "shell" | "opaque";
+  recordedAt: string;
+  evidenceMode: "exact-runtime" | "observed-runtime";
+  beforeTreeDigest: string;
+  afterTreeDigest: string;
+  changes: MutationProvenanceChange[];
+  integrityDigest: string;
+};
+
+function plain(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (!plain(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+}
+
+function hash(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function mutationProvenanceIdentity(value: Pick<MutationProvenanceRecord,
+  "taskRunId" | "toolCallIdentityHash" | "recordedAt" | "afterTreeDigest" | "changes">): string {
+  const identity = {
+    taskRunId: value.taskRunId,
+    toolCallIdentityHash: value.toolCallIdentityHash,
+    recordedAt: value.recordedAt,
+    afterTreeDigest: value.afterTreeDigest,
+    changes: value.changes
+  };
+  return hash(`mutation-provenance-identity-v1\0${JSON.stringify(canonical(identity))}`);
+}
+
+export function mutationProvenanceDigest(value: Omit<MutationProvenanceRecord, "integrityDigest"> | MutationProvenanceRecord): string {
+  const { integrityDigest: _ignored, ...payload } = value as MutationProvenanceRecord;
+  return `sha256:${hash(`mutation-provenance-record-v1\0${JSON.stringify(canonical(payload))}`)}`;
+}
+
+export function decodeMutationRepoPath(change: MutationProvenanceChange): string | null {
+  const value = Buffer.from(change.repoPathBase64, "base64url").toString("utf8");
+  return value && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value)
+    && !value.split("/").includes("..") && !value.includes("\0") ? value : null;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  const actual = Object.keys(value).sort(), expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function validChange(value: unknown): value is MutationProvenanceChange {
+  if (!plain(value) || !exactKeys(value, ["pathDigest", "repoPathBase64", "beforeCarrierDigest", "afterCarrierDigest", "afterContentDigest", "proofMode", "effect"])) return false;
+  if (!DIGEST.test(String(value.pathDigest))) return false;
+  if (typeof value.repoPathBase64 !== "string" || !value.repoPathBase64 || value.repoPathBase64.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(value.repoPathBase64)) return false;
+  if (value.beforeCarrierDigest !== null && !TREE.test(String(value.beforeCarrierDigest))) return false;
+  if (value.afterCarrierDigest !== null && !TREE.test(String(value.afterCarrierDigest))) return false;
+  if (value.afterContentDigest !== null && !DIGEST.test(String(value.afterContentDigest))) return false;
+  if (value.beforeCarrierDigest === value.afterCarrierDigest) return false;
+  if (value.proofMode !== null && !["full-content", "exact-replacement"].includes(String(value.proofMode))) return false;
+  if (!["exact-content", "content-preserved", "content-changed", "unknown"].includes(String(value.effect))) return false;
+  const repoPath = decodeMutationRepoPath(value as MutationProvenanceChange);
+  return Boolean(repoPath && value.pathDigest === `sha256:${hash(repoPath as string)}`);
+}
+
+export function mutationProvenanceErrors(value: unknown): string[] {
+  const keys = ["schemaVersion", "version", "recordId", "evidenceRef", "taskId", "taskRunId", "sessionIdentityHash", "toolCallIdentityHash", "toolName", "recordedAt", "evidenceMode", "beforeTreeDigest", "afterTreeDigest", "changes", "integrityDigest"];
+  if (!plain(value) || !exactKeys(value, keys)) return ["record shape is invalid"];
+  const errors: string[] = [];
+  if (value.schemaVersion !== 1 || value.version !== MUTATION_PROVENANCE_VERSION) errors.push("record version is invalid");
+  if (!PUBLIC_ID.test(String(value.taskId)) || !PUBLIC_ID.test(String(value.taskRunId))) errors.push("task identity is invalid");
+  if (!DIGEST.test(String(value.sessionIdentityHash)) || !DIGEST.test(String(value.toolCallIdentityHash))) errors.push("private identity hash is invalid");
+  if (!["edit", "write", "apply_patch", "shell", "opaque"].includes(String(value.toolName))
+    || !["exact-runtime", "observed-runtime"].includes(String(value.evidenceMode))) errors.push("tool evidence is invalid");
+  if (!TIMESTAMP.test(String(value.recordedAt)) || !Number.isFinite(Date.parse(String(value.recordedAt)))) errors.push("recorded timestamp is invalid");
+  if (!TREE.test(String(value.beforeTreeDigest)) || !TREE.test(String(value.afterTreeDigest)) || value.beforeTreeDigest === value.afterTreeDigest) errors.push("tree evidence is invalid");
+  if (!Array.isArray(value.changes) || value.changes.length < 1 || value.changes.length > 100 || !value.changes.every(validChange)) errors.push("file changes are invalid");
+  else if (new Set(value.changes.map((change) => (change as MutationProvenanceChange).pathDigest)).size !== value.changes.length) errors.push("file changes are duplicated");
+  else if (value.evidenceMode === "exact-runtime" && (
+    !["edit", "write", "apply_patch"].includes(String(value.toolName))
+    || value.changes.some((change) => {
+      const item = change as MutationProvenanceChange;
+      return item.afterCarrierDigest === null || item.afterContentDigest === null || item.proofMode === null || item.effect !== "exact-content";
+    })
+  )) errors.push("exact mutation proof is invalid");
+  else if (value.evidenceMode === "observed-runtime" && value.changes.some((change) => {
+    const item = change as MutationProvenanceChange;
+    return item.proofMode !== null || item.effect === "exact-content"
+      || (item.effect === "content-preserved" && item.afterContentDigest === null);
+  })) errors.push("observed mutation proof is invalid");
+  const identity = mutationProvenanceIdentity(value as MutationProvenanceRecord);
+  if (value.recordId !== `provenance.${identity}` || value.evidenceRef !== `mutation.${identity}`) errors.push("record identity is invalid");
+  if (!DIGEST.test(String(value.integrityDigest)) || value.integrityDigest !== mutationProvenanceDigest(value as MutationProvenanceRecord)) errors.push("record integrity is invalid");
+  return errors;
+}
+
+export function validateMutationProvenanceRecord(value: unknown): MutationProvenanceRecord {
+  const errors = mutationProvenanceErrors(value);
+  if (errors.length) throw new Error(`Invalid mutation provenance record: ${errors.join("; ")}`);
+  return structuredClone(value) as MutationProvenanceRecord;
+}

package/packages/piagent-core/runtime/inspection/mutation-provenance-recorder.ts

@@ -0,0 +1,48 @@
+import { currentFileContentDigests } from "../quality/model-mutation-proof.ts";
+import type { ModelMutationEvidenceCompletion, ModelMutationIdentity } from "../session/model-authorship-state.ts";
+import { appendMutationProvenance, type AppendMutationProvenanceOptions } from "./mutation-provenance-store.ts";
+
+type RecordMutationResultOptions = {
+  projectRoot: string;
+  identity: ModelMutationIdentity;
+  toolCallId: string;
+  toolName: string;
+  recordedAt: string;
+  successful: boolean;
+  currentSnapshot: Record<string, string>;
+  completion: ModelMutationEvidenceCompletion;
+  shellSnapshotBefore?: Record<string, string>;
+  shellChangedPaths: string[];
+  protectedPaths: string[];
+};
+
+function toolName(value: string): AppendMutationProvenanceOptions["toolName"] {
+  const normalized = value.toLowerCase();
+  if (normalized === "edit" || normalized === "write" || normalized === "apply_patch") return normalized;
+  if (["bash", "shell", "exec"].includes(normalized)) return "shell";
+  return "opaque";
+}
+
+export function recordMutationResult(options: RecordMutationResultOptions) {
+  if (!options.successful) return undefined;
+  const changedPaths = [...new Set([...options.completion.changedPaths, ...options.shellChangedPaths])].sort();
+  const beforeSnapshot = options.completion.beforeSnapshot ?? options.shellSnapshotBefore;
+  if (!beforeSnapshot || changedPaths.length === 0) return undefined;
+  const contentDigests = currentFileContentDigests(options.projectRoot, changedPaths);
+  return appendMutationProvenance({
+    projectRoot: options.projectRoot,
+    taskId: options.identity.taskId,
+    taskRunId: options.identity.taskRunId,
+    sessionId: options.identity.sessionId,
+    toolCallId: options.toolCallId,
+    toolName: toolName(options.toolName),
+    recordedAt: options.recordedAt,
+    beforeSnapshot,
+    afterSnapshot: options.currentSnapshot,
+    changedPaths,
+    recordedDigests: options.completion.recordedDigests,
+    recordedContentDigests: { ...contentDigests, ...options.completion.recordedContentDigests },
+    proofModes: options.completion.proofModes,
+    protectedPaths: options.protectedPaths
+  });
+}

package/packages/piagent-core/runtime/inspection/mutation-provenance-store.ts

@@ -0,0 +1,161 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { workingTreeEvidenceDigest, workingTreeSnapshotUsesCurrentAlgorithm } from "../../extensions/working-tree-digest.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import {
+  MUTATION_PROVENANCE_VERSION,
+  mutationProvenanceDigest,
+  mutationProvenanceIdentity,
+  validateMutationProvenanceRecord,
+  type MutationProvenanceRecord
+} from "./mutation-provenance-contract.ts";
+import { readTaskBaselineManifest, taskBaselineRetentionState } from "./source-evidence-store.ts";
+
+const MAX_RECORDS = 500;
+const MAX_RECORD_BYTES = 128 * 1024;
+
+export type AppendMutationProvenanceOptions = {
+  projectRoot: string;
+  taskId: string;
+  taskRunId: string;
+  sessionId: string;
+  toolCallId: string;
+  toolName: "edit" | "write" | "apply_patch" | "shell" | "opaque";
+  recordedAt: string;
+  beforeSnapshot: Record<string, string>;
+  afterSnapshot: Record<string, string>;
+  recordedDigests: Record<string, string>;
+  recordedContentDigests: Record<string, string>;
+  proofModes: Record<string, "full-content" | "exact-replacement">;
+  changedPaths: string[];
+  protectedPaths?: string[];
+};
+
+function hash(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function evidenceDirectory(projectRoot: string, taskRunId: string): string {
+  return path.join(projectRoot, ".pi", "piagent-state", "source-evidence", `run-${hash(taskRunId)}`, "mutations");
+}
+
+function readPrivate(projectRoot: string, file: string): Buffer {
+  const safe = resolveLocalStatePath(projectRoot, file, { label: "Mutation provenance", kind: "file" });
+  const descriptor = fs.openSync(safe, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_RECORD_BYTES) throw new Error("Mutation provenance record is oversized or not regular");
+    return fs.readFileSync(descriptor);
+  } finally { fs.closeSync(descriptor); }
+}
+
+function publishPrivate(projectRoot: string, target: string, content: Buffer): void {
+  const parent = ensurePrivateStateDirectory(projectRoot, path.dirname(target), "Mutation provenance directory");
+  const safeTarget = resolveLocalStatePath(projectRoot, target, { label: "Mutation provenance" });
+  const temporary = path.join(parent, `${path.basename(target)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  const descriptor = fs.openSync(temporary, "wx", 0o600);
+  try { fs.writeFileSync(descriptor, content); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600); }
+  finally { fs.closeSync(descriptor); }
+  try { fs.linkSync(temporary, safeTarget); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    if (!readPrivate(projectRoot, safeTarget).equals(content)) throw new Error("Mutation provenance identity collision");
+  } finally { fs.rmSync(temporary, { force: true }); }
+  try { fs.chmodSync(parent, 0o700); fs.chmodSync(safeTarget, 0o600); } catch {}
+}
+
+function safePath(value: string): boolean {
+  return Boolean(value && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value)
+    && !value.split("/").includes("..") && !value.includes("\0") && value.length <= 4096);
+}
+
+export function appendMutationProvenance(options: AppendMutationProvenanceOptions): MutationProvenanceRecord | undefined {
+  const manifest = readTaskBaselineManifest(options.projectRoot, options.taskRunId);
+  if (!manifest || manifest.taskId !== options.taskId || manifest.captureState !== "current"
+    || taskBaselineRetentionState(manifest, new Date(options.recordedAt)) !== "active") return undefined;
+  if (!workingTreeSnapshotUsesCurrentAlgorithm(options.beforeSnapshot) || !workingTreeSnapshotUsesCurrentAlgorithm(options.afterSnapshot)) return undefined;
+  const paths = [...new Set(options.changedPaths)].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+  if (paths.length < 1 || paths.length > 100) return undefined;
+  const evidenceMode = paths.every((repoPath) => options.recordedDigests[repoPath] && options.proofModes[repoPath])
+    ? "exact-runtime" as const : "observed-runtime" as const;
+  const previous = evidenceMode === "observed-runtime" ? readMutationProvenance(options.projectRoot, options.taskRunId).records : [];
+  const changes = [];
+  for (const repoPath of paths) {
+    const before = options.beforeSnapshot[repoPath] ?? null;
+    const after = options.afterSnapshot[repoPath];
+    const content = options.recordedContentDigests[repoPath] ?? null;
+    const proofMode = evidenceMode === "exact-runtime" ? options.proofModes[repoPath] : null;
+    if (!safePath(repoPath) || matchesProtectedPath(repoPath, options.protectedPaths ?? [])
+      || before === (after ?? null) || (content !== null && !/^[a-f0-9]{64}$/.test(content))) return undefined;
+    if (evidenceMode === "exact-runtime" && (!after || after !== options.recordedDigests[repoPath] || !content || !proofMode)) return undefined;
+    const priorContent = [...previous].reverse().flatMap((record) => record.changes)
+      .find((change) => Buffer.from(change.repoPathBase64, "base64url").toString("utf8") === repoPath)?.afterContentDigest ?? null;
+    const effect = evidenceMode === "exact-runtime" ? "exact-content"
+      : content && priorContent === `sha256:${content}` ? "content-preserved"
+        : content ? "content-changed" : "unknown";
+    changes.push({
+      pathDigest: `sha256:${hash(repoPath)}`,
+      repoPathBase64: Buffer.from(repoPath, "utf8").toString("base64url"),
+      beforeCarrierDigest: before,
+      afterCarrierDigest: after ?? null,
+      afterContentDigest: content ? `sha256:${content}` : null,
+      proofMode,
+      effect
+    });
+  }
+  const beforeTreeDigest = workingTreeEvidenceDigest(options.beforeSnapshot);
+  const afterTreeDigest = workingTreeEvidenceDigest(options.afterSnapshot);
+  if (beforeTreeDigest === afterTreeDigest) return undefined;
+  const core = {
+    taskRunId: options.taskRunId,
+    toolCallIdentityHash: `sha256:${hash(`tool-call\0${options.toolCallId}`)}`,
+    recordedAt: options.recordedAt,
+    afterTreeDigest,
+    changes
+  };
+  const identity = mutationProvenanceIdentity(core);
+  const payload: Omit<MutationProvenanceRecord, "integrityDigest"> = {
+    schemaVersion: 1, version: MUTATION_PROVENANCE_VERSION,
+    recordId: `provenance.${identity}`, evidenceRef: `mutation.${identity}`,
+    taskId: options.taskId, taskRunId: options.taskRunId,
+    sessionIdentityHash: `sha256:${hash(`session\0${options.sessionId}`)}`,
+    toolCallIdentityHash: core.toolCallIdentityHash,
+    toolName: options.toolName, recordedAt: options.recordedAt, evidenceMode,
+    beforeTreeDigest, afterTreeDigest, changes
+  };
+  const record = validateMutationProvenanceRecord({ ...payload, integrityDigest: mutationProvenanceDigest(payload) });
+  const directory = evidenceDirectory(options.projectRoot, options.taskRunId);
+  let existing = 0;
+  try { existing = fs.readdirSync(resolveLocalStatePath(options.projectRoot, directory, { label: "Mutation provenance", kind: "directory" })).filter((file) => file.endsWith(".json")).length; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  const target = path.join(directory, `${record.recordId}.json`);
+  if (existing >= MAX_RECORDS && !fs.existsSync(target)) throw new Error("Mutation provenance record quota is exhausted");
+  publishPrivate(options.projectRoot, target, Buffer.from(`${JSON.stringify(record, null, 2)}\n`));
+  return record;
+}
+
+export function readMutationProvenance(
+  projectRoot: string,
+  taskRunId: string
+): { records: MutationProvenanceRecord[]; corruptions: string[] } {
+  const directory = evidenceDirectory(projectRoot, taskRunId);
+  let files: string[];
+  try { files = fs.readdirSync(resolveLocalStatePath(projectRoot, directory, { label: "Mutation provenance", kind: "directory" })).filter((file) => file.endsWith(".json")).sort(); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { records: [], corruptions: [] };
+    return { records: [], corruptions: ["provenance-directory-unavailable"] };
+  }
+  if (files.length > MAX_RECORDS) return { records: [], corruptions: ["provenance-record-limit"] };
+  const records: MutationProvenanceRecord[] = [], corruptions: string[] = [];
+  for (const file of files) {
+    try {
+      const record = validateMutationProvenanceRecord(JSON.parse(readPrivate(projectRoot, path.join(directory, file)).toString("utf8")));
+      if (file !== `${record.recordId}.json` || record.taskRunId !== taskRunId) throw new Error("identity mismatch");
+      records.push(record);
+    } catch { corruptions.push(`record.${hash(file)}`); }
+  }
+  return { records: corruptions.length ? [] : records.sort((left, right) => left.recordedAt.localeCompare(right.recordedAt)), corruptions };
+}

package/packages/piagent-core/runtime/inspection/project-runtime-inspection.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readProjectProfileDocument } from "../../capabilities/project-profile.js";
+import { effectiveProtectedPaths } from "../../extensions/context-index-policy.js";
+import { collectServers, unreadableLayers } from "../../mcp/mcp-config-layers.js";
+
+function readRequiredJsonObject(file: string): Record<string, unknown> {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) throw new Error("inspection-policy-unavailable");
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("inspection-policy-unavailable");
+  return value as Record<string, unknown>;
+}
+
+export function runtimeProtectedPaths(packageRoot: string, cwd: string): string[] {
+  const policy = readRequiredJsonObject(path.join(packageRoot, "packages", "piagent-core", "policies", "base-policy.json"));
+  const profileFile = path.join(cwd, ".pi", "piagent-profile.json");
+  let profile: Record<string, unknown> = {};
+  try {
+    const stat = fs.lstatSync(profileFile);
+    if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= 1_048_576) {
+      profile = readProjectProfileDocument(packageRoot, profileFile).profile ?? {};
+    }
+  } catch {
+    // Missing or unsafe project profiles never remove the platform policy.
+  }
+  return effectiveProtectedPaths(policy, profile).readProtectedPaths;
+}
+
+export function runtimeConnectionDefinitions(cwd: string): {
+  servers: ReturnType<typeof collectServers>;
+  unreadableLayerCount: number;
+} {
+  return { servers: collectServers({ projectPath: cwd }), unreadableLayerCount: unreadableLayers({ projectPath: cwd }).length };
+}

package/packages/piagent-core/runtime/inspection/review-state-contract.ts

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+
+export const REVIEW_EVIDENCE_VERSION = "piagent-webui-review-evidence-v1";
+
+export type ReviewView = "task" | "working-tree" | "staged";
+export type ReviewTarget = {
+  view: ReviewView;
+  fileRef: string;
+  diffRef: string;
+  taskRevision: string;
+  workspaceRevision: string;
+  indexRevision: string | null;
+  viewRevision: string;
+  fileRevision: string;
+  baseDigest: string | null;
+  currentDigest: string | null;
+  patchPreimage: string;
+  contentDigest: string;
+};
+
+export type ReviewEvidenceRecord = {
+  schemaVersion: 1;
+  version: typeof REVIEW_EVIDENCE_VERSION;
+  recordId: string;
+  evidenceRef: string;
+  sequence: number;
+  taskId: string;
+  taskRunId: string;
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  commandId: string;
+  idempotencyKeyDigest: string;
+  actionDigest: string;
+  reviewState: "reviewed" | "unreviewed";
+  target: ReviewTarget;
+  requestedAt: string;
+  recordedAt: string;
+  retentionUntil: string;
+  observedRevisions: Record<string, string | null>;
+  integrityDigest: string;
+};
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const PUBLIC_REF = /^[A-Za-z0-9][A-Za-z0-9._:@~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const REVISION_KEYS = ["runtimeRevision", "taskRevision", "controlRevision", "workspaceRevision", "indexRevision",
+  "approvalRevision", "sessionOptionRevision", "queueRevision"];
+
+export function canonicalReviewValue(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalReviewValue).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalReviewValue(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+export function reviewDigest(value: unknown): string {
+  return `sha256:${createHash("sha256").update(canonicalReviewValue(value)).digest("hex")}`;
+}
+
+export function reviewRecordDigest(record: Omit<ReviewEvidenceRecord, "integrityDigest">): string {
+  return reviewDigest(record);
+}
+
+function timestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) return false;
+  const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
+export function validateReviewTarget(value: unknown): ReviewTarget {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Review target is invalid");
+  const target = value as ReviewTarget;
+  const keys = ["view", "fileRef", "diffRef", "taskRevision", "workspaceRevision", "indexRevision", "viewRevision", "fileRevision",
+    "baseDigest", "currentDigest", "patchPreimage", "contentDigest"];
+  if (canonicalReviewValue(Object.keys(target).sort()) !== canonicalReviewValue(keys.sort())
+    || !["task", "working-tree", "staged"].includes(target.view) || !REF.test(target.fileRef) || !REF.test(target.diffRef)
+    || ![target.taskRevision, target.workspaceRevision, target.viewRevision, target.fileRevision].every((item) => REVISION.test(item))
+    || target.indexRevision !== null && !REVISION.test(target.indexRevision)
+    || ![target.baseDigest, target.currentDigest].every((item) => item === null || DIGEST.test(item))
+    || !DIGEST.test(target.patchPreimage) || target.contentDigest !== target.patchPreimage) throw new Error("Review target is invalid");
+  return structuredClone(target);
+}
+
+export function validateReviewEvidenceRecord(value: unknown): ReviewEvidenceRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Review evidence is invalid");
+  const record = value as ReviewEvidenceRecord;
+  const keys = ["schemaVersion", "version", "recordId", "evidenceRef", "sequence", "taskId", "taskRunId", "projectRef", "runtimeInstanceId", "sessionRef", "commandId",
+    "idempotencyKeyDigest", "actionDigest", "reviewState", "target", "requestedAt", "recordedAt", "retentionUntil", "observedRevisions", "integrityDigest"];
+  if (canonicalReviewValue(Object.keys(record).sort()) !== canonicalReviewValue(keys.sort()) || record.schemaVersion !== 1
+    || record.version !== REVIEW_EVIDENCE_VERSION || ![record.recordId, record.evidenceRef, record.projectRef, record.runtimeInstanceId, record.sessionRef, record.commandId].every((item) => REF.test(item))
+    || ![record.taskId, record.taskRunId].every((item) => PUBLIC_REF.test(item))
+    || !Number.isInteger(record.sequence) || record.sequence < 1 || record.sequence > 2_000
+    || ![record.idempotencyKeyDigest, record.actionDigest, record.integrityDigest].every((item) => DIGEST.test(item))
+    || !["reviewed", "unreviewed"].includes(record.reviewState) || ![record.requestedAt, record.recordedAt, record.retentionUntil].every(timestamp)
+    || Date.parse(record.requestedAt) > Date.parse(record.recordedAt) || Date.parse(record.recordedAt) >= Date.parse(record.retentionUntil)) {
+    throw new Error("Review evidence is invalid");
+  }
+  validateReviewTarget(record.target);
+  const revisions = record.observedRevisions;
+  if (!revisions || typeof revisions !== "object" || Array.isArray(revisions)
+    || canonicalReviewValue(Object.keys(revisions).sort()) !== canonicalReviewValue([...REVISION_KEYS].sort())
+    || !REVISION.test(String(revisions.runtimeRevision ?? ""))
+    || REVISION_KEYS.slice(1).some((key) => revisions[key] !== null && !REVISION.test(String(revisions[key])))) throw new Error("Review revisions are invalid");
+  const { integrityDigest, ...payload } = record;
+  if (reviewRecordDigest(payload) !== integrityDigest) throw new Error("Review evidence integrity mismatch");
+  return structuredClone(record);
+}

package/packages/piagent-core/runtime/inspection/review-state-projection.ts

@@ -0,0 +1,93 @@
+import type { DiffDocument } from "./diff-projection.ts";
+import { canonicalReviewValue, reviewDigest, type ReviewEvidenceRecord, type ReviewTarget, type ReviewView } from "./review-state-contract.ts";
+import type { WebUiIdentity } from "./source-change-projection.ts";
+
+export type ReviewStateProjection = {
+  schemaVersion: 1;
+  version: "piagent-webui-review-state-v1";
+  generatedAt: string;
+  identity: WebUiIdentity;
+  state: "reviewed" | "unreviewed" | "stale" | "unavailable";
+  target: ReviewTarget | null;
+  recordedState: "reviewed" | "unreviewed" | null;
+  recordedAt: string | null;
+  evidenceRef: string | null;
+  reasonCode: string | null;
+  health: { state: "ok" | "degraded" | "unavailable" | "error"; reasonCode: string | null; message: string | null };
+};
+
+type DeriveReviewTargetOptions = {
+  diff: DiffDocument;
+  taskId: string;
+  taskRunId: string;
+  taskRevision: string;
+  workspaceRevision: string;
+  indexRevision: string | null;
+};
+
+function targetCore(options: DeriveReviewTargetOptions): Omit<ReviewTarget, "diffRef" | "patchPreimage" | "contentDigest"> & { basisRef: string } {
+  const diff = options.diff as Record<string, any>, file = diff.file as Record<string, any>, observed = diff.observed as Record<string, any>;
+  return {
+    view: diff.view as ReviewView, fileRef: String(file.fileRef), taskRevision: options.taskRevision,
+    workspaceRevision: options.workspaceRevision, indexRevision: options.indexRevision,
+    viewRevision: String(observed.viewRevision), fileRevision: String(observed.fileRevision),
+    baseDigest: observed.baseDigest ?? null, currentDigest: observed.currentDigest ?? null,
+    basisRef: String(diff.basis?.basisRef ?? file.basisRef)
+  };
+}
+
+export function deriveReviewTarget(options: DeriveReviewTargetOptions): ReviewTarget | null {
+  const diff = options.diff as Record<string, any>;
+  if (!options.taskId || !options.taskRunId || !options.taskRevision || !options.workspaceRevision
+    || diff.availability?.state !== "current" || diff.fallback?.kind !== "none"
+    || diff.truncation?.truncated !== false || diff.redaction?.applied !== false || diff.redaction?.truncated !== false
+    || diff.file?.status === "C" || diff.file?.content?.kind !== "text" || diff.file?.content?.access !== "available") return null;
+  const core = targetCore(options), preimage = reviewDigest({ schemaVersion: 1, taskId: options.taskId, taskRunId: options.taskRunId, ...core });
+  return { view: core.view, fileRef: core.fileRef, diffRef: `diff.${preimage.slice("sha256:".length)}`, taskRevision: core.taskRevision,
+    workspaceRevision: core.workspaceRevision, indexRevision: core.indexRevision, viewRevision: core.viewRevision,
+    fileRevision: core.fileRevision, baseDigest: core.baseDigest, currentDigest: core.currentDigest,
+    patchPreimage: preimage, contentDigest: preimage };
+}
+
+function sameTarget(left: ReviewTarget, right: ReviewTarget): boolean {
+  return canonicalReviewValue(left) === canonicalReviewValue(right);
+}
+
+export function projectReviewState(options: {
+  identity: WebUiIdentity;
+  target: ReviewTarget | null;
+  records: ReviewEvidenceRecord[];
+  corruptions?: string[];
+  generatedAt?: string;
+  unavailableReason?: string;
+}): ReviewStateProjection {
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
+  const base = { schemaVersion: 1 as const, version: "piagent-webui-review-state-v1" as const, generatedAt,
+    identity: structuredClone(options.identity) };
+  if (options.corruptions?.length) return { ...base, state: "unavailable", target: null, recordedState: null, recordedAt: null,
+    evidenceRef: null, reasonCode: "review-evidence-corrupt", health: { state: "error", reasonCode: "review-evidence-corrupt", message: "Review evidence is corrupt" } };
+  if (!options.target) {
+    const reasonCode = options.unavailableReason ?? "review-target-unavailable";
+    return { ...base, state: "unavailable", target: null, recordedState: null, recordedAt: null, evidenceRef: null, reasonCode,
+      health: { state: "unavailable", reasonCode, message: "The exact review target is unavailable" } };
+  }
+  const relevant = options.records.filter((record) => record.taskId === options.identity.taskId && record.taskRunId === options.identity.taskRunId
+    && record.target.view === options.target!.view && record.target.fileRef === options.target!.fileRef);
+  const latest = relevant.at(-1);
+  if (!latest) return { ...base, state: "unreviewed", target: structuredClone(options.target), recordedState: null, recordedAt: null,
+    evidenceRef: null, reasonCode: null, health: { state: "ok", reasonCode: null, message: null } };
+  if (!sameTarget(latest.target, options.target)) {
+    const priorReviewed = [...relevant].reverse().find((record) => record.reviewState === "reviewed");
+    if (priorReviewed) return { ...base, state: "stale", target: structuredClone(options.target), recordedState: "reviewed",
+      recordedAt: priorReviewed.recordedAt, evidenceRef: priorReviewed.evidenceRef, reasonCode: "review-target-changed",
+      health: { state: "degraded", reasonCode: "review-target-changed", message: "The file or diff changed after it was reviewed" } };
+    return { ...base, state: "unreviewed", target: structuredClone(options.target), recordedState: null, recordedAt: null,
+      evidenceRef: null, reasonCode: null, health: { state: "ok", reasonCode: null, message: null } };
+  }
+  if (latest.reviewState === "unreviewed") return { ...base, state: "unreviewed", target: structuredClone(options.target),
+    recordedState: "unreviewed", recordedAt: latest.recordedAt, evidenceRef: latest.evidenceRef, reasonCode: null,
+    health: { state: "ok", reasonCode: null, message: null } };
+  return { ...base, state: "reviewed", target: structuredClone(options.target), recordedState: "reviewed",
+    recordedAt: latest.recordedAt, evidenceRef: latest.evidenceRef, reasonCode: null,
+    health: { state: "ok", reasonCode: null, message: null } };
+}