forgeos 0.1.0-alpha.63 → 0.1.0-alpha.64

package/src/forge/agent-fabric/local-coding-worker.ts

@@ -0,0 +1,190 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { sha256Digest } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import type { LocalCodingTaskProposal } from "./local-task-contract.ts";
+import type { Digest } from "./types.ts";
+import { localFabricPath } from "./local-paths.ts";
+
+function git(root: string, args: readonly string[], maxBuffer = 128 * 1024): string {
+  try {
+    return execFileSync("git", [...args], {
+      cwd: root, encoding: "utf8", windowsHide: true,
+      timeout: 10_000, maxBuffer, stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    throw new AgentFabricError("AF_INVALID_STATE", `Git operation failed: ${args[0] ?? "unknown"}`);
+  }
+}
+
+export function buildLocalCodingContext(repositoryRoot: string, task: Readonly<LocalCodingTaskProposal>): string {
+  const sources = task.sourcePaths.map((path) => ({
+    path,
+    content: git(repositoryRoot, ["show", `${task.baseCommit}:${path}`], task.limits.maximumContextBytes + 1),
+  }));
+  const content = JSON.stringify({ baseCommit: task.baseCommit, sources });
+  if (Buffer.byteLength(content, "utf8") > task.limits.maximumContextBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Pinned source context exceeds the approved byte limit");
+  }
+  return content;
+}
+
+function validateModelFiles(text: string, task: Readonly<LocalCodingTaskProposal>): readonly { path: string; content: string }[] {
+  if (Buffer.byteLength(text, "utf8") > task.limits.maximumPatchBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output exceeds the approved patch byte limit");
+  }
+  let parsed: unknown;
+  const fenced = /^```(?:json)?\r?\n([\s\S]*?)\r?\n```$/u.exec(text.trim());
+  try { parsed = JSON.parse(fenced ? fenced[1]! : text); } catch {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output is not strict JSON");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model output is not a file proposal");
+  }
+  // Small local models sometimes emit the files array directly. Both forms
+  // undergo the same strict path, content, count, and size checks below.
+  const root = parsed as Record<string, unknown>;
+  const rootKeys = Object.keys(root).sort().join(",");
+  const fileMap = !Array.isArray(parsed) && rootKeys !== "files" &&
+    rootKeys !== "files,schemaVersion" && Object.keys(root).every((path) =>
+      task.writablePaths.includes(path) && typeof root[path] === "string");
+  const proposedFiles = Array.isArray(parsed) ? parsed : fileMap
+    ? Object.entries(root).map(([path, content]) => ({ path, content })) : root.files;
+  if ((!Array.isArray(parsed) && !fileMap &&
+      (rootKeys !== "files" &&
+       (rootKeys !== "files,schemaVersion" ||
+        (root.schemaVersion !== 1 && root.schemaVersion !== "1")))) ||
+      !Array.isArray(proposedFiles) || proposedFiles.length < 1 || proposedFiles.length > task.writablePaths.length) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model file proposal has unsupported structure");
+  }
+  const seen = new Set<string>();
+  return proposedFiles.map((item: unknown) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Invalid model file proposal");
+    }
+    const file = item as Record<string, unknown>;
+    if (Object.keys(file).sort().join(",") !== "content,path" ||
+        typeof file.path !== "string" || !task.writablePaths.includes(file.path) ||
+        seen.has(file.path.toLowerCase()) || typeof file.content !== "string" ||
+        file.content.includes("\u0000")) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Model proposed an unauthorized file or content");
+    }
+    seen.add(file.path.toLowerCase());
+    return { path: file.path, content: file.content };
+  });
+}
+
+function checkedTarget(worktreeRoot: string, path: string): string {
+  const target = resolve(worktreeRoot, path);
+  const prefix = `${worktreeRoot}${process.platform === "win32" ? "\\" : "/"}`;
+  if (!target.startsWith(prefix)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Model path escapes the isolated checkout");
+  }
+  let cursor = worktreeRoot;
+  for (const segment of path.split("/")) {
+    cursor = join(cursor, segment);
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Model path traverses a symbolic link");
+    }
+  }
+  return target;
+}
+
+export interface LocalPatchEvidence {
+  worktreeRoot: string;
+  baseCommit: string;
+  changedPaths: readonly string[];
+  diffDigest: Digest;
+  diffBytes: number;
+  diffPath: string;
+  verification: "diff_check_passed" | "diff_check_failed";
+}
+
+/** Recheck the live checkout before showing or accepting its saved diff. */
+export function verifyLocalPatchEvidence(patch: LocalPatchEvidence): void {
+  const canonical = realpathSync(patch.worktreeRoot);
+  const checkoutRoot = realpathSync(git(canonical, ["rev-parse", "--show-toplevel"]).trim());
+  if (checkoutRoot !== canonical || git(canonical, ["rev-parse", "HEAD"]).trim() !== patch.baseCommit) {
+    throw new AgentFabricError("AF_CONFLICT", "Approved patch checkout moved from its recorded base");
+  }
+  if (git(canonical, ["diff", "--cached", "--binary"]).length > 0 ||
+      git(canonical, ["ls-files", "--others", "--exclude-standard"]).length > 0) {
+    throw new AgentFabricError("AF_CONFLICT", "Patch checkout has unrecorded files or staged changes");
+  }
+  const diff = git(canonical, ["diff", "--binary"], patch.diffBytes + 1);
+  if (sha256Digest(diff) !== patch.diffDigest ||
+      sha256Digest(readFileSync(patch.diffPath, "utf8")) !== patch.diffDigest) {
+    throw new AgentFabricError("AF_CONFLICT", "Live patch no longer matches its recorded diff");
+  }
+}
+
+/** Apply a model's file proposal only inside a fresh checkout of the pinned commit. */
+export function materializeLocalCodingPatch(
+  repositoryRoot: string,
+  taskId: string,
+  task: Readonly<LocalCodingTaskProposal>,
+  modelText: string,
+): LocalPatchEvidence {
+  const files = validateModelFiles(modelText, task);
+  const worktreeRoot = localFabricPath(repositoryRoot, "worktrees", taskId.replace(/^task:/u, ""));
+  const existing = existsSync(worktreeRoot);
+  if (!existing) {
+    mkdirSync(dirname(worktreeRoot), { recursive: true });
+    git(repositoryRoot, ["worktree", "add", "--detach", "--", worktreeRoot, task.baseCommit]);
+  }
+  const canonical = realpathSync(worktreeRoot);
+  const reportedRoot = realpathSync(git(canonical, ["rev-parse", "--show-toplevel"]).trim());
+  if ((process.platform === "win32" ? reportedRoot.toLowerCase() : reportedRoot) !==
+      (process.platform === "win32" ? canonical.toLowerCase() : canonical)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Isolated checkout root is not its own Git worktree");
+  }
+  if (git(canonical, ["rev-parse", "HEAD"]).trim() !== task.baseCommit) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Isolated checkout is not at the approved base commit");
+  }
+  for (const file of files) {
+    const target = checkedTarget(canonical, file.path);
+    if (existing) {
+      if (!existsSync(target) || readFileSync(target, "utf8") !== file.content) {
+        throw new AgentFabricError("AF_CONFLICT", "Existing checkout differs from the recorded model result");
+      }
+    } else {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, file.content, { flag: "w" });
+    }
+  }
+  git(canonical, ["add", "-N", "--", ...files.map((file) => file.path)]);
+  const diff = git(canonical, ["diff", "--binary", "--", ...files.map((file) => file.path)],
+    task.limits.maximumPatchBytes + 1);
+  const diffBytes = Buffer.byteLength(diff, "utf8");
+  if (diffBytes === 0 || diffBytes > task.limits.maximumPatchBytes) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Resulting diff is empty or exceeds the approved patch limit");
+  }
+  const changedPaths = git(canonical, ["diff", "--name-only", "--", ...files.map((file) => file.path)])
+    .trim().split(/\r?\n/u).filter(Boolean);
+  if (changedPaths.length === 0 || changedPaths.some((path) => !task.writablePaths.includes(path))) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Resulting diff contains an unauthorized path");
+  }
+  const diffPath = localFabricPath(repositoryRoot, "artifacts", `${taskId.replace(/^task:/u, "")}.diff`);
+  mkdirSync(dirname(diffPath), { recursive: true });
+  if (existsSync(diffPath)) {
+    if (readFileSync(diffPath, "utf8") !== diff) {
+      throw new AgentFabricError("AF_CONFLICT", "Existing diff artifact differs from the model result");
+    }
+  } else {
+    writeFileSync(diffPath, diff, { flag: "wx" });
+  }
+  if (sha256Digest(readFileSync(diffPath, "utf8")) !== sha256Digest(diff)) {
+    throw new AgentFabricError("AF_INVALID_STATE", "Diff artifact failed readback");
+  }
+  let verification: LocalPatchEvidence["verification"] = "diff_check_passed";
+  try {
+    git(canonical, ["diff", "--check", "--", ...files.map((file) => file.path)]);
+  } catch {
+    verification = "diff_check_failed";
+  }
+  const patch = { worktreeRoot: canonical, baseCommit: task.baseCommit, changedPaths,
+    diffDigest: sha256Digest(diff), diffBytes, diffPath, verification };
+  verifyLocalPatchEvidence(patch);
+  return patch;
+}

package/src/forge/agent-fabric/local-control-store.ts

@@ -0,0 +1,239 @@
+import type { DbAdapter } from "../runtime/db/adapter.ts";
+import { sha256Digest, stableStringify } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import { ForgeAgentConductor } from "./hardened-conductor.ts";
+import { MemoryControlJournal } from "./journal.ts";
+import { replayControlState } from "./hardened-reducer.ts";
+import { ResourceLedger } from "./resource-ledger.ts";
+import type {
+  Clock, ControlEventEnvelope, OwnerAuthorizationVerifier, ResourceDefinition,
+  UncommittedControlEvent,
+} from "./types.ts";
+
+const CREATE_EVENTS_TABLE = `
+  CREATE TABLE IF NOT EXISTS _forge_agent_fabric_control_events (
+    root_execution_id TEXT NOT NULL,
+    event_sequence INTEGER NOT NULL,
+    event_id TEXT NOT NULL,
+    idempotency_key TEXT,
+    envelope_json TEXT NOT NULL,
+    PRIMARY KEY (root_execution_id, event_sequence),
+    UNIQUE (root_execution_id, event_id),
+    UNIQUE (root_execution_id, idempotency_key)
+  )`;
+
+export interface LocalControlStoreOptions {
+  adapter: DbAdapter;
+  clock: Clock;
+  ownerAuthorizationVerifier: OwnerAuthorizationVerifier;
+  resourceDefinitions?: readonly ResourceDefinition[];
+}
+
+export interface LocalControlTransitionResult<T> {
+  result: T;
+  events: readonly ControlEventEnvelope[];
+}
+
+/**
+ * Single-process PGlite transaction boundary around the synchronous P0a Conductor.
+ * Only trusted server code may call transition; callbacks must have no external effects.
+ */
+export class LocalControlStore {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly definitions: readonly ResourceDefinition[];
+  private schemaReady?: Promise<unknown>;
+  private closed = false;
+  private readonly externalRoots = new Set<string>();
+  private readonly externalRuns = new Set<Promise<unknown>>();
+
+  constructor(private readonly options: LocalControlStoreOptions) {
+    if (options.adapter.kind !== "pglite") {
+      throw new AgentFabricError("AF_INVALID_STATE", "Local control store requires the PGlite adapter");
+    }
+    this.definitions = structuredClone(options.resourceDefinitions ?? []);
+  }
+
+  private async serialized<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed) throw new AgentFabricError("AF_INVALID_STATE", "Local control store is closed");
+    const predecessor = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>((resolve) => { release = resolve; });
+    await predecessor;
+    try {
+      this.schemaReady ??= this.options.adapter.query(CREATE_EVENTS_TABLE);
+      await this.schemaReady;
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+
+  private async load(rootExecutionId: string): Promise<ControlEventEnvelope[]> {
+    if (!rootExecutionId || rootExecutionId.length > 128) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Invalid root execution identity");
+    }
+    const result = await this.options.adapter.query(
+      `SELECT event_sequence, envelope_json FROM _forge_agent_fabric_control_events
+       WHERE root_execution_id = $1 ORDER BY event_sequence`,
+      [rootExecutionId],
+    );
+    const events: ControlEventEnvelope[] = [];
+    for (const row of result.rows) {
+      if (typeof row.envelope_json !== "string") {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is missing");
+      }
+      let event: ControlEventEnvelope;
+      try {
+        event = JSON.parse(row.envelope_json) as ControlEventEnvelope;
+      } catch {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is not JSON");
+      }
+      if (!event || typeof event !== "object" ||
+          event.rootExecutionId !== rootExecutionId || event.sequence !== row.event_sequence) {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control envelope is outside its stream");
+      }
+      events.push(event);
+    }
+    replayControlState(events, {
+      ownerAuthorizationVerifier: this.options.ownerAuthorizationVerifier,
+      resourceDefinitions: this.definitions,
+    });
+    return events;
+  }
+
+  async readAll(rootExecutionId: string): Promise<readonly ControlEventEnvelope[]> {
+    return this.serialized(async () => structuredClone(await this.load(rootExecutionId)));
+  }
+
+  private hydrate(rootExecutionId: string, before: readonly ControlEventEnvelope[]): {
+    journal: MemoryControlJournal;
+    conductor: ForgeAgentConductor;
+  } {
+    const journal = new MemoryControlJournal();
+    for (const stored of before) {
+      const {
+        sequence: _sequence,
+        predecessorEventId: _predecessorEventId,
+        predecessorEventDigest: _predecessorEventDigest,
+        eventDigest: _eventDigest,
+        ...uncommitted
+      } = stored;
+      const restored = journal.append({
+        expectedSequence: journal.readAll().length,
+        event: uncommitted as UncommittedControlEvent,
+      });
+      if (stableStringify(restored) !== stableStringify(stored)) {
+        throw new AgentFabricError("AF_INVALID_EVENT", "Stored control event changed during hydration");
+      }
+    }
+    const ledger = this.definitions.length > 0
+      ? new ResourceLedger(this.definitions)
+      : undefined;
+    return {
+      journal,
+      conductor: new ForgeAgentConductor(
+        rootExecutionId, journal, this.options.clock, sha256Digest,
+        this.options.ownerAuthorizationVerifier, ledger,
+      ),
+    };
+  }
+
+  private async persist(rootExecutionId: string, beforeCount: number, additions: readonly ControlEventEnvelope[]): Promise<void> {
+    if (additions.length === 0) return;
+    const transaction = await this.options.adapter.begin();
+    try {
+      const cursor = await transaction.query(
+        `SELECT COALESCE(MAX(event_sequence), 0) AS current_sequence
+         FROM _forge_agent_fabric_control_events WHERE root_execution_id = $1`,
+        [rootExecutionId],
+      );
+      if (Number(cursor.rows[0]?.current_sequence) !== beforeCount) {
+        throw new AgentFabricError("AF_CONFLICT", "Local control journal compare-and-swap failed");
+      }
+      for (const event of additions) {
+        await transaction.query(
+          `INSERT INTO _forge_agent_fabric_control_events
+           (root_execution_id, event_sequence, event_id, idempotency_key, envelope_json)
+           VALUES ($1, $2, $3, $4, $5)`,
+          [rootExecutionId, event.sequence, event.eventId, event.idempotencyKey ?? null,
+            stableStringify(event)],
+        );
+      }
+      await transaction.commit();
+    } catch (error) {
+      await transaction.rollback().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async transition<T>(
+    rootExecutionId: string,
+    operation: (conductor: ForgeAgentConductor) => T,
+  ): Promise<LocalControlTransitionResult<T>> {
+    return this.serialized(async () => {
+      if (this.externalRoots.has(rootExecutionId)) {
+        throw new AgentFabricError("AF_CONFLICT", "External attempt is still in flight for this root");
+      }
+      const before = await this.load(rootExecutionId);
+      const { journal, conductor } = this.hydrate(rootExecutionId, before);
+      const result = operation(conductor);
+      if (result && typeof result === "object" && "then" in result) {
+        throw new AgentFabricError("AF_INVALID_STATE", "Control transitions must be synchronous");
+      }
+      const after = journal.readAll();
+      const additions = after.slice(before.length);
+      await this.persist(rootExecutionId, before.length, additions);
+      return { result, events: after };
+    });
+  }
+
+  /**
+   * Keep one external attempt per root while releasing the database writer
+   * lock for the model call. The permit is committed in a prior transition.
+   * A crash leaves it without an outcome, which recovery classifies as uncertain.
+   */
+  async runExternal<T>(
+    rootExecutionId: string,
+    operation: (conductor: ForgeAgentConductor) => Promise<T>,
+  ): Promise<LocalControlTransitionResult<T>> {
+    const prepared = await this.serialized(async () => {
+      if (this.externalRoots.has(rootExecutionId)) {
+        throw new AgentFabricError("AF_CONFLICT", "External attempt is already in flight for this root");
+      }
+      const before = await this.load(rootExecutionId);
+      const { journal, conductor } = this.hydrate(rootExecutionId, before);
+      this.externalRoots.add(rootExecutionId);
+      return { before, journal, conductor };
+    });
+    // No database transaction or writer lock remains open around the model call.
+    // A status read can therefore see only a committed journal prefix.
+    const execution = (async (): Promise<LocalControlTransitionResult<T>> => {
+      let result: T | undefined;
+      let failure: unknown;
+      try {
+        result = await operation(prepared.conductor);
+      } catch (error) {
+        failure = error;
+      }
+      const after = await this.serialized(async () => {
+        const events = prepared.journal.readAll();
+        await this.persist(rootExecutionId, prepared.before.length, events.slice(prepared.before.length));
+        return events;
+      });
+      if (failure !== undefined) throw failure;
+      return { result: result as T, events: after };
+    })();
+    this.externalRuns.add(execution);
+    try { return await execution; } finally {
+      this.externalRuns.delete(execution);
+      this.externalRoots.delete(rootExecutionId);
+    }
+  }
+
+  async close(): Promise<void> {
+    await Promise.allSettled([...this.externalRuns]);
+    this.closed = true;
+    await this.tail;
+    await this.options.adapter.close();
+  }
+}

package/src/forge/agent-fabric/local-paths.ts

@@ -0,0 +1,18 @@
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { AgentFabricError } from "./errors.ts";
+
+/** Check each local state component before opening files or creating worktrees. */
+export function localFabricPath(repositoryRoot: string, ...parts: string[]): string {
+  let current = repositoryRoot;
+  for (const part of [".forge", "local", "agent-fabric", ...parts]) {
+    if (!/^[A-Za-z0-9._-]+$/u.test(part) || part === "." || part === "..") {
+      throw new AgentFabricError("AF_INVALID_STATE", "Invalid local Agent Fabric path component");
+    }
+    current = join(current, part);
+    if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink()) {
+      throw new AgentFabricError("AF_INVALID_STATE", "Local Agent Fabric path traverses a symbolic link");
+    }
+  }
+  return current;
+}

package/src/forge/agent-fabric/local-task-contract.ts

@@ -0,0 +1,142 @@
+import { digestCanonical, sha256Digest, stableStringify } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import type { Digest } from "./types.ts";
+
+/** Untrusted request data. This does not grant authority or start a task. */
+export interface LocalCodingTaskProposal {
+  schemaVersion: 1;
+  repositoryId: string;
+  baseCommit: string;
+  goal: string;
+  acceptanceCriteria: readonly string[];
+  nonObjectives: readonly string[];
+  sourcePaths: readonly string[];
+  writablePaths: readonly string[];
+  requestedModelTargetId: string;
+  limits: {
+    maximumAttempts: number;
+    maximumWallClockMs: number;
+    maximumOutputTokens: number;
+    maximumContextBytes: number;
+    maximumPatchBytes: number;
+    expiresAt: number;
+  };
+}
+
+export interface ValidatedLocalCodingTaskProposal {
+  proposal: Readonly<LocalCodingTaskProposal>;
+  proposalDigest: Digest;
+}
+
+const MAX_PROPOSAL_BYTES = 32 * 1024;
+const MAX_CONTEXT_BYTES = 32 * 1024;
+const MAX_PATCH_BYTES = 48 * 1024;
+
+function invalid(field: string): never {
+  throw new AgentFabricError("AF_INVALID_STATE", `Invalid local coding task proposal field: ${field}`);
+}
+
+function record(value: unknown, field: string, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(field);
+  const item = value as Record<string, unknown>;
+  const actual = Object.keys(item);
+  if (actual.length !== keys.length ||
+      keys.some((key) => !Object.hasOwn(item, key)) ||
+      actual.some((key) => !keys.includes(key))) invalid(field);
+  return item;
+}
+
+function boundedText(value: unknown, field: string, maxBytes: number): string {
+  if (typeof value !== "string" || value.length === 0 || value.trim() !== value ||
+      Buffer.byteLength(value, "utf8") > maxBytes || /[\u0000-\u001f\u007f]/u.test(value)) invalid(field);
+  return value;
+}
+
+function identifier(value: unknown, field: string): string {
+  const text = boundedText(value, field, 128);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(text)) invalid(field);
+  return text;
+}
+
+function textList(value: unknown, field: string, minimum: number, maximum: number): string[] {
+  if (!Array.isArray(value) || value.length < minimum || value.length > maximum) invalid(field);
+  return value.map((item, index) => boundedText(item, `${field}[${index}]`, 512));
+}
+
+function relativeFilePath(value: unknown, field: string): string {
+  const path = boundedText(value, field, 240);
+  if (path.normalize("NFC") !== path || path.startsWith("/") ||
+      /[\\:*?"<>|]/u.test(path)) invalid(field);
+  const segments = path.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." ||
+      segment === ".." || [".git", ".forge", ".ssh", "node_modules", "_generated"].includes(segment.toLowerCase()) ||
+      /^\.env(?:\.|$)/iu.test(segment) ||
+      [".npmrc", ".pypirc", "forge.lock", "id_rsa", "id_ed25519"].includes(segment.toLowerCase()) ||
+      /\.(?:pem|key|p12|pfx)$/iu.test(segment) ||
+      segment.endsWith(".") || segment.endsWith(" ") ||
+      Buffer.byteLength(segment, "utf8") > 100 ||
+      /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu.test(segment))) invalid(field);
+  return path;
+}
+
+function pathList(value: unknown, field: string, maximum: number): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > maximum) invalid(field);
+  const paths = value.map((item, index) => relativeFilePath(item, `${field}[${index}]`));
+  if (new Set(paths.map((path) => path.toLowerCase())).size !== paths.length) invalid(field);
+  return paths;
+}
+
+function positiveInteger(value: unknown, field: string, maximum: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) invalid(field);
+  return value;
+}
+
+function freezeDeep<T>(value: T): T {
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) freezeDeep(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/**
+ * Validate and digest only a proposal. Trusted repository resolution, owner admission,
+ * path readback, resource reservation, and execution happen at later boundaries.
+ */
+export function validateLocalCodingTaskProposal(input: unknown): ValidatedLocalCodingTaskProposal {
+  const canonical = stableStringify(input);
+  if (Buffer.byteLength(canonical, "utf8") > MAX_PROPOSAL_BYTES) invalid("proposalBytes");
+  const raw = record(JSON.parse(canonical) as unknown, "proposal", [
+    "schemaVersion", "repositoryId", "baseCommit", "goal", "acceptanceCriteria",
+    "nonObjectives", "sourcePaths", "writablePaths", "requestedModelTargetId", "limits",
+  ]);
+  if (raw.schemaVersion !== 1) invalid("schemaVersion");
+  if (typeof raw.baseCommit !== "string" || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(raw.baseCommit)) {
+    invalid("baseCommit");
+  }
+  const limits = record(raw.limits, "limits", [
+    "maximumAttempts", "maximumWallClockMs", "maximumOutputTokens",
+    "maximumContextBytes", "maximumPatchBytes", "expiresAt",
+  ]);
+  const proposal: LocalCodingTaskProposal = {
+    schemaVersion: 1,
+    repositoryId: identifier(raw.repositoryId, "repositoryId"),
+    baseCommit: raw.baseCommit,
+    goal: boundedText(raw.goal, "goal", 4_000),
+    acceptanceCriteria: textList(raw.acceptanceCriteria, "acceptanceCriteria", 1, 16),
+    nonObjectives: textList(raw.nonObjectives, "nonObjectives", 0, 16),
+    sourcePaths: pathList(raw.sourcePaths, "sourcePaths", 24),
+    writablePaths: pathList(raw.writablePaths, "writablePaths", 12),
+    requestedModelTargetId: identifier(raw.requestedModelTargetId, "requestedModelTargetId"),
+    limits: {
+      maximumAttempts: positiveInteger(limits.maximumAttempts, "limits.maximumAttempts", 3),
+      maximumWallClockMs: positiveInteger(limits.maximumWallClockMs, "limits.maximumWallClockMs", 120_000),
+      maximumOutputTokens: positiveInteger(limits.maximumOutputTokens, "limits.maximumOutputTokens", 4_096),
+      maximumContextBytes: positiveInteger(limits.maximumContextBytes, "limits.maximumContextBytes", MAX_CONTEXT_BYTES),
+      maximumPatchBytes: positiveInteger(limits.maximumPatchBytes, "limits.maximumPatchBytes", MAX_PATCH_BYTES),
+      expiresAt: positiveInteger(limits.expiresAt, "limits.expiresAt", Number.MAX_SAFE_INTEGER),
+    },
+  };
+  const proposalDigest = digestCanonical(proposal, sha256Digest);
+  return { proposal: freezeDeep(proposal), proposalDigest };
+}