ambit-ts 0.1.0

package/dist/runtime/next.d.ts

@@ -0,0 +1,95 @@
+import type { NextRequest } from "next/server.js";
+import type { AmbitSpec } from "./index.ts";
+/**
+ * The Next.js App Router adapter (DESIGN.md §4.4, "Mapping contracts to
+ * handlers").
+ *
+ * `next` is imported for **types only** and is a devDependency here, never a
+ * dependency of the published package — the same treatment `hono` gets in
+ * `./hono.ts`, and 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/`.
+ *
+ * **What this adapter does not reach.** It covers one thing: a Route Handler
+ * exported from `app/**\/route.ts` and registered through {@link ambitRoute},
+ * running on the Node.js runtime. It establishes no context for, and enforces
+ * nothing in:
+ *
+ * - a route that sets `export const runtime = "edge"` — the hooks
+ *   (`installFetchHook` and friends) are Node.js hooks and are not installed
+ *   there, so no capability is checked on such a route. Nothing else about
+ *   `ambitRoute` on Edge is claimed either: no test runs there. DESIGN.md §12
+ *   "Edge runtimes": Phase 1 guarantees Node.js only.
+ * - Server Actions (`"use server"`), which are not route modules and have no
+ *   registration call to attach a spec to.
+ * - `middleware.ts`, which runs on the Edge runtime and outside any route
+ *   module.
+ * - the Pages Router (`pages/api/*`), which has a different handler shape.
+ *
+ * Reaching any of those is out of scope for this adapter, not something it
+ * silently half-covers: with no `ambitRoute` registration there is no context
+ * at all, and what an operation does then is `setUnscopedPolicy`'s decision
+ * (`allow` by default).
+ */
+/**
+ * The second argument Next.js passes a Route Handler: the matched dynamic
+ * segments. Declared here rather than imported because Next.js generates the
+ * per-route version into `.next/types/`, which does not exist in a repository
+ * that never runs `next build`.
+ */
+export interface RouteContext<Params extends Record<string, string | readonly string[]> = Record<string, string | readonly string[]>> {
+    /** A Promise since Next.js 15; `await`ed inside the context by `decode`. */
+    readonly params: Promise<Params>;
+}
+/**
+ * The shape Next.js expects `export const GET = …` in `app/**\/route.ts` to
+ * have.
+ */
+export type RouteHandler<Params extends Record<string, string | readonly string[]> = Record<string, string | readonly string[]>> = (request: NextRequest, context: RouteContext<Params>) => Promise<Response>;
+/**
+ * Register a contract-bearing handler as a Next.js Route Handler,
+ * establishing the entrypoint's capability set and budget for the whole
+ * request.
+ *
+ * ```ts
+ * // app/orders/route.ts
+ * export const POST = ambitRoute(
+ *   { capabilities: ["db:write:orders"], budget: { timeMs: 800 } },
+ *   createOrder,
+ *   async (request) => [await request.json() as CreateOrderInput] as const,
+ * );
+ * ```
+ *
+ * `spec` and `handler` are in the **same first two positions** as
+ * {@link ambitHandler}'s, and that is load-bearing rather than cosmetic:
+ * `RUNTIME_WRAPPER_NAMES` in `src/checker/backend/legacy-ts.ts` reads
+ * `arguments[0]` as the spec and `arguments[1]` as the handler for every
+ * registered wrapper, so one extraction serves all of them. Changing the order
+ * here would cost the check without saying so.
+ *
+ * Per §4.4, "Removing the double declaration", a literal `spec` beside a
+ * handler declared in the same file *is* that handler's `@capabilities` and
+ * `@budget`: the JSDoc tags need not repeat it. Writing both stays legal, and
+ * a disagreement is still an error — the capability list against
+ * `@capabilities` (`AMB-E010`) and `spec.budget` against `@budget`
+ * (`AMB-E011`).
+ *
+ * `decode` keeps the framework out of `handler`, exactly as in the Hono
+ * adapter: `NextRequest` is in no stub table, so a `request.json()` inside a
+ * contract-bearing function would make that function's requirement partly
+ * `unknown` (`AMB-W003`). It runs **inside** the context, so reading the
+ * request body and awaiting `context.params` count 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 propagates out of the handler to Next.js's error handling, not to the
+ * client (§4.4).
+ *
+ * The hooks this enforcement depends on are installed once per process, in
+ * `instrumentation.ts`'s `register()` — see `docs/integrations/nextjs.md`.
+ * Without them, `ambitRoute` still establishes the context and applies
+ * `timeMs`, but no capability is checked, because nothing is intercepting the
+ * operations.
+ */
+export declare function ambitRoute<Args extends readonly unknown[], Result, Params extends Record<string, string | readonly string[]> = Record<string, string | readonly string[]>>(spec: AmbitSpec, handler: (...args: Args) => Result | Promise<Result>, decode: (request: NextRequest, context: RouteContext<Params>) => readonly [...Args] | Promise<readonly [...Args]>): RouteHandler<Params>;

package/dist/runtime/next.js

@@ -0,0 +1,60 @@
+import { withAmbit } from "./index.js";
+/**
+ * Register a contract-bearing handler as a Next.js Route Handler,
+ * establishing the entrypoint's capability set and budget for the whole
+ * request.
+ *
+ * ```ts
+ * // app/orders/route.ts
+ * export const POST = ambitRoute(
+ *   { capabilities: ["db:write:orders"], budget: { timeMs: 800 } },
+ *   createOrder,
+ *   async (request) => [await request.json() as CreateOrderInput] as const,
+ * );
+ * ```
+ *
+ * `spec` and `handler` are in the **same first two positions** as
+ * {@link ambitHandler}'s, and that is load-bearing rather than cosmetic:
+ * `RUNTIME_WRAPPER_NAMES` in `src/checker/backend/legacy-ts.ts` reads
+ * `arguments[0]` as the spec and `arguments[1]` as the handler for every
+ * registered wrapper, so one extraction serves all of them. Changing the order
+ * here would cost the check without saying so.
+ *
+ * Per §4.4, "Removing the double declaration", a literal `spec` beside a
+ * handler declared in the same file *is* that handler's `@capabilities` and
+ * `@budget`: the JSDoc tags need not repeat it. Writing both stays legal, and
+ * a disagreement is still an error — the capability list against
+ * `@capabilities` (`AMB-E010`) and `spec.budget` against `@budget`
+ * (`AMB-E011`).
+ *
+ * `decode` keeps the framework out of `handler`, exactly as in the Hono
+ * adapter: `NextRequest` is in no stub table, so a `request.json()` inside a
+ * contract-bearing function would make that function's requirement partly
+ * `unknown` (`AMB-W003`). It runs **inside** the context, so reading the
+ * request body and awaiting `context.params` count 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 propagates out of the handler to Next.js's error handling, not to the
+ * client (§4.4).
+ *
+ * The hooks this enforcement depends on are installed once per process, in
+ * `instrumentation.ts`'s `register()` — see `docs/integrations/nextjs.md`.
+ * Without them, `ambitRoute` still establishes the context and applies
+ * `timeMs`, but no capability is checked, because nothing is intercepting the
+ * operations.
+ */
+export function ambitRoute(spec, handler, decode) {
+    const scoped = withAmbit(spec, async (request, context) => 
+    // `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(request, context))));
+    return async (request, context) => {
+        const result = await scoped(request, context);
+        // `Response.json` rather than `NextResponse.json`: the handler's return
+        // type is the domain's, and `NextResponse` adds nothing a Route Handler
+        // needs here. Next.js accepts any `Response`.
+        return result instanceof Response ? result : Response.json(result ?? null);
+    };
+}

package/dist/runtime/pg.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runtime enforcement for the `pg` client (DESIGN.md §4.4 (a), (c)).
+ *
+ * Unlike the `node:` builtins this is a **client wrap**, not a global
+ * monkeypatch: Ambit does not depend on `pg`, so the caller hands the module
+ * in — `installPgHook(await import("pg"))` — and Ambit replaces
+ * `Pool.prototype.query` and `Client.prototype.query`. `pg` was chosen over
+ * `@prisma/client` because those prototypes give install and restore the same
+ * symmetry `installFetchHook` has, while Prisma's only stable extension point
+ * (`$extends`) returns a *new* client and so cannot be undone (P5).
+ *
+ * What this does **not** do: derive a table from the statement. §4.4 is
+ * explicit — "the mere existence of a hook into a DB client is not taken to
+ * mean that table-level permissions can be decided for arbitrary SQL" — so the
+ * target is the database the
+ * connection names, and the exception says so rather than leaving the reader
+ * to assume table granularity.
+ */
+/** The `pg` surface this hook needs. Structural, so a test double satisfies it. */
+export interface PgModule {
+    readonly Pool?: {
+        readonly prototype: object;
+    };
+    readonly Client?: {
+        readonly prototype: object;
+    };
+}
+/**
+ * The capabilities one `query` requires, given the client it was called on and
+ * the arguments it was called with.
+ *
+ * Direction comes from `sqlStatementDirection` in `src/core/`, the same rule
+ * the static effect table uses — §4.4 (c) puts it in one place so the checker
+ * and the running process cannot answer differently about one statement.
+ */
+export declare function pgCapabilities(client: unknown, args: readonly unknown[]): {
+    readonly capabilities: readonly string[];
+    readonly detail: string;
+};
+/**
+ * Wrap `Pool.prototype.query` and `Client.prototype.query` on the `pg` module
+ * handed in, returning the function that restores both.
+ *
+ * `query` is promise-returning unless a callback is passed, so a denial
+ * rejects, or reaches the callback through `process.nextTick` when there is
+ * one — §4.4 (a)'s rule for each family.
+ */
+export declare function installPgHook(pg: PgModule): () => void;

package/dist/runtime/pg.js

@@ -0,0 +1,122 @@
+import { sqlStatementDirection } from "../core/index.js";
+import { checkCapabilities } from "./enforce.js";
+const TARGET_DETAIL = "the target is the database this connection names, not a table: Ambit does not read table names out of arbitrary SQL";
+const UNKNOWN_DATABASE_DETAIL = "the connection does not name a database, so the target could not be determined; only a grant that does not name one (db:read:*) can cover it";
+const OPAQUE_STATEMENT_DETAIL = "the statement's direction is not decidable from this call, so both db:read and db:write are required";
+/**
+ * The capabilities one `query` requires, given the client it was called on and
+ * the arguments it was called with.
+ *
+ * Direction comes from `sqlStatementDirection` in `src/core/`, the same rule
+ * the static effect table uses — §4.4 (c) puts it in one place so the checker
+ * and the running process cannot answer differently about one statement.
+ */
+export function pgCapabilities(client, args) {
+    const database = databaseOf(client);
+    const target = database ?? "unknown";
+    const direction = sqlStatementDirection(statementText(args[0]));
+    const capabilities = direction === "read"
+        ? [`db:read:${target}`]
+        : direction === "write"
+            ? [`db:write:${target}`]
+            : [`db:read:${target}`, `db:write:${target}`];
+    const notes = [TARGET_DETAIL];
+    if (database === undefined)
+        notes.push(UNKNOWN_DATABASE_DETAIL);
+    if (direction === "both")
+        notes.push(OPAQUE_STATEMENT_DETAIL);
+    return { capabilities, detail: notes.join("; ") };
+}
+/**
+ * `undefined` when the statement is not a string this call fixes — a
+ * `Submittable` (a cursor, say), or a config object with no `text`. That is
+ * not "no statement": it is "the direction is not decidable", which
+ * {@link pgCapabilities} turns into both directions.
+ */
+function statementText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value !== null && typeof value === "object") {
+        const text = value.text;
+        if (typeof text === "string")
+            return text;
+    }
+    return undefined;
+}
+/**
+ * The database a `pg` client is connected to, or `undefined` when the client
+ * does not name one — an environment-only configuration, or a
+ * `connectionString` with no path. Each of the shapes below is somewhere `pg`
+ * actually keeps it (`Pool#options`, `Client#connectionParameters`, and the
+ * `database` a connected client exposes).
+ */
+function databaseOf(client) {
+    if (client === null || typeof client !== "object")
+        return undefined;
+    const record = client;
+    for (const source of [record, record.options, record.connectionParameters]) {
+        if (source === null || typeof source !== "object")
+            continue;
+        const config = source;
+        const database = config.database;
+        if (typeof database === "string" && database.length > 0)
+            return database;
+        const fromUrl = databaseFromConnectionString(config.connectionString);
+        if (fromUrl !== undefined)
+            return fromUrl;
+    }
+    return undefined;
+}
+function databaseFromConnectionString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const name = new URL(value).pathname.replace(/^\//, "");
+        return name.length > 0 ? decodeURIComponent(name) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Wrap `Pool.prototype.query` and `Client.prototype.query` on the `pg` module
+ * handed in, returning the function that restores both.
+ *
+ * `query` is promise-returning unless a callback is passed, so a denial
+ * rejects, or reaches the callback through `process.nextTick` when there is
+ * one — §4.4 (a)'s rule for each family.
+ */
+export function installPgHook(pg) {
+    const restores = [];
+    for (const clientClass of [pg.Pool, pg.Client]) {
+        const prototype = clientClass?.prototype;
+        if (!prototype)
+            continue;
+        const original = prototype.query;
+        if (typeof original !== "function")
+            continue;
+        const target = original;
+        const hooked = function (...args) {
+            const { capabilities, detail } = pgCapabilities(this, args);
+            const error = checkCapabilities(capabilities, detail);
+            if (!error)
+                return target.apply(this, args);
+            const callback = args[args.length - 1];
+            if (typeof callback === "function") {
+                process.nextTick(callback, error);
+                return undefined;
+            }
+            return Promise.reject(error);
+        };
+        Object.defineProperty(hooked, "name", { value: "query" });
+        prototype.query = hooked;
+        restores.push(() => {
+            if (prototype.query === hooked)
+                prototype.query = original;
+        });
+    }
+    return () => {
+        for (const restore of restores)
+            restore();
+    };
+}

package/dist/stubs/constructors.d.ts

@@ -0,0 +1,34 @@
+import type { KnownEffect } from "../core/index.ts";
+/**
+ * Effect table for `new X(...)`, keyed in its own namespace: every key is the
+ * `calleeQualifiedName` of a call site, prefixed by {@link CONSTRUCTOR_KEY_PREFIX}
+ * (`"new Date"`, `"new @prisma/client.PrismaClient"`). The prefix keeps
+ * construction and plain calls apart — `URL(...)` and `new URL(...)` are not
+ * the same operation, and a space cannot occur in the qualified name a call
+ * produces, so the two key spaces can never collide.
+ *
+ * This table exists because before it, `new X(...)` was dropped from the call
+ * graph entirely: a function declared `@effects pure` that constructed a
+ * database client reported no call at all, not even `unknown`. DESIGN.md §3.4
+ * forbids turning an unanalyzed path into "no violation".
+ *
+ * Trust level: bundled with Ambit — the highest level in DESIGN.md §8.
+ */
+export declare const CONSTRUCTOR_KEY_PREFIX = "new ";
+export declare function constructorStubKey(qualifiedName: string): string;
+/**
+ * The effect of constructing `qualifiedName` (a {@link constructorStubKey}),
+ * or `undefined` when this table says nothing about it — which leaves the
+ * call `unknown`, never "no effect".
+ *
+ * `withoutArguments` distinguishes `new Date()` from `new Date(x)`; pass
+ * `true` when the construction has no arguments.
+ */
+export declare function lookupConstructorEffect(qualifiedName: string, withoutArguments: boolean): KnownEffect | undefined;
+/**
+ * True when constructing `qualifiedName` is known to have no `KnownEffect`.
+ * A nullary-only effect entry (`new Date()`) is excluded when the
+ * construction actually is nullary.
+ */
+export declare function isKnownPureConstructor(qualifiedName: string, withoutArguments: boolean): boolean;
+export declare function isConstructorKey(qualifiedName: string): boolean;

package/dist/stubs/constructors.js

@@ -0,0 +1,111 @@
+/**
+ * Effect table for `new X(...)`, keyed in its own namespace: every key is the
+ * `calleeQualifiedName` of a call site, prefixed by {@link CONSTRUCTOR_KEY_PREFIX}
+ * (`"new Date"`, `"new @prisma/client.PrismaClient"`). The prefix keeps
+ * construction and plain calls apart — `URL(...)` and `new URL(...)` are not
+ * the same operation, and a space cannot occur in the qualified name a call
+ * produces, so the two key spaces can never collide.
+ *
+ * This table exists because before it, `new X(...)` was dropped from the call
+ * graph entirely: a function declared `@effects pure` that constructed a
+ * database client reported no call at all, not even `unknown`. DESIGN.md §3.4
+ * forbids turning an unanalyzed path into "no violation".
+ *
+ * Trust level: bundled with Ambit — the highest level in DESIGN.md §8.
+ */
+export const CONSTRUCTOR_KEY_PREFIX = "new ";
+export function constructorStubKey(qualifiedName) {
+    return `${CONSTRUCTOR_KEY_PREFIX}${qualifiedName}`;
+}
+const CONSTRUCTOR_EFFECTS = new Map([
+    ["new node:net.Socket", "network"],
+    ["new node:tls.TLSSocket", "network"],
+    ["new node:http.Agent", "network"],
+    ["new node:https.Agent", "network"],
+    ["new WebSocket", "network"],
+    ["new node:worker_threads.Worker", "process"],
+]);
+/**
+ * Constructors that read non-deterministic input only when called with no
+ * arguments. `new Date()` reads the clock (DESIGN.md §4.2 lists the clock
+ * under `env`); `new Date(2020, 0, 1)` is a pure conversion of its arguments.
+ */
+const NULLARY_ONLY_EFFECTS = new Map([["new Date", "env"]]);
+/**
+ * Constructors known to perform none of Ambit's `KnownEffect`s. As with
+ * `src/stubs/pure-builtins.ts`, this claims "no `KnownEffect`", not purity in
+ * a stricter sense — `new Map()` allocates mutable state, which is outside
+ * the effect model (DESIGN.md §12).
+ *
+ * A constructor that takes a callback (`Promise`) is listed here, but the
+ * connector layer marks `new Promise(namedExecutor)` `callbackByReference`
+ * and `summarize.ts` then refuses the pure verdict — the executor's body was
+ * never walked (DESIGN.md §4.2 rule 4).
+ */
+const PURE_CONSTRUCTORS = new Set([
+    "new Map",
+    "new Set",
+    "new WeakMap",
+    "new WeakSet",
+    "new Array",
+    "new Object",
+    "new Promise",
+    "new RegExp",
+    "new Error",
+    "new TypeError",
+    "new RangeError",
+    "new SyntaxError",
+    "new EvalError",
+    "new ReferenceError",
+    "new AggregateError",
+    "new URL",
+    "new URLSearchParams",
+    "new TextEncoder",
+    "new TextDecoder",
+    "new AbortController",
+    "new Number",
+    "new String",
+    "new Boolean",
+    "new Int8Array",
+    "new Uint8Array",
+    "new Uint8ClampedArray",
+    "new Int16Array",
+    "new Uint16Array",
+    "new Int32Array",
+    "new Uint32Array",
+    "new Float32Array",
+    "new Float64Array",
+    "new BigInt64Array",
+    "new BigUint64Array",
+    "new ArrayBuffer",
+    "new DataView",
+]);
+/**
+ * The effect of constructing `qualifiedName` (a {@link constructorStubKey}),
+ * or `undefined` when this table says nothing about it — which leaves the
+ * call `unknown`, never "no effect".
+ *
+ * `withoutArguments` distinguishes `new Date()` from `new Date(x)`; pass
+ * `true` when the construction has no arguments.
+ */
+export function lookupConstructorEffect(qualifiedName, withoutArguments) {
+    const always = CONSTRUCTOR_EFFECTS.get(qualifiedName);
+    if (always)
+        return always;
+    return withoutArguments ? NULLARY_ONLY_EFFECTS.get(qualifiedName) : undefined;
+}
+/**
+ * True when constructing `qualifiedName` is known to have no `KnownEffect`.
+ * A nullary-only effect entry (`new Date()`) is excluded when the
+ * construction actually is nullary.
+ */
+export function isKnownPureConstructor(qualifiedName, withoutArguments) {
+    if (lookupConstructorEffect(qualifiedName, withoutArguments) !== undefined)
+        return false;
+    if (NULLARY_ONLY_EFFECTS.has(qualifiedName))
+        return true;
+    return PURE_CONSTRUCTORS.has(qualifiedName);
+}
+export function isConstructorKey(qualifiedName) {
+    return qualifiedName.startsWith(CONSTRUCTOR_KEY_PREFIX);
+}

package/dist/stubs/data-clients.d.ts

@@ -0,0 +1,9 @@
+import type { KnownEffect, LiteralArgument } from "../core/index.ts";
+/**
+ * The effects of a database or LLM client call, or `undefined` when this table
+ * says nothing about it — which leaves the call `unknown`, never "no effect".
+ *
+ * `literalArguments` is what the connector layer could read at the call site;
+ * it decides the direction for the SQL-statement methods above.
+ */
+export declare function lookupClientEffects(qualifiedName: string, literalArguments: readonly (LiteralArgument | undefined)[] | undefined): readonly KnownEffect[] | undefined;

package/dist/stubs/data-clients.js

@@ -0,0 +1,109 @@
+import { sqlStatementDirection } from "../core/index.js";
+/**
+ * Both directions, for an operation whose direction the source does not fix.
+ *
+ * This is the conservative reading, and it is a choice with a cost: a function
+ * that only ever reads, but builds its statement dynamically, has to declare
+ * `db_write` too. The alternative — picking `db_read` — would let a generated
+ * `UPDATE` pass a `@effects db_read` contract, which is the failure this whole
+ * layer exists to prevent (DESIGN.md §3.4).
+ */
+const READ_AND_WRITE = ["db_read", "db_write"];
+/**
+ * Methods whose effect is decided by a SQL statement argument, and which
+ * argument holds it. A literal statement (or a template literal whose static
+ * head reaches the first keyword) is classified by that keyword; anything else
+ * is {@link READ_AND_WRITE}.
+ */
+const SQL_STATEMENT_ARGUMENT = new Map([
+    ["pg.Pool.query", 0],
+    ["pg.Client.query", 0],
+    ["pg.PoolClient.query", 0],
+    ["mysql2.Pool.query", 0],
+    ["mysql2.Pool.execute", 0],
+    ["mysql2.Connection.query", 0],
+    ["mysql2.Connection.execute", 0],
+]);
+const CLIENT_METHOD_RULES = [
+    // @prisma/client — the delegate methods are the documented public API; the
+    // model segment is whatever the user's schema declares.
+    { pattern: "@prisma/client.PrismaClient.*.findMany", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.findFirst", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.findFirstOrThrow", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.findUnique", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.findUniqueOrThrow", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.count", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.aggregate", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.groupBy", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.*.create", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.createMany", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.update", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.updateMany", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.upsert", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.delete", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.*.deleteMany", effects: ["db_write"] },
+    // Prisma splits raw access by direction itself, so no statement inspection
+    // is needed: `$queryRaw` is for `SELECT`, `$executeRaw` for everything else.
+    { pattern: "@prisma/client.PrismaClient.$queryRaw", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.$queryRawUnsafe", effects: ["db_read"] },
+    { pattern: "@prisma/client.PrismaClient.$executeRaw", effects: ["db_write"] },
+    { pattern: "@prisma/client.PrismaClient.$executeRawUnsafe", effects: ["db_write"] },
+    // A transaction's callback is not walked from here, and its statements are
+    // whatever the caller put in it.
+    { pattern: "@prisma/client.PrismaClient.$transaction", effects: READ_AND_WRITE },
+    // openai — both the named and the default export are in use in the wild, so
+    // both spellings of the class key are listed.
+    { pattern: "openai.OpenAI.chat.completions.create", effects: ["llm"] },
+    { pattern: "openai.default.chat.completions.create", effects: ["llm"] },
+    { pattern: "openai.OpenAI.responses.create", effects: ["llm"] },
+    { pattern: "openai.default.responses.create", effects: ["llm"] },
+    { pattern: "openai.OpenAI.embeddings.create", effects: ["llm"] },
+    { pattern: "openai.default.embeddings.create", effects: ["llm"] },
+    // @anthropic-ai/sdk
+    { pattern: "@anthropic-ai/sdk.Anthropic.messages.create", effects: ["llm"] },
+    { pattern: "@anthropic-ai/sdk.default.messages.create", effects: ["llm"] },
+];
+/**
+ * The effects of a database or LLM client call, or `undefined` when this table
+ * says nothing about it — which leaves the call `unknown`, never "no effect".
+ *
+ * `literalArguments` is what the connector layer could read at the call site;
+ * it decides the direction for the SQL-statement methods above.
+ */
+export function lookupClientEffects(qualifiedName, literalArguments) {
+    const statementArgument = SQL_STATEMENT_ARGUMENT.get(qualifiedName);
+    if (statementArgument !== undefined) {
+        return sqlStatementEffects(literalArguments?.[statementArgument]);
+    }
+    for (const rule of CLIENT_METHOD_RULES) {
+        if (patternMatches(rule.pattern, qualifiedName))
+            return rule.effects;
+    }
+    return undefined;
+}
+/**
+ * The direction of one SQL statement, as effects. The keyword rule itself is
+ * `src/core/sql.ts`, shared with the runtime `pg` hook so the checker and the
+ * running process cannot disagree about the same statement (DESIGN.md §4.4).
+ */
+function sqlStatementEffects(argument) {
+    switch (sqlStatementDirection(argument?.text)) {
+        case "read":
+            return ["db_read"];
+        case "write":
+            return ["db_write"];
+        default:
+            return READ_AND_WRITE;
+    }
+}
+function patternMatches(pattern, qualifiedName) {
+    if (pattern === qualifiedName)
+        return true;
+    if (!pattern.includes("*"))
+        return false;
+    const patternSegments = pattern.split(".");
+    const nameSegments = qualifiedName.split(".");
+    if (patternSegments.length !== nameSegments.length)
+        return false;
+    return patternSegments.every((segment, index) => segment === "*" || segment === nameSegments[index]);
+}

package/dist/stubs/http-capabilities.d.ts

@@ -0,0 +1,15 @@
+import type { Capability, LiteralArgument } from "../core/index.ts";
+export interface HttpCapabilityRequirement {
+    /** The capability the call requires, when the host could be read from the source. */
+    readonly capability?: Capability;
+    /** Set when this operation has a target but the source does not fix it. */
+    readonly targetUnknown?: true;
+}
+/**
+ * The capability requirement of one call, or `undefined` when this table knows
+ * of no target for it — which is not the same as "requires nothing": every
+ * other operation simply has no rule here yet (`node:fs`, DB clients, LLM
+ * SDKs), and §4.4's caveat forbids inferring one for a DB client from a SQL
+ * string.
+ */
+export declare function lookupHttpCapability(qualifiedName: string, literalArguments: readonly (LiteralArgument | undefined)[] | undefined): HttpCapabilityRequirement | undefined;