ambit-ts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+Notable changes to `ambit-ts`. The format is
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the versioning is
+[semantic versioning](https://semver.org/spec/v2.0.0.html), with 0.x read as
+semver defines it — while the major version is 0, a **minor** release may make a
+breaking change (`docs/DESIGN.md` §9.3).
+
+What a release must announce here is `docs/DESIGN.md` §9.2's **guaranteed
+surface**. Changes outside that list — added stubs, added runtime hooks,
+`unknown`-rate movement, caching — are deliberately absent. What is implemented
+and what is not is [`docs/status.md`](docs/status.md); this file is not a status
+report.
+
+## [Unreleased]
+
+## [0.1.0] — unreleased
+
+The first release, so this records the surface it establishes rather than a
+difference from an earlier one. The date is stamped at publish.
+
+Two rules changed while nothing could yet depend on them. Governance takes
+effect at 1.0 or the first external adopter, **not** at the first npm publish
+(§9.1, [ADR-0010](docs/adr/0010-when-governance-takes-effect.md)). And §5.2's
+"an `id` is never deleted or reused" now says from which version it holds: 1.0.
+
+### Added
+
+- **Contract declarations as JSDoc tags on ordinary TypeScript**: `@effects`,
+  `@capabilities`, `@budget`, `@entrypoint`, and `@boundary reason="…"`. Nine
+  standard effects, plus user-defined effects composed from them. An undeclared
+  function is `unknown`, never `pure`.
+- **`ambit check`** — static checking, with `--coverage`, `--strict`,
+  `--format json` and `--format github`. Exit 0 when clean, 1 on a violation,
+  2 when analysis itself failed.
+- **`ambit init`** — proposes `@effects` for the functions that have none;
+  `--config` proposes the same declarations as `ambit.config.ts` entries.
+- **`ambit diff <ref> [dir]`** — compares the working tree's authority against a
+  base ref and exits 1 on an increase no approval covers. `--format github`
+  annotates each increase at its declaration. The full exit-code table is
+  `docs/DESIGN.md` §6.
+- **`ambit.approvals.md`** — the ledger `ambit diff` reads on both sides of a
+  comparison. One `- ` line approves one authority gained by one symbol, and
+  counts only in the comparison that adds it.
+- **NDJSON diagnostics** (`--format json`) — one record per diagnostic, plus one
+  `kind: "authority"` record per function, each carrying the analysis `engine`.
+- **18 diagnostic ids**, each with its meaning, severity and category in
+  [`docs/diagnostics/`](docs/diagnostics/README.md).
+- **Out-of-code contracts** — `ambit-ts/config`'s `defineConfig`, for code that
+  cannot carry a comment: all five tags, per-directory `strict`, and
+  user-defined effects. Where a symbol has both, the JSDoc contract is the one
+  in force.
+- **Runtime enforcement** — `ambit-ts/runtime`'s `withAmbit`, with capability
+  hooks over `fetch`, `node:fs`, `node:fs/promises`, `node:child_process` and
+  `pg`, `timeMs` budget enforcement, and a per-context audit trail.
+- **Framework adapters** — `ambit-ts/runtime/hono`'s `ambitHandler` and
+  `ambit-ts/runtime/next`'s `ambitRoute`. A literal `spec` passed to either, or
+  to `withAmbit`, is read as the handler's own `@capabilities` / `@budget`
+  declaration.
+
+`@budget` takes three limits and enforces one. `timeMs` is enforced; `costUsd`
+and `llmCalls` are parsed, carried and compared, and nothing increments them.
+The rest of what Ambit does not do is
+[`docs/limitations.md`](docs/limitations.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sano-suguru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# Ambit
+
+**Declare what AI-written TypeScript is allowed to do, and check it mechanically.**
+
+An agent can widen a function's authority faster than a human can review it.
+Ambit — the range of one's authority — makes that range an explicit JSDoc
+contract and verifies it.
+
+## The accident
+
+Three files. `priceOrder` declares `pure`; `applyTax` and `currentRate` declare
+nothing at all.
+
+```ts
+// pricing.ts
+/** @effects pure */
+export function priceOrder(subtotal: number, region: string): number {
+  return applyTax(subtotal, region);
+}
+
+// tax.ts
+export function applyTax(subtotal: number, region: string): number {
+  return Math.round(subtotal * (1 + currentRate(region)));
+}
+
+// rates.ts
+const FALLBACK_RATE = 0.08;
+
+export function currentRate(region: string): number {
+  void fetch(`https://rates.example.com/${region}`);  // <- the agent's one added line
+  return FALLBACK_RATE;
+}
+```
+
+The added line is two calls away from the declaration it breaks. The next check
+fails, and prints the way from one to the other:
+
+```console
+$ node src/cli/main.ts check test/fixtures/accident; echo "exit=$?"
+error: priceOrder declares pure but calls currentRate which has effects [network] (pricing.ts:4)
+  -> applyTax (tax.ts:3)
+  -> currentRate (rates.ts:3)
+  operation: fetch (rates.ts:4)
+files=3 functions=3 declared=1
+exit=1
+```
+
+No file here contains both the declaration and the `fetch`. Every file is
+locally unremarkable: `rates.ts` fetches a rate, which is what a rates module
+does, and nothing in it mentions `pure`. The violation exists only in the path
+between the three, which is why a rule that reads one node, one function, or one
+file at a time has nothing to fire on.
+
+TypeScript accepts that edit — the types still line up. It tells you whether a
+value has the type you expect, not whether a function is allowed to do what it
+does. Ambit moves that judgement out of convention and into an executable
+contract.
+
+## Quick start
+
+Requires Node.js 24.
+
+```sh
+npm i -D ambit-ts
+npx ambit init src     # propose `@effects` for the functions that have none
+npx ambit check src    # check what they now declare
+```
+
+`init` writes nothing on its own — it reports the declarations it would add, as
+fix candidates. `check` exits 0 when it reported nothing, 1 on an error, and 2
+when the analysis itself could not run; it never returns 0 for "could not
+tell".
+
+Backing out is `npm remove ambit-ts`. The `@effects` comments left behind are
+JSDoc, so the code still type-checks and runs with Ambit gone.
+
+See **[CLI and CI](#cli-and-ci)** below for the flags, the exit codes, and the
+GitHub Actions output.
+
+## What Ambit controls
+
+Contracts are JSDoc tags on ordinary TypeScript. Two of them can also be
+declared by the runtime registration beside a handler instead — see *Static
+check, runtime block* below.
+
+| Tag | Declares | Checked |
+|---|---|---|
+| `@effects` | what side effects a function may perform | statically, propagated through the call graph |
+| `@capabilities` | which resources it may reach | statically — may only narrow from caller to callee — and at run time by four hooks |
+| `@budget` | how much an entrypoint may spend | parsed and validated; of its three limits only `timeMs` is enforced while the code runs |
+| `@entrypoint` | where a request enters | warned when it declares no capability set (`AMB-W002`) |
+| `@boundary reason="…"` | that a body is not analysed, and its declared contract is trusted in its place | counted separately in `--coverage` |
+
+Which tag is enforced where, tag by tag, is in
+[docs/status.md](docs/status.md#contract-tag-support-at-a-glance).
+
+Effects are inferred from bundled tables covering `fetch`/`undici`, the
+`node:fs`, `node:http`/`https`/`net`, and `node:child_process` builtins, and
+five clients (`pg`, `mysql2`, `@prisma/client`, `openai`,
+`@anthropic-ai/sdk`). Everything else resolves to `unknown` — never to `pure` —
+and `--strict` turns those warnings into errors.
+
+For code you cannot edit — third party, generated, or not yours yet — declare
+the same contracts in `ambit.config.ts`:
+
+```ts
+import { defineConfig } from "ambit-ts/config";
+
+export default defineConfig({
+  effects: { payments: ["network", "db_write"] },
+  contracts: {
+    "src/legacy/billing.ts#charge": { effects: ["payments"] },
+  },
+  strict: ["src/app/**"],
+});
+```
+
+Where a symbol has both, the JSDoc contract is the one in force and the
+difference is reported as a warning (`AMB-W005`). `ambit init --config`
+proposes config entries for the declarations no comment can carry — accessors,
+anonymous default exports, and a class with no constructor.
+
+## Static check, runtime block
+
+`ambit check` reads the source and nothing that runs, so adopting the static
+check means writing the declarations and nothing more. Runtime enforcement is
+the opposite: it is adopted **per entrypoint**. Every entrypoint needs its own
+`withAmbit` or adapter registration, and a JSDoc tag alone never turns it on.
+
+```ts
+import { installFetchHook, withAmbit } from "ambit-ts/runtime";
+
+installFetchHook();
+
+/**
+ * @entrypoint
+ * @effects network
+ */
+async function refreshRates(currency: string): Promise<void> {
+  await fetch(`https://api.example.com/rates?base=${currency}`);
+  // await fetch("https://elsewhere.example/steal"); // AMB-E009 if this line is added
+}
+
+export const refresh = withAmbit(
+  {
+    capabilities: ["http:get:api.example.com"],
+    budget: { timeMs: 500, costUsd: 0.01, onExceed: "throw" },
+  },
+  refreshRates,
+);
+```
+
+That file passes `ambit check` as written; uncommenting the second `fetch`
+fails it.
+
+**The capability list and the budget are written once, in the registration.**
+A literal `spec` whose `handler` names a declaration in the same file *is* that
+handler's `@capabilities` and `@budget`, so the checker reads the same values
+the runtime will enforce. That keeps the contract a value in the module, which
+survives a build that strips comments and a bundler that renames everything.
+`@effects` and `@entrypoint` stay in the JSDoc, because the runtime never reads
+them. Writing the tags as well is still allowed and still checked —
+`AMB-E010` / `AMB-E011` fail the check if the two halves disagree.
+(`docs/DESIGN.md` §4.1 "Where declarations live" has the full rule; §4.4 "The
+range this does not reach" covers what happens when a `spec` cannot supply the
+declaration.)
+
+At run time `withAmbit` puts that capability set on the context, and four hooks
+check operations against it — `installFetchHook()`, `installFsHook()`,
+`installChildProcessHook()`, `installPgHook(pg)`. An ungranted operation throws
+`AmbitCapabilityError` before the socket, the file, or the process is reached,
+every decision is recorded on the context's audit trail, and `timeMs` is
+measured against the wall clock. Each install returns the function that
+restores the original, so removing Ambit is one call.
+
+A grant names `http:<method>:<host>`, `fs:read:` / `fs:write:` with the path
+resolved to an absolute path at the call, `proc:spawn:` with argv[0] as
+written, or `db:read:` / `db:write:` with the database the connection names.
+
+### Framework adapters
+
+On Hono, the adapter registers the same handler instead of a hand-written
+`withAmbit`:
+
+```ts
+import { Hono } from "hono";
+import { ambitHandler } from "ambit-ts/runtime/hono";
+
+const app = new Hono();
+
+app.get("/rates", ambitHandler(
+  { capabilities: ["http:get:api.example.com"], budget: { timeMs: 500 } },
+  refreshRates,
+  (c) => [c.req.query("currency") ?? "USD"] as const,
+));
+```
+
+Next.js App Router is supported for Node.js **Route Handlers** in
+`app/**/route.ts`, through `ambitRoute`. Server Actions, `middleware.ts`, the
+Pages Router, and any route on the Edge runtime are **not enforced** — see
+[docs/integrations/nextjs.md](docs/integrations/nextjs.md) for the registration,
+the `instrumentation.ts` hook install, and the coverage table.
+
+Express, BullMQ and the rest have no adapter. A route registered without one
+establishes no context, and `setUnscopedPolicy("allow" | "warn" | "deny")`
+decides what its operations do — `allow` by default, so adopting the runtime
+does not break code that has no contracts yet.
+
+## CLI and CI
+
+| Command | What it does |
+|---|---|
+| `ambit check <dir>` | Static check. `--coverage`, `--strict`, `--format json`, `--format github` |
+| `ambit init <dir>` | Proposes `@effects` for undeclared functions. `--config` for the ones no comment can carry |
+| `ambit diff <ref> [dir]` | Compares the working tree's authority against a base ref and fails on an increase no approval covers |
+
+Exit codes: **0** when nothing was reported, **1** on an error, **2** when the
+analysis itself could not run. That exit code is the whole CI integration:
+
+```yaml
+- run: npx ambit check src --strict
+```
+
+`--format github` turns each diagnostic into a GitHub Actions annotation on the
+declaration that broke, carrying the whole call path into the pull request:
+
+```console
+$ node src/cli/main.ts check test/fixtures/accident --format github; echo "exit=$?"
+::error file=test/fixtures/accident/pricing.ts,line=4,col=17,title=AMB-E001::priceOrder declares pure but calls currentRate which has effects [network]%0A-> applyTax (tax.ts:3)%0A-> currentRate (rates.ts:3)%0Aoperation: fetch (rates.ts:4)
+files=3 functions=3 declared=1
+exit=1
+```
+
+The second gate is `ambit diff`. It compares the authority of the working tree
+against a base ref, and an increase that no line in `ambit.approvals.md`
+approves fails the build — with the line to add, so approving it is a copy and
+a reason:
+
+```console
+$ node src/cli/main.ts diff HEAD src; echo "exit=$?"
+base HEAD (fa633b1) vs the working tree, over src
+
+2 authorities increased without approval:
+
+  core/authority-diff.ts#leakedHelper (core/authority-diff.ts:342)  [new symbol]
+    + network
+      operation: fetch (core/authority-diff.ts:343)
+    - `core/authority-diff.ts#leakedHelper` `effect:network` — <why this increase is correct>
+
+  core/authority-diff.ts#leakedHelper (core/authority-diff.ts:342)  [new symbol]
+    + capability http:get:exfil.example.com
+    - `core/authority-diff.ts#leakedHelper` `capability:http:get:exfil.example.com` — <why this increase is correct>
+
+Add each line above to ambit.approvals.md, with the reason, and
+commit it in the same change (DESIGN.md §6.3). An approval already in the base
+grants nothing.
+
+302 symbols unchanged, out of 303 symbols compared.
+exit=1
+```
+
+That is a real run against this repository, with one function added to
+`src/core/authority-diff.ts` that fetches from `exfil.example.com`. Only
+increases fail: tightening a contract is never taxed.
+
+## For coding agents
+
+`check --format json` emits NDJSON — one diagnostic per line, then a summary
+line — meant to be piped into an agent loop. Where a diagnostic carries a
+patch, the agent applies the edits and re-checks without a human in the loop;
+`AMB-E001` is the one that carries a patch today.
+
+```console
+$ node src/cli/main.ts check src --format json
+{"id":"AMB-E001","severity":"error","contract":{"declared":["pure"],"observed":["network"]},"fixes":[{"kind":"widen","consistentWithContract":false,"edits":[{"file":"tax.ts","range":[[0,4],[0,17]],"replacement":"@effects network"}]}], ...}
+{"kind":"summary","filesAnalyzed":1,"functionsExtracted":1,"functionsDeclared":1}
+# the agent applies fixes[0].edits — ranges are 0-based, end-exclusive
+$ node src/cli/main.ts check src --format json    # re-check
+```
+
+The patch Ambit offers widens the contract to what the code actually does. It
+is marked `consistentWithContract: false` and carries the callers it would
+affect, so the agent — or the human reading its output — can tell "the contract
+was wrong" from "the code was wrong". Ambit does not invent the other patch,
+the one that keeps the contract and rewrites the code.
+
+## Why not ESLint / Effect-TS / dependency-cruiser
+
+| Tool | Primary abstraction |
+|---|---|
+| ESLint | code-level lint rules |
+| dependency-cruiser | module dependency edges |
+| Effect-TS | effects represented in program values and types |
+| **Ambit** | **authority propagated across function calls** |
+
+Ambit's abstraction is the authority a function holds after propagation, which
+is why a `pure` function calling an undeclared helper that calls `fetch` is an
+error on the pure function, with the path reported — no single file contains the
+violation. A module graph that is entirely legal can still contain a `pure`
+helper that opens a socket. And where Effect-TS puts effects in the types of the
+values you construct — so the code is written in that style throughout — Ambit's
+static contracts are JSDoc comments on ordinary TypeScript: adding them changes
+no runtime behavior, and removing Ambit is a small diff.
+
+## What Ambit does not guarantee
+
+Ambit stops the violations it can detect and states the rest. It does **not**
+claim:
+
+- **Whole-program soundness.** No alias analysis is performed: a locally created
+  value handed elsewhere and then mutated (`sink(out); out.push(x)`) still reads
+  as local mutation. Property and method calls resolve from the receiver's
+  value, which `const` does not freeze.
+- **That `unknown` is safe.** A call Ambit cannot resolve is reported and
+  counted, never folded into `pure`. `--strict` makes it an error.
+- **Enforcement on the Edge runtime.** Every hook Ambit installs is a Node.js
+  one, so an Edge route has no capability checked at all.
+- **Interception beyond four hooks.** `fetch`, `node:fs`, `node:child_process`
+  and `pg`. `mysql2`, Prisma and the LLM SDKs have static effects but no hook,
+  so calling them is neither blocked nor recorded. Native addons, child
+  processes, and other `worker_threads` workers are outside every hook.
+- **That the declaration cannot simply be widened.** `check` validates code
+  against the contract currently written, so changing the contract can make it
+  green again. `ambit diff <ref>` is what reviews increases in authority, and it
+  has documented blind spots of its own
+  ([limitations](docs/limitations.md#what-ambit-diff-can-and-cannot-see)).
+- **That an approved increase is a safe one.** An approval line in
+  `ambit.approvals.md` records that an increase was put in front of a reviewer,
+  in the same pull request, where it can be read. It does not record that the
+  reviewer was right, and Ambit cannot check that a person wrote the line at
+  all — branch protection and a `CODEOWNERS` entry on the file are what make
+  that true.
+- **Targets finer than the resource.** A database target names the database, not
+  the table — Ambit does not read table names out of SQL — and a shell spawn
+  names the shell, not the program inside the command string.
+- **That `costUsd` and `llmCalls` are enforced.** They are parsed and validated.
+  Nothing increments them.
+
+[docs/limitations.md](docs/limitations.md) has all of this in detail.
+
+## Status
+
+Ambit is experimental and not production-ready. It is versioned `0.x`, and
+semver's 0.x rule is in force: **a minor release may make a breaking change** —
+diagnostic ids, the NDJSON field shape, and everything else on the guaranteed
+surface can still move. What that surface is, and what is explicitly not on it,
+is [DESIGN.md §9.2](docs/DESIGN.md#92-the-guaranteed-surface); every change to
+it is announced in [CHANGELOG.md](CHANGELOG.md). `check src` over Ambit's own source — 39 files,
+302 functions — takes 1.07–1.11 s across five runs; `diff HEAD src`, which
+analyzes two trees, takes 1.86–1.98 s across five runs. Nothing is cached, so a
+re-check costs the same. The analysis backend has been measured on a
+300-file project (458 ms, 348 MiB peak) as part of choosing it; the CLI on top
+of it has not. What is implemented and what is not, milestone by milestone with
+the measured numbers behind it, is in [docs/status.md](docs/status.md).
+
+The analysis runs on the TypeScript Compiler API (`typescript` 6.0.3, the
+JavaScript implementation). That is a decision, not an accident: native
+TypeScript 7 (the Go implementation) is three to four times faster and was still
+not adopted, because its API is published entirely under `unstable/` and,
+unless it is told which files changed, it answers from a stale snapshot without
+saying so.
+[ADR-0001](docs/adr/0001-analysis-backend.md) records the decision and what
+would reopen it.
+
+## Working on Ambit itself
+
+There is no build step during development: `.ts` runs directly under Node's
+type stripping.
+
+```sh
+git clone https://github.com/sano-suguru/ambit.git && cd ambit && pnpm install
+node src/cli/main.ts check src --coverage
+```
+
+That last command needs nothing prepared — it checks Ambit's own source, and
+exit 0 is the fastest evidence a change did what it claimed:
+
+```console
+warning: extractProject declares fs_read but calls something that could not be resolved (checker/backend/legacy-ts.ts:55)
+warning: loadProjectConfig declares fs_read but calls something that could not be resolved (checker/backend/legacy-ts.ts:165)
+...
+files=39 functions=302 declared=14
+declared-by: jsdoc=14 config=0
+unknown-rate=62.9% (190/302 functions) boundary-rate=0.0% (0/302 functions)
+```
+
+`pnpm test`, `pnpm exec tsc --noEmit` and `biome ci .` are the rest of the
+gate; [AGENTS.md](AGENTS.md) is the working agreement, including what belongs
+in which document.
+
+## Docs / License
+
+- [docs/DESIGN.md](docs/DESIGN.md) — the product specification.
+- [docs/adr/](docs/adr/README.md) — why each design is the one in the spec.
+- [docs/diagnostics/](docs/diagnostics/README.md) — the diagnostic code ledger.
+- [CHANGELOG.md](CHANGELOG.md) — every breaking change to the guaranteed surface.
+- [docs/limitations.md](docs/limitations.md) — where the analysis is narrower
+  than the model suggests.
+- [docs/status.md](docs/status.md) — what is implemented, with measured numbers.
+- [ROADMAP.md](ROADMAP.md) — milestones and the Phase 1 exit criterion.
+
+MIT licensed; see [LICENSE](LICENSE). Ambit is one person's experiment:
+no support commitment, no release schedule yet.

package/dist/checker/authority.d.ts

@@ -0,0 +1,13 @@
+import type { AuthorityRecord, SymbolId } from "../core/index.ts";
+import { type PropagatedFunction } from "./propagate.ts";
+/**
+ * Every analyzed function's authority, in the order `ambit check --format
+ * json` emits it and `ambit diff` compares it (DESIGN.md §5.1).
+ *
+ * Built from the propagated state alone, so it says the same thing the
+ * diagnostics say — a function's record and the diagnostic about it can never
+ * disagree about what its effects are. Records are sorted by symbol id, and
+ * every list inside one is sorted too, so two runs over the same tree produce
+ * byte-identical output and a diff never reports ordering as change.
+ */
+export declare function buildAuthorityRecords(state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly AuthorityRecord[];

package/dist/checker/authority.js

@@ -0,0 +1,87 @@
+import { formatCapability, KNOWN_EFFECTS } from "../core/index.js";
+import { operationSite } from "./diagnose.js";
+import { capabilityWitnessChain, chainToVia, witnessChain, } from "./propagate.js";
+/**
+ * Every analyzed function's authority, in the order `ambit check --format
+ * json` emits it and `ambit diff` compares it (DESIGN.md §5.1).
+ *
+ * Built from the propagated state alone, so it says the same thing the
+ * diagnostics say — a function's record and the diagnostic about it can never
+ * disagree about what its effects are. Records are sorted by symbol id, and
+ * every list inside one is sorted too, so two runs over the same tree produce
+ * byte-identical output and a diff never reports ordering as change.
+ */
+export function buildAuthorityRecords(state) {
+    return [...state.values()]
+        .map((propagated) => buildRecord(propagated, state))
+        .toSorted((a, b) => (a.symbol < b.symbol ? -1 : a.symbol > b.symbol ? 1 : 0));
+}
+function buildRecord(propagated, state) {
+    const { summary } = propagated;
+    const declaredEffects = summary.declared;
+    const declaredCapabilities = summary.capabilities;
+    const observed = KNOWN_EFFECTS.filter((effect) => propagated.observed.effects.has(effect));
+    const required = propagated.required.capabilities.map(formatCapability).toSorted();
+    return {
+        kind: "authority",
+        symbol: summary.id,
+        location: summary.location,
+        entrypoint: summary.entrypoint,
+        effects: {
+            // An `@effects` tag that did not parse is no declaration at all, the
+            // same reading `AMB-E002` and propagation give it: a broken tag must
+            // never be read as a narrower grant than the author wrote.
+            declared: declaredEffects.kind === "declared"
+                ? KNOWN_EFFECTS.filter((effect) => declaredEffects.effects.effects.has(effect))
+                : null,
+            observed,
+            unknown: propagated.observed.unknown,
+        },
+        capabilities: {
+            declared: declaredCapabilities.kind === "declared"
+                ? declaredCapabilities.capabilities.capabilities.map(formatCapability).toSorted()
+                : null,
+            required,
+            unknown: propagated.required.unknown,
+        },
+        paths: [
+            ...effectPaths(propagated, observed, state),
+            ...capabilityPaths(summary.id, required, state),
+        ],
+    };
+}
+/**
+ * The call path for each effect the function reaches, plus the operation site
+ * inside the function at the end of that path — exactly what `AMB-E001` puts
+ * in `contract.via` / `contract.operation`, computed the same way so a
+ * diff-rendered path and a check-rendered path are the same path.
+ *
+ * An effect the function performs itself has an empty `via` and still carries
+ * an operation, so the reader is sent to the `fetch(...)` line either way.
+ */
+function effectPaths(propagated, observed, state) {
+    const owner = propagated.summary.id;
+    return observed.map((effect) => {
+        const chain = witnessChain(owner, effect, state);
+        const operation = operationSite(effect, chain[chain.length - 1] ?? owner, state);
+        return {
+            authority: effect,
+            kind: "effect",
+            via: chainToVia(chain, state),
+            ...(operation ? { operation } : {}),
+        };
+    });
+}
+/**
+ * The call path for each capability the function requires. No operation site:
+ * a capability requirement is established by a declaration or by an
+ * operation's target, and the latter is already the effect's operation — a
+ * second, differently-derived site would be a guess (DESIGN.md §5.3).
+ */
+function capabilityPaths(owner, required, state) {
+    return required.map((capability) => ({
+        authority: capability,
+        kind: "capability",
+        via: chainToVia(capabilityWitnessChain(owner, capability, state), state),
+    }));
+}

package/dist/checker/backend/legacy-ts.d.ts

@@ -0,0 +1,26 @@
+import type { TsBackend, UnresolvedReason } from "../../core/index.ts";
+/**
+ * `TsBackend` implementation on the TypeScript Compiler API (DESIGN.md §3.4).
+ *
+ * **This is the adopted backend**, not a placeholder. M0.5's comparison ran and
+ * chose it — DESIGN.md §3.5 and `docs/adr/0001-analysis-backend.md`, with the measurements
+ * in `docs/status.md`. The native TypeScript 7 engine (Go) was faster on every
+ * corpus and was still not adopted: its API is published entirely under
+ * `unstable/`, it answers from a stale snapshot unless told which files
+ * changed, and none of its speed was needed to meet a threshold. §3.5 also
+ * records what would reopen the decision; changing the default now requires an
+ * RFC (§9).
+ *
+ * The name `typescript-legacy` is the engine id in diagnostics and predates
+ * that decision. It distinguishes the JavaScript implementation from the Go
+ * one; it does not mean unmaintained. The version tracks the JS line's newest
+ * stable release (6.0.3), by the rule in AGENTS.md.
+ *
+ * The separation this file sits behind is unchanged and still the point: this
+ * is the ONLY file allowed to import `typescript`, and no `ts.Node`,
+ * `ts.Symbol`, or `ts.Type` may be returned from `extractProject` — see
+ * `src/core/backend.ts`. Adoption makes the boundary more useful, not less: it
+ * is what will let §3.5's review happen without touching the contract layer.
+ */
+export declare const legacyTsBackend: TsBackend;
+export type { UnresolvedReason };