ambit-ts 0.1.0

package/dist/runtime/enforce.js

@@ -0,0 +1,95 @@
+import { capabilityCovers, formatCapability, parseCapability } from "../core/index.js";
+import { currentContext } from "./context.js";
+/**
+ * The capability decision every hook shares (DESIGN.md §4.4).
+ *
+ * Separate from `index.ts` so that `fs.ts`, `child-process.ts` and `pg.ts` can
+ * import the decision without importing the module that installs them, and so
+ * that the `runtime.unscoped` policy is one variable rather than one per hook.
+ */
+export class AmbitCapabilityError extends Error {
+    capability;
+    constructor(capability, granted, detail) {
+        const grantedList = granted.map(formatCapability).join(", ") || "(none)";
+        const suffix = detail ? ` — ${detail}` : "";
+        super(`capability ${capability} is not granted by this entrypoint (granted: ${grantedList})${suffix}`);
+        this.name = "AmbitCapabilityError";
+        this.capability = capability;
+    }
+}
+let unscopedPolicy = "allow";
+/**
+ * Set the process-wide `runtime.unscoped` policy (DESIGN.md §4.4).
+ *
+ * Process-wide and not per-entrypoint on purpose. The policy only applies
+ * where there is *no* context, so a per-entrypoint override would be read
+ * only by concurrent work running outside every entrypoint — which makes it a
+ * mutable global that unrelated calls observe changing mid-flight, not a
+ * setting scoped to anything. Set it once at startup.
+ */
+export function setUnscopedPolicy(policy) {
+    unscopedPolicy = policy;
+}
+/**
+ * Decide one capability without throwing, so a callback-style API can deliver
+ * the denial the way its caller expects (DESIGN.md §4.4: "synchronous APIs
+ * `throw`, callback APIs use `process.nextTick(callback, error)`, and Promise
+ * APIs reject").
+ *
+ * Returns the error to deliver, or `undefined` when the operation is allowed.
+ * Every decision inside a context — allowed or denied — is appended to the
+ * context's {@link AuditEntry} list.
+ */
+export function checkCapability(required, detail) {
+    const context = currentContext();
+    if (!context) {
+        if (unscopedPolicy === "deny") {
+            return new AmbitCapabilityError(required, [], detail ?? "no @entrypoint context is active");
+        }
+        if (unscopedPolicy === "warn") {
+            process.emitWarning(`capability ${required} used outside any @entrypoint context`, "AmbitUnscoped");
+        }
+        return undefined;
+    }
+    const parsed = parseCapability(required);
+    const allowed = parsed !== undefined && context.capabilities.some((grant) => capabilityCovers(grant, parsed));
+    const entry = {
+        capability: required,
+        allowed,
+        reason: allowed ? "granted" : "denied",
+    };
+    context.audit.push(entry);
+    if (allowed)
+        return undefined;
+    return new AmbitCapabilityError(required, context.capabilities, detail);
+}
+/**
+ * Decide several capabilities at once, all of which are required. Used where
+ * one operation touches two resources (`fs.rename`) or where the source does
+ * not fix the direction, so both directions are required (an opaque SQL
+ * statement — DESIGN.md §4.4 (c)).
+ *
+ * Every capability is checked, so the audit records all of them, and the
+ * first denial is the one reported.
+ */
+export function checkCapabilities(required, detail) {
+    let first;
+    for (const capability of required) {
+        const error = checkCapability(capability, detail);
+        if (error && !first)
+            first = error;
+    }
+    return first;
+}
+/**
+ * Check one capability against the active entrypoint context, throwing
+ * {@link AmbitCapabilityError} when it is not granted. Exported so an adapter
+ * for an unhooked client can perform the same check.
+ *
+ * With no active context the `runtime.unscoped` policy decides (§4.4).
+ */
+export function requireCapability(required, detail) {
+    const error = checkCapability(required, detail);
+    if (error)
+        throw error;
+}

package/dist/runtime/fs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime enforcement for `node:fs` and `node:fs/promises` (DESIGN.md §4.4
+ * (a), (b)).
+ *
+ * The mechanism is a monkeypatch of the module's own exports object, chosen
+ * over `diagnostics_channel` (which cannot block: a subscriber's `throw` does
+ * not stop `publish`) and over a loader hook (which covers nothing a
+ * monkeypatch does not). What a monkeypatch covers depends on *when* it is
+ * installed, not on the mechanism:
+ *
+ * - installed before anything has `import`ed `node:fs` — from a
+ *   `node --import` / `--require` preload — every form is covered, named ESM
+ *   imports included;
+ * - installed from inside the module graph, every `fs.readFile()` through the
+ *   default export or `requireBuiltin("node:fs")`, but not a named import
+ *   (`import { readFile } from "node:fs"`) that was already bound.
+ *
+ * `docs/limitations.md` states both, and neither covers native addons, a
+ * child process, or another worker thread.
+ */
+/** Which paths an operation reads and which it writes, by argument position. */
+interface FsRule {
+    readonly reads?: readonly number[];
+    readonly writes?: readonly number[];
+}
+/**
+ * The capabilities one path argument needs. Exported so a caller can see
+ * exactly what a given path resolves to before granting it.
+ *
+ * Relative paths resolve against `process.cwd()` *at the time of the call*,
+ * `Buffer` paths are decoded, and a `file:` URL is converted — §4.4 (b)'s
+ * normalisation, so that one file has one spelling in a grant.
+ */
+export declare function fsCapabilities(rule: FsRule, args: readonly unknown[]): readonly string[];
+/** The capabilities an `open` needs, from its `flags` argument (default `"r"`). */
+export declare function openCapabilities(args: readonly unknown[]): readonly string[];
+/**
+ * Replace the checked members of `node:fs` and `node:fs/promises`, returning
+ * the function that puts every one of them back.
+ *
+ * Same shape as `installFetchHook`: install returns restore, and restore only
+ * undoes what is still ours, so a hook installed on top of this one is not
+ * clobbered (P5: backing out at any time).
+ */
+export declare function installFsHook(): () => void;
+export {};

package/dist/runtime/fs.js

@@ -0,0 +1,188 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkCapabilities } from "./enforce.js";
+/**
+ * `require`, not `import`, and the difference is load-bearing.
+ *
+ * A builtin's ESM namespace is a snapshot of its properties taken when that
+ * builtin is first `import`ed. `import fs from "node:fs"` here would take
+ * that snapshot before this module has patched anything, and every
+ * `import { readFileSync } from "node:fs"` in the application would then be
+ * bound to the original — even from a preload. Reaching the module through
+ * `createRequire` leaves the snapshot to be taken later, from the patched object,
+ * which is what makes §4.4 (a)'s preload row true. Measured both ways.
+ */
+const requireBuiltin = createRequire(import.meta.url);
+const fs = requireBuiltin("node:fs");
+const fsPromises = requireBuiltin("node:fs/promises");
+/**
+ * The operations this hook checks. Anything absent is not checked and not
+ * recorded — `docs/limitations.md` lists what that leaves out rather than
+ * letting the omission read as "allowed".
+ *
+ * `open` is checked by flags rather than by name, so it appears in
+ * {@link FLAG_OPERATIONS} instead. `createReadStream` / `createWriteStream`
+ * are absent on purpose: both go through `fs.open`, which this hook replaces,
+ * so they are covered at that entry point (measured).
+ */
+const OPERATIONS = new Map([
+    ["readFile", { reads: [0] }],
+    ["readdir", { reads: [0] }],
+    ["access", { reads: [0] }],
+    ["stat", { reads: [0] }],
+    ["lstat", { reads: [0] }],
+    ["realpath", { reads: [0] }],
+    ["readlink", { reads: [0] }],
+    ["writeFile", { writes: [0] }],
+    ["appendFile", { writes: [0] }],
+    ["mkdir", { writes: [0] }],
+    ["rmdir", { writes: [0] }],
+    ["rm", { writes: [0] }],
+    ["unlink", { writes: [0] }],
+    ["truncate", { writes: [0] }],
+    ["chmod", { writes: [0] }],
+    ["symlink", { writes: [1] }],
+    ["rename", { reads: [0], writes: [1] }],
+    ["copyFile", { reads: [0], writes: [1] }],
+    ["link", { reads: [0], writes: [1] }],
+]);
+/** `open` decides its direction from `flags`, so it is handled apart from {@link OPERATIONS}. */
+const FLAG_OPERATIONS = new Set(["open"]);
+/**
+ * `existsSync` is the one read that must not answer `false` when denied
+ * (DESIGN.md §4.4 (a)): "not there" and "not allowed to look" are different
+ * answers, and returning `false` would report the second as the first.
+ */
+const SYNC_ONLY = new Set(["existsSync"]);
+/**
+ * The capabilities one path argument needs. Exported so a caller can see
+ * exactly what a given path resolves to before granting it.
+ *
+ * Relative paths resolve against `process.cwd()` *at the time of the call*,
+ * `Buffer` paths are decoded, and a `file:` URL is converted — §4.4 (b)'s
+ * normalisation, so that one file has one spelling in a grant.
+ */
+export function fsCapabilities(rule, args) {
+    const required = [];
+    for (const index of rule.reads ?? []) {
+        const target = normalizePath(args[index]);
+        if (target !== undefined)
+            required.push(`fs:read:${target}`);
+    }
+    for (const index of rule.writes ?? []) {
+        const target = normalizePath(args[index]);
+        if (target !== undefined)
+            required.push(`fs:write:${target}`);
+    }
+    return required;
+}
+/**
+ * `undefined` for an argument that names no path — a file descriptor, which
+ * `fs.readSync(fd)` takes. The path was checked when the descriptor was
+ * opened; checking it again here is impossible, not merely skipped.
+ */
+function normalizePath(value) {
+    if (typeof value === "number")
+        return undefined;
+    let text;
+    if (typeof value === "string")
+        text = value;
+    else if (value instanceof URL)
+        text = fileURLToPath(value);
+    else if (Buffer.isBuffer(value))
+        text = value.toString("utf8");
+    else
+        return undefined;
+    return path.resolve(text);
+}
+/** The capabilities an `open` needs, from its `flags` argument (default `"r"`). */
+export function openCapabilities(args) {
+    const target = normalizePath(args[0]);
+    if (target === undefined)
+        return [];
+    const flags = args[1];
+    const rule = openFlagsRule(flags);
+    return fsCapabilities(rule, [target, target]);
+}
+function openFlagsRule(flags) {
+    // A missing or non-flag second argument means the default, `"r"`.
+    if (typeof flags === "number") {
+        const access = flags & 0b11;
+        if (access === fs.constants.O_WRONLY)
+            return { writes: [1] };
+        if (access === fs.constants.O_RDWR)
+            return { reads: [0], writes: [1] };
+        return { reads: [0] };
+    }
+    if (typeof flags !== "string")
+        return { reads: [0] };
+    const reads = flags.startsWith("r") || flags.includes("+");
+    const writes = flags.includes("w") || flags.includes("a") || flags.includes("+");
+    return {
+        ...(reads ? { reads: [0] } : {}),
+        ...(writes ? { writes: [1] } : {}),
+    };
+}
+/**
+ * Replace the checked members of `node:fs` and `node:fs/promises`, returning
+ * the function that puts every one of them back.
+ *
+ * Same shape as `installFetchHook`: install returns restore, and restore only
+ * undoes what is still ours, so a hook installed on top of this one is not
+ * clobbered (P5: backing out at any time).
+ */
+export function installFsHook() {
+    const restores = [];
+    for (const [name, rule] of OPERATIONS) {
+        patch(fs, name, (args) => fsCapabilities(rule, args), "callback", restores);
+        patch(fs, `${name}Sync`, (args) => fsCapabilities(rule, args), "sync", restores);
+        patch(fsPromises, name, (args) => fsCapabilities(rule, args), "promise", restores);
+    }
+    for (const name of FLAG_OPERATIONS) {
+        patch(fs, name, openCapabilities, "callback", restores);
+        patch(fs, `${name}Sync`, openCapabilities, "sync", restores);
+        patch(fsPromises, name, openCapabilities, "promise", restores);
+    }
+    for (const name of SYNC_ONLY) {
+        patch(fs, name, (args) => fsCapabilities({ reads: [0] }, args), "sync", restores);
+    }
+    return () => {
+        for (const restore of restores)
+            restore();
+    };
+}
+/**
+ * Deliver a denial the way the API's own errors arrive: `throw` for the sync
+ * family, `process.nextTick(callback, error)` for the callback family, a
+ * rejected promise for `fs/promises` (DESIGN.md §4.4 (a)). A callback API that
+ * threw synchronously would break `try`/`catch`-free call sites that are
+ * correct as written.
+ */
+function patch(host, name, capabilities, family, restores) {
+    const original = host[name];
+    if (typeof original !== "function")
+        return;
+    const target = original;
+    const hooked = function (...args) {
+        const error = checkCapabilities(capabilities(args));
+        if (!error)
+            return target.apply(this, args);
+        if (family === "promise")
+            return Promise.reject(error);
+        if (family === "callback") {
+            const callback = args[args.length - 1];
+            if (typeof callback === "function") {
+                process.nextTick(callback, error);
+                return undefined;
+            }
+        }
+        throw error;
+    };
+    Object.defineProperty(hooked, "name", { value: name });
+    host[name] = hooked;
+    restores.push(() => {
+        if (host[name] === hooked)
+            host[name] = original;
+    });
+}

package/dist/runtime/hono.d.ts

@@ -0,0 +1,55 @@
+import type { Context, Env, Handler, Input } from "hono";
+import type { AmbitSpec } from "./index.ts";
+/**
+ * The Hono adapter (DESIGN.md §4.4, "Mapping contracts to handlers").
+ *
+ * `hono` is imported for **types only** and is a devDependency here, never a
+ * dependency of the published package — the same reason `installPgHook(pg)`
+ * takes the module from the caller instead of importing `pg` (§4.4 (c)).
+ * Nothing in this file imports `typescript` or anything under `src/checker/`.
+ */
+/**
+ * Register a contract-bearing handler on a Hono route, establishing the
+ * entrypoint's capability set and budget for the whole request.
+ *
+ * ```ts
+ * app.post("/orders", ambitHandler(
+ *   { capabilities: ["db:write:orders"], budget: { timeMs: 800 } },
+ *   createOrder,
+ *   async (c) => [await c.req.json<CreateOrderInput>()] as const,
+ * ));
+ * ```
+ *
+ * The three arguments are the decision §4.4 records, not a convenience:
+ *
+ * - `spec` sits in the same call as `handler`, so a literal one *is* that
+ *   handler's `@capabilities` and `@budget`: the tags need not repeat what the
+ *   registration already says. Where both are written, `ambit check` compares
+ *   them — the capability list against `@capabilities` (`AMB-E010`), and
+ *   `spec.budget` against `@budget` (`AMB-E011`, with an omitted `onExceed`
+ *   defaulted to `throw` on both sides) — and a disagreement is an error. The
+ *   two halves are judged independently: a spec may write one as a literal and
+ *   build the other at runtime, and `AMB-W004` reports whichever half could
+ *   neither declare nor be compared, where the handler's own JSDoc is then the
+ *   only declaration. Explicit registration was chosen over generated contract
+ *   data because the contract is then a value in the module — it survives a
+ *   build that strips comments, and a bundler that renames everything.
+ * - `decode` keeps the framework out of `handler`. Hono's `Context` is in no
+ *   stub table, so a `c.req.json()` inside a contract-bearing function would
+ *   make that function's requirement partly `unknown` (`AMB-W003`). Isolated
+ *   here, the handler stays framework-agnostic and statically analyzable.
+ *   It runs **inside** the context: reading the request body counts toward
+ *   `timeMs`.
+ *
+ * `AmbitCapabilityError` and `AmbitBudgetError` are **not** translated into
+ * HTTP statuses. A denied capability is this server's own code exceeding its
+ * grant, which is not what 403 says, and the message names the granted set —
+ * so it goes to the framework's error handler, not to the client (§4.4).
+ *
+ * A handler registered without this adapter establishes no context at all;
+ * what its operations do then is `setUnscopedPolicy`'s decision (`allow` by
+ * default). The adapter never invents an empty-capability context for a route
+ * it was not given, because a deny-everything context is indistinguishable
+ * from a missed registration.
+ */
+export declare function ambitHandler<Args extends readonly unknown[], Result, E extends Env = Env, P extends string = string, I extends Input = Input>(spec: AmbitSpec, handler: (...args: Args) => Result | Promise<Result>, decode: (c: Context<E, P, I>) => readonly [...Args] | Promise<readonly [...Args]>): Handler<E, P, I>;

package/dist/runtime/hono.js

@@ -0,0 +1,68 @@
+import { withAmbit } from "./index.js";
+/**
+ * The Hono adapter (DESIGN.md §4.4, "Mapping contracts to handlers").
+ *
+ * `hono` is imported for **types only** and is a devDependency here, never a
+ * dependency of the published package — the same reason `installPgHook(pg)`
+ * takes the module from the caller instead of importing `pg` (§4.4 (c)).
+ * Nothing in this file imports `typescript` or anything under `src/checker/`.
+ */
+/**
+ * Register a contract-bearing handler on a Hono route, establishing the
+ * entrypoint's capability set and budget for the whole request.
+ *
+ * ```ts
+ * app.post("/orders", ambitHandler(
+ *   { capabilities: ["db:write:orders"], budget: { timeMs: 800 } },
+ *   createOrder,
+ *   async (c) => [await c.req.json<CreateOrderInput>()] as const,
+ * ));
+ * ```
+ *
+ * The three arguments are the decision §4.4 records, not a convenience:
+ *
+ * - `spec` sits in the same call as `handler`, so a literal one *is* that
+ *   handler's `@capabilities` and `@budget`: the tags need not repeat what the
+ *   registration already says. Where both are written, `ambit check` compares
+ *   them — the capability list against `@capabilities` (`AMB-E010`), and
+ *   `spec.budget` against `@budget` (`AMB-E011`, with an omitted `onExceed`
+ *   defaulted to `throw` on both sides) — and a disagreement is an error. The
+ *   two halves are judged independently: a spec may write one as a literal and
+ *   build the other at runtime, and `AMB-W004` reports whichever half could
+ *   neither declare nor be compared, where the handler's own JSDoc is then the
+ *   only declaration. Explicit registration was chosen over generated contract
+ *   data because the contract is then a value in the module — it survives a
+ *   build that strips comments, and a bundler that renames everything.
+ * - `decode` keeps the framework out of `handler`. Hono's `Context` is in no
+ *   stub table, so a `c.req.json()` inside a contract-bearing function would
+ *   make that function's requirement partly `unknown` (`AMB-W003`). Isolated
+ *   here, the handler stays framework-agnostic and statically analyzable.
+ *   It runs **inside** the context: reading the request body counts toward
+ *   `timeMs`.
+ *
+ * `AmbitCapabilityError` and `AmbitBudgetError` are **not** translated into
+ * HTTP statuses. A denied capability is this server's own code exceeding its
+ * grant, which is not what 403 says, and the message names the granted set —
+ * so it goes to the framework's error handler, not to the client (§4.4).
+ *
+ * A handler registered without this adapter establishes no context at all;
+ * what its operations do then is `setUnscopedPolicy`'s decision (`allow` by
+ * default). The adapter never invents an empty-capability context for a route
+ * it was not given, because a deny-everything context is indistinguishable
+ * from a missed registration.
+ */
+export function ambitHandler(spec, handler, decode) {
+    const scoped = withAmbit(spec, async (c) => 
+    // `decode` may return a `readonly` tuple — `[x] as const` is what a caller
+    // naturally writes — and a readonly tuple spreads into rest parameters.
+    handler(...(await decode(c))));
+    return async (c) => {
+        const result = await scoped(c);
+        // `Response.json` rather than `c.json`: the handler's return type is the
+        // domain's, not Hono's `JSONValue`, and forcing it through that generic
+        // would mean casting every handler. The cost is that Hono's RPC type
+        // inference (`hc`) sees `Response`, not the handler's shape —
+        // `docs/limitations.md` records it.
+        return result instanceof Response ? result : Response.json(result ?? null);
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,71 @@
+import type { BudgetInput } from "../core/index.ts";
+export type { BudgetInput, OnExceed } from "../core/index.ts";
+export { installChildProcessHook, spawnCapability } from "./child-process.ts";
+export type { AmbitContext, AuditEntry, UnscopedPolicy } from "./context.ts";
+export { currentContext } from "./context.ts";
+export { AmbitCapabilityError, checkCapabilities, checkCapability, requireCapability, setUnscopedPolicy, } from "./enforce.ts";
+export { fsCapabilities, installFsHook } from "./fs.ts";
+export { installPgHook, pgCapabilities } from "./pg.ts";
+/**
+ * Runtime enforcement for an entrypoint (DESIGN.md §4.4, §4.5).
+ *
+ * Deliberately narrow, and the narrowness is the point: this enforces what it
+ * can actually check and says nothing about the rest. What is enforced today:
+ *
+ * - **capabilities**, for `globalThis.fetch` ({@link installFetchHook}),
+ *   `node:fs` and `node:fs/promises` ({@link installFsHook}),
+ *   `node:child_process` ({@link installChildProcessHook}), and the `pg`
+ *   client ({@link installPgHook}) — each once its hook has been installed.
+ *   Every other operation is unhooked and therefore unenforced: `mysql2`,
+ *   `@prisma/client`, `drizzle-orm`, `mongodb`, and every LLM SDK.
+ * - **`timeMs`**, checked when the handler settles (`throw`/`warn`) or via an
+ *   `AbortSignal` (`abort`).
+ *
+ * What is **not** enforced: `costUsd` and `llmCalls`. There is no LLM hook, so
+ * nothing would increment those counters; reporting them as enforced would be
+ * a number nobody measures. They are carried on the context for an adapter to
+ * use and are otherwise inert.
+ */
+export interface AmbitSpec {
+    /** The entrypoint's `@capabilities`, as written (`db:read:users`). */
+    readonly capabilities?: readonly string[];
+    /**
+     * The entrypoint's `@budget`, as written — `onExceed` may be omitted, and
+     * `{ timeMs: 500 }` is a complete spec. The default is resolved here, once,
+     * so the context an adapter reads always carries a settled policy.
+     */
+    readonly budget?: BudgetInput;
+}
+export declare class AmbitBudgetError extends Error {
+    constructor(message: string);
+}
+/**
+ * Run `handler` with the entrypoint's capability set and budget established
+ * (DESIGN.md §4.4: "Where there is no adapter, insert
+ * `withAmbit(spec, handler)` by hand").
+ *
+ * A malformed capability string throws at wrap time rather than being
+ * dropped: a grant that does not parse would silently become "grants nothing",
+ * and the handler would fail in a way that looks like a policy decision.
+ */
+export declare function withAmbit<Args extends readonly unknown[], Result>(spec: AmbitSpec, handler: (...args: Args) => Result | Promise<Result>): (...args: Args) => Promise<Result>;
+/**
+ * Wrap `globalThis.fetch` so every request is checked against the active
+ * entrypoint's capabilities as `http:<method>:<host>`.
+ *
+ * One of four hooks; see {@link installFsHook},
+ * {@link installChildProcessHook} and {@link installPgHook} for the rest.
+ * DESIGN.md §4.4's remaining targets — `mysql2`, `@prisma/client`,
+ * `drizzle-orm`, `mongodb`, and the LLM SDKs — are not hooked, and calling
+ * them is neither checked nor recorded.
+ *
+ * Returns a function that restores the original `fetch`, so a test — or a
+ * consumer backing Ambit out (P5) — can undo it.
+ */
+export declare function installFetchHook(): () => void;
+/**
+ * `http:<method>:<host>` for a request. The host includes the port when the
+ * URL carries one (`127.0.0.1:8080`), which is why a capability's target
+ * segment is allowed to contain a colon.
+ */
+export declare function fetchCapability(input: Parameters<typeof fetch>[0], init?: RequestInit): string;

package/dist/runtime/index.js

@@ -0,0 +1,126 @@
+import { DEFAULT_ON_EXCEED, parseCapability } from "../core/index.js";
+import { currentContext, runInContext } from "./context.js";
+import { requireCapability } from "./enforce.js";
+export { installChildProcessHook, spawnCapability } from "./child-process.js";
+export { currentContext } from "./context.js";
+export { AmbitCapabilityError, checkCapabilities, checkCapability, requireCapability, setUnscopedPolicy, } from "./enforce.js";
+export { fsCapabilities, installFsHook } from "./fs.js";
+export { installPgHook, pgCapabilities } from "./pg.js";
+export class AmbitBudgetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AmbitBudgetError";
+    }
+}
+/**
+ * Run `handler` with the entrypoint's capability set and budget established
+ * (DESIGN.md §4.4: "Where there is no adapter, insert
+ * `withAmbit(spec, handler)` by hand").
+ *
+ * A malformed capability string throws at wrap time rather than being
+ * dropped: a grant that does not parse would silently become "grants nothing",
+ * and the handler would fail in a way that looks like a policy decision.
+ */
+export function withAmbit(spec, handler) {
+    const capabilities = (spec.capabilities ?? []).map((text) => {
+        const capability = parseCapability(text);
+        if (!capability) {
+            throw new TypeError(`withAmbit: "${text}" is not a <resource>:<action>:<target> capability`);
+        }
+        return capability;
+    });
+    // Resolved once, at wrap time: neither depends on the arguments, and the
+    // context must carry a settled `onExceed` so an adapter reading it does not
+    // have to know the default.
+    const timeMs = spec.budget?.timeMs;
+    const onExceed = spec.budget?.onExceed ?? DEFAULT_ON_EXCEED;
+    const budget = spec.budget ? { ...spec.budget, onExceed } : undefined;
+    return async (...args) => {
+        const controller = new AbortController();
+        const context = {
+            capabilities,
+            ...(budget ? { budget } : {}),
+            startedAt: Date.now(),
+            signal: controller.signal,
+            audit: [],
+        };
+        let timer;
+        if (timeMs !== undefined && onExceed === "abort") {
+            timer = setTimeout(() => controller.abort(new AmbitBudgetError(exceeded(timeMs))), timeMs);
+            timer.unref?.();
+        }
+        try {
+            const result = await runInContext(context, () => handler(...args));
+            const elapsed = Date.now() - context.startedAt;
+            if (timeMs !== undefined && elapsed > timeMs) {
+                // Checked after the fact, and that is all this can honestly be:
+                // §4.5 says a budget does not undo spend already incurred or stop
+                // work that cannot be cancelled.
+                if (onExceed === "throw")
+                    throw new AmbitBudgetError(exceeded(timeMs, elapsed));
+                if (onExceed === "warn")
+                    process.emitWarning(exceeded(timeMs, elapsed), "AmbitBudget");
+            }
+            return result;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+}
+function exceeded(timeMs, elapsed) {
+    const actual = elapsed === undefined ? "" : ` (took ${elapsed}ms)`;
+    return `budget timeMs=${timeMs} exceeded${actual}`;
+}
+/**
+ * Wrap `globalThis.fetch` so every request is checked against the active
+ * entrypoint's capabilities as `http:<method>:<host>`.
+ *
+ * One of four hooks; see {@link installFsHook},
+ * {@link installChildProcessHook} and {@link installPgHook} for the rest.
+ * DESIGN.md §4.4's remaining targets — `mysql2`, `@prisma/client`,
+ * `drizzle-orm`, `mongodb`, and the LLM SDKs — are not hooked, and calling
+ * them is neither checked nor recorded.
+ *
+ * Returns a function that restores the original `fetch`, so a test — or a
+ * consumer backing Ambit out (P5) — can undo it.
+ */
+export function installFetchHook() {
+    const original = globalThis.fetch;
+    if (typeof original !== "function") {
+        throw new TypeError("installFetchHook: globalThis.fetch is not available");
+    }
+    const hooked = async (input, init) => {
+        requireCapability(fetchCapability(input, init));
+        // `onExceed: "abort"` aborts the entrypoint's signal; without joining it
+        // to the request, the signal would fire and the request would keep going,
+        // making the "abort" row of the README table false.
+        const budgetSignal = currentContext()?.signal;
+        if (!budgetSignal)
+            return original(input, init);
+        const signal = init?.signal ? AbortSignal.any([budgetSignal, init.signal]) : budgetSignal;
+        return original(input, { ...init, signal });
+    };
+    globalThis.fetch = hooked;
+    return () => {
+        // Only restore if nothing else re-wrapped fetch in the meantime;
+        // clobbering someone else's hook would be worse than leaving ours on.
+        if (globalThis.fetch === hooked)
+            globalThis.fetch = original;
+    };
+}
+/**
+ * `http:<method>:<host>` for a request. The host includes the port when the
+ * URL carries one (`127.0.0.1:8080`), which is why a capability's target
+ * segment is allowed to contain a colon.
+ */
+export function fetchCapability(input, init) {
+    const url = input instanceof URL
+        ? input
+        : new URL(typeof input === "string" ? input : input.url);
+    const method = (init?.method ??
+        (typeof input === "object" && "method" in input ? input.method : undefined) ??
+        "GET").toLowerCase();
+    return `http:${method}:${url.host}`;
+}