@piagent/platform 1.3.0 → 1.4.0

package/packages/piagent-core/runtime/inspection/source-change-projection.ts

@@ -0,0 +1,471 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import {
+  GitInspectionError,
+  type GitStatusRecord,
+  type GitStatusSnapshot,
+  collectGitStatus,
+  collectGitStatusForPaths,
+  readGitBlobDigests
+} from "./git-status-adapter.ts";
+import { collectNumstats, type LineStat } from "./git-numstat-adapter.ts";
+import { hashWorkspaceFile, inspectWorkspaceEntry, readWorkspaceFile, readWorkspaceLink } from "./workspace-file-reader.ts";
+import { collectTaskSourceChangeView } from "./task-source-projection.ts";
+import { sourceInspectionPlan } from "./source-inspection-plan.ts";
+const DEFAULT_PAGE_LIMIT = 300;
+const MAX_PAGE_LIMIT = 2_000;
+const MAX_TEXT_BYTES = 4 * 1024 * 1024;
+export type WebUiIdentity = {
+  projectRef: string;
+  runtimeInstanceId: string;
+  sessionRef: string;
+  taskId: string | null;
+  taskRunId: string | null;
+  agentOperationId: string | null;
+  toolCallId: string | null;
+};
+export type SourceProjectionOptions = {
+  cwd: string;
+  identity: WebUiIdentity;
+  generatedAt?: string;
+  pageLimit?: number;
+  taskRevision?: string | null;
+  isProtectedPath?: (repoRoot: string, repoPath: string) => boolean;
+  timeoutMs?: number;
+  maxGitBytes?: number;
+};
+export type SourceChangeDocument = Record<string, unknown> & {
+  view: "task" | "working-tree" | "staged";
+  viewRevision: string;
+  files: Array<Record<string, unknown>>;
+  page: { cursor: string | null; nextCursor: string | null; total: number; returned: number; truncated: boolean };
+  availability: { state: "current" | "stale" | "unavailable"; reasonCode: string | null; message: string | null };
+};
+export type SourceChangeViews = {
+  task: SourceChangeDocument | null;
+  workingTree: SourceChangeDocument;
+  staged: SourceChangeDocument;
+};
+export type SelectedSourceFileState = {
+  snapshot: GitStatusSnapshot;
+  record: GitStatusRecord;
+  file: Record<string, unknown>;
+};
+function visibleRecords(snapshot: GitStatusSnapshot): GitStatusRecord[] {
+  return snapshot.records.filter((record) => {
+    const paths = [record.path.value, record.oldPath?.value].filter((value): value is string => Boolean(value));
+    return !paths.some((value) => value === ".pi/piagent-state" || value.startsWith(".pi/piagent-state/"));
+  });
+}
+function hash(value: string | Buffer): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+function token(prefix: string, value: string | Buffer): string {
+  return `${prefix}.${hash(value)}`;
+}
+export function sourceRepoRef(snapshot: GitStatusSnapshot): string {
+  return token("repo", snapshot.repoRoot);
+}
+export function sourceFileRef(snapshot: GitStatusSnapshot, record: GitStatusRecord): string {
+  return token("file", `${snapshot.repoDigest}\0${record.path.digest}`);
+}
+function digest(value: Buffer): string {
+  return `sha256:${hash(value)}`;
+}
+function cleanTimestamp(value: string | undefined): string {
+  const timestamp = value ?? new Date().toISOString();
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(timestamp)) {
+    throw new Error("generatedAt must be a millisecond UTC timestamp");
+  }
+  return timestamp;
+}
+function indexRevision(snapshot: GitStatusSnapshot): string {
+  const evidence = visibleRecords(snapshot)
+    .filter((record) => record.kind === "unmerged" || ![".", "?", "!"].includes(record.indexStatus))
+    .map((record) => [record.path.digest, record.oldPath?.digest ?? null, record.indexStatus, record.indexMode, record.indexObject]);
+  return token("index", JSON.stringify([snapshot.headOid, evidence]));
+}
+function workspaceRevision(snapshot: GitStatusSnapshot, isProtectedPath?: SourceProjectionOptions["isProtectedPath"], digests?: Map<string, string | null>): string {
+  const evidence = visibleRecords(snapshot)
+    .filter((record) => record.kind !== "ignored")
+    .map((record) => {
+      const repoPath = record.path.value;
+      const status = [record.kind, record.indexStatus, record.worktreeStatus, record.oldPath?.digest ?? null,
+        record.headMode, record.indexMode, record.worktreeMode, record.headObject, record.indexObject];
+      if (!repoPath) return [record.path.digest, ...status, "unsafe-path"];
+      try {
+        const stat = inspectWorkspaceEntry(snapshot.repoRoot, repoPath);
+        if (isProtectedPath?.(snapshot.repoRoot, repoPath) === true
+          || (record.oldPath?.value && isProtectedPath?.(snapshot.repoRoot, record.oldPath.value) === true)) {
+          return [record.path.digest, ...status, "protected", stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs];
+        }
+        if (stat.isSymbolicLink()) return [record.path.digest, ...status, "symlink", readWorkspaceLink(snapshot.repoRoot, repoPath)];
+        if (stat.isFile()) {
+          const raw = hashWorkspaceFile(snapshot.repoRoot, repoPath);
+          const value = `sha256:${raw}`;
+          digests?.set(repoPath, value);
+          return [record.path.digest, ...status, "file", raw];
+        }
+        return [record.path.digest, ...status, "other", stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs];
+      } catch {
+        return [record.path.digest, ...status, "absent"];
+      }
+    });
+  return token("workspace", JSON.stringify([snapshot.repoDigest, snapshot.headOid, evidence]));
+}
+function isConflict(record: GitStatusRecord): boolean {
+  return record.kind === "unmerged" || record.indexStatus === "U" || record.worktreeStatus === "U";
+}
+function displayStatus(record: GitStatusRecord, view: "working-tree" | "staged"): "A" | "M" | "D" | "R" | "U" | "C" | null {
+  if (isConflict(record)) return "C";
+  if (view === "staged") {
+    if ([".", "?", "!"].includes(record.indexStatus)) return null;
+    if (record.indexStatus === "R") return "R";
+    if (record.indexStatus === "A" || record.indexStatus === "C") return "A";
+    if (record.indexStatus === "D") return "D";
+    return "M";
+  }
+  if (record.kind === "ignored") return null;
+  if (record.kind === "untracked") return "U";
+  if (record.kind === "renamed" || record.indexStatus === "R" || record.worktreeStatus === "R") return "R";
+  if (record.worktreeStatus === "D" || record.indexStatus === "D") return "D";
+  if (record.indexStatus === "A" || record.worktreeStatus === "A" || record.indexStatus === "C" || record.worktreeStatus === "C") return "A";
+  return "M";
+}
+function inspectUntracked(repoRoot: string, repoPath: string): { stat: LineStat; kind: "text" | "binary" | "symlink" | "unknown"; digest: string | null } {
+  try {
+    const fileStat = inspectWorkspaceEntry(repoRoot, repoPath);
+    if (fileStat.isSymbolicLink()) return { stat: { additions: null, deletions: null, binary: false }, kind: "symlink", digest: null };
+    if (!fileStat.isFile() || fileStat.size > MAX_TEXT_BYTES) {
+      return { stat: { additions: null, deletions: null, binary: false }, kind: "unknown", digest: null };
+    }
+    const content = readWorkspaceFile(repoRoot, repoPath, MAX_TEXT_BYTES);
+    if (content.includes(0)) return { stat: { additions: null, deletions: null, binary: true }, kind: "binary", digest: digest(content) };
+    const text = content.toString("utf8");
+    const additions = text.length === 0 ? 0 : text.split(/\r?\n/).length - (text.endsWith("\n") ? 1 : 0);
+    return { stat: { additions, deletions: 0, binary: false }, kind: "text", digest: digest(content) };
+  } catch {
+    return { stat: { additions: null, deletions: null, binary: false }, kind: "unknown", digest: null };
+  }
+}
+function currentFileDigest(repoRoot: string, repoPath: string): string | null {
+  try {
+    const stat = inspectWorkspaceEntry(repoRoot, repoPath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_TEXT_BYTES) return null;
+    return digest(readWorkspaceFile(repoRoot, repoPath, MAX_TEXT_BYTES));
+  } catch {
+    return null;
+  }
+}
+
+function modeKind(record: GitStatusRecord, view: "working-tree" | "staged", binary: boolean): "text" | "binary" | "symlink" | "submodule" | "unknown" {
+  if (record.submodule?.startsWith("S") || record.headMode === "160000" || record.indexMode === "160000" || record.worktreeMode === "160000") return "submodule";
+  const selected = view === "staged" ? record.indexMode : record.worktreeMode;
+  const mode = selected === "000000" ? record.headMode : selected;
+  if (mode === "120000") return "symlink";
+  if (binary) return "binary";
+  return mode === "000000" ? "unknown" : "text";
+}
+
+function unavailableStats(reasonCode: string) {
+  return { state: "unavailable", additions: null, deletions: null, reasonCode };
+}
+
+function projectFile(
+  snapshot: GitStatusSnapshot,
+  record: GitStatusRecord,
+  view: "working-tree" | "staged",
+  basisRef: string,
+  stats: Map<string, LineStat>,
+  blobDigests: Map<string, string>,
+  isProtectedPath?: SourceProjectionOptions["isProtectedPath"],
+  workspaceDigests?: Map<string, string | null>
+): Record<string, unknown> | null {
+  const status = displayStatus(record, view);
+  const repoPath = record.path.value;
+  if (!status || !repoPath || !record.path.display || (status === "R" && !record.oldPath?.display)) return null;
+  const conflict = isConflict(record);
+  const protectedPath = isProtectedPath?.(snapshot.repoRoot, repoPath) === true
+    || (record.oldPath?.value ? isProtectedPath?.(snapshot.repoRoot, record.oldPath.value) === true : false);
+  let stat = stats.get(repoPath);
+  let untracked: ReturnType<typeof inspectUntracked> | null = null;
+  if (record.kind === "untracked" && !protectedPath) {
+    untracked = inspectUntracked(snapshot.repoRoot, repoPath);
+    stat = untracked.stat;
+  }
+  const kind = untracked?.kind ?? modeKind(record, view, stat?.binary === true);
+  const statsProjection = conflict
+    ? unavailableStats("git-conflict")
+    : protectedPath
+      ? unavailableStats("protected-path")
+      : kind === "binary" || kind === "symlink" || kind === "submodule" || kind === "unknown" || !stat || stat.additions === null || stat.deletions === null
+        ? unavailableStats(kind === "binary" ? "binary-content" : kind === "symlink" ? "symlink-content" : kind === "submodule" ? "submodule-content" : "line-stats-unavailable")
+        : { state: "exact", additions: stat.additions, deletions: stat.deletions, reasonCode: null };
+  const baseDigest = status === "A" || status === "U" || protectedPath || !record.headObject
+    ? null
+    : blobDigests.get(record.headObject) ?? null;
+  const currentDigest = status === "D" || protectedPath
+    ? null
+    : untracked?.digest
+      ?? (view === "working-tree"
+        ? workspaceDigests?.has(repoPath) ? workspaceDigests.get(repoPath) ?? null : currentFileDigest(snapshot.repoRoot, repoPath)
+        : record.indexObject ? blobDigests.get(record.indexObject) ?? null : null);
+  const repoRef = sourceRepoRef(snapshot);
+  const fileRef = sourceFileRef(snapshot, record);
+  const fileRevision = token("file-rev", JSON.stringify([view, status, record.indexObject, currentDigest, stat]));
+  return {
+    repoRef,
+    basisRef,
+    fileRef,
+    fileRevision,
+    path: record.path.display,
+    oldPath: status === "R" ? record.oldPath?.display ?? null : null,
+    pathDisplay: record.path.displayMode,
+    status,
+    git: { indexStatus: record.indexStatus, worktreeStatus: record.worktreeStatus, conflict },
+    baseDigest,
+    currentDigest,
+    content: protectedPath
+      ? { kind: "unknown", access: "protected", reasonCode: "protected-path" }
+      : kind === "unknown"
+        ? { kind, access: "unavailable", reasonCode: "content-kind-unavailable" }
+        : { kind, access: "available", reasonCode: null },
+    stats: statsProjection,
+    provenance: {
+      classification: "post-baseline-unattributed",
+      evidence: "unavailable",
+      baselineEvidenceRef: null,
+      mutationEvidenceRefs: [],
+      reasonCode: "provenance-evidence-unavailable"
+    },
+    criterionIds: [],
+    verifierAttemptIds: [],
+    health: protectedPath
+      ? { state: "degraded", reasonCode: "protected-path", message: "Content is protected by policy" }
+      : { state: "ok", reasonCode: null, message: null }
+  };
+}
+
+export async function collectSelectedSourceFileState(
+  options: SourceProjectionOptions,
+  view: "working-tree" | "staged",
+  fileRef: string,
+  basisRef: string,
+  targetRepoPaths?: string[]
+): Promise<SelectedSourceFileState | null> {
+  const snapshot = targetRepoPaths?.length
+    ? await collectGitStatusForPaths(options.cwd, targetRepoPaths, { timeoutMs: options.timeoutMs, maxBytes: options.maxGitBytes })
+    : await collectGitStatus(options.cwd, { timeoutMs: options.timeoutMs, maxBytes: options.maxGitBytes });
+  const record = visibleRecords(snapshot).find((candidate) => sourceFileRef(snapshot, candidate) === fileRef);
+  if (!record || !displayStatus(record, view) || !record.path.value) return null;
+  const repoPaths = [record.oldPath?.value, record.path.value].filter((value): value is string => Boolean(value));
+  const protectedPath = repoPaths.some((repoPath) => options.isProtectedPath?.(snapshot.repoRoot, repoPath) === true);
+  const stats = await collectNumstats(snapshot, view, protectedPath ? [] : repoPaths, options.timeoutMs, options.maxGitBytes);
+  const objectIds = protectedPath ? [] : [record.headObject, record.indexObject].filter((value): value is string => Boolean(value));
+  const blobDigests = await readGitBlobDigests(snapshot.repoRoot, objectIds, { timeoutMs: options.timeoutMs, maxBlobBytes: MAX_TEXT_BYTES });
+  const file = projectFile(snapshot, record, view, basisRef, stats, blobDigests, options.isProtectedPath);
+  return file ? { snapshot, record, file } : null;
+}
+
+function baseDocument(
+  identity: WebUiIdentity,
+  view: SourceChangeDocument["view"],
+  viewRevision: string,
+  generatedAt: string,
+  basis: Record<string, unknown>,
+  files: Array<Record<string, unknown>>,
+  pageLimit: number,
+  issues: Array<Record<string, unknown>> = []
+): SourceChangeDocument {
+  const ordered = [...files].sort((left, right) => String(left.path).localeCompare(String(right.path), "en"));
+  const returned = ordered.slice(0, pageLimit);
+  const truncated = returned.length < ordered.length;
+  const restricted = ordered.filter((file) => (file.content as any)?.access === "protected").length;
+  const degraded = issues.length > 0 || restricted > 0;
+  return {
+    schemaVersion: 1,
+    version: "piagent-webui-source-change-v1",
+    generatedAt,
+    identity,
+    view,
+    viewRevision,
+    bases: [basis],
+    availability: { state: "current", reasonCode: null, message: null },
+    files: returned,
+    page: { cursor: null, nextCursor: truncated ? token("page", `${viewRevision}:${pageLimit}`) : null, total: ordered.length, returned: returned.length, truncated },
+    truncationReason: truncated ? "page-limit" : null,
+    redaction: { applied: restricted > 0, valuesRemoved: restricted, truncated: false },
+    health: degraded
+      ? { state: "degraded", reasonCode: issues.length ? "path-projection-unavailable" : "source-content-restricted", message: issues.length ? "Some Git paths could not be projected safely" : "Some source content is protected by policy" }
+      : { state: "ok", reasonCode: null, message: null },
+    issues
+  };
+}
+
+function unavailableTaskDocument(options: SourceProjectionOptions, generatedAt: string, workspaceRev: string, repoRef: string): SourceChangeDocument | null {
+  if (!options.identity.taskId || !options.identity.taskRunId) return null;
+  const basisRef = token("basis", `${options.identity.taskRunId}:task:unavailable`);
+  const viewRevision = token("task", `${options.identity.taskRunId}:baseline-unavailable:${workspaceRev}`);
+  return {
+    schemaVersion: 1,
+    version: "piagent-webui-source-change-v1",
+    generatedAt,
+    identity: options.identity,
+    view: "task",
+    viewRevision,
+    bases: [{
+      basisRef,
+      repoRef,
+      view: "task",
+      state: "unavailable",
+      reasonCode: "task-baseline-content-unavailable",
+      basisRevision: token("basis-rev", `${options.identity.taskRunId}:unavailable`),
+      taskRunId: options.identity.taskRunId,
+      taskRevision: options.taskRevision ?? "task-revision.unavailable",
+      workspaceRevision: workspaceRev,
+      baselineManifestRef: null,
+      baselineTreeDigest: null
+    }],
+    availability: { state: "unavailable", reasonCode: "task-baseline-content-unavailable", message: "Exact task changes require Task Baseline Manifest evidence" },
+    files: [],
+    page: { cursor: null, nextCursor: null, total: 0, returned: 0, truncated: false },
+    truncationReason: null,
+    redaction: { applied: false, valuesRemoved: 0, truncated: false },
+    health: { state: "unavailable", reasonCode: "task-baseline-content-unavailable", message: "Task baseline content evidence is not available" },
+    issues: []
+  };
+}
+
+export async function collectSourceChangeViewsStrict(options: SourceProjectionOptions): Promise<SourceChangeViews> {
+  const generatedAt = cleanTimestamp(options.generatedAt);
+  const pageLimit = Number.isInteger(options.pageLimit) ? Math.max(1, Math.min(MAX_PAGE_LIMIT, options.pageLimit as number)) : DEFAULT_PAGE_LIMIT;
+  const gitOptions = { timeoutMs: options.timeoutMs, maxBytes: options.maxGitBytes };
+  const before = await collectGitStatus(options.cwd, gitOptions);
+  const beforeWorkspaceRev = workspaceRevision(before, options.isProtectedPath);
+  const beforeIndexRev = indexRevision(before);
+  const inspection = sourceInspectionPlan(before, options.isProtectedPath);
+  const [workingStats, stagedStats, blobDigests] = await Promise.all([
+    collectNumstats(before, "working-tree", inspection.workingTreePaths, options.timeoutMs, options.maxGitBytes),
+    collectNumstats(before, "staged", inspection.stagedPaths, options.timeoutMs, options.maxGitBytes),
+    readGitBlobDigests(before.repoRoot, inspection.objectIds, { timeoutMs: options.timeoutMs, maxBlobBytes: MAX_TEXT_BYTES })
+  ]);
+  const after = await collectGitStatus(before.repoRoot, gitOptions);
+  const repoRef = sourceRepoRef(before);
+  const workspaceDigests = new Map<string, string | null>();
+  const workspaceRev = workspaceRevision(after, options.isProtectedPath, workspaceDigests);
+  const indexRev = indexRevision(after);
+  const stale = beforeWorkspaceRev !== workspaceRev || beforeIndexRev !== indexRev;
+  const project = (view: "working-tree" | "staged", stats: Map<string, LineStat>) => {
+    const basisRef = token("basis", `${repoRef}:${view}:${before.headOid ?? "unborn"}:${view === "staged" ? indexRev : workspaceRev}`);
+    const viewRevision = view === "staged" ? indexRev : workspaceRev;
+    const basis = {
+      basisRef,
+      repoRef,
+      view,
+      state: stale ? "stale" : "current",
+      reasonCode: stale ? "git-race" : null,
+      basisRevision: token("basis-rev", `${basisRef}:${viewRevision}`),
+      headState: before.headState,
+      headRef: before.headOid ? `git.${before.headOid}` : null,
+      ...(view === "working-tree"
+        ? { workspaceRevision: workspaceRev, indexRevision: indexRev }
+        : { indexRevision: indexRev, workspaceRevision: workspaceRev })
+    };
+    if (stale) {
+      const document = baseDocument(options.identity, view, viewRevision, generatedAt, basis, [], pageLimit);
+      document.availability = { state: "stale", reasonCode: "git-race", message: "Git state changed during collection; retry the projection" };
+      document.health = { state: "degraded", reasonCode: "git-race", message: "Git state changed during collection" };
+      return document;
+    }
+    const issues: Array<Record<string, unknown>> = [];
+    const files = visibleRecords(before).flatMap((record) => {
+      const file = projectFile(before, record, view, basisRef, stats, blobDigests, options.isProtectedPath, workspaceDigests);
+      if (file) return [file];
+      if (displayStatus(record, view) && !record.path.display) {
+        issues.push({
+          issueRef: token("issue", `${view}:${record.path.digest}`),
+          severity: "warning",
+          code: "path-projection-unavailable",
+          message: "A Git path could not be represented safely",
+          relatedRefs: []
+        });
+      }
+      return [];
+    });
+    return baseDocument(options.identity, view, viewRevision, generatedAt, basis, files, pageLimit, issues);
+  };
+
+  return {
+    task: await collectTaskSourceChangeView(options) ?? unavailableTaskDocument(options, generatedAt, workspaceRev, repoRef),
+    workingTree: project("working-tree", workingStats),
+    staged: project("staged", stagedStats)
+  };
+}
+
+function unavailableGitDocument(
+  options: SourceProjectionOptions,
+  generatedAt: string,
+  view: "working-tree" | "staged",
+  repoRef: string,
+  workspaceRev: string,
+  indexRev: string,
+  reasonCode: string,
+  message: string
+): SourceChangeDocument {
+  const basisRef = token("basis", `${repoRef}:${view}:${reasonCode}`);
+  const basis = {
+    basisRef,
+    repoRef,
+    view,
+    state: "unavailable",
+    reasonCode,
+    basisRevision: token("basis-rev", `${basisRef}:unavailable`),
+    headState: "unavailable",
+    headRef: null,
+    ...(view === "working-tree"
+      ? { workspaceRevision: workspaceRev, indexRevision: indexRev }
+      : { indexRevision: indexRev, workspaceRevision: workspaceRev })
+  };
+  return {
+    schemaVersion: 1,
+    version: "piagent-webui-source-change-v1",
+    generatedAt,
+    identity: options.identity,
+    view,
+    viewRevision: view === "working-tree" ? workspaceRev : indexRev,
+    bases: [basis],
+    availability: { state: "unavailable", reasonCode, message },
+    files: [],
+    page: { cursor: null, nextCursor: null, total: 0, returned: 0, truncated: false },
+    truncationReason: null,
+    redaction: { applied: false, valuesRemoved: 0, truncated: false },
+    health: { state: "unavailable", reasonCode, message },
+    issues: []
+  };
+}
+
+export async function collectSourceChangeViews(options: SourceProjectionOptions): Promise<SourceChangeViews> {
+  try {
+    return await collectSourceChangeViewsStrict(options);
+  } catch (error) {
+    const generatedAt = cleanTimestamp(options.generatedAt);
+    const reasonCode = error instanceof GitInspectionError ? error.code : "git-collection-failed";
+    const message = ({
+      "not-git": "The selected workspace is not a Git repository",
+      timeout: "Git source collection timed out",
+      "output-limit": "Git source collection exceeded its output cap",
+      "git-failed": "Git source collection failed",
+      "invalid-output": "Git returned an invalid source status",
+      "git-collection-failed": "Workspace source evidence could not be read safely"
+    } as Record<string, string>)[reasonCode] ?? "Git source collection failed";
+    const root = path.resolve(options.cwd);
+    const repoRef = token("repo", root);
+    const workspaceRev = token("workspace", `${root}:${reasonCode}:unavailable`);
+    const indexRev = token("index", `${root}:${reasonCode}:unavailable`);
+    return {
+      task: unavailableTaskDocument(options, generatedAt, workspaceRev, repoRef),
+      workingTree: unavailableGitDocument(options, generatedAt, "working-tree", repoRef, workspaceRev, indexRev, reasonCode, message),
+      staged: unavailableGitDocument(options, generatedAt, "staged", repoRef, workspaceRev, indexRev, reasonCode, message)
+    };
+  }
+}

package/packages/piagent-core/runtime/inspection/source-evidence-contract.ts

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+
+export const TASK_BASELINE_MANIFEST_VERSION = "piagent-task-baseline-manifest-v1" as const;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const TREE_DIGEST = /^wt-content-v2:[a-f0-9]{64}$/;
+const OID = /^[a-f0-9]{40,64}$/;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+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 BaselineEntryState = "blob" | "absent" | "symlink" | "submodule" | "protected" | "oversized" | "unavailable";
+
+export type TaskBaselineEntry = {
+  pathRef: string;
+  pathDigest: string;
+  repoPathBase64: string | null;
+  state: BaselineEntryState;
+  reasonCode: string | null;
+  contentRef: string | null;
+  byteLength: number;
+  mode: string;
+  headObject: string | null;
+  indexObject: string | null;
+};
+
+export type TaskBaselineRoot = {
+  repoRef: string;
+  projectPath: string;
+  headState: "head" | "unborn" | "unavailable";
+  headOid: string | null;
+  workspaceRevision: string;
+  indexRevision: string;
+  state: "current" | "unavailable";
+  reasonCode: string | null;
+  entries: TaskBaselineEntry[];
+};
+
+export type TaskBaselineManifest = {
+  schemaVersion: 1;
+  version: typeof TASK_BASELINE_MANIFEST_VERSION;
+  taskId: string;
+  taskRunId: string;
+  sessionIdentityHash: string;
+  capturedAt: string;
+  retentionUntil: string;
+  baselineDigestAlgorithm: "wt-content-v2";
+  baselineTreeDigest: string;
+  captureState: "current" | "degraded" | "unavailable";
+  reasonCode: string | null;
+  limits: { maxEntries: number; maxFileBytes: number; maxTotalBytes: number; capturedBytes: number };
+  roots: TaskBaselineRoot[];
+  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])]));
+}
+
+export function taskBaselineManifestDigest(value: Omit<TaskBaselineManifest, "integrityDigest"> | TaskBaselineManifest): string {
+  const { integrityDigest: _ignored, ...payload } = value as TaskBaselineManifest;
+  return `sha256:${createHash("sha256").update(`task-baseline-manifest-v1\0${JSON.stringify(canonical(payload))}`).digest("hex")}`;
+}
+
+function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function reason(value: unknown): boolean {
+  return typeof value === "string" && /^[a-z0-9][a-z0-9.-]{0,95}$/.test(value);
+}
+
+function validEntry(value: unknown): value is TaskBaselineEntry {
+  if (!plain(value) || !exactKeys(value, ["pathRef", "pathDigest", "repoPathBase64", "state", "reasonCode", "contentRef", "byteLength", "mode", "headObject", "indexObject"])) return false;
+  if (!TOKEN.test(String(value.pathRef)) || !DIGEST.test(String(value.pathDigest))) return false;
+  if (value.repoPathBase64 !== null && (typeof value.repoPathBase64 !== "string" || value.repoPathBase64.length > 4096 || !/^[A-Za-z0-9_-]*$/.test(value.repoPathBase64))) return false;
+  const states: BaselineEntryState[] = ["blob", "absent", "symlink", "submodule", "protected", "oversized", "unavailable"];
+  if (!states.includes(value.state as BaselineEntryState)) return false;
+  if (!Number.isInteger(value.byteLength) || (value.byteLength as number) < 0 || (value.byteLength as number) > 16 * 1024 * 1024) return false;
+  if (!/^[0-7]{6}$/.test(String(value.mode))) return false;
+  if (value.headObject !== null && !OID.test(String(value.headObject))) return false;
+  if (value.indexObject !== null && !OID.test(String(value.indexObject))) return false;
+  if (["blob", "symlink"].includes(String(value.state))) return DIGEST.test(String(value.contentRef)) && value.reasonCode === null;
+  if (value.contentRef !== null) return false;
+  return ["protected", "oversized", "unavailable"].includes(String(value.state)) ? reason(value.reasonCode) : value.reasonCode === null;
+}
+
+function validRoot(value: unknown): value is TaskBaselineRoot {
+  if (!plain(value) || !exactKeys(value, ["repoRef", "projectPath", "headState", "headOid", "workspaceRevision", "indexRevision", "state", "reasonCode", "entries"])) return false;
+  if (!TOKEN.test(String(value.repoRef)) || typeof value.projectPath !== "string" || !value.projectPath || value.projectPath.length > 1024) return false;
+  if (!TOKEN.test(String(value.workspaceRevision)) || !TOKEN.test(String(value.indexRevision))) return false;
+  if (!Array.isArray(value.entries) || value.entries.length > 2000 || !value.entries.every(validEntry)) return false;
+  if (value.headState === "head") { if (!OID.test(String(value.headOid))) return false; }
+  else if (!["unborn", "unavailable"].includes(String(value.headState)) || value.headOid !== null) return false;
+  if (value.state === "current") return value.reasonCode === null;
+  return value.state === "unavailable" && reason(value.reasonCode);
+}
+
+export function taskBaselineManifestErrors(value: unknown): string[] {
+  const errors: string[] = [];
+  const keys = ["schemaVersion", "version", "taskId", "taskRunId", "sessionIdentityHash", "capturedAt", "retentionUntil", "baselineDigestAlgorithm", "baselineTreeDigest", "captureState", "reasonCode", "limits", "roots", "integrityDigest"];
+  if (!plain(value) || !exactKeys(value, keys)) return ["manifest shape is invalid"];
+  if (value.schemaVersion !== 1 || value.version !== TASK_BASELINE_MANIFEST_VERSION) errors.push("manifest 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))) errors.push("session identity hash is invalid");
+  const capturedAt = Date.parse(String(value.capturedAt));
+  const retentionUntil = Date.parse(String(value.retentionUntil));
+  if (!TIMESTAMP.test(String(value.capturedAt)) || !TIMESTAMP.test(String(value.retentionUntil))
+    || !Number.isFinite(capturedAt) || !Number.isFinite(retentionUntil)
+    || retentionUntil <= capturedAt || retentionUntil - capturedAt > 365 * 24 * 60 * 60 * 1000) errors.push("manifest timestamps are invalid");
+  if (value.baselineDigestAlgorithm !== "wt-content-v2" || !TREE_DIGEST.test(String(value.baselineTreeDigest))) errors.push("baseline tree digest is invalid");
+  if (!plain(value.limits) || !exactKeys(value.limits, ["maxEntries", "maxFileBytes", "maxTotalBytes", "capturedBytes"])) errors.push("manifest limits are invalid");
+  else if (
+    !Number.isInteger(value.limits.maxEntries) || (value.limits.maxEntries as number) < 1 || (value.limits.maxEntries as number) > 2000
+    || !Number.isInteger(value.limits.maxFileBytes) || (value.limits.maxFileBytes as number) < 1024 || (value.limits.maxFileBytes as number) > 16 * 1024 * 1024
+    || !Number.isInteger(value.limits.maxTotalBytes) || (value.limits.maxTotalBytes as number) < 1024 * 1024 || (value.limits.maxTotalBytes as number) > 256 * 1024 * 1024
+    || !Number.isInteger(value.limits.capturedBytes) || (value.limits.capturedBytes as number) < 0 || (value.limits.capturedBytes as number) > (value.limits.maxTotalBytes as number)
+  ) errors.push("manifest limit values are invalid");
+  if (!Array.isArray(value.roots) || value.roots.length < 1 || value.roots.length > 32 || !value.roots.every(validRoot)) errors.push("manifest roots are invalid");
+  if (!["current", "degraded", "unavailable"].includes(String(value.captureState))) errors.push("capture state is invalid");
+  else if (value.captureState === "current" ? value.reasonCode !== null : !reason(value.reasonCode)) errors.push("capture reason is invalid");
+  if (!DIGEST.test(String(value.integrityDigest)) || value.integrityDigest !== taskBaselineManifestDigest(value as TaskBaselineManifest)) errors.push("manifest integrity digest is invalid");
+  return errors;
+}
+
+export function validateTaskBaselineManifest(value: unknown): TaskBaselineManifest {
+  const errors = taskBaselineManifestErrors(value);
+  if (errors.length) throw new Error(`Invalid task baseline manifest: ${errors.join("; ")}`);
+  return structuredClone(value) as TaskBaselineManifest;
+}