ambit-ts 0.1.0

package/dist/core/summary.d.ts

@@ -0,0 +1,240 @@
+import type { UnresolvedReason } from "./backend.ts";
+import type { Budget } from "./budget.ts";
+import type { Capability, CapabilitySet } from "./capability.ts";
+import type { EffectSet, KnownEffect } from "./effects.ts";
+import type { SourceLocation } from "./location.ts";
+import type { SymbolId } from "./symbol-id.ts";
+/** A call resolved to another function Ambit has a summary for. */
+export interface ResolvedCall {
+    readonly kind: "resolved";
+    readonly location: SourceLocation;
+    readonly callee: SymbolId;
+}
+/**
+ * A call matched against a known stub (`src/stubs/`); its effects are known
+ * directly.
+ *
+ * `effects` is a set, not one effect, because an operation's direction is not
+ * always decidable from the source: `pool.query(sql)` with a non-literal
+ * statement may read or write, and the stub table answers with both rather
+ * than picking one (DESIGN.md §4.2, "Operations whose read/write direction is
+ * not statically determined"). One call site produces one
+ * `StubCall` whatever the size of that set — never one per effect, which
+ * would double-count it in `--coverage`.
+ */
+export interface StubCall {
+    readonly kind: "stub";
+    readonly location: SourceLocation;
+    readonly effects: readonly KnownEffect[];
+    readonly qualifiedName: string;
+    /**
+     * The capability this call requires, when the stub tables know of a target
+     * and the source fixes it — a literal URL's host (DESIGN.md §4.4's static
+     * half). Absent when the operation has no target this layer claims to know.
+     */
+    readonly requiredCapability?: Capability;
+    /**
+     * Set when the operation *has* a target the runtime will match but the
+     * source does not fix it (a URL built at runtime). Distinct from having no
+     * requirement at all: the caller's capability requirement is then not fully
+     * known, which is `AMB-W003`, not silence.
+     */
+    readonly capabilityTargetUnknown?: true;
+}
+/**
+ * A call matched against the pure-builtins allowlist (`src/stubs/
+ * pure-builtins.ts`) — a default-lib method (e.g. `Set.has`, `Array.map`)
+ * known to have no effect. `qualifiedName` is in that allowlist's own
+ * namespace (`checker.getFullyQualifiedName()` form), a different space from
+ * `StubCall.qualifiedName`'s module-specifier form — never compare the two.
+ */
+export interface KnownPureCall {
+    readonly kind: "known-pure";
+    readonly location: SourceLocation;
+    readonly qualifiedName: string;
+}
+/**
+ * A call whose target or effects could not be determined (DESIGN.md §4.2
+ * rule 6). `qualifiedName` is carried through from a stub-lookup miss (see
+ * `summarize.ts`'s `toCall`) so `src/checker/coverage.ts` can report which
+ * unresolved names recur most — the signal for "what to stub next".
+ */
+export interface UnresolvedCall {
+    readonly kind: "unresolved";
+    readonly location: SourceLocation;
+    readonly reason: UnresolvedReason;
+    readonly qualifiedName?: string;
+}
+/**
+ * A site that changes a value in place (DESIGN.md §4.2, "Local mutation and
+ * `pure`") — a mutating builtin method (`src/stubs/mutating-builtins.ts`)
+ * or an assignment / `++` / `delete` targeting a property.
+ *
+ * `escaping` is the whole decision: `false` means the mutated value was
+ * allocated inside the function, so no caller can observe the change and the
+ * site carries no effect; `true` means the root is a parameter, `this`, a
+ * module-scope binding, or something the analysis could not pin down, and the
+ * site carries `state_write`. The undecidable case is over-approximated to
+ * `true`, matching the `db_read`/`db_write` rule in §4.2.
+ *
+ * `unknownCallback` is a mutator handed a callback by reference
+ * (`xs.sort(cmp)`): the mutation is known, the callback's own effects are not
+ * (§4.2 rule 4), so the site is both `state_write` and `unknown`.
+ */
+export interface MutationCall {
+    readonly kind: "mutation";
+    readonly location: SourceLocation;
+    readonly escaping: boolean;
+    readonly qualifiedName?: string;
+    readonly unknownCallback?: true;
+}
+export type Call = ResolvedCall | StubCall | KnownPureCall | UnresolvedCall | MutationCall;
+/**
+ * Whether a call site leaves the caller's effect set incomplete — an
+ * unresolved call, or a mutator whose callback was passed by reference.
+ * Both mean "there may be more effects here than are listed".
+ */
+export declare function callLeavesUnknown(call: Call): boolean;
+/**
+ * Whether a function declared `@effects`, and what.
+ *
+ * `{ kind: "none" }` is distinct from a declared empty set: it means no tag
+ * was present at all (undeclared), which this slice treats as a coverage
+ * concern rather than as `unknown` in propagation (DESIGN.md §4.2:
+ * "Undeclared" and "`unknown`" are not the same thing).
+ *
+ * `{ kind: "invalid" }` means a tag was present but contained a token that is
+ * neither `pure` nor a known effect (a typo, e.g. `@effects netwrok`) — see
+ * `AMB-E002` in `diagnose.ts`. Treated the same as `"none"` everywhere except
+ * diagnosis: a broken declaration must not silently collapse to `pure` (an
+ * empty set), and its caller must not trust it as a boundary either.
+ */
+export type DeclaredEffects = {
+    readonly kind: "none";
+} | {
+    readonly kind: "invalid";
+    readonly raw: string;
+} | {
+    readonly kind: "declared";
+    readonly effects: EffectSet;
+};
+/**
+ * Whether a function declared `@capabilities`, and what. Mirrors
+ * {@link DeclaredEffects}: `"invalid"` is a tag that was present but did not
+ * parse, and is treated as undeclared everywhere except diagnosis, so a broken
+ * declaration never reads as a narrower grant than was written.
+ */
+export type DeclaredCapabilities = {
+    readonly kind: "none";
+} | {
+    readonly kind: "invalid";
+    readonly raw: string;
+} | {
+    readonly kind: "declared";
+    readonly capabilities: CapabilitySet;
+};
+/** Whether a function declared `@budget`, and what. */
+export type DeclaredBudget = {
+    readonly kind: "none";
+} | {
+    readonly kind: "invalid";
+    readonly raw: string;
+} | {
+    readonly kind: "declared";
+    readonly budget: Budget;
+};
+/**
+ * Whether a function declared `@boundary` (DESIGN.md §4.6) — an explicit
+ * statement that its body is not statically checked and that the contract it
+ * declares to the outside is to be trusted instead.
+ *
+ * `reason` is required by §4.6, so a tag without one is `"invalid"`: an
+ * unexplained hole in the analysis is the thing the tag exists to make
+ * visible.
+ */
+export type DeclaredBoundary = {
+    readonly kind: "none";
+} | {
+    readonly kind: "invalid";
+    readonly raw: string;
+} | {
+    readonly kind: "declared";
+    readonly reason: string;
+};
+/**
+ * One tag where JSDoc and `ambit.config.ts` both declared something and the
+ * two did not agree (DESIGN.md §4.1: "If a symbol has both JSDoc and config,
+ * JSDoc wins and the difference is warned about"). Reported as `AMB-W005`.
+ *
+ * Both sides are held as their formatted text, not as parsed objects: the
+ * comparison has already happened, and what the message needs is the two
+ * declarations as a reader would recognize them.
+ */
+export interface ContractDivergence {
+    /** The contract tag: `effects`, `capabilities`, `budget`, `entrypoint` or `boundary`. */
+    readonly tag: string;
+    readonly jsDoc: string;
+    readonly config: string;
+}
+/**
+ * Where one declaration came from.
+ *
+ * `"spec"` is a `withAmbit` / `ambitHandler` registration in the same file as
+ * the handler it names, whose `capabilities` / `budget` the source fixes as
+ * literals (DESIGN.md §4.4). It is a declaration, not an observation: the
+ * runtime establishes exactly that set, so the source has already said what
+ * the contract is and the JSDoc tag beside it would only repeat it.
+ *
+ * Only `"jsdoc"` and `"config"` can ever appear on {@link
+ * ContractOrigins.effects}: `@effects` is never delivered to the runtime and
+ * so has no place in a spec.
+ */
+export type DeclarationOrigin = "jsdoc" | "config" | "spec";
+/**
+ * Which side supplied each contract tag, for the tags anything supplied.
+ *
+ * Per tag rather than per function because the sides fill different tags: a
+ * function can take `@effects` from its JSDoc and its capability set from the
+ * registration beside it, and `--coverage`'s `declared-by` breakdown counts
+ * the `effects` half (DESIGN.md §4.1, "Out-of-code declarations").
+ */
+export interface ContractOrigins {
+    readonly effects?: DeclarationOrigin;
+    readonly capabilities?: DeclarationOrigin;
+    readonly budget?: DeclarationOrigin;
+}
+/** Ambit's own representation of one function, independent of any backend. */
+export interface FunctionSummary {
+    readonly id: SymbolId;
+    readonly location: SourceLocation;
+    /**
+     * Where each contract tag was written, carried through from
+     * {@link RawJsDoc.tagLocations} so a fix can rewrite the tag in place
+     * instead of guessing at a line (DESIGN.md §5.3).
+     */
+    readonly tagLocations: ReadonlyMap<string, SourceLocation>;
+    /** Where a new contract comment would go (see {@link ExtractedFunction.declarationStart}). */
+    readonly declarationStart: SourceLocation;
+    /** The existing JSDoc block, when there is exactly one — a tag can be added to it. */
+    readonly jsDocRange?: SourceLocation;
+    /** A class's construction with no constructor written: real, but with nowhere to hang a contract. */
+    readonly implicitConstructor?: true;
+    /** Only `ambit.config.ts` can declare this symbol — see {@link ExtractedFunction.configOnly}. */
+    readonly configOnly?: true;
+    /**
+     * Which side supplied each declared tag, when anything did. Absent for a
+     * function nothing declared anything for. `--coverage` counts the `effects`
+     * half apart so a codebase can see how much of its contract surface lives
+     * outside the code (DESIGN.md §4.1, "Out-of-code declarations").
+     */
+    readonly declaredBy?: ContractOrigins;
+    /** Tags JSDoc and config both declared and disagreed on. JSDoc is what {@link FunctionSummary} carries. */
+    readonly divergences?: readonly ContractDivergence[];
+    readonly declared: DeclaredEffects;
+    readonly capabilities: DeclaredCapabilities;
+    readonly budget: DeclaredBudget;
+    readonly boundary: DeclaredBoundary;
+    /** `@entrypoint` (DESIGN.md §4.1): where the runtime establishes a context. */
+    readonly entrypoint: boolean;
+    readonly calls: readonly Call[];
+}

package/dist/core/summary.js

@@ -0,0 +1,8 @@
+/**
+ * Whether a call site leaves the caller's effect set incomplete — an
+ * unresolved call, or a mutator whose callback was passed by reference.
+ * Both mean "there may be more effects here than are listed".
+ */
+export function callLeavesUnknown(call) {
+    return call.kind === "unresolved" || (call.kind === "mutation" && call.unknownCallback === true);
+}

package/dist/core/symbol-id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A stable identifier for a function or method declaration.
+ *
+ * Built from the file path (relative to the project root passed to
+ * `ambit check`) and a "."-joined declaration path (e.g. `["Foo",
+ * "bar"]` for method `bar` on class `Foo`), joined with `#`
+ * (`src/tax.ts#calculateTax`, matching the form used in DESIGN.md §5.1's
+ * `contract.via[].symbol`).
+ *
+ * Never derived from a compiler-internal id or snapshot offset (DESIGN.md
+ * §5.3), so it stays valid across re-analysis and across backends.
+ */
+export type SymbolId = string & {
+    readonly __brand: "SymbolId";
+};
+export declare function symbolId(relativeFilePath: string, declarationPath: readonly string[]): SymbolId;
+/**
+ * The short, human-facing name for a symbol id: the last segment of the
+ * declaration path (`src/tax.ts#Foo.bar` → `bar`). Used by diagnostic
+ * messages and by the CLI's human-readable rendering, which is why it lives
+ * here rather than beside either one — DESIGN.md §5 makes the text output a
+ * rendering of the structured diagnostic, so both sides must name a symbol
+ * the same way.
+ */
+export declare function displayName(id: SymbolId): string;

package/dist/core/symbol-id.js

@@ -0,0 +1,23 @@
+export function symbolId(relativeFilePath, declarationPath) {
+    return `${relativeFilePath}#${declarationPath.join(".")}`;
+}
+/**
+ * The short, human-facing name for a symbol id: the last segment of the
+ * declaration path (`src/tax.ts#Foo.bar` → `bar`). Used by diagnostic
+ * messages and by the CLI's human-readable rendering, which is why it lives
+ * here rather than beside either one — DESIGN.md §5 makes the text output a
+ * rendering of the structured diagnostic, so both sides must name a symbol
+ * the same way.
+ */
+export function displayName(id) {
+    const afterHash = id.split("#")[1] ?? id;
+    const parts = afterHash.split(".");
+    const last = parts[parts.length - 1];
+    if (last === undefined)
+        return id;
+    // A bare "constructor" names nothing — keep the class with it
+    // (`Client.constructor`), since every class contributes one.
+    if (last === "constructor" && parts.length >= 2)
+        return `${parts[parts.length - 2]}.${last}`;
+    return last;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Package entry point. Re-exports the contract model and diagnostic types so a
+ * consumer can type NDJSON output from `ambit check` without depending on the
+ * checker or on `typescript`.
+ *
+ * Runtime enforcement is a separate entry (`ambit-ts/runtime`) so a production
+ * process imports only what it needs (DESIGN.md §6: "Production uses
+ * `ambit-ts/runtime` and the necessary adapters and contract data. The compiler
+ * and the development CLI are not to be required production dependencies").
+ * The single package does not yet meet that: `typescript` is a `dependencies`
+ * entry, so importing only the runtime still installs the compiler. §6 records
+ * the decision to keep one package until a production adopter exists.
+ */
+export * from "./core/index.ts";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Package entry point. Re-exports the contract model and diagnostic types so a
+ * consumer can type NDJSON output from `ambit check` without depending on the
+ * checker or on `typescript`.
+ *
+ * Runtime enforcement is a separate entry (`ambit-ts/runtime`) so a production
+ * process imports only what it needs (DESIGN.md §6: "Production uses
+ * `ambit-ts/runtime` and the necessary adapters and contract data. The compiler
+ * and the development CLI are not to be required production dependencies").
+ * The single package does not yet meet that: `typescript` is a `dependencies`
+ * entry, so importing only the runtime still installs the compiler. §6 records
+ * the decision to keep one package until a production adopter exists.
+ */
+export * from "./core/index.js";

package/dist/runtime/child-process.d.ts

@@ -0,0 +1,29 @@
+export interface SpawnRequirement {
+    readonly capability: string;
+    readonly detail?: string;
+}
+/**
+ * The capability one `child_process` call requires.
+ *
+ * `spawn`, `execFile` and their `Sync` forms name their program in argv[0],
+ * and it is taken **as written** — no `PATH` lookup, because resolving it
+ * would mean reading the filesystem to answer a question about a string, and
+ * the answer would depend on the environment rather than on the call.
+ *
+ * `exec`, `execSync`, and any form with `shell: true` run a shell. Which
+ * program the shell then runs is inside a shell command string, and naming it
+ * would need a shell parser — the same claim §4.4 forbids for table names
+ * inside arbitrary SQL. So the capability names the shell, and the exception
+ * says exactly that.
+ */
+export declare function spawnCapability(kind: "spawn" | "exec" | "fork", args: readonly unknown[]): SpawnRequirement;
+/**
+ * Replace the checked members of `node:child_process`, returning the function
+ * that puts them back — the shape `installFetchHook` established.
+ *
+ * `spawn` and `fork` have no callback to hand an error to and return a
+ * `ChildProcess` rather than a result, so a denial throws; `exec` and
+ * `execFile` deliver through their callback when one is present, which is
+ * §4.4 (a)'s rule for the callback family.
+ */
+export declare function installChildProcessHook(): () => void;

package/dist/runtime/child-process.js

@@ -0,0 +1,124 @@
+import { createRequire } from "node:module";
+import { checkCapability } from "./enforce.js";
+/** `createRequire` rather than `import`, for the reason `fs.ts` documents. */
+const requireBuiltin = createRequire(import.meta.url);
+const childProcess = requireBuiltin("node:child_process");
+/**
+ * Runtime enforcement for `node:child_process` (DESIGN.md §4.4 (a), (b)).
+ *
+ * Same monkeypatch mechanism and the same install-order caveat as
+ * {@link installFsHook}: installed from a preload it covers named ESM imports
+ * too; installed from inside the module graph it covers the default export and
+ * `requireBuiltin("node:child_process")`, not a named import already bound. It never
+ * covers what happens *inside* the child.
+ */
+/** The default shell `exec` uses when `options.shell` does not name one. */
+const DEFAULT_SHELL = process.platform === "win32" ? "cmd.exe" : "/bin/sh";
+/**
+ * Why a shell spawn cannot name the program that runs. Carried into the
+ * exception text because DESIGN.md §4.4 requires an operation Ambit cannot
+ * decide to say so where the user reads it, not only in the docs.
+ */
+const SHELL_DETAIL = "this spawns a shell, and the granted shell can run any program: the capability names the shell, not the program in the command string";
+/**
+ * The capability one `child_process` call requires.
+ *
+ * `spawn`, `execFile` and their `Sync` forms name their program in argv[0],
+ * and it is taken **as written** — no `PATH` lookup, because resolving it
+ * would mean reading the filesystem to answer a question about a string, and
+ * the answer would depend on the environment rather than on the call.
+ *
+ * `exec`, `execSync`, and any form with `shell: true` run a shell. Which
+ * program the shell then runs is inside a shell command string, and naming it
+ * would need a shell parser — the same claim §4.4 forbids for table names
+ * inside arbitrary SQL. So the capability names the shell, and the exception
+ * says exactly that.
+ */
+export function spawnCapability(kind, args) {
+    if (kind === "fork") {
+        // A fork always runs this Node binary; the module path is an argument to it.
+        return { capability: `proc:spawn:${process.execPath}` };
+    }
+    const shell = shellOption(args);
+    if (kind === "exec" || shell !== undefined) {
+        return { capability: `proc:spawn:${shell ?? DEFAULT_SHELL}`, detail: SHELL_DETAIL };
+    }
+    const command = typeof args[0] === "string" ? args[0] : undefined;
+    if (command === undefined) {
+        return {
+            capability: "proc:spawn:unknown",
+            detail: "the command is not a string in this call, so it cannot be named",
+        };
+    }
+    return { capability: `proc:spawn:${command}` };
+}
+/**
+ * `options.shell` when the call asks for a shell, `undefined` when it does
+ * not. `shell: true` means the platform default.
+ */
+function shellOption(args) {
+    for (const argument of args.slice(1)) {
+        if (argument === null || typeof argument !== "object" || Array.isArray(argument))
+            continue;
+        const shell = argument.shell;
+        if (typeof shell === "string")
+            return shell;
+        if (shell === true)
+            return DEFAULT_SHELL;
+        return undefined;
+    }
+    return undefined;
+}
+/** Which member takes which shape of argument, and how a denial is delivered. */
+const OPERATIONS = [
+    { name: "spawn", kind: "spawn", family: "sync" },
+    { name: "spawnSync", kind: "spawn", family: "sync" },
+    { name: "execFile", kind: "spawn", family: "callback" },
+    { name: "execFileSync", kind: "spawn", family: "sync" },
+    { name: "exec", kind: "exec", family: "callback" },
+    { name: "execSync", kind: "exec", family: "sync" },
+    { name: "fork", kind: "fork", family: "sync" },
+];
+/**
+ * Replace the checked members of `node:child_process`, returning the function
+ * that puts them back — the shape `installFetchHook` established.
+ *
+ * `spawn` and `fork` have no callback to hand an error to and return a
+ * `ChildProcess` rather than a result, so a denial throws; `exec` and
+ * `execFile` deliver through their callback when one is present, which is
+ * §4.4 (a)'s rule for the callback family.
+ */
+export function installChildProcessHook() {
+    const host = childProcess;
+    const restores = [];
+    for (const { name, kind, family } of OPERATIONS) {
+        const original = host[name];
+        if (typeof original !== "function")
+            continue;
+        const target = original;
+        const hooked = function (...args) {
+            const { capability, detail } = spawnCapability(kind, args);
+            const error = checkCapability(capability, detail);
+            if (!error)
+                return target.apply(this, args);
+            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;
+        });
+    }
+    return () => {
+        for (const restore of restores)
+            restore();
+    };
+}

package/dist/runtime/context.d.ts

@@ -0,0 +1,37 @@
+import type { Budget, Capability } from "../core/index.ts";
+/**
+ * The capability and budget context an entrypoint establishes (DESIGN.md
+ * §4.4). `AsyncLocalStorage` holds the context; the blocking itself is the
+ * hooks' job — §4.4 is explicit that the two are separate
+ * ("`AsyncLocalStorage` is responsible for holding the context; the blocking
+ * itself is implemented by the adapter").
+ *
+ * Nothing here imports `typescript` or anything under `src/checker/`:
+ * §3.4 keeps runtime enforcement independent of the analysis engine, so
+ * production never depends on a compiler. `test/architecture.test.ts`
+ * enforces that.
+ */
+export interface AmbitContext {
+    readonly capabilities: readonly Capability[];
+    readonly budget?: Budget;
+    /** Wall-clock start, for `timeMs`. */
+    readonly startedAt: number;
+    /** Aborted when a `timeMs` budget with `onExceed: "abort"` runs out. */
+    readonly signal?: AbortSignal;
+    /** Every capability check made in this context, for auditing. */
+    readonly audit: AuditEntry[];
+}
+export interface AuditEntry {
+    readonly capability: string;
+    readonly allowed: boolean;
+    readonly reason: "granted" | "denied" | "unscoped";
+}
+/**
+ * What a capability check does when no entrypoint context is active
+ * (DESIGN.md §4.4 `runtime.unscoped`). `allow` is the default so that
+ * adopting the runtime does not break code that has no entrypoints declared
+ * yet (P3: incremental adoption).
+ */
+export type UnscopedPolicy = "allow" | "warn" | "deny";
+export declare function currentContext(): AmbitContext | undefined;
+export declare function runInContext<T>(context: AmbitContext, fn: () => T): T;

package/dist/runtime/context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function currentContext() {
+    return storage.getStore();
+}
+export function runInContext(context, fn) {
+    return storage.run(context, fn);
+}

package/dist/runtime/enforce.d.ts

@@ -0,0 +1,52 @@
+import type { Capability } from "../core/index.ts";
+import type { UnscopedPolicy } from "./context.ts";
+/**
+ * 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 declare class AmbitCapabilityError extends Error {
+    readonly capability: string;
+    constructor(capability: string, granted: readonly Capability[], detail?: string);
+}
+/**
+ * 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 declare function setUnscopedPolicy(policy: UnscopedPolicy): void;
+/**
+ * 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 declare function checkCapability(required: string, detail?: string): AmbitCapabilityError | undefined;
+/**
+ * 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 declare function checkCapabilities(required: readonly string[], detail?: string): AmbitCapabilityError | undefined;
+/**
+ * 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 declare function requireCapability(required: string, detail?: string): void;