@open-everywhere/core 0.1.0

package/dist/agent/access/window-gated.js

@@ -0,0 +1,611 @@
+// The STRUCTURAL toolset-by-grain gate: a wide-hands tool resolves to `null` on a grain outside its kit, so the model never sees it. The gate is ABSENCE, not refusal.
+// 🔴 The posture is NOT a blanket fail-closed. Narrowing to standing needs a POSITIVE standing signal (the `oe_grain:"standing"` stamp, or a `:oe-sup:g`-suffixed non-task token); an ABSENT signal is fail-OPEN, since a native-shaped token with no stamp classifies "native" and keeps the full kit, which is correct for a real @mention session. Only a THROWN grain read narrows.
+// So a DM seat is narrowed only because its ingress positively stamps `oe_grain:"standing"` — without that stamp it would silently re-widen, which is why every DM ingress seam stamps and the stamp is unit-pinned.
+// Three layers: presence at `session.started`, one `turn.tool_gated` evidence row per gated resolution (names, counts and ids only, never message text), and an execute backstop behind the wall.
+// 🔴 Every dynamic entry needs a durable descriptor and every `session.started` resolver must be IDEMPOTENT: eve re-runs them when a persisted callback has no live binding, and an entry whose required phase has no descriptor is refused — eve then drops that resolver's WHOLE result, so the tool is silently absent. A framework-named tool additionally needs a `disableTool()` sentinel plus a per-grain kit, because a dynamic `null` does not remove eve's static default.
+import { defineDynamic, defineTool } from "eve/tools";
+import { bindFrom, windowGrainOf, currentWakeId, currentWindowToken, deploymentOrg, FIRE_UNATTENDED_ATTR } from "../identity/binding.js";
+import { auditWindowToolGate } from "../audit/window-tool-gate.js";
+import { classifySessionId } from "../channels/window-key.js";
+// Side-effectful import: installs the globalThis tool-result projection hook the eve patch
+// consults, and provides the per-tool projection registry preRegisterDynamicEntry fills.
+import { registerAuthoredProjectionName, setVariantProjectedName } from "./untrusted-projection.js";
+// The grain-posture tables + the pure CI checker live in the (dependency-free) manifest module so
+// scripts/window-gate-lint.ts can enumerate them without dragging the agent graph. Re-exported here
+// for the runtime + existing importers (window-capability-test.ts et al. import from this module).
+import { WINDOW_GATED_TOOLS, withheldFromGrain, fullKit } from "./window-gate-manifest.js";
+// OPE-111 — the per-WAKE durable-job restriction layered over (never instead of) the grain gate.
+import { allowedOnRestrictedJobWake, jobFireStamped, resolveJobWakePosture } from "./job-posture.js";
+import { isJobSession, jobWakeEscalated } from "./job-session-state.js";
+// OPE-301 — the per-WAKE lean-conversational-seat restriction, same layering, opposite fail direction.
+import { allowedOnLeanSeat, resolveLeanSeatPosture } from "./lean-seat.js";
+import { canDelegateFromSeat } from "./delegation-mount.js";
+export { WINDOW_GATED_TOOLS, WINDOW_UNGATED_TOOLS, withheldFromGrain, checkWindowGateManifest, fullKit } from "./window-gate-manifest.js";
+/** The request-time policy of either shape, bound to its owner: a bare policy binds to the ENTRY, since it may be authored in method syntax and read `this`, and a configuration's `request` binds to the configuration. */
+export function approvalRequestOf(entry) {
+    const approval = entry.approval;
+    if (approval === undefined)
+        return undefined;
+    if (typeof approval === "function")
+        return approval.bind(entry);
+    return approval.request.bind(approval);
+}
+/**
+ * The RESPONSE-time policy of an approval configuration (eve 0.34+), bound to its owner, or
+ * `undefined` for a bare policy / an entry with no approval. Only a configuration can carry one.
+ */
+export function approvalResponseOf(entry) {
+    const approval = entry.approval;
+    if (approval === undefined || typeof approval === "function")
+        return undefined;
+    const response = approval.response;
+    return response === undefined ? undefined : response.bind(approval);
+}
+/** Is this grain NARROWED of the wide-hands kit? It drives the evidence row: a narrowed conversational-root seat emits `turn.tool_gated`, while a `task` worker missing the standing-only delegation tools stays SILENT — grain confinement, not a narrowing event. */
+function isNarrowedGrain(grain) {
+    return !fullKit().includes(grain);
+}
+/** Fail-CLOSED grain read: any error narrows to standing (design A7 — the conversational kit's own
+ *  resolvers are independent, so the session stays functional with tiny hands, never full-open). */
+function grainOf(ctx) {
+    try {
+        return windowGrainOf(ctx);
+    }
+    catch {
+        return "standing";
+    }
+}
+/**
+ * The audit row's domain label, routed through the one typed session-id codec.
+ * BYTE-IDENTITY CAVEAT: the codec-`native` branch re-applies the original UNANCHORED `:oe-sup:g` split, which labels a malformed suffix-not-at-tail token; real tokens never reach it.
+ * EXECUTE-CONTEXT FALLBACK: a tool-execute context carries no `channel`, so only when that raw token is absent does this fall back to the host-stamped window token; a resolver context keeps the primary branch.
+ */
+export function domainLabelOf(ctx) {
+    try {
+        const raw = ctx.channel?.continuationToken ?? currentWindowToken(ctx);
+        const sid = classifySessionId(raw);
+        if (sid.kind === "window" || sid.kind === "task" || sid.kind === "thread-seat")
+            return sid.key.domain;
+        if (sid.kind === "container-supervisor")
+            return sid.containerKey.length > 0 ? sid.containerKey : "unknown";
+        // codec `native`: preserve the original UNANCHORED fallback (see caveat above).
+        if (typeof raw !== "string")
+            return "unknown";
+        const token = raw.startsWith("unified:") ? raw.slice("unified:".length) : raw;
+        const suffix = token.lastIndexOf(":oe-sup:g");
+        return suffix > 0 ? token.slice(0, suffix) : "unknown";
+    }
+    catch {
+        return "unknown"; // labelling must never fail the gate (the gate already narrowed)
+    }
+}
+// One `turn.tool_gated` row per gated SESSION resolution: the first resolver to run emits the full withheld list and the rest dedupe through this per-invocation set.
+// 🔴 A `session.started` arm is NOT a once-per-session arm: eve re-invokes session-scoped resolvers when a live durable session reaches a new runtime revision, so a seat that survives a deploy emits a fresh row under the new build — a new process, so the dedupe never suppresses it.
+const auditedSessions = new Set();
+async function auditGateOnce(ctx, grain) {
+    try {
+        const sessionId = ctx.session?.id ?? domainLabelOf(ctx);
+        if (auditedSessions.has(sessionId))
+            return;
+        auditedSessions.add(sessionId);
+        await auditWindowToolGate({
+            org: deploymentOrg(),
+            domain: domainLabelOf(ctx),
+            grain,
+            withheld: withheldFromGrain(grain),
+            wakeId: currentWakeId(ctx) ?? null,
+            sessionId: ctx.session?.id ?? null,
+        });
+    }
+    catch {
+        // Evidence is best-effort — an audit failure must never fail the session's start (the
+        // withholding itself has already happened; absence never depends on this row landing).
+    }
+}
+/** TEST SEAM: reset the once-per-session audit dedupe (unit tests mint many synthetic sessions). */
+export function _resetWindowGateAuditForTest() {
+    auditedSessions.clear();
+}
+/** Refusal text per grain — states the seat's shape and the delegation route, nothing leading. */
+function refusalFor(name, grain) {
+    if (grain === "standing") {
+        return (`${name} is not available on a standing (always-on watcher) seat — a worker runs it with ` +
+            "the full toolset. Hand it to one if this seat holds a delegation verb; if it holds none, say " +
+            "so rather than trying.");
+    }
+    return `${name} is not available on a ${grain} session.`;
+}
+/**
+ * The per-attempt grain refusal — the shared layer-3 backstop behind the absence wall.
+ * It re-resolves the grain (fail-closed) and, outside `allowed`, stamps a per-attempt `turn.tool_gated` row (the name only — never the call's input, which can carry injected content) and throws the refusal.
+ */
+export async function grainBackstopAtExecute(name, allowed, ctx, refusal = (grain) => refusalFor(name, grain)) {
+    const grain = grainOf(ctx);
+    // OPE-111 FIRST: the job-wake restriction is orthogonal to grain and STRICTLY narrower, so a tool
+    // the grain would admit is still refused on an un-escalated durable-job fire. Same evidence row,
+    // tagged `job-wake` so the two withholdings are distinguishable in the audit.
+    if (jobWakeWithholds(name, ctx)) {
+        await auditWindowToolGate({
+            org: deploymentOrg(),
+            domain: domainLabelOf(ctx),
+            grain,
+            withheld: [name],
+            wakeId: currentWakeId(ctx) ?? null,
+            sessionId: ctx.session?.id ?? null,
+            reason: "job-wake",
+        }).catch(() => undefined);
+        throw new Error(`${name} is not available on an un-escalated durable-job fire — a job runs on its own schedule with nobody in the room, so it keeps reads, its replies and its own progress ledger. Report what you found and record it with record_job_state; a person in this thread can take the step that needs ${name}.`);
+    }
+    // OPE-301 SECOND: the lean-conversational-seat restriction, behind the job arm (a restricted job
+    // wake is judged by the job kit alone — the two must never intersect, or a fire loses its reads).
+    // Same evidence row, tagged `lean-seat`.
+    if (leanSeatWithholds(name, ctx)) {
+        await auditWindowToolGate({
+            org: deploymentOrg(),
+            domain: domainLabelOf(ctx),
+            grain,
+            withheld: [name],
+            wakeId: currentWakeId(ctx) ?? null,
+            sessionId: ctx.session?.id ?? null,
+            reason: "lean-seat",
+        }).catch(() => undefined);
+        throw new Error(`${name} is not held by this conversational seat — this seat talks and delegates. Hand the work to a worker (\`agent\`, or \`spawn_thread_session\` for anything long): the worker holds the full kit, and its result comes back to you to relay.`);
+    }
+    if (allowed.includes(grain))
+        return;
+    await auditWindowToolGate({
+        org: deploymentOrg(),
+        domain: domainLabelOf(ctx),
+        grain,
+        withheld: [name],
+        wakeId: currentWakeId(ctx) ?? null,
+        sessionId: ctx.session?.id ?? null,
+    }).catch(() => undefined);
+    throw new Error(refusal(grain));
+}
+/** Is this seat a DM-family root? The POSITIVE binding-mode read the DM carve-in keys on, invariant across the DM re-seat unlike any delegation predicate. Fail-soft to false: an unresolvable binding simply does not carve in. */
+function isDmFamilySeat(ctx) {
+    try {
+        const mode = bindFrom(ctx).mode;
+        return mode === "dm" || mode === "mpim";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The lean-seat arm of the execute backstop. It re-derives the answer from the SEAT IDENTITY — grain, `canDelegateFromSeat`, and this delivery's own fire stamps — rather than from the session slot, so it holds where the slot read fails soft.
+ * Coverage: it sees only the GATED tools, the ones wrapped here; the relocated always-available verbs are withheld from a lean wake by ABSENCE at the model call, so this arm is a replay-edge tripwire and absence is the wall.
+ * FAIL DIRECTION: `false`, do not withhold, on anything unreadable — the lean cut must never strand a seat it cannot positively classify — and a fire stamp reads as "not a conversational wake", preserving fire posture.
+ */
+function leanSeatWithholds(name, ctx) {
+    try {
+        // The seat-independent roster first, then the DM carve-in resolved from the BINDING MODE — the same question hooks/lean-seat.ts asks, so this arm and the model-call seam agree on which seats keep the DM-walled self-verbs.
+        if (allowedOnLeanSeat(name, isDmFamilySeat(ctx)))
+            return false;
+        // 🔴 `current` ONLY, with no `initiator` fallback: `initiator` is the immutable session-OPENING bag, so on a fire-opened session it carries the fire's markers forever and an unreadable `current` would take the WIDEST answer. An absent `current` therefore reads as "not a fire", and a posture decision fails narrow.
+        // The job arm keeps its fallback deliberately: there the fire stamp means `restricted`, so reaching back to the initiator withholds MORE.
+        const attrs = ctx.session?.auth?.current?.attributes;
+        const v = attrs?.[FIRE_UNATTENDED_ATTR];
+        const unattended = (typeof v === "string" ? v : Array.isArray(v) ? v[0] : undefined) === "true";
+        if (unattended || jobFireStamped(attrs))
+            return false; // a fire keeps its own posture
+        const posture = resolveLeanSeatPosture({ grain: grainOf(ctx), canDelegate: canDelegateFromSeat(ctx), unattendedFire: false });
+        return posture === "lean";
+    }
+    catch {
+        return false; // an unreadable identity must not strand the seat; the grain backstop still runs
+    }
+}
+/**
+ * The job-wake arm of the execute backstop, orthogonal to grain and checked FIRST, because a durable-job session's toolset is frozen at its first fire.
+ * It is the sturdier of the two: it reads the fire stamp straight off THIS delivery's auth attributes — host-set, unforgeable, fresh every delivery — so it holds where the model-call seam's eve-context read fails soft.
+ * Coverage: it sees only the GATED tools; the always-available consequential verbs are withheld from a restricted wake by ABSENCE at the model call plus their own consequence gates.
+ */
+function jobWakeWithholds(name, ctx) {
+    try {
+        const attrs = ctx.session?.auth?.current?.attributes ?? ctx.session?.auth?.initiator?.attributes;
+        const posture = resolveJobWakePosture({
+            jobFire: jobFireStamped(attrs),
+            jobSession: isJobSession(),
+            humanPrincipal: jobWakeEscalated(),
+        });
+        return posture === "restricted" && !allowedOnRestrictedJobWake(name);
+    }
+    catch {
+        // Unreadable auth on a tool we cannot classify: this helper's only job is to WITHHOLD, and it
+        // has no evidence that this is a job wake at all — so it declines to withhold and the grain
+        // backstop below (which fails closed to `standing` on a throw) makes the call.
+        return false;
+    }
+}
+/** The execute-entry BACKSTOP (layer 3): re-check the grain even if the tool was somehow resolved/
+ *  called, refuse fail-closed, and stamp a per-attempt turn.tool_gated row (name only — never the
+ *  call's input, which can carry injected content). */
+function gatedExecute(name, entry) {
+    return async (input, ctx) => {
+        await grainBackstopAtExecute(name, WINDOW_GATED_TOOLS[name] ?? [], ctx);
+        return entry.execute(input, ctx);
+    };
+}
+// The SAME global registry eve's dynamic-tool lifecycle reads. OE writes to it only as a stable, direct-callable alias for tests; eve's own session-scoped names are what production replay reads.
+const STEP_REGISTRY_KEY = Symbol.for("@workflow/core//registeredSteps");
+function stepRegistry() {
+    const g = globalThis;
+    let reg = g[STEP_REGISTRY_KEY];
+    if (reg === undefined) {
+        reg = new Map();
+        g[STEP_REGISTRY_KEY] = reg;
+    }
+    return reg;
+}
+/** OE's own `slug:entryKey` alias naming — NOT what eve durably records. eve derives its own session-scoped name; this stays only for the tests that use it as a lookup key decoupled from any session. */
+export function replayStepNames(slug, entryKey) {
+    return {
+        execute: `eve:framework-dynamic:${slug}:${entryKey}`,
+        approval: `eve:dynamic-tool-approval:${slug}:${entryKey}`,
+        approvalResponse: `eve:dynamic-tool-approval-response:${slug}:${entryKey}`,
+        toModelOutput: `eve:dynamic-tool-model-output:${slug}:${entryKey}`,
+    };
+}
+/**
+ * eve's durable callback contract, addressed by its global symbols because the module is not on eve's exports map.
+ * 🔴 Every dynamic-tool callback must carry a `{callback, closure}` descriptor, keyed by `(toolName, phase)`. An entry whose required phase has none is REFUSED, and eve drops that resolver's whole result — the tool is silently absent, with one log line and no red anywhere.
+ * eve's build transform issues one only for a callback authored INLINE in transformed source, which the gated execute built here is not, so OE issues its own and fills only what is missing.
+ * A descriptor carrying a `stepId` is refused by name, and the registry is process-local and fills at resolve time — which is why every resolver here must stay IDEMPOTENT.
+ */
+const DURABLE_TOOL_CALLBACKS = Symbol.for("eve:durable-dynamic-tool-callbacks");
+/**
+ * eve's rule for a PERSISTED closure, mirrored because eve does not publish the module: JSON scalars, arrays and PLAIN objects only, `undefined` values skipped and cycles refused. A Date, a Map, a class instance or a function is not serializable, and `JSON.stringify` silently DROPS a function-valued property rather than throwing.
+ * Being stricter than eve is harmless here: the only consequence is overwriting a descriptor that could have been kept.
+ */
+function isDurableClosureSerializable(value, seen = new WeakSet()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every((item) => isDurableClosureSerializable(item, seen));
+    if (typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype)
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    for (const item of Object.values(value)) {
+        if (item === undefined)
+            continue;
+        if (!isDurableClosureSerializable(item, seen))
+            return false;
+    }
+    seen.delete(value);
+    return true;
+}
+function fillDurableCallbackDescriptors(entry, callbacks, options = {}) {
+    const holder = entry;
+    const existing = holder[DURABLE_TOOL_CALLBACKS] ?? {};
+    const next = {};
+    for (const [phase, reference] of Object.entries(existing))
+        if (reference !== undefined)
+            next[phase] = reference;
+    const closure = (options.closure ?? {});
+    // `execute` is always required by eve; the other phases are described only when the entry authors them, or eve would register a binding nothing ever calls.
+    // `overwrite` REPLACES the descriptor eve's build transform stamped, and only {@link preRegisterDynamicVariants} passes it: two variants of one name each stamp their own body into the shared slot, so the last resolver would otherwise win it.
+    for (const [phase, callback] of Object.entries(callbacks)) {
+        if (callback === undefined)
+            continue;
+        const held = next[phase];
+        if (held !== undefined && options.overwrite !== true) {
+            // 🔴 Defer only to a descriptor eve can actually READ: the build transform captures whatever the inline callback reads from an enclosing scope, and a capture that does not serialize throws at resolve time and drops the resolver's WHOLE result (measured: every `browser_*` tool vanished from the deployed build).
+            // So OE takes the slot back rather than deferring. This is a BACKSTOP — the fix is to author the callback so the transform captures nothing, which only a build-output test can see.
+            if (isDurableClosureSerializable(held.closure))
+                continue;
+            console.error(`[open-everywhere:dynamic-tools] the build transform's "${phase}" descriptor carries a non-serializable ` +
+                "capture, which eve would refuse — taking the slot back with an empty closure. Hoist the callback out of " +
+                "the defineTool literal into a module-level factory (OPE-1063; see scripts/dynamic-callback-closure-bundle-test.ts).");
+        }
+        // A FRESH closure object per phase. eve JSON-parses it into a new value anyway, but sharing one
+        // object across phases would let a future mutation of one descriptor reach the others.
+        next[phase] = { callback, closure: { ...closure } };
+    }
+    Object.defineProperty(holder, DURABLE_TOOL_CALLBACKS, { configurable: true, value: next });
+}
+/**
+ * Fill ONE dynamic-tool entry's durable callback descriptors, record its mounted name as one that authors its own `toModelOutput`, and alias its phases under a stable `slug:entryKey` name as a test convenience.
+ * REPLAY CORRECTNESS needs the descriptor: a phase with none is refused and eve drops the resolver's whole result, and since OPE-378 it is the ONLY carrier of an authored envelope. eve rebinds whenever a resolver runs, so this must stay safe to call again on the same entry.
+ * The MOUNTED name is the resolver SLUG for a single branded entry (its `entryKey` starts with "_") and the BARE map key for a kit member.
+ * 🔴 ONE ENTRY PER MOUNTED NAME: eve keys its callback registry by `(toolName, phase)` alone, so several implementations under one name must go through {@link preRegisterDynamicVariants}, which puts one dispatcher in that slot.
+ */
+/**
+ * 🔴 The NAME is the only identity eve has: its durable callback registry is keyed on `(toolName, phase)` alone, so two entries under one name share ONE `execute` slot and the last resolver in the process wins it. A replayed turn rebuilds description and schema from the persisted record but takes `execute` from that slot, so the contract the model was offered and the code that runs can disagree.
+ * Measured: a unified seat was offered the unified `reply` and ran the per-surface one, which holds no wake-authority fence, so a fabricated wake id posted. The offline collision test reads this map.
+ */
+const MOUNTED_ENTRIES = new Map();
+/** The name a pre-registered entry MOUNTS under, which is what eve keys its callbacks by: the resolver SLUG for a bare branded entry, the BARE KEY for a map entry. Every single-entry key starts with "_" and no kit key does. */
+function mountedNameOf(slug, entryKey) {
+    return entryKey.startsWith("_") ? slug : entryKey;
+}
+function claimMountedName(mountedName, entry, variantManaged) {
+    const held = MOUNTED_ENTRIES.get(mountedName);
+    if (held === undefined) {
+        MOUNTED_ENTRIES.set(mountedName, { entries: new Set([entry]), variantManaged });
+        return;
+    }
+    held.entries.add(entry);
+    if (variantManaged)
+        held.variantManaged = true;
+}
+/** Every entry registered at module load, by the name it mounts under. A read for inventory tests: the schema lint (OPE-2068) walks it to reach the gated tools, whose schemas no static export carries. */
+export function registeredMountedEntries() {
+    return new Map([...MOUNTED_ENTRIES].map(([name, held]) => [name, held.entries]));
+}
+/**
+ * Every mounted name that more than one entry claims, with the two facts that decide whether the claim is safe: the name goes through {@link preRegisterDynamicVariants}, and every entry's durable `execute` descriptor carries the SAME callback. Both must hold, because eve keeps one callback per `(toolName, phase)`.
+ * `execute` alone is enough: every projection-authoring variant gets the same shared dispatcher, so two projections under one name can only arrive through the single-entry door twice, which already differs in `execute`.
+ */
+export function mountedEntryCollisions() {
+    const out = [];
+    for (const [name, held] of MOUNTED_ENTRIES) {
+        if (held.entries.size < 2)
+            continue;
+        const callbacks = new Set();
+        for (const entry of held.entries) {
+            const described = entry[DURABLE_TOOL_CALLBACKS];
+            callbacks.add(described?.execute?.callback);
+        }
+        out.push({ distinctExecuteCallbacks: callbacks.size, entryCount: held.entries.size, name, variantManaged: held.variantManaged });
+    }
+    return out;
+}
+/**
+ * The authored `toModelOutput` of the ONE entry mounted under `mountedName` — a TEST SEAM that delegates to the entry rather than holding a copy that could drift from it.
+ * 🔴 It calls the projection UNBOUND, because both eve paths do: binding `this` here would make a projection that reads `this` pass in a test and throw in production.
+ * 🔴 It REFUSES a name holding more than one entry rather than picking one — a variant family has no single projection, since the shared dispatcher needs a variant key this signature does not carry.
+ */
+export function authoredModelProjectionFor(mountedName) {
+    const held = MOUNTED_ENTRIES.get(mountedName);
+    if (held === undefined)
+        return undefined;
+    if (held.entries.size !== 1) {
+        throw new Error(`authoredModelProjectionFor("${mountedName}"): ${held.entries.size} entries mount under this name — a variant family has no single projection to return.`);
+    }
+    const [entry] = held.entries;
+    const project = entry?.toModelOutput;
+    if (typeof project !== "function")
+        return undefined;
+    return (output) => project(output);
+}
+/**
+ * Pre-register SEVERAL entries that mount under ONE tool name — 🔴 the only safe way to put two implementations behind one name.
+ * It issues ONE shared dispatcher per phase into every variant's durable descriptor, so eve's `(toolName, phase)` slot holds the same callback whichever variant resolved last; and it puts the variant's key in that descriptor's `closure`, which eve persists per tool and hands back on replay, so the dispatcher re-selects the exact variant the session mounted.
+ * It OVERWRITES the descriptor eve's build transform stamped, because those per-variant stamps are what collide. A variant may author `toModelOutput`, which rides the same dispatcher.
+ * 🔴 A variant family's mounted name NEVER enters the projection registry, a name set whose one job is classification and which would vouch for every variant at once: a family where EVERY variant projects is declared to the hook separately, and one with a silent variant keeps the connector fence on the whole name.
+ */
+export function preRegisterDynamicVariants(mountedName, variants) {
+    const entryKeys = Object.keys(variants);
+    if (entryKeys.length < 2) {
+        throw new Error(`preRegisterDynamicVariants("${mountedName}"): needs at least two variants — use preRegisterDynamicEntry for one.`);
+    }
+    installVariants(mountedName, variants);
+}
+/** Every mounted name registered through {@link registerDynamicVariant}. The static families know all their variants at module load; the credential-grant plane cannot — a grant's tool is built at RESOLVE time from a store row — so the set for one name GROWS as sessions resolve. */
+const INCREMENTAL_VARIANTS = new Map();
+/**
+ * 🔴 The only safe door for a resolve-time tool whose name is not unique per process: two SESSIONS can hold different grants under one mounted name, and eve keys its durable registry by `(toolName, phase)` alone, so without a dispatcher a replayed turn in the FIRST session would run the SECOND session's grant, with a credential behind it.
+ * It re-installs the dispatcher over the WHOLE accumulated set on every call, so the callback eve holds knows every variant registered so far and every descriptor carries that same callback. `entryKey` is the variant's durable key — for a grant, the grant id — and a closure with no key throws rather than guessing.
+ * GROWTH: one entry per (name, variant) this PROCESS resolved, bounded by live grants rather than by calls. A real cost, stated rather than hidden.
+ */
+export function registerDynamicVariant(mountedName, entryKey, entry) {
+    const held = INCREMENTAL_VARIANTS.get(mountedName) ?? {};
+    held[entryKey] = entry;
+    INCREMENTAL_VARIANTS.set(mountedName, held);
+    installVariants(mountedName, held);
+}
+/** Test seam: forget every incrementally-registered variant. Never called in production. */
+export function _resetDynamicVariantsForTest() {
+    INCREMENTAL_VARIANTS.clear();
+}
+/** The shared body of both variant doors. It carries no arity rule of its own — a single variant is
+ *  legal here, because the incremental door legitimately starts with one and grows. */
+function installVariants(mountedName, variants) {
+    const entryKeys = Object.keys(variants);
+    /** The variant the PERSISTED closure names. Fails closed: a closure with no key can only come from
+     *  metadata this function did not write, and guessing there is what OPE-1059 was. */
+    const pick = (closure) => {
+        const entryKey = closure?.entryKey;
+        if (typeof entryKey !== "string" || variants[entryKey] === undefined) {
+            throw new Error(`Dynamic tool "${mountedName}" was replayed with no variant key in its durable closure (got ${JSON.stringify(entryKey)}). ` +
+                `Its metadata predates the variant dispatcher and cannot say which implementation the session mounted. Start a new session.`);
+        }
+        return { entry: variants[entryKey], entryKey };
+    };
+    const shared = {};
+    shared.execute = ((closure, input, ctx) => pick(closure).entry.execute(input, ctx));
+    const hasApprovalRequest = entryKeys.some((k) => approvalRequestOf(variants[k]) !== undefined);
+    const hasApprovalResponse = entryKeys.some((k) => approvalResponseOf(variants[k]) !== undefined);
+    if (hasApprovalRequest) {
+        shared.approvalRequest = ((closure, actx) => {
+            const { entry, entryKey } = pick(closure);
+            const request = approvalRequestOf(entry);
+            if (request === undefined)
+                throw new Error(`Dynamic tool "${mountedName}" variant "${entryKey}" has no approval request policy.`);
+            return request(actx);
+        });
+    }
+    if (hasApprovalResponse) {
+        shared.approvalResponse = ((closure, rctx) => {
+            const { entry, entryKey } = pick(closure);
+            const response = approvalResponseOf(entry);
+            if (response === undefined)
+                throw new Error(`Dynamic tool "${mountedName}" variant "${entryKey}" has no approval response policy.`);
+            return response(rctx);
+        });
+    }
+    // The model projection rides the dispatcher like the other phases, because eve hands this callback the persisted closure too, so the variant key that resolves `execute` resolves the envelope as well.
+    const hasModelOutput = entryKeys.some((k) => typeof variants[k].toModelOutput === "function");
+    if (hasModelOutput) {
+        shared.toModelOutput = ((closure, out) => {
+            const { entry, entryKey } = pick(closure);
+            const project = entry.toModelOutput;
+            if (typeof project !== "function")
+                throw new Error(`Dynamic tool "${mountedName}" variant "${entryKey}" authors no toModelOutput.`);
+            return project.call(entry, out);
+        });
+    }
+    // A name whose EVERY variant authors an envelope tells the patch-side hook to leave its result alone. `every`, never `some`: the hook sees only the name, so a family with one silent variant keeps the connector wrap on the whole name. Recomputed on every registration.
+    setVariantProjectedName(mountedName, entryKeys.length > 0 && entryKeys.every((k) => typeof variants[k].toModelOutput === "function"));
+    const reg = stepRegistry();
+    for (const entryKey of entryKeys) {
+        const entry = variants[entryKey];
+        // The direct-callable test aliases stay PER VARIANT and bypass the dispatcher, so a test can
+        // still reach one variant by name without inventing a closure. Both routes end at the same
+        // `entry.execute`; the dispatcher only chooses which entry that is.
+        const names = replayStepNames(mountedName, entryKey);
+        reg.set(names.execute, ((_cv, input, ctx) => entry.execute(input, ctx)));
+        const approval = approvalRequestOf(entry);
+        if (approval !== undefined)
+            reg.set(names.approval, ((_cv, actx) => approval(actx)));
+        const approvalResponse = approvalResponseOf(entry);
+        if (approvalResponse !== undefined)
+            reg.set(names.approvalResponse, ((_cv, rctx) => approvalResponse(rctx)));
+        const project = entry.toModelOutput;
+        if (typeof project === "function")
+            reg.set(names.toModelOutput, ((_cv, out) => project.call(entry, out)));
+        // Describe exactly the phases THIS variant authors. Describing one the entry does not have would
+        // make eve attach a projection to a tool that never asked for one, and the dispatcher would then
+        // throw at render time on a variant with nothing to run.
+        const own = { execute: shared.execute };
+        if (approval !== undefined)
+            own.approvalRequest = shared.approvalRequest;
+        if (approvalResponse !== undefined)
+            own.approvalResponse = shared.approvalResponse;
+        if (typeof project === "function")
+            own.toModelOutput = shared.toModelOutput;
+        fillDurableCallbackDescriptors(entry, own, { closure: { entryKey }, overwrite: true });
+        claimMountedName(mountedName, entry, true);
+    }
+}
+/**
+ * REPLAY DOCTRINE: every dynamic tool authors its entry as a top-level FACTORED `defineTool` const and pre-registers it here, never inline in the resolver.
+ * eve's bundler transform hoists an inline literal under a global build-order-counter step name that shifts across deploys, which once cross-wired a resumed session's durable metadata to a DIFFERENT tool's execute.
+ * `disableTool()` is NOT the way to hide an authored tool — that sentinel removes a framework-default tool at build time; the dynamic-resolver way is to return `null` for `session.started`.
+ * 🔴 Enforced by `npm run lint:dynamic-replay`, which reds on a `defineTool` literal at or after a `defineDynamic(` call, or on an entry registered through none of these calls. It is a SOURCE scan and does not catch every inline shape, so keep authoring entries as top-level consts.
+ */
+export function preRegisterDynamicEntry(slug, entryKey, entry) {
+    const names = replayStepNames(slug, entryKey);
+    const reg = stepRegistry();
+    claimMountedName(mountedNameOf(slug, entryKey), entry, false);
+    // ONE definition per phase, shared by the alias registry and the durable descriptor below, so the test alias and what eve actually calls on replay cannot drift. The aliases are a convenience for tests; production replay does not consult these names.
+    const callbacks = {};
+    callbacks.execute = ((_cv, input, ctx) => entry.execute(input, ctx));
+    reg.set(names.execute, callbacks.execute);
+    const approval = approvalRequestOf(entry);
+    if (approval !== undefined) {
+        callbacks.approvalRequest = ((_cv, actx) => approval(actx));
+        reg.set(names.approval, callbacks.approvalRequest);
+    }
+    const approvalResponse = approvalResponseOf(entry);
+    if (approvalResponse !== undefined) {
+        callbacks.approvalResponse = ((_cv, rctx) => approvalResponse(rctx));
+        reg.set(names.approvalResponse, callbacks.approvalResponse);
+    }
+    if (typeof entry.toModelOutput === "function") {
+        // NAME ONLY: eve carries an authored projection through replay unaided now, so this registration is a CLASSIFICATION — it keeps the connector wrap off a `ns__name` tool that authors its own envelope.
+        registerAuthoredProjectionName(mountedNameOf(slug, entryKey));
+        // 🔴 The descriptor is now the ONLY carrier of the authored envelope: it is what `replayDynamicTools` resolves, and a gap in it takes the whole tool off the seat rather than only its envelope off the result.
+        callbacks.toModelOutput = ((_cv, out) => entry.toModelOutput(out));
+        reg.set(names.toModelOutput, callbacks.toModelOutput);
+    }
+    fillDurableCallbackDescriptors(entry, callbacks);
+}
+function armEntry(name, entry) {
+    return defineTool({ ...entry, execute: gatedExecute(name, entry) });
+}
+/**
+ * Wrap ONE authored tool in the grain gate. `name` MUST equal the tool file's slug, or the gate would cover a different name than the one that mounts; the entry's `approval` is kept and pre-registered so it survives a resumed session.
+ * `mountGate` is an optional per-tool MOUNT predicate applied after the grain check passes: a false verdict makes the tool structurally ABSENT, for a runtime precondition the grain read cannot see — a standing seat on a native token has no window to mint a thread seat into.
+ * It is defence-in-depth, with the tool's own execute guard as the authoritative wall, so a predicate must fail OPEN on anything it cannot positively decide.
+ */
+export function windowGated(name, entry, mountGate) {
+    // The lookup here is the UN-TABLED-NAME throw and nothing else, never a value to reuse: a wide-hands row is a GETTER over the flag-derived matrix, so the resolver below re-reads the row per session and the execute backstop re-reads it per call. Freezing one side would skew what a seat mounts against what it may run.
+    // MEASURED boot order: a gated tool module loads after the app's settings are registered, so a capture here would survive boot and fail on any later settings registration instead.
+    if (WINDOW_GATED_TOOLS[name] === undefined) {
+        throw new Error(`windowGated("${name}"): not in WINDOW_GATED_TOOLS — add the kit row (the table is the single source of truth)`);
+    }
+    const armed = armEntry(name, entry);
+    preRegisterDynamicEntry(name, "_single", armed);
+    const dyn = defineDynamic({
+        events: {
+            "session.started": async (_event, ctx) => {
+                const c = ctx;
+                const grain = grainOf(c);
+                if (!WINDOW_GATED_TOOLS[name].includes(grain)) {
+                    if (isNarrowedGrain(grain))
+                        await auditGateOnce(c, grain);
+                    return null;
+                }
+                // Per-tool mount precondition beyond grain (see the doc): a false verdict makes the tool
+                // absent WITHOUT a turn.tool_gated row — this is a structural confinement (the seat simply
+                // can't use the tool), not a narrowing event, same as a task seat lacking `agent`.
+                if (mountGate && !mountGate(c))
+                    return null;
+                return armed;
+            },
+        },
+    });
+    return dyn;
+}
+/**
+ * Wrap a MAP of tools in the grain gate from one resolver file; map entries mount under their BARE key names, which is what lets one resolver re-provide the disabled framework names per grain.
+ * `mountGates` is the per-KEY analogue of {@link windowGated}'s `mountGate`, with identical semantics: a false verdict withholds that ONE key with no evidence row (structural confinement), and it carries the same duty to fail open.
+ */
+export function windowGatedKit(slug, entries, mountGates = {}) {
+    const armed = {};
+    for (const [name, entry] of Object.entries(entries)) {
+        if (WINDOW_GATED_TOOLS[name] === undefined) {
+            throw new Error(`windowGatedKit("${slug}"): "${name}" is not in WINDOW_GATED_TOOLS — add the kit row`);
+        }
+        armed[name] = armEntry(name, entry);
+        preRegisterDynamicEntry(slug, name, armed[name]);
+    }
+    for (const name of Object.keys(mountGates)) {
+        if (armed[name] === undefined) {
+            throw new Error(`windowGatedKit("${slug}"): mountGates names "${name}", which is not a key of this kit — a predicate on a name the kit doesn't provide gates nothing (fix the name)`);
+        }
+    }
+    return defineDynamic({
+        events: {
+            "session.started": async (_event, ctx) => {
+                const c = ctx;
+                const grain = grainOf(c);
+                const mounted = {};
+                let withheldAny = false;
+                for (const name of Object.keys(armed)) {
+                    if (!WINDOW_GATED_TOOLS[name].includes(grain)) {
+                        withheldAny = true;
+                        continue;
+                    }
+                    // Grain admits it; a false mount predicate still withholds it — but silently (structural),
+                    // so it must NOT set withheldAny and trip the narrowing audit row.
+                    const gate = mountGates[name];
+                    if (gate && !gate(c))
+                        continue;
+                    mounted[name] = armed[name];
+                }
+                if (withheldAny && isNarrowedGrain(grain))
+                    await auditGateOnce(c, grain);
+                return Object.keys(mounted).length > 0 ? mounted : null;
+            },
+        },
+    });
+}
+/** Resolve a windowGated export the way eve would at `session.started`. Any in-process seam that calls one gated tool from another MUST go through here, so the call rides the same grain gate and execute backstop. */
+export async function resolveWindowGated(gated, ctx) {
+    const resolver = gated.events?.["session.started"];
+    if (typeof resolver !== "function")
+        throw new Error("resolveWindowGated: not a windowGated dynamic tool");
+    return await resolver({ type: "session.started" }, ctx);
+}
+//# sourceMappingURL=window-gated.js.map