@open-everywhere/core 0.1.0

package/agent/lib/process-registry.ts

@@ -0,0 +1,52 @@
+// process-registry — one shared store per registration seam, keyed by a `Symbol.for` on
+// `globalThis` so it survives this package being LOADED TWICE in one process.
+//
+// WHY THIS EXISTS (OPE-406). A registration seam has two halves that must meet: a writer
+// (`registerXProvider()` at boot, or a test stub) and a reader (the runtime resolution that
+// fails closed when nothing is registered). Both halves address the seam by importing the same
+// core module — which is an identity, not a path. Two things break that identity:
+//
+//   1. In-repo, since `exports` points at `dist/`, a file importing `@open-everywhere/core/...`
+//      and a file importing `../agent/...` load DIFFERENT copies of the same module. Root
+//      `scripts/` composition tests are in the first world, `packages/core/scripts/` tests in the
+//      second, and shared test stubs serve both.
+//   2. For consumers, an npm dedupe failure (two paths to core in one tree) does the same thing.
+//
+// The failure mode is what makes this worth a shared mechanism rather than a fix per site: these
+// registries are FAIL-CLOSED BY OMISSION, so a split does not throw. The writer registers into one
+// copy, the reader finds an empty registry in the other, and the system quietly behaves as if the
+// platform were not installed — replies drop, trust fails closed, a mapper's verdict vanishes. A
+// loud error would have been kinder.
+//
+// SCOPE — deliberately not applied to all ~80 register* seams in core. It belongs on the seams a
+// PROVIDER or app-boot populates and a runtime path reads, where the split is both plausible and
+// silent. A module-private map is still the right default for anything a single module owns.
+//
+// VERSION SAFETY: the key carries a version suffix (`.v1`). Two different core versions sharing one
+// process get the same store only while they agree on the shape; any change to a registered value's
+// contract must bump the suffix, exactly as a stored-data format change would.
+
+/** Fetch (or create) the process-wide `Map` for a registration seam. */
+export function processRegistryMap<V>(name: string): Map<string, V> {
+  const key = Symbol.for(`open-everywhere.${name}`);
+  const g = globalThis as { [k: symbol]: unknown };
+  const existing = g[key];
+  if (existing instanceof Map) return existing as Map<string, V>;
+  const fresh = new Map<string, V>();
+  g[key] = fresh;
+  return fresh;
+}
+
+/** A single mutable slot (the one-value seams: a bridge, a client) shared process-wide. */
+export function processRegistrySlot<V>(name: string): { get(): V | null; set(value: V | null): void } {
+  const key = Symbol.for(`open-everywhere.${name}`);
+  const g = globalThis as { [k: symbol]: unknown };
+  if (!(g[key] instanceof Object) || !("oeSlot" in (g[key] as object))) g[key] = { oeSlot: null as V | null };
+  const box = g[key] as { oeSlot: V | null };
+  return {
+    get: () => box.oeSlot,
+    set: (value: V | null) => {
+      box.oeSlot = value;
+    },
+  };
+}

package/agent/memory/agents-codemod.ts

@@ -0,0 +1,443 @@
+// The only module that edits the agents overlay (`agents.generated.ts`): it derives one domain, at most one silo, one bundle and one domain-scoped binding from a frozen AgentSpec by pure structural transformation, so the same inputs give byte-identical output.
+// An EXPOSED agent must stay curated read-only: `assertExposedAgentSpec` guards the input and `assertExposedAgentsCurated` re-checks the merged config.
+
+import { connectorGrantName } from "../access/bundle.js";
+import type { Binding, Bundle, Scope } from "../access/bundle.js";
+import { overlayModuleHeader, unwrapOverlayModule, wrapOverlayModule, type OverlayModuleGrammar } from "../access/overlay-module.js";
+import type { Domain } from "./domain.js";
+import { memoryRefs } from "./domain.js";
+import type { MemorySilo } from "./silo.js";
+import type { MemorySelection } from "./selection.js";
+
+export type AgentMemory =
+  | { readonly kind: "existing-silo"; readonly silo: string }
+  /** Materialise a NEW, READ-ONLY curated silo — the exposed-agent-safe path. */
+  | {
+      readonly kind: "new-readonly";
+      readonly provider: string;
+      readonly container?: string;
+      readonly path?: string;
+      readonly select?: MemorySelection;
+      readonly skill?: string;
+    };
+
+export interface AgentSpec {
+  readonly name: string;
+  readonly title?: string;
+  /** Fully-qualified surface keys (`platform/workspace/surface`) — the derived domain's roster. */
+  readonly channels: readonly string[];
+  readonly memory: AgentMemory;
+  /** `contentOrigin` is deliberately absent: it is an operator assertion, and no codemod may write one. */
+  readonly connectors?: readonly { readonly name: string; readonly credential: string }[];
+  readonly instructions?: string;
+  /** Exposed to a wider/less-trusted audience → curated read-only only (see the exposure invariant). */
+  readonly exposed?: boolean;
+}
+
+/** The overlay is data-only. The `specs` side-table carries the frozen specs so the config-load exposure guard can tell which domains were born exposed; a `Domain` has no `exposed` field. */
+export interface AgentsFile {
+  readonly domains: readonly Domain[];
+  readonly silos: readonly MemorySilo[];
+  readonly bundles: readonly Bundle[];
+  readonly bindings: readonly Binding[];
+  readonly specs: readonly AgentSpec[];
+}
+
+/** A codemod refusal — invalid file, invalid spec, or an invariant breach. Distinct type so callers
+ *  can tell "refused by design" from an unexpected failure (mirrors GrantsCodemodError). */
+export class AgentsCodemodError extends Error {}
+
+export function emptyAgentsFile(): AgentsFile {
+  return { domains: [], silos: [], bundles: [], bindings: [], specs: [] };
+}
+
+export function agentSiloName(spec: AgentSpec): string {
+  return spec.memory.kind === "existing-silo" ? spec.memory.silo : `${spec.name}-silo`;
+}
+
+/** The `agent:` prefix namespaces an overlay bundle away from code bundles and from the grants overlay's `grants:` bundles, so a collision is impossible to miss. */
+export function agentBundleName(spec: AgentSpec | { readonly name: string }): string {
+  return `agent:${spec.name}`;
+}
+
+/**
+ * INPUT-time guard: an exposed spec may only reach a READ-ONLY silo. `new-readonly` memory is read-only by construction; an `existing-silo` reference must resolve through `resolveSilo` and be `readOnly: true`.
+ * A writable or unresolvable target throws.
+ */
+export function assertExposedAgentSpec(spec: AgentSpec, resolveSilo?: (name: string) => MemorySilo | undefined): void {
+  if (!spec.exposed) return;
+  if (spec.memory.kind === "new-readonly") return; // curated read-only by construction — the safe path
+  const name = spec.memory.silo;
+  const silo = resolveSilo?.(name);
+  if (!silo) {
+    throw new AgentsCodemodError(
+      `exposed agent "${spec.name}" references existing silo "${name}", but it cannot be resolved to confirm it is read-only — an exposed agent may only read a curated READ-ONLY silo (pass the merged silo set, or use a { kind: "new-readonly" } silo)`,
+    );
+  }
+  if (silo.readOnly !== true) {
+    throw new AgentsCodemodError(
+      `exposed agent "${spec.name}" reads silo "${name}", which is WRITABLE — an exposed agent may only read a curated READ-ONLY silo (mark the silo readOnly, or give the agent its own { kind: "new-readonly" } silo)`,
+    );
+  }
+}
+
+/**
+ * CONFIG-LOAD guard over the MERGED domains and silos: every exposed spec's domain must have no `match`, no `includeOrg`, and only read-only silos.
+ * Throws with every problem listed.
+ */
+export function assertExposedAgentsCurated(
+  domains: readonly Domain[],
+  silos: readonly MemorySilo[],
+  specs: readonly AgentSpec[],
+): void {
+  const domainByName = new Map(domains.map((d) => [d.name, d]));
+  const siloByName = new Map(silos.map((s) => [s.name, s]));
+  const bad: string[] = [];
+  for (const spec of specs) {
+    if (!spec.exposed) continue;
+    const domain = domainByName.get(spec.name);
+    if (!domain) {
+      bad.push(`  exposed agent "${spec.name}" has no merged domain — the overlay derived one, so a missing domain means the merge dropped it`);
+      continue;
+    }
+    if (domain.match !== undefined) {
+      bad.push(`  exposed agent "${spec.name}" resolves to a criteria (match "${domain.match}") domain — an exposed agent must be a domain with a reach, never a pseudo-domain`);
+    }
+    if (domain.includeOrg !== undefined) {
+      bad.push(`  exposed agent "${spec.name}" sets includeOrg "${domain.includeOrg}" — an exposed agent may not inherit the org brain (that would leak internal memory to a wider audience)`);
+    }
+    for (const ref of memoryRefs(domain)) {
+      const silo = siloByName.get(ref);
+      if (!silo) {
+        bad.push(`  exposed agent "${spec.name}" references silo "${ref}", which is not in the merged silo set`);
+      } else if (silo.readOnly !== true) {
+        bad.push(`  exposed agent "${spec.name}" reads WRITABLE silo "${ref}" — an exposed agent may only read curated read-only silos`);
+      }
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      "open-everywhere: exposed agent(s) violate the curated-read-only invariant:\n" +
+        bad.join("\n") +
+        "\n(memory/agents-codemod.ts assertExposedAgentsCurated / create_agent flow).",
+    );
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+/** `{ name, credential }` objects and nothing else: `credential` is a choice the requester made at propose time, and `contentOrigin` is an operator assertion no codemod may invent. */
+function assertAgentConnectorGrants(what: string, value: unknown): void {
+  if (!Array.isArray(value)) throw new AgentsCodemodError(`${what} connectors must be an array`);
+  for (const g of value) {
+    if (!isRecord(g) || typeof g.name !== "string" || !g.name || typeof g.credential !== "string" || !g.credential) {
+      throw new AgentsCodemodError(`${what} has a malformed connector grant — the overlay writes { name, credential } objects (got: ${JSON.stringify(g)})`);
+    }
+    const extra = Object.keys(g).filter((k) => k !== "name" && k !== "credential");
+    if (extra.length > 0) {
+      throw new AgentsCodemodError(
+        `${what} connector grant "${g.name}" carries field(s) ${extra.join(", ")} — the overlay writes only { name, credential } (a \`contentOrigin\` declaration is an operator assertion; put it in a code bundle)`,
+      );
+    }
+  }
+}
+
+/** The exact set of keys each emitted shape may carry — anything else is a hand-edit gone wrong. */
+const DOMAIN_FIELDS = new Set(["name", "title", "reach", "memory"]);
+const SILO_FIELDS = new Set(["name", "description", "provider", "container", "path", "readOnly", "skill", "recursive", "select"]);
+const BUNDLE_FIELDS = new Set(["name", "title", "connectors", "instructions"]);
+const BINDING_FIELDS = new Set(["bundle", "scope"]);
+const SPEC_FIELDS = new Set(["name", "title", "channels", "memory", "connectors", "instructions", "exposed"]);
+
+function refuseUnknownFields(what: string, obj: Record<string, unknown>, allowed: Set<string>): void {
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new AgentsCodemodError(`${what} has field "${k}" — the agents overlay is machine-owned and carries only its emitted fields (put anything else in code config)`);
+    }
+  }
+}
+
+/**
+ * STRICT and fail-loud: unknown keys, a non-`agent:` bundle name and a non-domain-scoped binding all throw, because the overlay is machine-written and a silently mis-parsed agents file is the security bug.
+ * Deep semantic validation stays with the load-time asserts on the merged config.
+ */
+export function parseAgentsFile(value: unknown): AgentsFile {
+  if (!isRecord(value)) throw new AgentsCodemodError("agents file must be a JSON object with domains/silos/bundles/bindings/specs arrays");
+  const keys = Object.keys(value).filter((k) => k !== "$comment");
+  const unknown = keys.filter((k) => !["domains", "silos", "bundles", "bindings", "specs"].includes(k));
+  if (unknown.length > 0) throw new AgentsCodemodError(`agents file has unknown top-level key(s): ${unknown.join(", ")}`);
+  for (const arr of ["domains", "silos", "bundles", "bindings", "specs"] as const) {
+    if (!Array.isArray(value[arr])) throw new AgentsCodemodError(`agents file needs a \`${arr}\` array (use [] when empty)`);
+  }
+
+  const domains: Domain[] = [];
+  for (const d of value.domains as unknown[]) {
+    if (!isRecord(d) || typeof d.name !== "string" || d.name.length === 0) {
+      throw new AgentsCodemodError(`every agents domain needs a name (got: ${JSON.stringify(d)})`);
+    }
+    if (d.channels !== undefined && d.reach === undefined) {
+      throw new AgentsCodemodError(
+        `agents domain "${String(d.name)}" carries \`channels\`, which OPE-254 replaced with \`reach\` — one list holding exact keys and containers alike. The overlay is machine-owned, so rename that key in agent/memory/config/agents.generated.ts (the values are unchanged) or regenerate the file.`,
+      );
+    }
+    refuseUnknownFields(`agents domain "${String(d.name)}"`, d, DOMAIN_FIELDS);
+    if (d.reach !== undefined && !isStringArray(d.reach)) throw new AgentsCodemodError(`agents domain "${d.name}" reach must be a string array`);
+    if (d.memory !== undefined && typeof d.memory !== "string" && !isStringArray(d.memory)) {
+      throw new AgentsCodemodError(`agents domain "${d.name}" memory must be a silo name or a list of silo names`);
+    }
+    domains.push(d as unknown as Domain);
+  }
+
+  const silos: MemorySilo[] = [];
+  for (const s of value.silos as unknown[]) {
+    if (!isRecord(s) || typeof s.name !== "string" || s.name.length === 0 || typeof s.provider !== "string" || s.provider.length === 0) {
+      throw new AgentsCodemodError(`every agents silo needs a name and a provider (got: ${JSON.stringify(s)})`);
+    }
+    refuseUnknownFields(`agents silo "${String(s.name)}"`, s, SILO_FIELDS);
+    silos.push(s as unknown as MemorySilo);
+  }
+
+  const bundles: Bundle[] = [];
+  for (const b of value.bundles as unknown[]) {
+    if (!isRecord(b) || typeof b.name !== "string" || !b.name.startsWith("agent:")) {
+      throw new AgentsCodemodError(`every agents bundle needs an "agent:"-prefixed name (got: ${JSON.stringify(isRecord(b) ? b.name : b)})`);
+    }
+    refuseUnknownFields(`agents bundle "${b.name}"`, b, BUNDLE_FIELDS);
+    if (b.connectors !== undefined) assertAgentConnectorGrants(`agents bundle "${b.name}"`, b.connectors);
+    if (b.instructions !== undefined && typeof b.instructions !== "string") throw new AgentsCodemodError(`agents bundle "${b.name}" instructions must be a string`);
+    bundles.push(b as unknown as Bundle);
+  }
+
+  const bindings: Binding[] = [];
+  for (const bd of value.bindings as unknown[]) {
+    if (!isRecord(bd) || typeof bd.bundle !== "string" || !bd.bundle.startsWith("agent:") || !isRecord(bd.scope)) {
+      throw new AgentsCodemodError(`every agents binding needs { bundle: "agent:…", scope } (got: ${JSON.stringify(bd)})`);
+    }
+    refuseUnknownFields(`agents binding "${bd.bundle}"`, bd, BINDING_FIELDS);
+    const scope = bd.scope as Record<string, unknown>;
+    if (scope.level !== "domain" || typeof scope.domain !== "string" || scope.domain.includes("/")) {
+      throw new AgentsCodemodError(`agents binding for "${bd.bundle}" must be domain-scoped with a bare domain name ({ level: "domain", domain: "<name>" })`);
+    }
+    bindings.push(bd as unknown as Binding);
+  }
+
+  const specs: AgentSpec[] = [];
+  for (const sp of value.specs as unknown[]) {
+    if (!isRecord(sp) || typeof sp.name !== "string" || sp.name.length === 0) {
+      throw new AgentsCodemodError(`every agents spec needs a name (got: ${JSON.stringify(sp)})`);
+    }
+    refuseUnknownFields(`agents spec "${String(sp.name)}"`, sp, SPEC_FIELDS);
+    if (!isStringArray(sp.channels)) throw new AgentsCodemodError(`agents spec "${sp.name}" needs a channels string array`);
+    if (!isRecord(sp.memory) || (sp.memory.kind !== "existing-silo" && sp.memory.kind !== "new-readonly")) {
+      throw new AgentsCodemodError(`agents spec "${sp.name}" memory must be { kind: "existing-silo" | "new-readonly", … }`);
+    }
+    if (sp.memory.kind === "existing-silo" && typeof sp.memory.silo !== "string") {
+      throw new AgentsCodemodError(`agents spec "${sp.name}" existing-silo memory needs a silo name`);
+    }
+    if (sp.memory.kind === "new-readonly" && typeof sp.memory.provider !== "string") {
+      throw new AgentsCodemodError(`agents spec "${sp.name}" new-readonly memory needs a provider`);
+    }
+    if (sp.connectors !== undefined) assertAgentConnectorGrants(`agents spec "${sp.name}"`, sp.connectors);
+    if (sp.exposed !== undefined && typeof sp.exposed !== "boolean") throw new AgentsCodemodError(`agents spec "${sp.name}" exposed must be a boolean`);
+    specs.push(sp as unknown as AgentSpec);
+  }
+
+  return { domains, silos, bundles, bindings, specs };
+}
+
+// Canonical key order per shape; unknown keys (a future field) go last, alphabetically, so a
+// vocabulary extension can't reshuffle existing lines.
+const DOMAIN_KEYS = ["name", "title", "reach", "memory"];
+const SILO_KEYS = ["name", "description", "provider", "container", "path", "readOnly", "recursive", "skill", "select"];
+const BUNDLE_KEYS = ["name", "title", "connectors", "instructions"];
+const BINDING_KEYS = ["bundle", "scope"];
+const SCOPE_KEYS = ["level", "domain"];
+const SPEC_KEYS = ["name", "title", "channels", "memory", "connectors", "instructions", "exposed"];
+const MEMORY_KEYS = ["kind", "silo", "provider", "container", "path", "skill", "select"];
+const SELECTION_KEYS = ["default", "rules"];
+const RULE_KEYS = ["path", "mode"];
+
+function orderKeys(obj: Record<string, unknown>, order: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of order) if (k in obj) out[k] = obj[k];
+  for (const k of Object.keys(obj).sort()) if (!(k in out)) out[k] = obj[k];
+  return out;
+}
+
+function canonicalSelection(sel: MemorySelection): Record<string, unknown> {
+  const obj: Record<string, unknown> = { ...sel };
+  if (sel.rules) obj.rules = sel.rules.map((r) => orderKeys({ ...r }, RULE_KEYS));
+  return orderKeys(obj, SELECTION_KEYS);
+}
+
+function canonicalDomain(d: Domain): Record<string, unknown> {
+  const obj: Record<string, unknown> = { ...d };
+  if (d.reach) obj.reach = [...d.reach].sort();
+  if (Array.isArray(d.memory)) obj.memory = [...d.memory].sort();
+  return orderKeys(obj, DOMAIN_KEYS);
+}
+
+function canonicalSilo(s: MemorySilo): Record<string, unknown> {
+  const obj: Record<string, unknown> = { ...s };
+  if (s.select) obj.select = canonicalSelection(s.select);
+  return orderKeys(obj, SILO_KEYS);
+}
+
+function canonicalBundle(b: Bundle): Record<string, unknown> {
+  const obj: Record<string, unknown> = { ...b };
+  // Sort by grant name and rebuild each grant's own keys in a fixed order: the type also admits a declared `contentOrigin`, and a default comparator over objects would canonicalise neither.
+  if (b.connectors) {
+    obj.connectors = [...b.connectors]
+      .sort((x, y) => connectorGrantName(x).localeCompare(connectorGrantName(y)))
+      .map((g) => (typeof g === "string" ? g : { name: g.name, credential: g.credential }));
+  }
+  return orderKeys(obj, BUNDLE_KEYS);
+}
+
+function canonicalBinding(bd: Binding): Record<string, unknown> {
+  return orderKeys({ ...bd, scope: orderKeys({ ...bd.scope } as Record<string, unknown>, SCOPE_KEYS) }, BINDING_KEYS);
+}
+
+function canonicalSpec(sp: AgentSpec): Record<string, unknown> {
+  const obj: Record<string, unknown> = { ...sp };
+  obj.channels = [...sp.channels].sort();
+  if (sp.connectors) obj.connectors = [...sp.connectors].sort((x, y) => x.name.localeCompare(y.name)).map((g) => ({ name: g.name, credential: g.credential }));
+  const mem: Record<string, unknown> = { ...sp.memory };
+  if (sp.memory.kind === "new-readonly" && sp.memory.select) mem.select = canonicalSelection(sp.memory.select);
+  obj.memory = orderKeys(mem, MEMORY_KEYS);
+  return orderKeys(obj, SPEC_KEYS);
+}
+
+function scopeSortKey(s: Scope): string {
+  return `${s.domain ?? ""}/${s.level}`;
+}
+
+/**
+ * Canonical, byte-deterministic serialisation of the overlay's DATA: each array sorted (domains/
+ * silos/bundles/specs by name, bindings by (bundle, domain)), inner arrays canonicalised, fixed key
+ * order, 2-space indent, trailing newline. `parseAgentsFile ∘ stringifyAgents` is a fixpoint.
+ */
+export function stringifyAgents(file: AgentsFile): string {
+  const canonical = {
+    domains: [...file.domains].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalDomain),
+    silos: [...file.silos].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalSilo),
+    bundles: [...file.bundles].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalBundle),
+    bindings: [...file.bindings]
+      .sort((a, b) => a.bundle.localeCompare(b.bundle) || scopeSortKey(a.scope).localeCompare(scopeSortKey(b.scope)))
+      .map(canonicalBinding),
+    specs: [...file.specs].sort((a, b) => a.name.localeCompare(b.name)).map(canonicalSpec),
+  };
+  return JSON.stringify(canonical, null, 2) + "\n";
+}
+
+const AGENTS_MODULE: OverlayModuleGrammar = {
+  what: "agents overlay",
+  header: overlayModuleHeader("agents overlay", "packages/core/agent/memory/agents-codemod.ts"),
+  typeImport: 'import type { AgentsFile } from "@open-everywhere/core/agent/memory/agents-codemod.js";',
+  typeName: "AgentsFile",
+};
+
+export function emitAgentsModule(file: AgentsFile): string {
+  return wrapOverlayModule(AGENTS_MODULE, stringifyAgents(file));
+}
+
+/**
+ * Parses the module and VERIFIES THE ROUND TRIP: re-emitting the parsed data must reproduce the file byte for byte, so a hand-edited overlay is refused rather than silently rewritten.
+ * `npm run lint:overlays` runs the same check.
+ */
+export function parseAgentsModule(text: string): AgentsFile {
+  const file = parseAgentsFile(unwrapOverlayModule(AGENTS_MODULE, text, (m) => new AgentsCodemodError(m)));
+  if (emitAgentsModule(file) !== text) {
+    throw new AgentsCodemodError(
+      "agents overlay is not in canonical form — re-emitting its own data does not reproduce the file, so it has been hand-edited. Run `npm run overlays:normalize` and commit the result (the codemod refuses to rewrite a file it did not write).",
+    );
+  }
+  return file;
+}
+
+/** LENIENT re-emit for `npm run overlays:normalize`: take whatever well-shaped data the module
+ *  carries and return the canonical module text. The only path allowed to accept a non-canonical
+ *  file — its whole job is to produce the canonical one. */
+export function renormalizeAgentsModule(text: string): string {
+  return emitAgentsModule(parseAgentsFile(unwrapOverlayModule(AGENTS_MODULE, text, (m) => new AgentsCodemodError(m))));
+}
+
+function upsertByName<T extends { readonly name: string }>(list: readonly T[], next: T): T[] {
+  const has = list.some((x) => x.name === next.name);
+  return has ? list.map((x) => (x.name === next.name ? next : x)) : [...list, next];
+}
+
+function upsertBinding(list: readonly Binding[], next: Binding): Binding[] {
+  const has = list.some((b) => b.bundle === next.bundle && b.scope.level === next.scope.level && b.scope.domain === next.scope.domain);
+  return has ? list.map((b) => (b.bundle === next.bundle && b.scope.level === next.scope.level && b.scope.domain === next.scope.domain ? next : b)) : [...list, next];
+}
+
+export interface ApplyAgentResult {
+  readonly file: AgentsFile;
+  /** False when the spec's whole effect was already present (idempotent re-apply). */
+  readonly changed: boolean;
+}
+
+/**
+ * Pure, deterministic and idempotent: re-applying a spec whose effect is already present returns `changed: false` and byte-identical output.
+ * It does NOT call `assertExposedAgentSpec` — the caller runs that guard before applying, and the config-load assert is the backstop.
+ */
+export function applyAgentSpec(file: AgentsFile, spec: AgentSpec): ApplyAgentResult {
+  if (!spec.name || spec.name.includes("/")) {
+    throw new AgentsCodemodError(`agent name "${spec.name}" must be a bare, non-empty domain name (no "/")`);
+  }
+  const siloName = agentSiloName(spec);
+  const bundleName = agentBundleName(spec);
+
+  const domain: Domain = {
+    name: spec.name,
+    ...(spec.title !== undefined ? { title: spec.title } : {}),
+    reach: [...spec.channels],
+    memory: siloName,
+  };
+
+  const newSilo: MemorySilo | undefined =
+    spec.memory.kind === "new-readonly"
+      ? {
+          name: siloName,
+          provider: spec.memory.provider,
+          ...(spec.memory.container !== undefined ? { container: spec.memory.container } : {}),
+          ...(spec.memory.path !== undefined ? { path: spec.memory.path } : {}),
+          readOnly: true,
+          ...(spec.memory.skill !== undefined ? { skill: spec.memory.skill } : {}),
+          ...(spec.memory.select !== undefined ? { select: spec.memory.select } : {}),
+        }
+      : undefined;
+
+  const bundle: Bundle = {
+    name: bundleName,
+    ...(spec.title !== undefined ? { title: spec.title } : {}),
+    ...(spec.connectors !== undefined && spec.connectors.length > 0
+      ? {
+          connectors: [...new Map(spec.connectors.map((g) => [g.name, g])).values()]
+            .sort((x, y) => x.name.localeCompare(y.name))
+            .map((g) => ({ name: g.name, credential: g.credential })),
+        }
+      : {}),
+    ...(spec.instructions !== undefined ? { instructions: spec.instructions } : {}),
+  };
+
+  const binding: Binding = { bundle: bundleName, scope: { level: "domain", domain: spec.name } };
+
+  const next: AgentsFile = {
+    domains: upsertByName(file.domains, domain),
+    silos: newSilo ? upsertByName(file.silos, newSilo) : file.silos,
+    bundles: upsertByName(file.bundles, bundle),
+    bindings: upsertBinding(file.bindings, binding),
+    specs: upsertByName(file.specs, spec),
+  };
+
+  const changed = stringifyAgents(next) !== stringifyAgents(file);
+  return { file: next, changed };
+}

package/agent/memory/connector-memory.ts

@@ -0,0 +1,137 @@
+// Connector-owned memory backings (github, notion) declare a capability here, so a domain projects only what its own connector grants already reach.
+// First-party backings (postgres, sqlite) are not declared here — the deployment holds their credential.
+
+import type { MemorySilo } from "./silo.js";
+import type { Domain } from "./domain.js";
+import { memoryRefs } from "./domain.js";
+
+export type ConnectorMemoryMode = "materialise" | "read-write" | "skill";
+
+/** The grants a domain holds, projected down to what a memory capability can be checked against. A capability's own validator receives this, so core never learns a vendor's grant shape. */
+export interface DomainMemoryGrants {
+  /** Connector slugs this domain's bundles grant (access/bundle.ts `connectors` + `providers`). */
+  readonly connectors: readonly string[];
+  /** GitHub repos ("owner/name") this domain's bundles grant (access/bundle.ts `repos`). */
+  readonly repos: readonly string[];
+}
+
+/**
+ * A connector's optional MEMORY capability — declared by the provider package that owns the
+ * connector, registered at boot beside its `MemoryProvider`.
+ */
+export interface ConnectorMemoryCapability {
+  /** The `MemoryProvider` id a silo names in `silo.provider` (e.g. "github", "notion"). */
+  readonly provider: string;
+  /** The CONNECTOR slug a domain must be granted for this backing to be usable there. */
+  readonly connector: string;
+  readonly mode: ConnectorMemoryMode;
+  /**
+   * 🔴 THE ONLY PERMITTED VALUE. A shared domain brain materialised through one person's user-subject token would bake that person's personal access into a cache every session in the domain reads.
+   * Declared rather than assumed, so the refusal is a type error at the call site and a throw at registration, not a comment somebody has to remember.
+   */
+  readonly subject: "app-principal";
+  /** What `silo.container` means for this backing — quoted in config errors. */
+  readonly containerLabel: string;
+  /** For `mode: "skill"`: the skill that teaches how to reach this source. */
+  readonly skill?: string;
+  /**
+   * Return `null` when `silo.container` is inside what the domain has been granted READ access to, or a problem string when it is not.
+   * Omit it when the backing has no container-level grant plane; the connector-grant check is then the whole invariant.
+   */
+  readonly assertContainerGranted?: (silo: MemorySilo, grants: DomainMemoryGrants) => string | null;
+}
+
+const REGISTRY = new Map<string, ConnectorMemoryCapability>();
+
+/**
+ * Declare a connector's memory capability. Called from the provider package's `register()`,
+ * beside its `registerProvider(...)` — the two are wired together and neither is useful alone.
+ * Fails LOUD on a re-declaration under a different connector, and on any subject other than the
+ * app-principal arm.
+ */
+export function registerConnectorMemory(cap: ConnectorMemoryCapability): void {
+  if (cap.subject !== "app-principal") {
+    throw new Error(
+      `connector-owned memory "${cap.provider}": subject must be "app-principal" (got ${JSON.stringify(cap.subject)}) — ` +
+        `a shared domain brain is never materialised through a user-subject token (memory/connector-memory.ts).`,
+    );
+  }
+  const existing = REGISTRY.get(cap.provider);
+  if (existing && existing.connector !== cap.connector) {
+    throw new Error(
+      `connector-owned memory "${cap.provider}" is already declared against connector "${existing.connector}" ` +
+        `and is being re-declared against "${cap.connector}" — two provider packages cannot own one backing id.`,
+    );
+  }
+  REGISTRY.set(cap.provider, cap);
+}
+
+/** The capability declared for a `MemoryProvider` id, or undefined for a first-party backing. */
+export function connectorMemoryFor(providerId: string | undefined): ConnectorMemoryCapability | undefined {
+  return providerId ? REGISTRY.get(providerId) : undefined;
+}
+
+/** Every declared capability, sorted by provider id — the roster's contribution view (OPE-375). */
+export function connectorMemoryCapabilities(): readonly ConnectorMemoryCapability[] {
+  return [...REGISTRY.values()].sort((a, b) => (a.provider < b.provider ? -1 : a.provider > b.provider ? 1 : 0));
+}
+
+/** Test seam: forget every declaration (the registry is process-global, like every other). */
+export function resetConnectorMemoryForTest(): void {
+  REGISTRY.clear();
+}
+
+/**
+ * Fail loud at config load when a domain's connector-owned silo reaches past that domain's grants: the domain must hold the connector grant, and the container must satisfy the capability's own validator.
+ * Every problem is reported at once. A first-party backing declares no capability and is skipped.
+ */
+export function assertConnectorMemoryGrants(
+  domains: readonly Domain[],
+  silos: readonly MemorySilo[],
+  grantsFor: (domain: Domain) => DomainMemoryGrants | null,
+): void {
+  const byName = new Map(silos.map((s) => [s.name, s]));
+  const problems: string[] = [];
+
+  for (const domain of domains) {
+    let grants: DomainMemoryGrants | null = null;
+    let resolved = false;
+    for (const ref of memoryRefs(domain)) {
+      const silo = byName.get(ref);
+      if (!silo) continue; // an unknown silo name is a DIFFERENT config error, owned by the resolver
+      const cap = connectorMemoryFor(silo.provider);
+      if (!cap) continue; // first-party backing — the deployment is the credential holder
+      if (!resolved) {
+        grants = grantsFor(domain);
+        resolved = true;
+      }
+      if (!grants) {
+        problems.push(
+          `  domain "${domain.name}" references silo "${silo.name}" (${cap.provider}-backed) but the domain has NO ` +
+            `resolvable access grants — memory rides the same route as connector access, so bind a bundle granting ` +
+            `the "${cap.connector}" connector to this domain (access/bundles.ts).`,
+        );
+        continue;
+      }
+      if (!grants.connectors.includes(cap.connector)) {
+        problems.push(
+          `  domain "${domain.name}" references silo "${silo.name}" (${cap.provider}-backed) but does not hold the ` +
+            `"${cap.connector}" connector grant — a memory projection IS read access, so it must be DECLARED on the ` +
+            `connector plane rather than smuggled in through silo config. Grant "${cap.connector}" to this domain ` +
+            `(bundle.connectors / bundle.providers) or drop the silo from the domain's memory list.`,
+        );
+        continue;
+      }
+      const containerProblem = cap.assertContainerGranted?.(silo, grants);
+      if (containerProblem) problems.push(`  domain "${domain.name}" / silo "${silo.name}": ${containerProblem}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      "open-everywhere: connector-owned memory silo(s) reach past their domain's grants:\n" +
+        problems.join("\n") +
+        "\n(memory/connector-memory.ts / docs/capabilities/memory.md — the prefetch invariant)",
+    );
+  }
+}