forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/forge/agent-fabric/local-evolution-registry.ts

@@ -0,0 +1,427 @@
+import { randomUUID } from "node:crypto";
+import type { DbAdapter, DbTransaction } from "../runtime/db/adapter.ts";
+import { digestCanonical, sha256Digest, stableStringify } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import type { Digest } from "./types.ts";
+
+/** A candidate is data. This registry never loads or executes its artifact. */
+export interface ExtensionCandidate {
+  extensionKey: string;
+  artifactDigest: Digest;
+  manifestDigest: Digest;
+}
+
+export interface ExtensionVersion extends ExtensionCandidate {
+  versionId: string;
+  registeredAt: number;
+}
+
+export interface FixedEvaluationSuite {
+  suiteId: string;
+  suiteDigest: Digest;
+  caseIds: readonly string[];
+}
+
+export interface EvaluationCaseEvidence {
+  caseId: string;
+  passed: boolean;
+  evidenceDigest: Digest;
+}
+
+export interface EvaluationRecord {
+  versionId: string;
+  suiteId: string;
+  suiteDigest: Digest;
+  state: "running" | "passed" | "failed" | "inconclusive";
+  cases: readonly EvaluationCaseEvidence[];
+  evidenceDigest: Digest | null;
+}
+
+export type EvolutionDecisionAction = "canary" | "promote" | "rollback" | "revoke";
+export type EvolutionChannel = "canary" | "stable";
+
+export interface EvolutionVersionStatus {
+  version: ExtensionVersion;
+  evaluation: EvaluationRecord | null;
+  revoked: boolean;
+  channels: readonly EvolutionChannel[];
+  lastDecision: { action: EvolutionDecisionAction; decidedAt: number; verifierId: string } | null;
+}
+
+export interface OwnerDecisionChallenge {
+  decisionNonce: string;
+  action: EvolutionDecisionAction;
+  versionId: string;
+  extensionKey: string;
+  expectedSelection: string | null;
+  evaluationDigest: Digest | null;
+}
+
+/** Must be backed by trusted owner ingress, separate from CLI/MCP/model input. */
+export interface EvolutionOwnerVerifier {
+  verify(challenge: Readonly<OwnerDecisionChallenge>): Promise<{
+    verifierId: string;
+    challengeDigest: Digest;
+    evidenceDigest: Digest;
+  }>;
+}
+
+export interface EvolutionRegistryOptions {
+  adapter: DbAdapter;
+  suite: FixedEvaluationSuite;
+  evaluator: (version: Readonly<ExtensionVersion>, suite: Readonly<FixedEvaluationSuite>) => Promise<readonly EvaluationCaseEvidence[]>;
+  ownerVerifier: EvolutionOwnerVerifier;
+  now?: () => number;
+}
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const KEY = /^[a-z][a-z0-9._-]{0,63}$/u;
+const VERSION = /^extension:sha256:[0-9a-f]{64}$/u;
+const ATTEMPT = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/u;
+
+function invalid(message: string): never { throw new AgentFabricError("AF_INVALID_STATE", message); }
+function conflict(message: string): never { throw new AgentFabricError("AF_CONFLICT", message); }
+function validDigest(value: unknown): value is Digest { return typeof value === "string" && DIGEST.test(value); }
+function validTime(value: number): boolean { return Number.isSafeInteger(value) && value >= 0; }
+function versionIdFor(candidate: ExtensionCandidate): string {
+  return `extension:${digestCanonical(candidate, sha256Digest)}`;
+}
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_versions (
+    version_id TEXT PRIMARY KEY, extension_key TEXT NOT NULL,
+    artifact_digest TEXT NOT NULL, manifest_digest TEXT NOT NULL,
+    registered_at BIGINT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_evaluations (
+    version_id TEXT PRIMARY KEY, suite_id TEXT NOT NULL, suite_digest TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('running','passed','failed','inconclusive')),
+    cases_json TEXT NOT NULL, evidence_digest TEXT)`,
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_decisions (
+    decision_sequence BIGSERIAL PRIMARY KEY, version_id TEXT NOT NULL,
+    extension_key TEXT NOT NULL, action TEXT NOT NULL,
+    challenge_digest TEXT NOT NULL, owner_evidence_digest TEXT NOT NULL,
+    verifier_id TEXT NOT NULL, decided_at BIGINT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_selections (
+    extension_key TEXT NOT NULL, channel TEXT NOT NULL,
+    version_id TEXT, PRIMARY KEY (extension_key, channel))`,
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_revocations (
+    version_id TEXT PRIMARY KEY, decided_at BIGINT NOT NULL)`,
+  `CREATE TABLE IF NOT EXISTS _forge_fabric_extension_attempts (
+    attempt_id TEXT PRIMARY KEY, version_id TEXT NOT NULL,
+    extension_key TEXT NOT NULL, channel TEXT NOT NULL, bound_at BIGINT NOT NULL)`,
+] as const;
+
+/** Serialized single-owner PGlite registry. All state mutations commit before acknowledgement. */
+export class LocalEvolutionRegistry {
+  private schemaReady?: Promise<void>;
+  private tail: Promise<void> = Promise.resolve();
+  private readonly now: () => number;
+  private readonly suite: FixedEvaluationSuite;
+
+  constructor(private readonly options: EvolutionRegistryOptions) {
+    if (options.adapter.kind !== "pglite") invalid("Evolution registry requires local PGlite");
+    const suite = structuredClone(options.suite);
+    if (!KEY.test(suite.suiteId) || !validDigest(suite.suiteDigest) ||
+        suite.caseIds.length === 0 || suite.caseIds.length > 64 ||
+        new Set(suite.caseIds).size !== suite.caseIds.length ||
+        suite.caseIds.some((id) => !KEY.test(id)) ||
+        suite.suiteDigest !== digestCanonical({ suiteId: suite.suiteId, caseIds: suite.caseIds }, sha256Digest)) {
+      invalid("Invalid fixed evaluation suite");
+    }
+    this.suite = suite;
+    this.now = options.now ?? Date.now;
+  }
+
+  private async ready(): Promise<void> {
+    this.schemaReady ??= (async () => {
+      for (const statement of SCHEMA) await this.options.adapter.query(statement);
+    })();
+    await this.schemaReady;
+  }
+
+  private async serialized<T>(fn: () => Promise<T>): Promise<T> {
+    const previous = this.tail;
+    let release!: () => void;
+    this.tail = new Promise<void>((resolve) => { release = resolve; });
+    await previous;
+    try { await this.ready(); return await fn(); } finally { release(); }
+  }
+
+  private async transaction<T>(fn: (tx: DbTransaction) => Promise<T>): Promise<T> {
+    const tx = await this.options.adapter.begin();
+    try {
+      const result = await fn(tx);
+      await tx.commit();
+      return result;
+    } catch (error) {
+      await tx.rollback().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async register(candidate: ExtensionCandidate): Promise<ExtensionVersion> {
+    if (!candidate || !KEY.test(candidate.extensionKey) || !validDigest(candidate.artifactDigest) ||
+        !validDigest(candidate.manifestDigest)) invalid("Invalid extension candidate");
+    const exactCandidate: ExtensionCandidate = {
+      extensionKey: candidate.extensionKey,
+      artifactDigest: candidate.artifactDigest,
+      manifestDigest: candidate.manifestDigest,
+    };
+    const versionId = versionIdFor(exactCandidate);
+    const registeredAt = this.now();
+    if (!validTime(registeredAt)) invalid("Invalid registry time");
+    return this.serialized(async () => {
+      await this.options.adapter.query(
+        `INSERT INTO _forge_fabric_extension_versions
+         (version_id, extension_key, artifact_digest, manifest_digest, registered_at)
+         VALUES ($1,$2,$3,$4,$5) ON CONFLICT (version_id) DO NOTHING`,
+        [versionId, exactCandidate.extensionKey, exactCandidate.artifactDigest,
+          exactCandidate.manifestDigest, registeredAt],
+      );
+      return (await this.getVersion(versionId))!;
+    });
+  }
+
+  async getVersion(versionId: string): Promise<ExtensionVersion | null> {
+    if (!VERSION.test(versionId)) invalid("Invalid extension version ID");
+    await this.ready();
+    const rows = (await this.options.adapter.query(
+      `SELECT version_id, extension_key, artifact_digest, manifest_digest, registered_at
+       FROM _forge_fabric_extension_versions WHERE version_id=$1`, [versionId],
+    )).rows;
+    const row = rows[0];
+    if (!row) return null;
+    const candidate = {
+      extensionKey: row.extension_key as string,
+      artifactDigest: row.artifact_digest as Digest,
+      manifestDigest: row.manifest_digest as Digest,
+    };
+    const registeredAt = Number(row.registered_at);
+    if (!KEY.test(candidate.extensionKey) || !validDigest(candidate.artifactDigest) ||
+        !validDigest(candidate.manifestDigest) || !validTime(registeredAt) ||
+        versionIdFor(candidate) !== row.version_id) invalid("Stored extension version is inconsistent");
+    return { ...candidate, versionId, registeredAt };
+  }
+
+  async evaluate(versionId: string): Promise<EvaluationRecord> {
+    const version = await this.getVersion(versionId);
+    if (!version) throw new AgentFabricError("AF_NOT_FOUND", "Extension version not found");
+    const suite = this.suite;
+    await this.serialized(async () => {
+      await this.transaction(async (tx) => {
+        const existing = (await tx.query(
+          `SELECT version_id FROM _forge_fabric_extension_evaluations WHERE version_id=$1`, [versionId],
+        )).rows[0];
+        if (existing) conflict("Extension evaluation already started");
+        await tx.query(
+          `INSERT INTO _forge_fabric_extension_evaluations
+           (version_id,suite_id,suite_digest,state,cases_json,evidence_digest)
+           VALUES ($1,$2,$3,'running','[]',NULL)`, [versionId, suite.suiteId, suite.suiteDigest],
+        );
+      });
+    });
+    let cases: readonly EvaluationCaseEvidence[] = [];
+    let state: EvaluationRecord["state"] = "inconclusive";
+    try {
+      const result = await this.options.evaluator(structuredClone(version), structuredClone(suite));
+      if (result.length !== suite.caseIds.length || result.length > 64 ||
+          result.some((item, index) => !item || item.caseId !== suite.caseIds[index] ||
+            typeof item.passed !== "boolean" || !validDigest(item.evidenceDigest))) {
+        invalid("Evaluator returned evidence outside the fixed suite");
+      }
+      cases = structuredClone(result);
+      state = cases.every((item) => item.passed) ? "passed" : "failed";
+    } catch {
+      // An evaluator error is not evidence of a failed case. It remains inconclusive.
+    }
+    const evidenceDigest = state === "inconclusive" ? null : digestCanonical(
+      { versionId, suiteId: suite.suiteId, suiteDigest: suite.suiteDigest, cases }, sha256Digest,
+    );
+    await this.serialized(async () => {
+      const update = await this.options.adapter.query(
+        `UPDATE _forge_fabric_extension_evaluations
+         SET state=$2,cases_json=$3,evidence_digest=$4
+         WHERE version_id=$1 AND state='running'`,
+        [versionId, state, stableStringify(cases), evidenceDigest],
+      );
+      if (update.rowCount !== 1) conflict("Evaluation state changed before completion");
+    });
+    return { versionId, suiteId: suite.suiteId, suiteDigest: suite.suiteDigest, state, cases, evidenceDigest };
+  }
+
+  async getEvaluation(versionId: string): Promise<EvaluationRecord | null> {
+    if (!VERSION.test(versionId)) invalid("Invalid extension version ID");
+    await this.ready();
+    const row = (await this.options.adapter.query(
+      `SELECT suite_id,suite_digest,state,cases_json,evidence_digest
+       FROM _forge_fabric_extension_evaluations WHERE version_id=$1`, [versionId],
+    )).rows[0];
+    if (!row) return null;
+    let cases: EvaluationCaseEvidence[];
+    try { cases = JSON.parse(String(row.cases_json)) as EvaluationCaseEvidence[]; }
+    catch { return invalid("Stored evaluation is not JSON"); }
+    const state = row.state as EvaluationRecord["state"];
+    const suite = this.suite;
+    if (row.suite_id !== suite.suiteId || row.suite_digest !== suite.suiteDigest ||
+        !["running", "passed", "failed", "inconclusive"].includes(state) ||
+        !Array.isArray(cases) ||
+        (state === "running" || state === "inconclusive" ? cases.length !== 0 || row.evidence_digest !== null :
+          cases.length !== suite.caseIds.length || cases.some((item, index) =>
+            item?.caseId !== suite.caseIds[index] || typeof item.passed !== "boolean" ||
+            !validDigest(item.evidenceDigest)) ||
+          (state === "passed") !== cases.every((item) => item.passed) ||
+          row.evidence_digest !== digestCanonical(
+            { versionId, suiteId: suite.suiteId, suiteDigest: suite.suiteDigest, cases }, sha256Digest,
+          ))) invalid("Stored evaluation evidence is inconsistent");
+    return { versionId, suiteId: suite.suiteId, suiteDigest: suite.suiteDigest, state,
+      cases, evidenceDigest: row.evidence_digest as Digest | null };
+  }
+
+  async selected(extensionKey: string, channel: EvolutionChannel): Promise<string | null> {
+    if (!KEY.test(extensionKey) || !["canary", "stable"].includes(channel)) invalid("Invalid selection query");
+    await this.ready();
+    const row = (await this.options.adapter.query(
+      `SELECT version_id FROM _forge_fabric_extension_selections WHERE extension_key=$1 AND channel=$2`,
+      [extensionKey, channel],
+    )).rows[0];
+    const versionId = row?.version_id as string | null ?? null;
+    if (versionId && (await this.options.adapter.query(
+      `SELECT version_id FROM _forge_fabric_extension_revocations WHERE version_id=$1`, [versionId],
+    )).rows.length > 0) invalid("Selected extension is revoked");
+    return versionId;
+  }
+
+  /** Bounded owner status for one immutable version; no artifact bytes or decision secrets. */
+  async status(versionId: string): Promise<EvolutionVersionStatus | null> {
+    const version = await this.getVersion(versionId);
+    if (!version) return null;
+    const [evaluation, revokedRows, selectionRows, decisionRows] = await Promise.all([
+      this.getEvaluation(versionId),
+      this.options.adapter.query(`SELECT version_id FROM _forge_fabric_extension_revocations WHERE version_id=$1`, [versionId]),
+      this.options.adapter.query(`SELECT channel FROM _forge_fabric_extension_selections WHERE extension_key=$1 AND version_id=$2`,
+        [version.extensionKey, versionId]),
+      this.options.adapter.query(`SELECT action,decided_at,verifier_id FROM _forge_fabric_extension_decisions
+        WHERE version_id=$1 ORDER BY decision_sequence DESC LIMIT 1`, [versionId]),
+    ]);
+    const channels = selectionRows.rows.map((row) => row.channel as EvolutionChannel);
+    if (channels.some((channel) => channel !== "canary" && channel !== "stable")) invalid("Stored channel is inconsistent");
+    const last = decisionRows.rows[0];
+    return { version, evaluation, revoked: revokedRows.rows.length > 0, channels,
+      lastDecision: last ? { action: last.action as EvolutionDecisionAction,
+        decidedAt: Number(last.decided_at), verifierId: String(last.verifier_id) } : null };
+  }
+
+  async decide(action: EvolutionDecisionAction, versionId: string, expectedSelection: string | null): Promise<void> {
+    if (!["canary", "promote", "rollback", "revoke"].includes(action) || !VERSION.test(versionId) ||
+        (expectedSelection !== null && !VERSION.test(expectedSelection))) invalid("Invalid evolution decision");
+    const version = await this.getVersion(versionId);
+    if (!version) throw new AgentFabricError("AF_NOT_FOUND", "Extension version not found");
+    const channel: EvolutionChannel = action === "canary" ? "canary" : "stable";
+    const evaluation = await this.getEvaluation(versionId);
+    if (action !== "revoke" && evaluation?.state !== "passed") {
+      conflict("Passing fixed-suite evaluation is required for selection");
+    }
+    const challenge: OwnerDecisionChallenge = {
+      decisionNonce: randomUUID(),
+      action, versionId, extensionKey: version.extensionKey, expectedSelection,
+      evaluationDigest: evaluation?.evidenceDigest ?? null,
+    };
+    const proof = await this.options.ownerVerifier.verify(structuredClone(challenge));
+    const challengeDigest = digestCanonical(challenge, sha256Digest);
+    if (!proof || !KEY.test(proof.verifierId) || proof.challengeDigest !== challengeDigest ||
+        !validDigest(proof.evidenceDigest)) invalid("Trusted owner verification did not bind this decision");
+    const decidedAt = this.now();
+    if (!validTime(decidedAt)) invalid("Invalid registry time");
+    await this.serialized(async () => this.transaction(async (tx) => {
+      const current = (await tx.query(
+        `SELECT version_id FROM _forge_fabric_extension_selections WHERE extension_key=$1 AND channel=$2`,
+        [version.extensionKey, channel],
+      )).rows[0]?.version_id as string | null ?? null;
+      if (current !== expectedSelection) conflict("Selection changed before owner decision");
+      const revoked = (await tx.query(
+        `SELECT version_id FROM _forge_fabric_extension_revocations WHERE version_id=$1`, [versionId],
+      )).rows.length > 0;
+      if (revoked) conflict("Revoked extension cannot be selected or decided again");
+      if (action !== "revoke") {
+        const storedEvaluation = (await tx.query(
+          `SELECT state,evidence_digest FROM _forge_fabric_extension_evaluations WHERE version_id=$1`,
+          [versionId],
+        )).rows[0];
+        if (storedEvaluation?.state !== "passed" ||
+            storedEvaluation.evidence_digest !== challenge.evaluationDigest) {
+          conflict("Passing fixed-suite evaluation is required for selection");
+        }
+        if (action === "rollback" && (await tx.query(
+          `SELECT version_id FROM _forge_fabric_extension_decisions
+           WHERE version_id=$1 AND action IN ('promote','rollback') LIMIT 1`, [versionId],
+        )).rows.length === 0) conflict("Rollback target was never a stable version");
+      }
+      await tx.query(
+        `INSERT INTO _forge_fabric_extension_decisions
+         (version_id,extension_key,action,challenge_digest,owner_evidence_digest,verifier_id,decided_at)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)`,
+        [versionId, version.extensionKey, action, challengeDigest, proof.evidenceDigest, proof.verifierId, decidedAt],
+      );
+      if (action === "revoke") {
+        await tx.query(`INSERT INTO _forge_fabric_extension_revocations (version_id,decided_at) VALUES ($1,$2)`,
+          [versionId, decidedAt]);
+        await tx.query(
+          `UPDATE _forge_fabric_extension_selections SET version_id=NULL
+           WHERE extension_key=$1 AND version_id=$2`, [version.extensionKey, versionId],
+        );
+      } else {
+        await tx.query(
+          `INSERT INTO _forge_fabric_extension_selections (extension_key,channel,version_id)
+           VALUES ($1,$2,$3) ON CONFLICT (extension_key,channel)
+           DO UPDATE SET version_id=EXCLUDED.version_id`,
+          [version.extensionKey, channel, versionId],
+        );
+      }
+    }));
+  }
+
+  async bindAttempt(attemptId: string, extensionKey: string, channel: EvolutionChannel): Promise<{
+    attemptId: string; versionId: string; extensionKey: string; channel: EvolutionChannel;
+  }> {
+    if (!ATTEMPT.test(attemptId) || !KEY.test(extensionKey) || !["canary", "stable"].includes(channel)) {
+      invalid("Invalid attempt binding");
+    }
+    const boundAt = this.now();
+    if (!validTime(boundAt)) invalid("Invalid registry time");
+    return this.serialized(async () => this.transaction(async (tx) => {
+      const old = (await tx.query(
+        `SELECT version_id,extension_key,channel FROM _forge_fabric_extension_attempts WHERE attempt_id=$1`, [attemptId],
+      )).rows[0];
+      if (old) {
+        conflict("Attempt is already bound; read its existing version instead of dispatching again");
+      }
+      const versionId = (await tx.query(
+        `SELECT version_id FROM _forge_fabric_extension_selections WHERE extension_key=$1 AND channel=$2`,
+        [extensionKey, channel],
+      )).rows[0]?.version_id as string | null;
+      if (!versionId) conflict("No extension selected on this channel");
+      if ((await tx.query(
+        `SELECT version_id FROM _forge_fabric_extension_revocations WHERE version_id=$1`, [versionId],
+      )).rows.length > 0) conflict("Revoked extension cannot be selected");
+      await tx.query(
+        `INSERT INTO _forge_fabric_extension_attempts
+         (attempt_id,version_id,extension_key,channel,bound_at) VALUES ($1,$2,$3,$4,$5)`,
+        [attemptId, versionId, extensionKey, channel, boundAt],
+      );
+      return { attemptId, versionId, extensionKey, channel };
+    }));
+  }
+
+  async getAttempt(attemptId: string): Promise<{ attemptId: string; versionId: string;
+    extensionKey: string; channel: EvolutionChannel } | null> {
+    if (!ATTEMPT.test(attemptId)) invalid("Invalid attempt identity");
+    await this.ready();
+    const row = (await this.options.adapter.query(
+      `SELECT version_id,extension_key,channel FROM _forge_fabric_extension_attempts WHERE attempt_id=$1`,
+      [attemptId],
+    )).rows[0];
+    if (!row) return null;
+    return { attemptId, versionId: row.version_id as string,
+      extensionKey: row.extension_key as string, channel: row.channel as EvolutionChannel };
+  }
+}

package/src/forge/agent-fabric/local-evolution-service.ts

@@ -0,0 +1,200 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createPgliteAdapter } from "../runtime/db/pglite-adapter.ts";
+import type { DbAdapter } from "../runtime/db/adapter.ts";
+import { digestCanonical, sha256Digest } from "./canonical.ts";
+import { AgentFabricError } from "./errors.ts";
+import { localEvolutionOwnerVerifier } from "./local-evolution-approval.ts";
+import { LOCAL_ADAPTIVE_EXTENSION_KEY, assertLocalAdaptiveInputs,
+  evaluateLocalAdaptiveProfile, parseLocalAdaptiveInputProfile } from "./local-evolution-profile.ts";
+import { LocalEvolutionRegistry, type EvolutionChannel, type EvolutionDecisionAction,
+  type EvolutionOwnerVerifier, type EvolutionVersionStatus, type FixedEvaluationSuite } from "./local-evolution-registry.ts";
+import { localFabricPath } from "./local-paths.ts";
+import type { Digest } from "./types.ts";
+
+const MAX_MANIFEST = 16 * 1024;
+const MAX_ARTIFACT = 1024 * 1024;
+const suiteId = "local-adaptive-input-profile-v1";
+const caseIds = ["artifact-integrity", "manifest-integrity", "manifest-contract",
+  "profile-contract", "accept-valid-input", "reject-wrong-label", "reject-over-limit"] as const;
+export const LOCAL_EVOLUTION_SUITE: FixedEvaluationSuite = {
+  suiteId, caseIds, suiteDigest: digestCanonical({ suiteId, caseIds }, sha256Digest),
+};
+
+interface ExtensionManifest {
+  schemaVersion: 1;
+  extensionKey: string;
+  artifactPath: string;
+}
+
+function invalid(message: string): never { throw new AgentFabricError("AF_INVALID_STATE", message); }
+function digest(bytes: Buffer): Digest { return `sha256:${createHash("sha256").update(bytes).digest("hex")}`; }
+function strictManifest(bytes: Buffer): ExtensionManifest {
+  let value: unknown;
+  try { value = JSON.parse(bytes.toString("utf8")); } catch { return invalid("Extension manifest is invalid JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid("Extension manifest must be an object");
+  const item = value as Partial<ExtensionManifest>;
+  if (Object.keys(item).sort().join(",") !== "artifactPath,extensionKey,schemaVersion" ||
+      item.schemaVersion !== 1 || typeof item.extensionKey !== "string" || item.extensionKey !== LOCAL_ADAPTIVE_EXTENSION_KEY ||
+      typeof item.artifactPath !== "string" || !/^[A-Za-z0-9_./-]{1,256}$/u.test(item.artifactPath) ||
+      item.artifactPath.split("/").some((part) => part === ".." || part === "." || part === "") ||
+      !item.artifactPath.endsWith(".json")) {
+    invalid("Extension manifest is outside the local v1 contract");
+  }
+  return item as ExtensionManifest;
+}
+
+function readBounded(path: string, max: number): Buffer {
+  const size = statSync(path).size;
+  if (!Number.isSafeInteger(size) || size < 1 || size > max || !statSync(path).isFile()) invalid("Extension file size or type is invalid");
+  const bytes = readFileSync(path);
+  if (bytes.length !== size) invalid("Extension file changed during read");
+  return bytes;
+}
+
+function sourcePath(root: string, path: string): string {
+  const full = realpathSync(resolve(root, path));
+  const rel = relative(root, full);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) invalid("Extension source must be inside this repository");
+  return full;
+}
+
+function storedPath(root: string, kind: "artifact" | "manifest", digestValue: Digest): string {
+  if (!/^sha256:[0-9a-f]{64}$/u.test(digestValue)) invalid("Invalid stored extension digest");
+  return localFabricPath(root, "evolution", kind === "artifact" ? "artifacts" : "manifests", `${digestValue.slice(7)}.${kind === "artifact" ? "bin" : "json"}`);
+}
+
+function store(root: string, kind: "artifact" | "manifest", bytes: Buffer): Digest {
+  const value = digest(bytes);
+  const path = storedPath(root, kind, value);
+  mkdirSync(dirname(path), { recursive: true });
+  if (!existsSync(path)) {
+    try { writeFileSync(path, bytes, { flag: "wx", mode: 0o600 }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+  }
+  if (!readBounded(path, kind === "artifact" ? MAX_ARTIFACT : MAX_MANIFEST).equals(bytes)) {
+    invalid("Stored immutable extension bytes differ from candidate");
+  }
+  return value;
+}
+
+export class LocalEvolutionService {
+  private constructor(readonly repositoryRoot: string, private readonly adapter: DbAdapter,
+    readonly registry: LocalEvolutionRegistry) {}
+
+  static async open(repositoryRoot: string, ownerVerifier: EvolutionOwnerVerifier = localEvolutionOwnerVerifier()): Promise<LocalEvolutionService> {
+    const root = realpathSync(repositoryRoot);
+    const adapter = await createPgliteAdapter(localFabricPath(root, "evolution", "pglite"));
+    const evaluator = async (version: { artifactDigest: Digest; manifestDigest: Digest; extensionKey: string }) => {
+      let artifact: Buffer | null = null;
+      let manifest: Buffer | null = null;
+      try { artifact = readBounded(storedPath(root, "artifact", version.artifactDigest), MAX_ARTIFACT); } catch { /* fixed case fails */ }
+      try { manifest = readBounded(storedPath(root, "manifest", version.manifestDigest), MAX_MANIFEST); } catch { /* fixed case fails */ }
+      const artifactObserved = artifact ? digest(artifact) : sha256Digest("missing-artifact");
+      const manifestObserved = manifest ? digest(manifest) : sha256Digest("missing-manifest");
+      let contract = false;
+      if (manifest) {
+        try { contract = strictManifest(manifest).extensionKey === version.extensionKey; } catch { /* fixed case fails */ }
+      }
+      const profile = artifact ? evaluateLocalAdaptiveProfile(artifact) :
+        { contract: false, acceptsValid: false, rejectsWrongLabel: false, rejectsOverLimit: false };
+      return [
+        { caseId: caseIds[0], passed: artifactObserved === version.artifactDigest, evidenceDigest: artifactObserved },
+        { caseId: caseIds[1], passed: manifestObserved === version.manifestDigest, evidenceDigest: manifestObserved },
+        { caseId: caseIds[2], passed: contract, evidenceDigest: digestCanonical({ manifestDigest: manifestObserved, extensionKey: version.extensionKey, contract }, sha256Digest) },
+        ...([
+          ["profile-contract", profile.contract],
+          ["accept-valid-input", profile.acceptsValid],
+          ["reject-wrong-label", profile.rejectsWrongLabel],
+          ["reject-over-limit", profile.rejectsOverLimit],
+        ] as const).map(([caseId, passed]) => ({
+          caseId, passed, evidenceDigest: digestCanonical({ artifactDigest: artifactObserved, caseId, passed }, sha256Digest),
+        })),
+      ];
+    };
+    try { return new LocalEvolutionService(root, adapter, new LocalEvolutionRegistry({
+      adapter, suite: LOCAL_EVOLUTION_SUITE, evaluator, ownerVerifier,
+    })); } catch (error) { await adapter.close(); throw error; }
+  }
+
+  async close(): Promise<void> { await this.adapter.close(); }
+
+  async register(manifestPath: string): Promise<EvolutionVersionStatus> {
+    const manifest = readBounded(sourcePath(this.repositoryRoot, manifestPath), MAX_MANIFEST);
+    const parsed = strictManifest(manifest);
+    const artifact = readBounded(sourcePath(this.repositoryRoot, parsed.artifactPath), MAX_ARTIFACT);
+    const artifactDigest = store(this.repositoryRoot, "artifact", artifact);
+    const manifestDigest = store(this.repositoryRoot, "manifest", manifest);
+    const version = await this.registry.register({ extensionKey: parsed.extensionKey, artifactDigest, manifestDigest });
+    return (await this.registry.status(version.versionId))!;
+  }
+
+  async status(versionId: string): Promise<EvolutionVersionStatus> {
+    const result = await this.registry.status(versionId);
+    if (!result) throw new AgentFabricError("AF_NOT_FOUND", "Extension version not found");
+    return result;
+  }
+
+  async evaluate(versionId: string): Promise<EvolutionVersionStatus> {
+    await this.registry.evaluate(versionId);
+    return this.status(versionId);
+  }
+
+  async decide(action: EvolutionDecisionAction, versionId: string): Promise<EvolutionVersionStatus> {
+    // Adaptive execution holds this same lock from profile readback through worker
+    // dispatch. A concurrent promotion or revocation must not pass between those
+    // two operations and silently change what the owner approved.
+    const lockPath = localFabricPath(this.repositoryRoot, "adaptive-lock");
+    let descriptor: number;
+    try { descriptor = openSync(lockPath, "wx", 0o600); }
+    catch { throw new AgentFabricError("AF_CONFLICT", "Adaptive owner is busy; inspect adaptive status before changing its profile"); }
+    try {
+      const before = await this.status(versionId);
+      const channel: EvolutionChannel = action === "canary" ? "canary" : "stable";
+      const expected = await this.registry.selected(before.version.extensionKey, channel);
+      await this.registry.decide(action, versionId, expected);
+      return this.status(versionId);
+    } finally { closeSync(descriptor); unlinkSync(lockPath); }
+  }
+
+  /** Loading returns verified bytes only for the currently selected, evaluated, non-revoked version. */
+  async loadSelected(extensionKey: string, channel: EvolutionChannel): Promise<{
+    versionId: string; artifact: Buffer; manifest: ExtensionManifest;
+  }> {
+    const versionId = await this.registry.selected(extensionKey, channel);
+    if (!versionId) throw new AgentFabricError("AF_CONFLICT", "No selected extension version on this channel");
+    const status = await this.status(versionId);
+    if (status.revoked || !status.channels.includes(channel) || status.evaluation?.state !== "passed" ||
+        status.evaluation.suiteDigest !== LOCAL_EVOLUTION_SUITE.suiteDigest) {
+      throw new AgentFabricError("AF_CONFLICT", "Extension version is not loadable");
+    }
+    const artifact = readBounded(storedPath(this.repositoryRoot, "artifact", status.version.artifactDigest), MAX_ARTIFACT);
+    const manifestBytes = readBounded(storedPath(this.repositoryRoot, "manifest", status.version.manifestDigest), MAX_MANIFEST);
+    if (digest(artifact) !== status.version.artifactDigest || digest(manifestBytes) !== status.version.manifestDigest) {
+      invalid("Stored immutable extension bytes changed");
+    }
+    const manifest = strictManifest(manifestBytes);
+    if (manifest.extensionKey !== extensionKey) invalid("Stored extension manifest key changed");
+    // Guard a revocation racing with a file read before handing bytes to the caller.
+    if (await this.registry.selected(extensionKey, channel) !== versionId) {
+      throw new AgentFabricError("AF_CONFLICT", "Extension selection changed during load");
+    }
+    return { versionId, artifact, manifest };
+  }
+
+  /** Bind one attempt to the selected immutable profile and narrow only its input data. */
+  async resolveSelectedLocalAdaptiveInputs(channel: EvolutionChannel, attemptId: string,
+    inventory: string, constraints: string): Promise<{
+    versionId: string; inventory: string; constraints: string;
+  }> {
+    const loaded = await this.loadSelected(LOCAL_ADAPTIVE_EXTENSION_KEY, channel);
+    const profile = parseLocalAdaptiveInputProfile(loaded.artifact);
+    assertLocalAdaptiveInputs(profile, inventory, constraints);
+    const binding = await this.registry.bindAttempt(attemptId, LOCAL_ADAPTIVE_EXTENSION_KEY, channel);
+    if (binding.versionId !== loaded.versionId) {
+      throw new AgentFabricError("AF_CONFLICT", "Selected profile changed before attempt binding");
+    }
+    return { versionId: binding.versionId, inventory, constraints };
+  }
+}