ambit-ts 0.1.0

package/dist/checker/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./authority.ts";
+export * from "./backend/legacy-ts.ts";
+export * from "./config.ts";
+export * from "./coverage.ts";
+export * from "./diagnose.ts";
+export * from "./init.ts";
+export * from "./propagate.ts";
+export * from "./summarize.ts";

package/dist/checker/index.js

@@ -0,0 +1,8 @@
+export * from "./authority.js";
+export * from "./backend/legacy-ts.js";
+export * from "./config.js";
+export * from "./coverage.js";
+export * from "./diagnose.js";
+export * from "./init.js";
+export * from "./propagate.js";
+export * from "./summarize.js";

package/dist/checker/init.d.ts

@@ -0,0 +1,38 @@
+import type { Diagnostic, DiagnosticEngine, SymbolId } from "../core/index.ts";
+import type { PropagatedFunction } from "./propagate.ts";
+/**
+ * Where `ambit init --config` writes: the config file `ambit check` would
+ * load, its current text, and the analysis root every {@link SymbolId}'s file
+ * half is relative to.
+ *
+ * The root is needed because the two are written against different bases —
+ * a symbol id is relative to `check <dir>`, a `contracts` key is relative to
+ * the config file (DESIGN.md §4.1 (c)) — and a patch that ignored the
+ * difference would propose a key that names nothing.
+ */
+export interface ConfigTarget {
+    /** The config file as the output names it — root-relative when it is under the root. */
+    readonly path: string;
+    readonly source: string;
+    readonly rootDir: string;
+}
+/**
+ * `ambit init`'s analysis half (DESIGN.md §4.1: "`ambit init` infers the
+ * effects of existing code from the evidence in 4.2 and emits JSDoc additions
+ * as fix candidates in diagnostics (chapter 5, `fixes[].edits`)").
+ *
+ * For every function that has no `@effects` tag and whose propagated effect
+ * set is fully known, emit an `AMB-I001` info diagnostic carrying one
+ * applicable patch that adds the tag.
+ *
+ * The `unknown` guard is the whole point. A function whose effects could not
+ * be resolved gets **no** proposal: writing `@effects pure` on it would turn
+ * "we could not tell" into a declared guarantee, which is precisely what §4.3
+ * says `unknown` exists to prevent. Those functions stay undeclared and keep
+ * showing up in `--coverage`, exactly as §4.1 says they should.
+ *
+ * Nothing here writes to disk. The proposals are diagnostics, so the same
+ * NDJSON an agent already consumes carries them, and applying them is the
+ * caller's decision.
+ */
+export declare function proposeContracts(state: ReadonlyMap<SymbolId, PropagatedFunction>, engine: DiagnosticEngine, configTarget?: ConfigTarget): readonly Diagnostic[];

package/dist/checker/init.js

@@ -0,0 +1,205 @@
+import path from "node:path";
+import { KNOWN_EFFECTS } from "../core/index.js";
+/**
+ * `ambit init`'s analysis half (DESIGN.md §4.1: "`ambit init` infers the
+ * effects of existing code from the evidence in 4.2 and emits JSDoc additions
+ * as fix candidates in diagnostics (chapter 5, `fixes[].edits`)").
+ *
+ * For every function that has no `@effects` tag and whose propagated effect
+ * set is fully known, emit an `AMB-I001` info diagnostic carrying one
+ * applicable patch that adds the tag.
+ *
+ * The `unknown` guard is the whole point. A function whose effects could not
+ * be resolved gets **no** proposal: writing `@effects pure` on it would turn
+ * "we could not tell" into a declared guarantee, which is precisely what §4.3
+ * says `unknown` exists to prevent. Those functions stay undeclared and keep
+ * showing up in `--coverage`, exactly as §4.1 says they should.
+ *
+ * Nothing here writes to disk. The proposals are diagnostics, so the same
+ * NDJSON an agent already consumes carries them, and applying them is the
+ * caller's decision.
+ */
+export function proposeContracts(state, engine, configTarget) {
+    const proposals = [];
+    for (const propagated of state.values()) {
+        const { summary } = propagated;
+        if (summary.declared.kind !== "none")
+            continue;
+        // A boundary's body was never analyzed, so there is nothing inferred to
+        // propose — and proposing the empty set would be the worst possible
+        // suggestion for a function that exists to hide something.
+        if (summary.boundary.kind === "declared")
+            continue;
+        if (propagated.observed.unknown)
+            continue;
+        const effects = KNOWN_EFFECTS.filter((effect) => propagated.observed.effects.has(effect));
+        const tag = `@effects ${effects.length === 0 ? "pure" : effects.join(", ")}`;
+        // Declarations no JSDoc comment can carry: an accessor or an anonymous
+        // default export (DESIGN.md §4.1 (a)), and a class that writes no
+        // constructor (its construction has a declaration path and no declaration
+        // site at all). All three have a stable symbol id, so `ambit.config.ts`
+        // can name them — which is what `--config` proposes.
+        if (summary.configOnly || summary.implicitConstructor) {
+            const edit = configTarget ? configEdit(configTarget, summary.id, effects) : undefined;
+            proposals.push(proposal(propagated, effects, configProposalMessage(summary, effects, tag, configTarget, edit !== undefined), edit
+                ? [
+                    {
+                        rank: 1,
+                        kind: "narrow",
+                        summary: `Declare [${effects.join(", ") || "no effects"}] for ${displayName(summary.id)} in ${configTarget?.path ?? "ambit.config.ts"}`,
+                        confidence: 1,
+                        consistentWithContract: true,
+                        edits: [edit],
+                    },
+                ]
+                : []));
+            continue;
+        }
+        const edit = contractEdit(propagated, tag);
+        if (!edit)
+            continue;
+        proposals.push(proposal(propagated, effects, `${displayName(summary.id)} has no @effects; its observed effects are [${effects.join(", ") || "none"}]`, [
+            {
+                rank: 1,
+                kind: "narrow",
+                summary: `Declare ${tag} on ${displayName(summary.id)}`,
+                confidence: 1,
+                // Adding a declaration where there was none cannot contradict a
+                // contract that does not exist, and the set proposed is exactly
+                // what was observed — so this neither loosens nor tightens.
+                consistentWithContract: true,
+                edits: [edit],
+            },
+        ]));
+    }
+    return proposals;
+    function proposal(propagated, effects, message, fixes) {
+        return {
+            id: "AMB-I001",
+            severity: "info",
+            category: "effects",
+            message,
+            location: propagated.summary.location,
+            contract: { declared: [], observed: effects, via: [] },
+            fixes,
+            docs: "docs/diagnostics/README.md#amb-i001",
+            engine,
+        };
+    }
+}
+/**
+ * The patch that adds `tag`: a new line inside the existing JSDoc block when
+ * there is one, or a fresh single-line block above the declaration when there
+ * is not. Both are inserts (a zero-width range), so nothing existing is
+ * overwritten.
+ */
+function contractEdit(propagated, tag) {
+    const { summary } = propagated;
+    const indent = " ".repeat(Math.max(0, summary.declarationStart.col - 1));
+    const comment = summary.jsDocRange;
+    if (comment) {
+        // Insert the tag on its own line just before the block's closing `*/`,
+        // which is the last two characters of the block.
+        const closingCol = comment.endCol - 2;
+        if (closingCol < 1)
+            return undefined;
+        // A one-line block (`/** text *​/`) has to become multi-line to hold a
+        // tag on its own line; a multi-line one is already sitting at the start
+        // of a `*`-prefixed line, so it only needs the line itself.
+        const singleLine = comment.line === comment.endLine;
+        const replacement = singleLine ? `\n${indent} * ${tag}\n${indent} ` : `* ${tag}\n${indent} `;
+        return {
+            file: comment.file,
+            range: [
+                [comment.endLine - 1, closingCol - 1],
+                [comment.endLine - 1, closingCol - 1],
+            ],
+            replacement,
+        };
+    }
+    return {
+        file: summary.declarationStart.file,
+        range: [
+            [summary.declarationStart.line - 1, summary.declarationStart.col - 1],
+            [summary.declarationStart.line - 1, summary.declarationStart.col - 1],
+        ],
+        replacement: `/** ${tag} */\n${indent}`,
+    };
+}
+/**
+ * What a config-only proposal says, which depends on how far the command can
+ * actually get: `--config` with a config file present produces a patch; every
+ * other combination produces the reason there is none. Never silence — the
+ * effects are real, and P4 forbids hiding what cannot be declared.
+ */
+function configProposalMessage(summary, effects, tag, configTarget, hasEdit) {
+    const what = `${displayName(summary.id)} runs [${effects.join(", ") || "no effects"}]`;
+    if (hasEdit)
+        return `${what} and has no declaration; add it to ${configTarget?.path}`;
+    if (summary.implicitConstructor && configTarget === undefined) {
+        return `${what} but has no constructor to declare them on; write an explicit constructor to carry ${tag}, or declare "${summary.id}" in ambit.config.ts (ambit init --config)`;
+    }
+    if (configTarget === undefined) {
+        return `${what} and cannot carry a JSDoc contract; declare "${summary.id}" in ambit.config.ts (ambit init --config)`;
+    }
+    return `${what} and cannot carry a JSDoc contract; ${configTarget.path} has no \`contracts\` block to append "${summary.id}" to`;
+}
+/**
+ * The patch that appends one `contracts` entry to an existing config file.
+ *
+ * Inserted at the end of the `contracts: {` line, so the edit is a single
+ * line's insertion into text this command did not parse — the config was
+ * loaded by importing it, not by building an AST, and guessing where the
+ * block *ends* would mean matching braces in a file that may contain any
+ * expression. `undefined` when there is no such line: §5.3 forbids emitting a
+ * candidate that does not apply.
+ *
+ * The key is rebased from the analysis root to the config file's directory
+ * (§4.1 (c)).
+ */
+function configEdit(target, id, effects) {
+    const lines = target.source.split("\n");
+    const pattern = /(?:^|[^A-Za-z0-9_$])contracts\s*:\s*\{/;
+    const index = lines.findIndex((line) => pattern.test(line));
+    const line = lines[index];
+    if (index < 0 || line === undefined)
+        return undefined;
+    const opening = pattern.exec(line);
+    if (!opening)
+        return undefined;
+    // Inserted immediately after the `{`, not at the end of the line: a
+    // formatter collapses an empty block to `contracts: {},` and appending
+    // after that line's text would put the entry outside the object.
+    const column = opening.index + opening[0].length;
+    const indent = " ".repeat(line.length - line.trimStart().length + 2);
+    const key = configKeyFor(target, id);
+    const value = `{ effects: [${effects.map((effect) => `"${effect}"`).join(", ")}] }`;
+    return {
+        file: target.path,
+        range: [
+            [index, column],
+            [index, column],
+        ],
+        replacement: `\n${indent}"${key}": ${value},`,
+    };
+}
+/** A symbol id rebased onto the config file's directory (DESIGN.md §4.1 (c)). */
+function configKeyFor(target, id) {
+    const hash = id.indexOf("#");
+    if (hash < 0)
+        return id;
+    const absolute = path.resolve(target.rootDir, id.slice(0, hash));
+    const configDir = path.dirname(path.resolve(target.rootDir, target.path));
+    const relative = path.relative(configDir, absolute).split(path.sep).join("/");
+    return `${relative}#${id.slice(hash + 1)}`;
+}
+function displayName(id) {
+    const afterHash = id.split("#")[1] ?? id;
+    const parts = afterHash.split(".");
+    const last = parts[parts.length - 1];
+    if (last === undefined)
+        return id;
+    if (last === "constructor" && parts.length >= 2)
+        return `${parts[parts.length - 2]}.${last}`;
+    return last;
+}

package/dist/checker/propagate.d.ts

@@ -0,0 +1,69 @@
+import type { CapabilitySet, ContractViaEntry, EffectSet, FunctionSummary, KnownEffect, SymbolId } from "../core/index.ts";
+/** One function's propagated (transitive) effects, plus provenance for diagnostics. */
+export interface PropagatedFunction {
+    readonly summary: FunctionSummary;
+    readonly observed: EffectSet;
+    /**
+     * For an effect in `observed` that this function does not produce
+     * directly, the immediate callee it was inherited through. Absent for an
+     * effect this function produces itself (a direct stub call).
+     */
+    readonly effectWitness: ReadonlyMap<KnownEffect, SymbolId>;
+    /** The immediate callee `unknown` was inherited through, if not direct. */
+    readonly unknownWitness?: SymbolId;
+    /**
+     * The capabilities this function's body needs (DESIGN.md §4.4). A second
+     * lattice over the same call graph, with the same trust rule as effects: a
+     * callee that declares `@capabilities` contributes what it declared, and an
+     * undeclared one contributes what its own body was inferred to need — so a
+     * grant checks through an undeclared middle function.
+     *
+     * A requirement arises in two ways. It is inherited from a callee's
+     * declaration — the narrowing rule between a caller's grant and a callee's
+     * declaration — or it is produced directly, by a bundled operation whose
+     * target the source fixes: a literal URL's host (§4.4's static half,
+     * `src/stubs/http-capabilities.ts`). The same operation with a target the
+     * source does not fix contributes `unknown` instead, never nothing.
+     */
+    readonly required: CapabilitySet;
+    /** For a required capability this function does not declare itself, the immediate callee it came through. */
+    readonly capabilityWitness: ReadonlyMap<string, SymbolId>;
+    /**
+     * The immediate callee an *unknown capability requirement* came through, if
+     * not direct. Tracked apart from {@link unknownWitness} because the two have
+     * different causes: effects go unknown at an unresolved call, while
+     * capabilities also go unknown at a perfectly resolved `@boundary` callee
+     * that declared no `@capabilities`. Reporting the second as "reaches a call
+     * that could not be resolved" would send a reader hunting for an unresolved
+     * call that does not exist.
+     */
+    readonly capabilityUnknownWitness?: SymbolId;
+}
+/**
+ * Compute each function's transitive effect set by a worklist fixed point
+ * over the call graph (DESIGN.md §4.2: "Cycles in the call graph are
+ * propagated to a fixed point using strongly connected components or the
+ * like"). Handles cycles by iterating to a stable state — no
+ * strongly-connected-component precomputation, since `EffectSet` only grows
+ * (union is monotonic) and the id space is finite, so this always
+ * terminates.
+ */
+export declare function propagate(summaries: readonly FunctionSummary[]): ReadonlyMap<SymbolId, PropagatedFunction>;
+/** Walk `effectWitness` chains from `start` to the function that produces `effect` directly. */
+export declare function witnessChain(start: SymbolId, effect: KnownEffect, state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly SymbolId[];
+/** Walk `capabilityUnknownWitness` from `start` to the function whose capability requirement first went unknown. */
+export declare function capabilityUnknownWitnessChain(start: SymbolId, state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly SymbolId[];
+/** Walk `capabilityWitness` chains from `start` to the function that declares `capability`. */
+export declare function capabilityWitnessChain(start: SymbolId, capability: string, state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly SymbolId[];
+/** Walk `unknownWitness` chain from `start` to the function with the direct unresolved call. */
+export declare function unknownWitnessChain(start: SymbolId, state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly SymbolId[];
+/**
+ * A witness chain rendered as `contract.via` entries: each hop named by its
+ * symbol id and located at its own declaration (DESIGN.md §5.1 — "`via` is a
+ * sequence of functions, and each element's position is that function's
+ * declaration position").
+ *
+ * Lives beside the chain walkers rather than beside either consumer, because
+ * a diagnostic's path and an authority record's path must be the same path.
+ */
+export declare function chainToVia(chain: readonly SymbolId[], state: ReadonlyMap<SymbolId, PropagatedFunction>): readonly ContractViaEntry[];

package/dist/checker/propagate.js

@@ -0,0 +1,259 @@
+import { callLeavesUnknown, capabilitySetsEqual, effectSetOf, effectSetsEqual, emptyCapabilitySet, formatCapability, unionCapabilitySets, unionEffectSets, unknownCapabilitySet, unknownEffectSet, } from "../core/index.js";
+/**
+ * Compute each function's transitive effect set by a worklist fixed point
+ * over the call graph (DESIGN.md §4.2: "Cycles in the call graph are
+ * propagated to a fixed point using strongly connected components or the
+ * like"). Handles cycles by iterating to a stable state — no
+ * strongly-connected-component precomputation, since `EffectSet` only grows
+ * (union is monotonic) and the id space is finite, so this always
+ * terminates.
+ */
+export function propagate(summaries) {
+    const byId = new Map(summaries.map((s) => [s.id, s]));
+    const state = new Map();
+    for (const summary of summaries) {
+        state.set(summary.id, {
+            summary,
+            observed: directEffects(summary),
+            effectWitness: new Map(),
+            required: emptyCapabilitySet(),
+            capabilityWitness: new Map(),
+        });
+    }
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const summary of summaries) {
+            const next = deriveState(summary, byId, state);
+            const previous = state.get(summary.id);
+            if (!previous ||
+                !effectSetsEqual(previous.observed, next.observed) ||
+                !capabilitySetsEqual(previous.required, next.required)) {
+                changed = true;
+            }
+            state.set(summary.id, next);
+        }
+    }
+    return state;
+}
+/**
+ * The capabilities a function's own body requires before anything is
+ * propagated into it: what its bundled-operation call sites fix statically,
+ * plus `unknown` when one of them has a target the source does not fix, or
+ * when a call could not be resolved at all.
+ */
+function directCapabilities(summary) {
+    let set = emptyCapabilitySet();
+    let unknown = false;
+    for (const call of summary.calls) {
+        if (callLeavesUnknown(call)) {
+            unknown = true;
+            continue;
+        }
+        if (call.kind !== "stub")
+            continue;
+        if (call.requiredCapability) {
+            set = unionCapabilitySets(set, {
+                capabilities: [call.requiredCapability],
+                unknown: false,
+            });
+        }
+        if (call.capabilityTargetUnknown)
+            unknown = true;
+    }
+    return unknown ? { capabilities: set.capabilities, unknown: true } : set;
+}
+function directEffects(summary) {
+    const stubEffects = summary.calls
+        .filter((call) => call.kind === "stub")
+        .flatMap((call) => call.effects);
+    let set = effectSetOf(...stubEffects);
+    // A mutation whose receiver is reachable from outside the function is a
+    // direct `state_write` (DESIGN.md §4.2, "Local mutation and `pure`"); a local
+    // one is recorded as a site but contributes nothing.
+    if (summary.calls.some((call) => call.kind === "mutation" && call.escaping)) {
+        set = unionEffectSets(set, effectSetOf("state_write"));
+    }
+    if (summary.calls.some(callLeavesUnknown)) {
+        set = unionEffectSets(set, unknownEffectSet());
+    }
+    return set;
+}
+/**
+ * What a caller inherits from a resolved call to `calleeSummary`.
+ *
+ * A *declared* callee is a trust boundary: its own body is checked against
+ * its own declaration by `diagnose.ts` (independently, on that function's
+ * own record), and callers propagate the declared set rather than the
+ * callee's inferred one. This is the usual modular-typing shape (a
+ * function's signature, not its body, is what callers see) and is also
+ * what makes "undeclared = unknown" workable as a coverage concept rather
+ * than a propagation rule — DESIGN.md §4.2 states it directly: "Undeclared"
+ * and "`unknown`" are not the same thing.
+ * A declared tag never carries `unknown` itself, so trusting it means a
+ * callee's own undeclared internal `unknown` does not leak to callers; it
+ * stays that callee's own AMB-W001, not its callers'.
+ *
+ * An *undeclared* callee has no signature to trust, so its own
+ * recursively-inferred `observed` set is used instead — this is what lets
+ * inference cross undeclared code (§4.3, incremental adoption).
+ */
+function contributionOf(calleeSummary, calleeState) {
+    if (calleeSummary.declared.kind === "declared")
+        return calleeSummary.declared.effects;
+    return calleeState.observed;
+}
+/** The capability requirement a caller inherits from a resolved call. Same trust rule as {@link contributionOf}. */
+function capabilityContributionOf(calleeSummary, calleeState) {
+    if (calleeSummary.capabilities.kind === "declared")
+        return calleeSummary.capabilities.capabilities;
+    return calleeState.required;
+}
+/**
+ * A `@boundary` function's contract is taken as written and its body is not
+ * propagated through (DESIGN.md §4.6: "do not statically check inside this
+ * function; trust the effects and capabilities it declares outward").
+ *
+ * What it declares is what it contributes. What it does *not* declare is
+ * `unknown`, not empty: the body was excluded from analysis, so an
+ * undeclared dimension is unexamined, and calling it "requires nothing"
+ * would turn an explicit hole into a guarantee (P4).
+ */
+function boundaryState(summary) {
+    return {
+        summary,
+        observed: summary.declared.kind === "declared" ? summary.declared.effects : unknownEffectSet(),
+        effectWitness: new Map(),
+        required: summary.capabilities.kind === "declared"
+            ? summary.capabilities.capabilities
+            : unknownCapabilitySet(),
+        capabilityWitness: new Map(),
+    };
+}
+function deriveState(summary, byId, state) {
+    if (summary.boundary.kind === "declared")
+        return boundaryState(summary);
+    const direct = directEffects(summary);
+    const hasDirectUnresolved = summary.calls.some(callLeavesUnknown);
+    let merged = direct;
+    const directRequired = directCapabilities(summary);
+    // A capability requirement can go unknown right here — an unresolved call,
+    // or a bundled operation whose target the source does not fix — in which
+    // case there is no callee to name as the witness.
+    const hasDirectCapabilityUnknown = directRequired.unknown;
+    let required = directRequired;
+    const effectWitness = new Map();
+    const capabilityWitness = new Map();
+    let unknownWitness;
+    let capabilityUnknownWitness;
+    for (const call of summary.calls) {
+        if (call.kind !== "resolved")
+            continue;
+        const calleeSummary = byId.get(call.callee);
+        const calleeState = state.get(call.callee);
+        if (!calleeSummary || !calleeState)
+            continue; // defensive: should always resolve within the same summary set
+        const contribution = contributionOf(calleeSummary, calleeState);
+        merged = unionEffectSets(merged, contribution);
+        for (const effect of contribution.effects) {
+            if (!direct.effects.has(effect) && !effectWitness.has(effect)) {
+                effectWitness.set(effect, call.callee);
+            }
+        }
+        if (contribution.unknown && !hasDirectUnresolved && unknownWitness === undefined) {
+            unknownWitness = call.callee;
+        }
+        const capabilityContribution = capabilityContributionOf(calleeSummary, calleeState);
+        required = unionCapabilitySets(required, capabilityContribution);
+        for (const capability of capabilityContribution.capabilities) {
+            const key = formatCapability(capability);
+            if (!capabilityWitness.has(key))
+                capabilityWitness.set(key, call.callee);
+        }
+        if (capabilityContribution.unknown &&
+            !hasDirectCapabilityUnknown &&
+            capabilityUnknownWitness === undefined) {
+            capabilityUnknownWitness = call.callee;
+        }
+    }
+    return {
+        summary,
+        observed: merged,
+        effectWitness,
+        unknownWitness: hasDirectUnresolved ? undefined : unknownWitness,
+        required,
+        capabilityWitness,
+        capabilityUnknownWitness: hasDirectCapabilityUnknown ? undefined : capabilityUnknownWitness,
+    };
+}
+/** Walk `effectWitness` chains from `start` to the function that produces `effect` directly. */
+export function witnessChain(start, effect, state) {
+    const chain = [];
+    let current = start;
+    const visited = new Set([current]);
+    for (;;) {
+        const next = state.get(current)?.effectWitness.get(effect);
+        if (next === undefined || visited.has(next))
+            return chain;
+        chain.push(next);
+        visited.add(next);
+        current = next;
+    }
+}
+/** Walk `capabilityUnknownWitness` from `start` to the function whose capability requirement first went unknown. */
+export function capabilityUnknownWitnessChain(start, state) {
+    const chain = [];
+    let current = start;
+    const visited = new Set([current]);
+    for (;;) {
+        const next = state.get(current)?.capabilityUnknownWitness;
+        if (next === undefined || visited.has(next))
+            return chain;
+        chain.push(next);
+        visited.add(next);
+        current = next;
+    }
+}
+/** Walk `capabilityWitness` chains from `start` to the function that declares `capability`. */
+export function capabilityWitnessChain(start, capability, state) {
+    const chain = [];
+    let current = start;
+    const visited = new Set([current]);
+    for (;;) {
+        const next = state.get(current)?.capabilityWitness.get(capability);
+        if (next === undefined || visited.has(next))
+            return chain;
+        chain.push(next);
+        visited.add(next);
+        current = next;
+    }
+}
+/** Walk `unknownWitness` chain from `start` to the function with the direct unresolved call. */
+export function unknownWitnessChain(start, state) {
+    const chain = [];
+    let current = start;
+    const visited = new Set([current]);
+    for (;;) {
+        const next = state.get(current)?.unknownWitness;
+        if (next === undefined || visited.has(next))
+            return chain;
+        chain.push(next);
+        visited.add(next);
+        current = next;
+    }
+}
+/**
+ * A witness chain rendered as `contract.via` entries: each hop named by its
+ * symbol id and located at its own declaration (DESIGN.md §5.1 — "`via` is a
+ * sequence of functions, and each element's position is that function's
+ * declaration position").
+ *
+ * Lives beside the chain walkers rather than beside either consumer, because
+ * a diagnostic's path and an authority record's path must be the same path.
+ */
+export function chainToVia(chain, state) {
+    return chain.map((id) => {
+        const location = state.get(id)?.summary.location;
+        return { symbol: id, file: location?.file ?? "", line: location?.line ?? 0 };
+    });
+}

package/dist/checker/summarize.d.ts

@@ -0,0 +1,27 @@
+import type { EffectSet, ExtractedFile, FunctionSummary, KnownEffect } from "../core/index.ts";
+import type { ResolvedConfig } from "./config.ts";
+/**
+ * Turn a backend's raw extraction into Ambit's own analysis representation
+ * (DESIGN.md §3.4 layer 2), independent of which backend produced it.
+ */
+export declare function summarizeExtractedFiles(files: readonly ExtractedFile[], config?: ResolvedConfig): readonly FunctionSummary[];
+/**
+ * `@boundary reason="..."`. DESIGN.md §4.6 makes `reason` mandatory, so a tag
+ * without one does not declare a boundary — it declares an unexplained hole,
+ * which is exactly what the tag exists to prevent. Both quoted and bare
+ * `reason=` forms are accepted; anything else is `"invalid"`.
+ */
+export declare function parseBoundaryTag(text: string): string | undefined;
+/**
+ * `pure` is the literal spelling for the empty set (DESIGN.md §4.2 rule 2).
+ * Returns `undefined` when a token is neither `pure` nor a known effect (a
+ * typo, e.g. `@effects netwrok`) — such a declaration must not silently
+ * collapse to an empty (`pure`) contract. The caller reports this as
+ * `AMB-E002` (`diagnose.ts`) instead of the tag's real, but broken, contract.
+ */
+export declare function parseEffectsTag(text: string, aliases?: EffectAliases): EffectSet | undefined;
+/**
+ * User-defined effect names and the standard effects they stand for. Absent
+ * when no config was loaded, in which case every name has to be standard.
+ */
+export type EffectAliases = ReadonlyMap<string, readonly KnownEffect[]> | undefined;