nexakit 0.0.0-stage → 0.2.0

package/src/client-supervised-store.js

@@ -0,0 +1,167 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { createStoreFiles, bytesHash } from "./client-runtime-store-files.js";
+import { createSupervisedPermit, revokeSupervisedPermit } from "./client-supervised-permit.js";
+import { createSupervisedContract, hash, same, taskKey, zeroMetrics, terminalStates, errorCode, fail, copyInertJson } from "./client-supervised-contract.js";
+
+const names = ["0000.json", "0001.json", "0002.json", "0003.json"];
+const unfinished = new Set(["reserved", "start-claimed", "started"]);
+
+/** Separate one-attempt store; construction never initializes or repairs paths. */
+export function createSupervisedStore(schema, configuration, dependencies = {}) {
+  const contract = createSupervisedContract(schema), cfg = copyInertJson(configuration);
+  if (Object.keys(cfg).join() !== "root" || typeof cfg.root !== "string" || !path.isAbsolute(cfg.root) || path.normalize(cfg.root) !== cfg.root) throw Error("Invalid supervised store configuration");
+  const files = createStoreFiles(dependencies.io), checkpoint = dependencies.checkpoint ?? (async () => {});
+  const clock = dependencies.clock ?? Date.now;
+  let rootIdentity;
+  async function root() {
+    const tmp = await fs.realpath(os.tmpdir());
+    // S2 is experiments only: do not activate a permanent project/user store.
+    if (path.dirname(cfg.root) !== tmp || !/^agent-supervised-[a-zA-Z0-9-]+$/.test(path.basename(cfg.root))) fail("supervised-root-not-temporary");
+    const s = await files.directory(cfg.root, rootIdentity); rootIdentity ??= s; return s;
+  }
+  function stamp() {
+    const n = clock(); if (!Number.isFinite(n)) fail("supervised-clock-unavailable");
+    return new Date(n).toISOString().replace(/\.\d{3}Z$/, "Z");
+  }
+  async function readChain(dir, identity, expectedDirectory) {
+    await root(); await files.directory(dir, expectedDirectory); await files.contents(dir, [...names, "confirmed.json"]);
+    const events = [], bytesHashes = []; let missingSeen = false;
+    for (const name of names) {
+      const p = path.join(dir, name);
+      if (!await files.exists(p)) { missingSeen = true; continue; }
+      if (missingSeen) fail("supervised-event-gap");
+      const { bytes } = await files.read(p, 131072); const e = contract.event(bytes);
+      if (e.limits.graceMs + e.limits.confirmationMs >= e.limits.timeoutMs || e.limits.maxLineBytes > e.limits.maxOutputBytes) fail("supervised-incompatible-limits");
+      const prior = events.at(-1);
+      if (e.sequence !== events.length || taskKey(e.identity) !== taskKey(identity) ||
+          e.previousSha256 !== (bytesHashes.at(-1) ?? null)) fail("supervised-event-chain-mismatch");
+      if (!prior) {
+        if (e.state !== "reserved" || !same(e.metrics, zeroMetrics()) || e.reasons.length) fail("supervised-invalid-reservation");
+      } else {
+        if (!same(e.identity, prior.identity) || e.attemptId !== prior.attemptId || e.fixtureId !== prior.fixtureId ||
+            e.requestSha256 !== prior.requestSha256 || !same(e.limits, prior.limits) || Date.parse(e.observedAt) < Date.parse(prior.observedAt)) fail("supervised-event-binding-mismatch");
+        const allowed = prior.state === "reserved" ? ["start-claimed", "canceled", "failed", "timed-out", "indeterminate"]
+          : prior.state === "start-claimed" ? ["started", "failed", "canceled", "timed-out", "indeterminate"]
+            : prior.state === "started" ? [...terminalStates] : [];
+        if (!allowed.includes(e.state) || e.metrics.spawnAttempts < prior.metrics.spawnAttempts ||
+            e.metrics.mainStartsObserved < prior.metrics.mainStartsObserved || e.metrics.mainStartsObserved > e.metrics.spawnAttempts ||
+            ["stdoutBytes", "stderrBytes", "events", "elapsedMs"].some(k => e.metrics[k] < prior.metrics[k])) fail("supervised-invalid-transition");
+        if (e.state === "start-claimed" && (e.metrics.spawnAttempts !== 1 || e.metrics.mainStartsObserved !== 0 || e.reasons.length)) fail("supervised-invalid-claim");
+        if (e.state === "started" && (e.metrics.spawnAttempts !== 1 || e.metrics.mainStartsObserved !== 1 || e.reasons.length)) fail("supervised-invalid-start");
+        if (terminalStates.has(e.state)) {
+          if (!e.reasons.length || e.state !== "indeterminate" && !e.metrics.terminationConfirmed) fail("supervised-unconfirmed-terminal");
+          if (e.state === "completed-for-review" && (prior.state !== "started" || e.metrics.mainStartsObserved !== 1 ||
+              e.metrics.stdoutBytes > e.limits.maxOutputBytes || e.metrics.stderrBytes > e.limits.maxStderrBytes ||
+              e.metrics.events > e.limits.maxEvents || e.metrics.elapsedMs > e.limits.timeoutMs)) fail("supervised-invalid-completion");
+        }
+      }
+      events.push(e); bytesHashes.push(bytesHash(bytes));
+    }
+    if (!events.length) fail("supervised-empty-reservation");
+    let receipt = false;
+    if (await files.exists(path.join(dir, "confirmed.json"))) {
+      const seal = contract.receipt((await files.read(path.join(dir, "confirmed.json"), 131072)).bytes);
+      if (!terminalStates.has(events.at(-1).state) || events.at(-1).state === "indeterminate" || seal.terminalSha256 !== bytesHashes.at(-1)) fail("supervised-receipt-mismatch");
+      receipt = true;
+    }
+    return { events, bytesHashes, last: events.at(-1), receipt };
+  }
+  async function observe(input) {
+    const r = { state: "clear", budgetConsumed: false, eventCount: 0, lastState: null, spawnAttempts: null,
+      mainStartsObserved: null, fixtureModelCalls: 0, actualModelCalls: null, internalCallCeiling: null,
+      remoteCancellationVerified: false, reasons: [] };
+    try {
+      const i = contract.identity(input); await root(); const dir = path.join(cfg.root, taskKey(i));
+      if (!await files.exists(dir)) return contract.observation(r);
+      r.budgetConsumed = true;
+      const c = await readChain(dir, i); const e = c.last;
+      r.eventCount = c.events.length; r.lastState = e.state;
+      r.spawnAttempts = e.metrics.spawnAttempts; r.mainStartsObserved = e.metrics.mainStartsObserved;
+      // Recorded zeros before observation do not prove that no process started.
+      if (unfinished.has(e.state) || e.state === "indeterminate" || !c.receipt) {
+        r.state = "reconciliation-required"; r.mainStartsObserved = e.metrics.mainStartsObserved === 1 ? 1 : null;
+        if (e.state === "reserved") r.spawnAttempts = null;
+      } else r.state = "consumed";
+      r.reasons = [r.state === "consumed" ? "supervised-budget-consumed" : "supervised-reconciliation-required"];
+    } catch (e) {
+      r.state = "reconciliation-required"; r.budgetConsumed = true; r.reasons = [errorCode(e)];
+      r.spawnAttempts = null; r.mainStartsObserved = null;
+    }
+    return contract.observation(r);
+  }
+  async function withReservation(input, consumer) {
+    const r = { state: "blocked", durability: "unconfirmed", reasons: [], value: null };
+    let handle, created = false;
+    try {
+      const d = contract.request(input); if (typeof consumer !== "function") fail("supervised-consumer-required");
+      const rootStat = await root(), dir = path.join(cfg.root, taskKey(d.identity));
+      await checkpoint("before-reserve");
+      try { await files.io.mkdir(dir, { mode: 0o700 }); created = true; }
+      catch (e) { if (e.code === "EEXIST") fail("supervised-budget-reserved"); throw e; }
+      const dirStat = await files.directory(dir); await files.syncDirectory(cfg.root, rootStat);
+      await checkpoint("after-directory");
+      let chain = [];
+      async function append(state, metrics, reasons = []) {
+        await root(); await files.directory(dir, dirStat);
+        if (chain.length) {
+          const current = await readChain(dir, d.identity, dirStat);
+          if (!same(current.events, chain)) fail("supervised-reservation-changed");
+        } else await files.contents(dir, []);
+        const prev = chain.at(-1);
+        const e = contract.event({ schemaVersion: "1.0.0", scope: "fixture-only", sequence: chain.length,
+          previousSha256: prev ? bytesHash((await files.read(path.join(dir, names[chain.length - 1]), 131072)).bytes) : null,
+          identity: d.identity, attemptId: d.attemptId, fixtureId: d.fixtureId, requestSha256: hash(d), limits: d.limits,
+          state, observedAt: stamp(), metrics, reasons: [...new Set(reasons)].sort(), fixtureModelCalls: 0,
+          actualModelCalls: null, internalCallCeiling: null, remoteCancellationVerified: false });
+        if (chain.length >= names.length) fail("supervised-event-limit");
+        const resource = await files.exclusive(path.join(dir, names[chain.length]));
+        try {
+          await files.write(resource, Buffer.from(JSON.stringify(e) + "\n"));
+          await checkpoint("after-write-" + state);
+          await files.syncDirectory(dir, dirStat); await files.owned(resource);
+        } finally { await resource.handle.close(); }
+        const read = await readChain(dir, d.identity, dirStat);
+        if (!same(read.last, e)) fail("supervised-write-not-confirmed");
+        chain = read.events;
+        await checkpoint("durable-" + state);
+      }
+      await append("reserved", zeroMetrics()); r.durability = "confirmed";
+      handle = createSupervisedPermit(hash(d), async () => {
+        await append("start-claimed", { ...zeroMetrics(), spawnAttempts: 1 });
+      }, async () => {
+        await append("started", { ...zeroMetrics(), spawnAttempts: 1, mainStartsObserved: 1 });
+      });
+      await checkpoint("before-consumer");
+      const value = contract.processReport(await consumer(handle)); r.value = value;
+      revokeSupervisedPermit(handle);
+      // An unfinished started write may still be completing. Do not race it by
+      // appending a terminal event; keep the reservation for reconciliation.
+      if (value.state === "indeterminate") {
+        r.state = "reconciliation-required"; r.reasons = ["supervised-reconciliation-required"]; return r;
+      }
+      const c = await readChain(dir, d.identity, dirStat);
+      if (!same(c.events, chain)) fail("supervised-reservation-changed");
+      const finalState = value.state === "not-started" ? "failed" : value.state;
+      await append(finalState, value.metrics, value.reasons.length ? value.reasons : ["supervised-local-result"]);
+      // Only write the receipt after terminal data, directory sync and readback
+      // have completed. A partial terminal append alone never proves settlement.
+      const terminal = await readChain(dir, d.identity, dirStat);
+      const receipt = contract.receipt({ schemaVersion: "1.0.0", scope: "fixture-only", terminalSha256: terminal.bytesHashes.at(-1) });
+      const seal = await files.exclusive(path.join(dir, "confirmed.json"));
+      try {
+        await files.write(seal, Buffer.from(JSON.stringify(receipt) + "\n"));
+        await files.syncDirectory(dir, dirStat); await files.owned(seal);
+      } finally { await seal.handle.close(); }
+      if (!(await readChain(dir, d.identity, dirStat)).receipt) fail("supervised-write-not-confirmed");
+      r.state = finalState === "indeterminate" ? "reconciliation-required" : "recorded";
+      r.reasons = r.state === "recorded" ? ["supervised-result-recorded"] : ["supervised-reconciliation-required"];
+    } catch (e) {
+      r.state = created ? "reconciliation-required" : "blocked";
+      r.durability = "unconfirmed"; r.reasons = [errorCode(e)];
+    } finally { if (handle) revokeSupervisedPermit(handle); }
+    return r;
+  }
+  return Object.freeze({ observe, withReservation });
+}

package/src/client-supervised-supervisor.js

@@ -0,0 +1,167 @@
+import { supportsLocalPosix } from "./client-local-platform.js";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn as nativeSpawn } from "node:child_process";
+import { claimSupervisedPermit } from "./client-supervised-permit.js";
+import { createSupervisedProtocol } from "./client-supervised-protocol.js";
+import { createSupervisedContract, hash, monotonicMs, zeroMetrics, errorCode, fail } from "./client-supervised-contract.js";
+
+const script = fileURLToPath(new URL("./runtime-fixtures/supervised/fixture.cjs", import.meta.url));
+const childScript = fileURLToPath(new URL("./runtime-fixtures/supervised/child.cjs", import.meta.url));
+
+/** Trusted fixture runner, not a native subscription runner. */
+export function createSupervisedSupervisor(schema, dependencies = {}) {
+  const contract = createSupervisedContract(schema);
+  const spawn = dependencies.spawn ?? nativeSpawn, kill = dependencies.kill ?? process.kill.bind(process);
+  const mono = dependencies.monotonic ?? monotonicMs, checkpoint = dependencies.checkpoint ?? (async () => {});
+  return async function supervise(handle, input, { signal, beganAt = mono() } = {}) {
+    const r = { scope: "fixture-only", state: "not-started", fixtureExecuted: false, nativeExecuted: false,
+      runtimeReady: false, verifiedAdmission: false, actualModelCalls: null, fixtureModelCalls: 0,
+      internalCallCeiling: null, remoteCancellationVerified: false, metrics: zeroMetrics(),
+      exitObserved: false, pipesClosed: false, groupObservation: "not-started", reasons: [] };
+    const elapsed = () => Math.max(0, Math.ceil(mono() - beganAt));
+    let cwd, owned, spawnReturned = false, attempted = false;
+    try {
+      const d = contract.request(input), l = d.limits;
+      if (!supportsLocalPosix(process.platform)) fail("supervised-platform-not-admitted");
+      if (!Number.isFinite(beganAt) || beganAt > mono()) fail("supervised-invalid-deadline");
+      const budget = () => {
+        if (signal?.aborted) fail("supervised-canceled-before-start");
+        if (elapsed() >= l.timeoutMs - l.graceMs - l.confirmationMs) fail("supervised-deadline-before-start");
+      };
+      budget();
+      for (const file of [script, childScript]) {
+        const s = await fs.lstat(file);
+        if (!s.isFile() || s.isSymbolicLink() || (s.mode & 0o022)) fail("supervised-fixture-source-unsafe");
+      }
+      const parent = await fs.lstat(path.dirname(script));
+      if (!parent.isDirectory() || parent.isSymbolicLink() || (parent.mode & 0o022)) fail("supervised-fixture-directory-unsafe");
+      const workspaceParent = dependencies.workspaceParent ?? await fs.realpath(os.tmpdir());
+      if (dependencies.workspaceParent !== undefined) {
+        const s = await fs.lstat(workspaceParent);
+        if (await fs.realpath(workspaceParent) !== workspaceParent || !s.isDirectory() || s.isSymbolicLink() ||
+            (s.mode & 0o7777) !== 0o700 || s.uid !== process.getuid()) fail("supervised-workspace-parent-unsafe");
+      }
+      cwd = await fs.realpath(await fs.mkdtemp(path.join(workspaceParent, "agent-supervised-work-")));
+      await fs.chmod(cwd, 0o700); owned = await fs.lstat(cwd);
+      budget(); await checkpoint("before-claim");
+      const capability = await claimSupervisedPermit(handle, hash(d));
+      // Claim consumed the only local start right; no reuse if later checks fail.
+      budget(); await checkpoint("before-spawn"); budget();
+      r.metrics.spawnAttempts = 1; attempted = true;
+      const child = spawn(process.execPath, [script, d.fixtureId], {
+        shell: false, detached: true, cwd, env: { LANG: "C", LC_ALL: "C" }, stdio: ["pipe", "pipe", "pipe"]
+      });
+      spawnReturned = true;
+      // Register all lifecycle handlers synchronously, before awaiting storage.
+      await new Promise(resolve => {
+        const protocol = createSupervisedProtocol(l), stderr = new TextDecoder("utf-8", { fatal: true });
+        let done = false, spawned = false, spawnFailed = false, canceled = false, cancelAt = null, forced = false;
+        let groupGone = false, startedWritePending = false, startedWriteFailed = false;
+        let stdinClosed = false, stdoutClosed = false, stderrClosed = false, closed = false, exitCode = null;
+        let timer, hardTimer;
+        const add = c => { if (!r.reasons.includes(c)) r.reasons.push(c); };
+        const groupAlive = () => {
+          if (groupGone || spawnFailed) return false;
+          if (!spawned) return true;
+          try { kill(-child.pid, 0); return true; }
+          catch (e) { if (e?.code === "ESRCH") { groupGone = true; return false; } add("supervised-group-unconfirmed"); return true; }
+        };
+        const send = sig => {
+          if (!spawned || groupGone) return;
+          try { kill(-child.pid, sig); }
+          catch (e) { if (e?.code === "ESRCH") groupGone = true; else add("supervised-signal-unconfirmed"); }
+        };
+        const cancel = (code, state = "failed") => {
+          if (done) return; add(code);
+          if (canceled) return;
+          canceled = true; cancelAt = mono(); r.state = state;
+          child.stdin.destroy(); send("SIGTERM");
+        };
+        const finish = uncertain => {
+          if (done) return; done = true;
+          clearInterval(timer); clearTimeout(hardTimer); signal?.removeEventListener("abort", abort);
+          const counts = protocol.counts();
+          Object.assign(r.metrics, { stdoutBytes: counts.stdoutBytes, events: counts.events, elapsedMs: elapsed() });
+          r.pipesClosed = stdinClosed && stdoutClosed && stderrClosed && closed;
+          r.groupObservation = spawnFailed ? "not-started" : groupGone ? "absent" : "unconfirmed";
+          r.metrics.terminationConfirmed = spawnFailed || r.exitObserved && r.pipesClosed && groupGone;
+          if (uncertain || startedWriteFailed || r.metrics.elapsedMs > l.timeoutMs) {
+            r.state = "indeterminate"; add("supervised-reconciliation-required");
+          } else if (spawnFailed) { r.state = "not-started"; }
+          else if (!canceled && r.state !== "failed") r.state = "completed-for-review";
+          if (!r.reasons.length) add("supervised-fixture-completed");
+          child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy(); resolve();
+        };
+        const poll = () => {
+          if (done) return;
+          if (elapsed() >= l.timeoutMs - l.graceMs - l.confirmationMs && !canceled) cancel("supervised-deadline", "timed-out");
+          if (canceled && !forced && mono() - cancelAt >= l.graceMs) { forced = true; send("SIGKILL"); }
+          const alive = groupAlive();
+          if (r.exitObserved && closed && stdinClosed && stdoutClosed && stderrClosed && !startedWritePending && !alive) {
+            if (!canceled && !spawnFailed) {
+              try { if (exitCode !== 0) fail("supervised-exit-failed"); protocol.finish(); stderr.decode(); }
+              catch (e) { r.state = "failed"; add(errorCode(e)); }
+            }
+            finish(false);
+          } else if (r.exitObserved && alive && !canceled) cancel("supervised-descendants-live");
+          if (spawnFailed && closed) finish(false);
+        };
+        const abort = () => cancel("supervised-canceled", "canceled");
+        child.on("spawn", () => {
+          spawned = true;
+          if (done) { send("SIGKILL"); return; }
+          r.fixtureExecuted = true; r.metrics.mainStartsObserved = 1; startedWritePending = true;
+          if (canceled) send("SIGTERM");
+          Promise.resolve().then(() => checkpoint("spawn-observed")).then(() => capability.started())
+            .catch(() => { startedWriteFailed = true; cancel("supervised-start-record-unconfirmed"); })
+            .finally(() => { startedWritePending = false; poll(); });
+        });
+        child.on("error", () => { if (done) return; if (!spawned) { spawnFailed = true; add("supervised-spawn-failed"); } else cancel("supervised-process-error"); });
+        child.on("exit", code => { if (done) return; r.exitObserved = true; exitCode = code; poll(); });
+        child.on("close", () => { closed = true; poll(); });
+        child.stdin.on("close", () => { stdinClosed = true; poll(); });
+        child.stdout.on("close", () => { stdoutClosed = true; poll(); });
+        child.stderr.on("close", () => { stderrClosed = true; poll(); });
+        for (const [stream, name] of [[child.stdin, "stdin"], [child.stdout, "stdout"], [child.stderr, "stderr"]]) {
+          stream.on("error", () => cancel("supervised-" + name + "-error"));
+        }
+        child.stdout.on("data", chunk => {
+          if (done || canceled) return;
+          try { protocol.push(chunk); } catch (e) { cancel(errorCode(e)); }
+        });
+        child.stderr.on("data", chunk => {
+          if (done || canceled) return;
+          r.metrics.stderrBytes += chunk.length;
+          if (r.metrics.stderrBytes > l.maxStderrBytes) cancel("supervised-stderr-limit");
+          else try { stderr.decode(chunk, { stream: true }); } catch { cancel("supervised-stderr-invalid-utf8"); }
+        });
+        signal?.addEventListener("abort", abort, { once: true }); if (signal?.aborted) abort();
+        timer = setInterval(poll, 10);
+        hardTimer = setTimeout(() => { send("SIGKILL"); poll(); if (!done) finish(true); }, Math.max(1, l.timeoutMs - elapsed()));
+        try { child.stdin.end(d.inputText, e => { if (e) cancel("supervised-stdin-error"); }); }
+        catch { cancel("supervised-stdin-error"); }
+      });
+    } catch (e) {
+      r.reasons = [errorCode(e)]; r.metrics.elapsedMs = elapsed();
+      r.metrics.terminationConfirmed = !spawnReturned;
+      if (spawnReturned) r.state = "indeterminate";
+      else if (e?.code === "supervised-canceled-before-start") r.state = "canceled";
+      else if (e?.code === "supervised-deadline-before-start") r.state = "timed-out";
+      // attempted is distinct from a returned ChildProcess and a spawn event.
+      if (attempted) r.metrics.spawnAttempts = 1;
+    } finally {
+      if (cwd && (!spawnReturned || r.metrics.terminationConfirmed)) {
+        try {
+          const s = await fs.lstat(cwd);
+          if (s.dev !== owned.dev || s.ino !== owned.ino || !s.isDirectory() || s.isSymbolicLink()) throw Error("changed");
+          await fs.rmdir(cwd);
+        } catch { r.state = "indeterminate"; r.reasons.push("supervised-workspace-cleanup-required"); }
+      }
+    }
+    r.reasons = [...new Set(r.reasons)].sort();
+    return contract.processReport(r);
+  };
+}

package/src/client-supervised.js

@@ -0,0 +1,160 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { copyInertJson, copyBytes, decode, parseEventJson, ParseFailure, fail } from "./client-output-json.js";
+import { CONTROLS, EFFECTS, hash, same, unique, fresh } from "./client-runtime-core.js";
+
+const SCHEMA_ID = "https://agent-toolkit.local/schemas/agent-client-supervised.schema.json";
+const MAX_INPUT_BYTES = 131072;
+const REQUIRED_CONTROLS = CONTROLS.filter(id => id !== "internal-call-limit");
+const SECTIONS = ["selection", "binding", "expectedBinding", "limits", "context", "authorization", "limitations", "history", "installation", "controls", "effects", "access", "observations"];
+const GATES = ["trusted-authorization-and-limitations", "native-installation-and-controls", "subscription-and-billing", "selection-and-private-context", "supervised-history-and-durable-reservation", "local-supervision-and-termination", "human-result-review"];
+
+function declarationScope(data, policySha256) {
+  const summary = value => {
+    if (!value) return null;
+    const { assessment, billingAssessment, ...declaration } = value;
+    return declaration;
+  };
+  const ordered = (items, key) => (items ?? []).map(summary).sort((a, b) => a[key] < b[key] ? -1 : a[key] > b[key] ? 1 : 0);
+  const authorization = summary(data.authorization);
+  if (authorization) authorization.effectsApproved = [...authorization.effectsApproved].sort();
+  return hash({ profile: data.profile, intentId: data.intentId, identity: data.identity,
+    selection: summary(data.selection), binding: data.binding ?? null, expectedBinding: data.expectedBinding ?? null,
+    limits: data.limits ?? null, context: summary(data.context), authorization,
+    limitations: summary(data.limitations), history: summary(data.history), access: summary(data.access),
+    controls: ordered(data.controls, "controlId"), effects: ordered(data.effects, "effectId"),
+    observations: [...(data.observations ?? [])].sort(), policySha256 });
+}
+
+// A separate pure review of declarations. This is not a C1 admission or a launcher.
+export function createClientSupervisedEvaluator(schema, trustedPolicy) {
+  let contract; let policy;
+  try { contract = copyInertJson(schema); policy = copyInertJson(trustedPolicy); }
+  catch { throw Error("Invalid supervised evaluation configuration"); }
+  if (contract?.$id !== SCHEMA_ID) throw Error("Unsupported supervised evaluation schema");
+  const ajv = new Ajv2020({ strict: true, allErrors: true });
+  ajv.addFormat("date-time", { type: "string", validate: value => {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(value)) return false;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value.replace(/Z$/, ".000Z");
+  } });
+  ajv.addSchema(contract);
+  const validator = name => ajv.compile({ $ref: `${SCHEMA_ID}#/$defs/${name}` });
+  const validInput = validator("input"), validPolicy = validator("policy"), validReport = validator("report");
+  if (!validPolicy(policy) || policy.limits.terminationGraceSeconds >= policy.limits.timeoutSeconds ||
+      policy.limits.maxEventBytes > policy.limits.maxStdoutBytes) throw Error("Invalid supervised evaluation policy");
+  const revoked = new Set(policy.revokedEvidenceRefs), policySha256 = hash(policy);
+
+  return function evaluateSupervisedIntent(input) {
+    const report = { schemaVersion: "1.0.0", profile: "supervised-subscription", intentId: null, state: "invalid",
+      executed: false, runtimeReady: false, verifiedAdmission: false, externalBillingVerified: false,
+      selectionVerified: false, internalCallCeiling: null, remoteCancellationVerified: false,
+      reasons: [], missing: [], externalGates: [...GATES], audit: { inputSha256: null, scopeSha256: null, policySha256 } };
+    const blockers = new Set(), missing = new Set();
+    const block = reason => blockers.add(reason);
+    function finish(state, reasons = []) {
+      report.state = state; report.reasons = [...new Set(reasons)].sort(); report.missing = [...missing].sort();
+      if (!validReport(report)) throw Error("Supervised evaluation report invariant failed");
+      return report;
+    }
+    try {
+      const parsed = typeof input === "string" || (input && typeof input === "object" && ArrayBuffer.isView(input))
+        ? parseEventJson(decode(copyBytes(input, MAX_INPUT_BYTES))) : input;
+      const data = copyInertJson(parsed);
+      const serialized = JSON.stringify(data);
+      parseEventJson(decode(copyBytes(serialized, MAX_INPUT_BYTES))); // Validate Unicode in copied object strings too.
+      if (!validInput(data)) fail("invalid-supervised-input");
+      if (data.controls && !unique(data.controls.map(c => c.controlId))) fail("duplicate-supervised-control");
+      if (data.effects && !unique(data.effects.map(e => e.effectId))) fail("duplicate-supervised-effect");
+      report.intentId = data.intentId; report.audit.inputSha256 = hash(data);
+      for (const section of SECTIONS) if (data[section] === undefined) missing.add(section);
+
+      // Evidence is bound to the whole intent, not just an installation or a task name.
+      const { assessment: selectionAssessment, ...selection } = data.selection ?? {};
+      const { assessment: contextAssessment, ...context } = data.context ?? {};
+      const scope = declarationScope(data, policySha256);
+      report.audit.scopeSha256 = scope;
+      function reference(id, label) {
+        if (id === null) missing.add(`${label}.reference`);
+        else if (revoked.has(id)) block(`supervised-reference-revoked:${label}`);
+      }
+      function assess(a, label, sources) {
+        if (!a) return;
+        reference(a.evidenceRef, label);
+        if (a.scopeSha256 !== scope) block(`supervised-scope-mismatch:${label}`);
+        if (!fresh(a, data.now, policy.maxEvidenceAgeSeconds)) block(`supervised-evidence-not-fresh:${label}`);
+        if (a.status === "rejected") block(`supervised-evidence-rejected:${label}`);
+        else if (a.status !== "confirmed") missing.add(`${label}.confirmation`);
+        else if (!sources.includes(a.source)) block(`supervised-source-conflict:${label}`);
+      }
+      const human = ["operator-attestation"], test = ["installation-test"], attested = [...human, ...test];
+      if (data.binding && data.expectedBinding && !same(data.binding, data.expectedBinding)) block("supervised-binding-mismatch");
+      if (data.selection) {
+        assess(selectionAssessment, "selection", attested);
+        if (["latest", "default", "opus", "sonnet", "haiku", "fable"].includes(selection.model) || selection.model.split("-").includes("latest")) block("supervised-model-not-pinned");
+        if (data.binding && (selection.client !== data.binding.client || selection.provider !== data.binding.provider)) block("supervised-selection-binding-mismatch");
+        if (selection.source === "operator-choice" && selectionAssessment.source !== "operator-attestation") block("supervised-selection-source-conflict");
+      }
+      if (data.limits) {
+        for (const key of Object.keys(policy.limits)) if (data.limits[key] > policy.limits[key]) block("supervised-limits-exceed-policy");
+        if (data.limits.terminationGraceSeconds >= data.limits.timeoutSeconds) block("supervised-grace-outside-deadline");
+        if (data.limits.maxEventBytes > data.limits.maxStdoutBytes) block("supervised-event-limit-inconsistent");
+      }
+      if (data.context) {
+        assess(contextAssessment, "context", attested);
+        if (data.limits && context.inputBytes > data.limits.maxInputBytes) block("supervised-context-exceeds-budget");
+      }
+      if (data.authorization) {
+        const a = data.authorization;
+        assess(a.assessment, "authorization", human);
+        if (a.status !== "approved") block("supervised-authorization-not-approved");
+        if (data.limits && !same(a.limits, data.limits)) block("supervised-authorization-limits-mismatch");
+        if (data.identity.mode === "tutor" && a.writer !== "user") block("supervised-tutor-authority-conflict");
+      }
+      if (data.identity.role === "tutor" && data.identity.mode !== "tutor") block("supervised-tutor-mode-conflict");
+      if (data.limitations) {
+        assess(data.limitations.assessment, "limitations", human);
+        if (!data.limitations.internalCallsUnknownAccepted || !data.limitations.remoteCancellationUnknownAccepted) block("supervised-limitations-not-accepted");
+      }
+      if (data.history) {
+        const h = data.history;
+        assess(h.assessment, "history", attested);
+        if (h.projectId !== data.identity.projectId || h.taskId !== data.identity.taskId) block("supervised-history-identity-mismatch");
+        if (h.state !== "clear") block("supervised-history-reconciliation-required");
+        if (h.mainStartsUsed === 0 && (h.durationUsedSeconds > 0 || (h.actualModelCalls !== null && h.actualModelCalls > 0))) block("supervised-history-counters-inconsistent");
+        if (data.limits && (h.mainStartsUsed >= data.limits.maxMainStarts || h.durationUsedSeconds >= data.limits.timeoutSeconds)) block("supervised-budget-exhausted");
+        if (h.mainStartsUsed > 0 && h.actualModelCalls === null) block("supervised-prior-consumption-unresolved");
+      }
+      if (data.installation) assess(data.installation.assessment, "installation", test);
+      for (const id of REQUIRED_CONTROLS) {
+        const c = data.controls?.find(c => c.controlId === id), label = `controls.${id}`;
+        if (!c) { missing.add(label); continue; }
+        assess(c.assessment, label, test);
+        for (const key of ["mechanismId", "positiveEvidenceRef", "negativeEvidenceRef"]) {
+          if (c[key] === null) missing.add(`${label}.${key.toLowerCase()}`);
+          else if (key !== "mechanismId") reference(c[key], `${label}.${key.toLowerCase()}`);
+        }
+      }
+      for (const id of EFFECTS) {
+        const e = data.effects?.find(e => e.effectId === id), label = `effects.${id}`;
+        if (!e) { missing.add(label); continue; }
+        assess(e.assessment, label, test);
+        if (e.presence === "unknown" || e.disposition !== "allowed") block(`supervised-effect-unconfirmed:${id}`);
+        if (["native-auth", "provider-inference"].includes(id) && e.presence === "absent") block(`supervised-required-effect-absent:${id}`);
+        if (e.presence === "present" && !data.authorization?.effectsApproved.includes(id)) block(`supervised-effect-not-authorized:${id}`);
+      }
+      if (data.access) {
+        assess(data.access.assessment, "access", attested);
+        assess(data.access.billingAssessment, "billing", attested);
+        if (data.access.method !== "subscription-session") block("supervised-subscription-required");
+        if (data.access.externalBilling !== "disabled") block("supervised-external-billing-not-disabled");
+      }
+      for (const code of data.observations ?? []) block(`supervised-unresolved:${code}`);
+      if (blockers.size) return finish("blocked", [...blockers]);
+      if (missing.size) return finish("incomplete", ["supervised-declarations-incomplete"]);
+      return finish("ready-for-supervised-review", ["supervised-declarations-only"]);
+    } catch (error) {
+      if (!(error instanceof ParseFailure)) throw error;
+      return finish("invalid", [error.code]);
+    }
+  };
+}