@descryy/core 0.1.0

package/dist/store/writer.js

@@ -0,0 +1,279 @@
+/**
+ * The batch writer — DEC-015.
+ *
+ * "The writer deletes everything previously written by `producedBy` for
+ * `sourceFiles`, then inserts, in one transaction." That sentence hides three
+ * decisions the decision entry does not make, and getting any of them wrong
+ * loses data silently. They are made here and each is tested.
+ *
+ * ## 1. Invalidation matches on adapter *id* and *repo*, not `producedBy` alone
+ *
+ * `producedBy` is `id@version`. Matching the full string would mean an adapter
+ * upgrade never invalidates anything the old version wrote — the two producers
+ * would simply coexist, and the graph would hold both readings of every file
+ * forever. §24.1 is explicit: "an adapter version bump invalidates every node
+ * and edge that adapter produced". So overlap is computed on the id, and the
+ * version is what makes the *stale* rows recognisable.
+ *
+ * `repo` is a second, equally load-bearing part of the same match, added after
+ * a real defect: a store holding more than one repository (`descry-runtime`'s
+ * graph correlator merges a frontend and a backend into one store to trace
+ * across them, per DEC-228) can have two repos using the same adapter with an
+ * overlapping relative file path — `src/index.ts`, `package.json`, anything
+ * common. Without `repo` in this match, writing the second repo's batch reads
+ * as "adapter X re-ran over a file it already owned" and evicts the first
+ * repo's run outright — silent cross-repository data loss, not a wrong
+ * answer. `invalidateAdapter` below is intentionally *not* repo-scoped — its
+ * own contract is "every repo," a different, explicitly global operation.
+ *
+ * ## 2. Prior runs are matched by file-set *overlap*, not equality
+ *
+ * A batch is the unit of invalidation, but the batch that previously owned a
+ * file may have covered a different set of files. Deleting only exact-matching
+ * runs leaves two rows for the same symbol; deleting only the intersection is
+ * impossible, because an edge has no file. So every prior run of the same
+ * adapter that touches *any* of these files is replaced whole — and the files
+ * it covered that this batch does not re-supply are reported as `evictedFiles`.
+ * Reporting them is the honest-degradation rule (principle 7): the caller is
+ * told what fell out, rather than discovering it as a missing edge next week.
+ *
+ * ## 3. A run also cleans up after its own previous write
+ *
+ * The run id is content-derived from producer, repo, commit and file set — not
+ * from the nodes. So an adapter re-run at the same commit over the same files
+ * lands on the *same* run id, and "delete the prior runs" excludes it by
+ * definition. Without a self-clean pass, rows that run no longer produces stay
+ * forever: the upsert refreshes what is still there and nothing removes what is
+ * not. Every write therefore ends by deleting its own run's rows that this batch
+ * did not supply.
+ *
+ * ## 4. Re-supplied nodes are updated, not deleted and recreated
+ *
+ * A node id is stable across file moves by construction (DEC-004), so re-parsing
+ * a file normally yields the ids that were already there. Deleting a prior run's
+ * nodes wholesale would cascade away every edge *other* runs had pointing into
+ * them, and those runs will not be re-run. Instead: upsert the ids this batch
+ * supplies, then delete the prior run — whose remaining nodes are exactly those
+ * it no longer produces. Edges into a node that genuinely disappeared do cascade
+ * away, and are reported as `orphanedEdges`, because keeping an edge to a node
+ * that no longer exists is the wrong-edge failure the precision rule forbids.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson, edgeId } from "@descryy/ir";
+import { EDGE_MERGE_CONDITION, NODE_MERGE_CONDITION } from "../graph/merge.js";
+/** Split `adapterId@version`. The Normaliser has already guaranteed the shape. */
+function splitProducer(producedBy) {
+    const at = producedBy.lastIndexOf("@");
+    return { id: producedBy.slice(0, at), version: producedBy.slice(at + 1) };
+}
+function hash128(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * A run id derived from the batch's content, never a counter.
+ *
+ * Re-ingesting an identical batch must land on the same row, or "idempotent"
+ * cannot even be stated as a property. `sourceFiles` is sorted first so that an
+ * adapter listing the same files in a different order does not create a second
+ * run for identical work.
+ */
+export function runIdFor(batch) {
+    return `r1:${hash128(canonicalJson([batch.producedBy, batch.repo, batch.commitSha, [...batch.sourceFiles].sort()]))}`;
+}
+function unresolvedId(ref) {
+    return `u1:${hash128(canonicalJson([ref.fromNodeId, ref.edgeType, ref.rawTarget, ref.file, ref.line, ref.producedBy]))}`;
+}
+/**
+ * **Delegates to `@descryy/ir`'s `edgeId()` — it must not re-derive this.**
+ *
+ * It used to, as a hand-rolled `` `e1:${hash128(...)}` ``, and that was a
+ * latent identity split: DEC-054 moved the prefixes to `n2:`/`e2:` and this
+ * copy was never moved with them, so `edgeId()` and the stored id agreed on
+ * every byte of the hash and disagreed on the prefix. Nothing caught it
+ * because `edgeId()` had zero callers — the first caller to look an edge up
+ * by its public id would have silently matched nothing, which is DEC-055's
+ * measured failure (16 joins to 0, no error anywhere) reproduced inside the
+ * engine rather than across two adapters.
+ *
+ * One identity, one function. See DEC-NEXT-edge-id-prefix-split.
+ */
+function edgeRowId(edge) {
+    return edgeId(edge.from, edge.to, edge.type);
+}
+/**
+ * Write one normalised batch. **Input must already have passed the Normaliser** —
+ * this function does no validation, on purpose. Two validators drift; one
+ * validator at the boundary is a boundary.
+ */
+export function writeBatch(driver, batch, options = {}) {
+    const now = options.now ?? Date.now;
+    const runId = runIdFor(batch);
+    const { id: adapterId, version } = splitProducer(batch.producedBy);
+    const incomingFiles = new Set(batch.sourceFiles);
+    return driver.transaction(() => {
+        // --- find the prior runs this batch supersedes --------------------------
+        const priorRuns = driver
+            .prepare("SELECT id, source_files FROM adapter_runs WHERE adapter_id = ? AND repo = ? AND id != ?")
+            .all(adapterId, batch.repo, runId)
+            .filter((row) => {
+            const files = JSON.parse(row.source_files);
+            return files.some((f) => incomingFiles.has(f));
+        });
+        const evicted = new Set();
+        for (const run of priorRuns) {
+            for (const file of JSON.parse(run.source_files)) {
+                if (!incomingFiles.has(file))
+                    evicted.add(file);
+            }
+        }
+        const ownRunIds = [runId, ...priorRuns.map((r) => r.id)];
+        const foreignEdgesBefore = countForeignEdges(driver, ownRunIds);
+        // A scratch list of what this batch supplies, so the self-clean below is a
+        // set difference rather than a `NOT IN (?, ?, ...)` with one parameter per
+        // row — which caps out at SQLITE_MAX_VARIABLE_NUMBER on a large batch.
+        driver.exec(`CREATE TEMP TABLE IF NOT EXISTS supplied (kind TEXT NOT NULL, id TEXT NOT NULL, PRIMARY KEY (kind, id))`);
+        driver.exec("DELETE FROM temp.supplied");
+        const remember = driver.prepare("INSERT OR IGNORE INTO temp.supplied (kind, id) VALUES (?, ?)");
+        // Rows owned by a run this write replaces are always overwritten, never
+        // merged. DEC-012 arbitrates between two *different* producers claiming the
+        // same thing; the same adapter re-running over the same files is
+        // invalidation, and the fresh reading wins even when it reached a lower
+        // resolution — stale R3 facts about code that has since changed are worse
+        // than accurate R1 ones. Without this, a degraded re-run would fail the
+        // merge test, leave the row owned by the prior run, and then lose it to that
+        // run's cascade a few statements later.
+        for (const run of priorRuns)
+            remember.run("run", run.id);
+        // --- the run row, before anything references it -------------------------
+        driver
+            .prepare(`INSERT INTO adapter_runs
+           (id, repo, workspace, commit_sha, adapter_id, adapter_version, produced_by,
+            reached_resolution, source_files, file_count, written_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           commit_sha = excluded.commit_sha,
+           adapter_version = excluded.adapter_version,
+           produced_by = excluded.produced_by,
+           reached_resolution = excluded.reached_resolution,
+           written_at = excluded.written_at`)
+            .run(runId, batch.repo, batch.workspace ?? null, batch.commitSha, adapterId, version, batch.producedBy, batch.reachedResolution, JSON.stringify([...batch.sourceFiles].sort()), batch.sourceFiles.length, now());
+        // ON CONFLICT DO UPDATE, never INSERT OR REPLACE. `REPLACE` is a DELETE
+        // followed by an INSERT, so with foreign keys on it would cascade away this
+        // run's own nodes and edges before re-inserting them — and because the run
+        // id is content-derived, re-ingesting an identical batch hits that path
+        // every single time.
+        // --- nodes: upsert first, so ids that survive keep their inbound edges ---
+        const insertNode = driver.prepare(`INSERT INTO nodes
+         (id, type, name, file_path, start_line, end_line, language, produced_by, resolution, attrs, run_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, name = excluded.name, file_path = excluded.file_path,
+         start_line = excluded.start_line, end_line = excluded.end_line,
+         language = excluded.language, produced_by = excluded.produced_by,
+         resolution = excluded.resolution, attrs = excluded.attrs, run_id = excluded.run_id
+       WHERE nodes.run_id = excluded.run_id
+          OR nodes.run_id IN (SELECT id FROM temp.supplied WHERE kind = 'run')
+          OR (${NODE_MERGE_CONDITION})`);
+        for (const node of batch.nodes) {
+            insertNode.run(node.id, node.type, node.name, node.file, node.range?.startLine ?? null, node.range?.endLine ?? null, node.language, node.producedBy, node.resolution, canonicalJson(node.attrs), runId);
+            remember.run("node", node.id);
+        }
+        // --- retire the prior runs ----------------------------------------------
+        // Everything still pointing at them is, by definition, what this batch no
+        // longer produces. The cascade removes it; the counts above and below say
+        // how much.
+        if (priorRuns.length > 0) {
+            const del = driver.prepare("DELETE FROM adapter_runs WHERE id = ?");
+            for (const run of priorRuns)
+                del.run(run.id);
+        }
+        // ...and after this run's own previous write. See note 3 above: an adapter
+        // re-run at the same commit reuses the run id, so this is the only thing
+        // that removes what it stopped producing.
+        driver
+            .prepare(`DELETE FROM nodes WHERE run_id = ?
+           AND id NOT IN (SELECT id FROM temp.supplied WHERE kind = 'node')`)
+            .run(runId);
+        // --- edges and unresolved references -------------------------------------
+        const insertEdge = driver.prepare(`INSERT INTO edges
+         (id, source, target, type, resolution, confidence, produced_by, observed_by_run, attrs, run_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         resolution = excluded.resolution, confidence = excluded.confidence,
+         produced_by = excluded.produced_by, observed_by_run = excluded.observed_by_run,
+         attrs = excluded.attrs, run_id = excluded.run_id
+       WHERE edges.run_id = excluded.run_id
+          OR edges.run_id IN (SELECT id FROM temp.supplied WHERE kind = 'run')
+          OR (${EDGE_MERGE_CONDITION})`);
+        for (const edge of batch.edges) {
+            const id = edgeRowId(edge);
+            remember.run("edge", id);
+            insertEdge.run(id, edge.from, edge.to, edge.type, edge.resolution, edge.confidence, edge.producedBy, edge.observedByRun ?? null, edge.attrs === undefined ? null : canonicalJson(edge.attrs), runId);
+        }
+        const insertRef = driver.prepare(`INSERT INTO unresolved_refs
+         (id, from_node_id, edge_type, raw_target, file_path, line, produced_by, reason, attrs, run_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET reason = excluded.reason, attrs = excluded.attrs, run_id = excluded.run_id`);
+        driver
+            .prepare(`DELETE FROM edges WHERE run_id = ?
+           AND id NOT IN (SELECT id FROM temp.supplied WHERE kind = 'edge')`)
+            .run(runId);
+        for (const ref of batch.unresolved) {
+            const id = unresolvedId(ref);
+            remember.run("ref", id);
+            insertRef.run(id, ref.fromNodeId, ref.edgeType, ref.rawTarget, ref.file, ref.line, ref.producedBy, ref.reason, ref.attrs === undefined ? null : canonicalJson(ref.attrs), runId);
+        }
+        driver
+            .prepare(`DELETE FROM unresolved_refs WHERE run_id = ?
+           AND id NOT IN (SELECT id FROM temp.supplied WHERE kind = 'ref')`)
+            .run(runId);
+        // Edges belonging to neither this run nor the runs it replaced can only have
+        // vanished by cascade — an endpoint node ceased to exist. Measured directly
+        // rather than inferred from a before/after total, which dedupe would skew.
+        const orphaned = foreignEdgesBefore - countForeignEdges(driver, ownRunIds);
+        return {
+            runId,
+            nodesWritten: batch.nodes.length,
+            edgesWritten: batch.edges.length,
+            unresolvedWritten: batch.unresolved.length,
+            runsReplaced: priorRuns.length,
+            evictedFiles: [...evicted].sort(),
+            orphanedEdges: orphaned,
+        };
+    });
+}
+/** Edges owned by some run other than the ones this write is touching. */
+function countForeignEdges(driver, ownRunIds) {
+    const placeholders = ownRunIds.map(() => "?").join(", ");
+    return (driver
+        .prepare(`SELECT COUNT(*) AS n FROM edges WHERE run_id NOT IN (${placeholders})`)
+        .get(...ownRunIds)?.n ?? 0);
+}
+/**
+ * Remove everything an adapter ever produced, at every version, for every repo.
+ *
+ * §24.1's invalidation rule, as its own operation rather than a side effect of
+ * writing. It is deliberately separate from `writeBatch`: an upgraded adapter
+ * usually re-runs over a subset of files first, and folding this into the write
+ * path would make a partial re-run delete data it was never going to replace.
+ */
+export function invalidateAdapter(driver, adapterId) {
+    return driver.transaction(() => {
+        const result = driver.prepare("DELETE FROM adapter_runs WHERE adapter_id = ?").run(adapterId);
+        return { runsRemoved: result.changes };
+    });
+}
+/** §11.14 rebuild acceleration. Layer 1 change detection reads this. */
+export function putFileHash(driver, filePath, hash, parsedAt) {
+    driver
+        .prepare(`INSERT INTO file_hashes (file_path, hash, last_parsed_at) VALUES (?, ?, ?)
+       ON CONFLICT(file_path) DO UPDATE SET hash = excluded.hash, last_parsed_at = excluded.last_parsed_at`)
+        .run(filePath, hash, parsedAt);
+}
+/** Nodes touching these files, unchanged. */
+export function getFileHash(driver, filePath) {
+    return driver
+        .prepare("SELECT hash FROM file_hashes WHERE file_path = ?")
+        .get(filePath)?.hash;
+}
+//# sourceMappingURL=writer.js.map

package/dist/store/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/store/writer.ts"],"names":[],"mappings":"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"}

package/dist/tiers/certify.d.ts

@@ -0,0 +1,375 @@
+/**
+ * The capability-tier generator. DEC-075 §6, in code.
+ *
+ * > *"A tier is generated from `capabilities()`, never written in prose, and may
+ * > be published for a language only when the corpus passes at the resolution
+ * > the tier claims, a ≥200-edge precision draw passes on at least two
+ * > repositories the adapter's author did not choose, and `capabilities()`
+ * > declares exactly the node and edge types the adapter emitted."*
+ *
+ * ## The design point: this thing exists to say no
+ *
+ * A generator that awards a tier to everything it is shown is a rubber stamp
+ * with a build step. The output that matters is **the row that failed**, which
+ * is why `unmet` is a list of requirements with their statements rather than a
+ * boolean, and why `certify` never returns a bare tier without also returning
+ * what the next tier up is missing.
+ *
+ * Two rules follow from that, and both are the opposite of what is convenient:
+ *
+ * 1. **Absent evidence is not a pass.** No precision draw recorded means the
+ *    attested requirement is unmet, exactly as if a recorded draw had failed.
+ *    The alternative — treating silence as satisfaction — is how every unearned
+ *    claim in this repository would have been generated.
+ * 2. **An attested requirement is labelled attested, in the output, always.**
+ *    A machine can check "≥200 edges" and "two repositories". It cannot check
+ *    *"the author did not choose them"*, because that is a fact about a person's
+ *    intent. Marking it as declared-by-a-human is what stops this function
+ *    laundering a judgement into a computed result. `certify` therefore reports
+ *    `attestedBy` alongside the tier, and a consumer that prints the tier
+ *    without it has dropped the only part that says who is responsible.
+ *
+ * ## What it does not do
+ *
+ * It does not run the conformance harness or the precision benches. It is given
+ * their results. That keeps it pure and testable, and it keeps the awkward fact
+ * visible: the precision evidence is **recorded by hand today**, because the
+ * benches are throwaway scripts that print to a terminal. `GateEvidence` is
+ * where that hand-recording is written down and dated, rather than living in a
+ * decision document that nothing reads.
+ */
+import type { CapabilityMatrix, EdgeType, NodeType, ResolutionLevel } from "@descryy/ir";
+import type { RefusalCensus } from "../query/unresolved.ts";
+import { type Requirement, type Tier } from "./ladder.ts";
+/**
+ * One adjudicated precision draw, as DEC-075 §6.2 requires it.
+ *
+ * `authorChose` is the field that makes this honest. It defaults to nothing —
+ * a recorder who has not thought about it produces an incomplete record rather
+ * than an accidental pass, the same reason `reliabilityCap`'s `nameLevel` has
+ * no default.
+ */
+export interface PrecisionDraw {
+    readonly repository: string;
+    readonly edgeType: EdgeType | "mixed";
+    readonly drawn: number;
+    readonly correct: number;
+    /**
+     * How many of `drawn` the adjudicator actually rendered a verdict on —
+     * `undefined` when every adjudicator this project has ever recorded a draw
+     * with decides every row it draws, so `decided` and `drawn` have always
+     * been the same number and no draw needed to say so until now.
+     *
+     * **Kotlin is the first adapter where they diverge, and the divergence
+     * exposed a real instrument defect.** `correct / drawn` silently punishes
+     * an adjudicator for honestly declining to decide a row exactly as if it
+     * had decided that row wrong — okhttp drew 200, decided 192, and every one
+     * of the 192 it *did* decide was correct (192/192 = 100%, its own
+     * pre-registered gate: GATE PASSED); `correct / drawn` reads that as
+     * 192/200 = 96%, below the 98% floor, for a reason that has nothing to do
+     * with the adapter's precision. Precision is measured over `decided` rows
+     * only (see `checkPrecisionDraws`); `decided / drawn` — coverage — is a
+     * separate, always-disclosed axis (`bench/tier-matrix.mjs`'s
+     * `describeDrawCoverage`), never folded into the precision figure: a draw
+     * with high coverage and lower precision and one with low coverage and
+     * clean precision are different facts, and burying the second inside a
+     * clean-looking percentage is the failure this field exists to prevent.
+     */
+    readonly decided?: number;
+    /**
+     * How many candidates of this edge type the repository contained — the
+     * population the draw was taken **from**, not the sample size.
+     *
+     * ## Zero out of zero is undefined here too
+     *
+     * Without it, `0 edges drawn, below 200` and `47 edges drawn, below 200` print
+     * identically, and they are different facts with different remedies:
+     *
+     * | | statement about | what to do |
+     * | --- | --- | --- |
+     * | population 0 | **the corpus** — this reference set contains nothing to sample | find other repositories, or accept the bar is unreachable here |
+     * | population > 0, drawn short | **the adapter** — measured and short | measure more |
+     *
+     * Python is the live case: `USES_API` is emitted and measures **0 edges** on
+     * both reference repositories, and that zero is *correct* — a backend service
+     * in this reference set is a provider rather than a consumer, so no 200-edge
+     * draw is reachable from it at all. Reporting that as "below 200" tells a
+     * reader to measure harder, when the honest answer is that **this reference
+     * set cannot answer the question**.
+     *
+     * `undefined` means the population was not recorded, which is neither zero nor
+     * non-zero and is reported as its own case — the same reason
+     * `capabilitiesHonest` has an `"unknown"`.
+     */
+    readonly population?: number;
+    /**
+     * The refusal census for this draw's edge type, from `classifyRefusals`.
+     *
+     * ## Why the census rather than a recorded "drawable" count
+     *
+     * The number that decides reachability is **population minus `outOfScope`**:
+     * a call read correctly that targets something this workspace does not serve
+     * can never become an edge here, however good the adapter gets.
+     *
+     * | | population | outOfScope | drawable | reads as |
+     * | --- | --- | --- | --- | --- |
+     * | `saleor` | 0 | 0 | **0** | nothing to sample |
+     * | `dispatch` | 4 | 4 | **0** | four third-party calls, refused forever |
+     * | `discourse` | 20 | 0 | **20** | a capability gap the adapter owns |
+     *
+     * Carrying the census rather than a recorded count keeps this **derived**, so
+     * a measured zero still attests to itself and needs no attribution — unlike a
+     * `StructuralLimit`. And it cannot drift from the ledger, **because it is the
+     * ledger**: a separately recorded "drawable" number is the same fact in two
+     * places, and this project has measured what that costs.
+     *
+     * ## The abuse route, which is why `scopeKnown` is load-bearing
+     *
+     * With no internal hosts supplied, `classifyRefusals` classifies **every**
+     * absolute target as `outOfScope` and says so — it "understates the deficit".
+     * Subtracting blindly there would let an adapter that declares no hosts write
+     * off every external-looking call as unreachable and **improve its tier by
+     * supplying less information**. So `scopeKnown === false` makes the
+     * subtraction **unavailable**, never zero.
+     *
+     * Absent entirely, `drawable` falls back to the full population — which blames
+     * the **adapter** rather than the corpus. That is the safe direction: the
+     * failure being guarded is a tier improved by withholding evidence.
+     */
+    readonly refusals?: RefusalCensus;
+    /** The negative control over the same adjudicator. Must be ~0. */
+    readonly controlDrawn: number;
+    readonly controlCorrect: number;
+    /**
+     * Did the adapter's author pick this repository? DEC-075 §6.2 requires two
+     * where the answer is **no**. Declared, never inferred — see the header.
+     */
+    readonly authorChose: boolean;
+    /** Who recorded this, so an attested claim has a name against it. */
+    readonly recordedBy: string;
+    readonly recordedOn: string;
+    /**
+     * The mixed draw's own composition, by edge type — `undefined` for every
+     * draw recorded before this field existed, and that absence is itself
+     * meaningful (see `checkCapability`'s use of it: no data means the
+     * type-floor check does not run for that draw, not that it fails).
+     *
+     * The gap this closes: DEC-221 made the precision draw whole-graph and
+     * NOT edge-type-scoped (a `USES_API`-only draw structurally cannot carry
+     * a negative control, DEC-164 §2). That is still correct for what a
+     * *draw* needs to qualify. But a language's tier can rest on a capability
+     * (`A.callers` on `USES_API`, `A.routes` on `SERVES_API`) that the draw
+     * happened to sample almost none of — Kotlin's ktor draw cleared 98%
+     * precision overall while carrying exactly one decided `USES_API` row,
+     * which is evidence of nothing about that specific capability. This field
+     * is what lets `checkCapability` tell "the capability was validated" from
+     * "the capability was declared and the aggregate draw happened to pass".
+     */
+    readonly perEdgeType?: Readonly<Record<string, {
+        readonly decided: number;
+        readonly correct: number;
+    }>>;
+}
+export interface ConformanceEvidence {
+    readonly resolution: ResolutionLevel;
+    readonly passed: boolean;
+    /**
+     * DEC-070's **adapter** verdict — no type emitted that `capabilities()` did
+     * not declare.
+     *
+     * Deliberately not "the manifest check produced no findings". That check
+     * reports two different things and only one of them is the adapter's fault:
+     * `adapterFailed` (emitted-but-undeclared, a real overclaim) and `corpusThin`
+     * (declared-but-unexercised, a fact about the corpus). Reading them as one
+     * failed every adapter in the repository at Tier C on its first run here,
+     * because a low-resolution sweep leaves plenty declared and unexercised.
+     */
+    readonly manifestClean: boolean;
+}
+export interface GateEvidence {
+    readonly adapter: string;
+    readonly language: string;
+    readonly capabilities: CapabilityMatrix;
+    /** What the adapter actually emitted, if a run is available to compare. */
+    readonly emittedNodeTypes?: readonly NodeType[];
+    readonly emittedEdgeTypes?: readonly EdgeType[];
+    readonly conformance: readonly ConformanceEvidence[];
+    readonly precisionDraws: readonly PrecisionDraw[];
+    /**
+     * Types the adapter declares that **no corpus pattern exercised**.
+     *
+     * `checkManifest` already computes this and calls it `unpublishable`, with
+     * the comment *"not publishable as a tier claim"* — written before any tier
+     * generator existed. It is exactly right: a declared type nothing exercised
+     * is an untested claim, and a tier resting on it rests on a promise. Treated
+     * here as not satisfying a capability requirement at all, with its own reason
+     * so it is distinguishable from a type that was never declared.
+     */
+    readonly unpublishableTypes?: readonly string[];
+    /**
+     * Capabilities that **cannot exist in this language**, whatever anyone builds.
+     *
+     * DEC-123's case: `REQUIRED_NOT_DECLARED` fires only when an environment
+     * accessor *fails* on absence, and JavaScript has no such form — `process.env.X`
+     * yields undefined. No adapter effort makes that finding reachable in
+     * TypeScript. Without this, the generator scores it as **absent evidence**,
+     * which is the verdict for *"nobody has built it yet"*, and the two collapse
+     * into one output.
+     *
+     * That collapse is the one distinction §20.2 exists to hold: *"we found
+     * nothing"* and *"we cannot check this"* are different sentences. At the tier
+     * layer the difference is between a gap someone should close and a boundary
+     * nobody can.
+     *
+     * **A limit does not block the tier, and it does not vanish either.** It is
+     * carried onto the certificate and printed, so the tier is published *with*
+     * its qualifier. Awarding the tier silently would claim the capability;
+     * withholding it forever would punish a language for its own semantics.
+     *
+     * `id` matches a requirement id (`A.callers`) or names a check
+     * (`REQUIRED_NOT_DECLARED`). `declaredBy` is required for the same reason
+     * `PrecisionDraw.recordedBy` is: **this is a human judgement, and an
+     * unattributable one is a way to dodge a requirement that is merely unbuilt.**
+     * A limit with no reason or no declarer is ignored, and the requirement is
+     * checked normally.
+     */
+    readonly structuralLimits?: readonly StructuralLimit[];
+    /**
+     * Capabilities claimed **below** what the evidence supports, pending an open
+     * policy. See `PolicyCap` — this neither waives a requirement nor blocks a
+     * tier; it stops a deliberate cap being published as an absence.
+     */
+    readonly policyCaps?: readonly PolicyCap[];
+}
+/** A capability this language cannot have. Declared, never inferred. */
+export interface StructuralLimit {
+    /** A requirement id, or the name of a check. */
+    readonly id: string;
+    /** Why it is unreachable *in this language*, in terms of the language. */
+    readonly reason: string;
+    /** Who declared it. An anonymous structural limit is not admissible. */
+    readonly declaredBy: string;
+}
+/**
+ * A capability we **could** claim higher and are deliberately claiming lower,
+ * pending a policy that has not been written.
+ *
+ * ## The third state, and why two were not enough
+ *
+ * The certificate could say two things about a capability it does not claim:
+ *
+ * | | meaning |
+ * | --- | --- |
+ * | **absent** | we have not measured it |
+ * | **unreachable** (`StructuralLimit`) | this language structurally cannot produce it |
+ * | **capped** *(this)* | we could claim more and are choosing not to, pending a policy |
+ *
+ * Publishing the third as the first **understates a capability we have** — the
+ * tier layer would tell a user we cannot do something we deliberately declined
+ * to claim. That is §20.2's distinction one layer up, and the same family as the
+ * `FILE` gap: two different sentences collapsing into one because there was only
+ * one field to put them in.
+ *
+ * The case that produced it: an introspection-fed route table is R4 on fidelity
+ * — it is read from a running process — and is claimed at R3 because R4's
+ * promotion and expiry policy is open, R4 requires `observedByRun`, and R4 is
+ * unconditionally class A (DEC-115). Nothing is lost, because R3 already reaches
+ * class A for a name-level fact; what is lost is the *promise about expiry*, and
+ * that is exactly what wants recording.
+ *
+ * ## It does not waive anything
+ *
+ * Unlike a `StructuralLimit`, a cap is **not** removed from the tier check. The
+ * requirement is met at the lower claim, so there is nothing to waive — and that
+ * asymmetry is deliberate: if a cap could skip a requirement it would become the
+ * cheapest way to collect a tier, which is the abuse `admissibleLimits` already
+ * guards against for the other kind.
+ */
+export interface PolicyCap {
+    /** A requirement id, or the name of a check. */
+    readonly id: string;
+    /** What the evidence would support claiming. */
+    readonly claimable: string;
+    /** What is actually claimed. */
+    readonly claimed: string;
+    /**
+     * The open policy that would lift the cap.
+     *
+     * **Required, and a cap without one is ignored.** "Capped pending nothing" is
+     * not a cap, it is a decision — and a cap that names no condition can never be
+     * discharged, so it would sit on the certificate forever looking like caution.
+     */
+    readonly pendingOn: string;
+    /** Who declared it. Same rule as `StructuralLimit`: unattributable is not admissible. */
+    readonly declaredBy: string;
+}
+/** A bar the reference set cannot answer, because it holds nothing to sample. */
+export interface EmptyPopulation {
+    readonly repository: string;
+    readonly edgeType: EdgeType | "mixed";
+}
+export interface UnmetRequirement {
+    readonly requirement: Requirement;
+    /** Why it is unmet, in terms of what was found rather than what was wanted. */
+    readonly because: string;
+}
+export interface TierCertificate {
+    readonly adapter: string;
+    readonly language: string;
+    /** `null` means not even Tier C — and `unmetForNext` says what is missing. */
+    readonly tier: Tier | null;
+    /** The tier immediately above `tier`, and every requirement it lacks. */
+    readonly nextTier: Tier | null;
+    readonly unmetForNext: readonly UnmetRequirement[];
+    /** Every tier's verdict, so a reader can see the whole ladder at once. */
+    readonly byTier: Readonly<Record<Tier, readonly UnmetRequirement[]>>;
+    /**
+     * Names of the people whose declarations this tier rests on. Empty when the
+     * tier needed no attested requirement — C and B do not.
+     */
+    readonly attestedBy: readonly string[];
+    /**
+     * Edge types the qualifying precision draws actually covered. Empty under
+     * the same condition as `attestedBy`. See the generator's own comment: a
+     * tier resting on, say, an `IMPORTS`-only draw has not had `USES_API`
+     * itself sampled, and this is where a reader finds that out rather than
+     * assuming "Tier A" answered a question it did not.
+     */
+    readonly attestedEdgeTypes: readonly (EdgeType | "mixed")[];
+    /**
+     * Requirements waived because this language cannot satisfy them, and checks
+     * declared unreachable. **Never empty-by-omission in the printed form** — a
+     * consumer that prints the tier without these has published a capability
+     * claim the certificate does not make.
+     */
+    readonly limitations: readonly StructuralLimit[];
+    /**
+     * Deliberate under-claims, printed for the same reason `limitations` are:
+     * omitting them publishes a cap as an absence, which understates a capability
+     * the adapter has.
+     */
+    readonly policyCaps: readonly PolicyCap[];
+    /**
+     * Bars this **reference set** cannot answer — every recorded draw whose
+     * population was zero.
+     *
+     * Printed beside the structural limitations because it is the same kind of
+     * statement: not *"the adapter fell short"* but *"there was nothing here to
+     * measure"*. The remedy is other repositories, and a certificate that does not
+     * say so sends a reader to measure harder against an empty population.
+     */
+    readonly unreachableHere: readonly EmptyPopulation[];
+    /** DEC-075 §6.3: does `capabilities()` match what was emitted? */
+    readonly capabilitiesHonest: boolean | "unknown";
+}
+export declare function certify(evidence: GateEvidence): TierCertificate;
+/**
+ * The certificate as a developer should read it: the tier, then immediately the
+ * reason it is not higher.
+ *
+ * The failing rows are not an appendix. A support matrix that prints "B" and
+ * stops teaches a reader that B is the ceiling; printing what A is missing
+ * turns the same fact into a work item.
+ */
+export declare function formatCertificate(certificate: TierCertificate): string;
+//# sourceMappingURL=certify.d.ts.map