universal-physics-tensor 0.45.2 → 0.46.0

package/dist/atlas/derivation.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Atlas Phase 3 — `Derivation` (a hyperedge) and multicategory composition.
+ *
+ * A `Derivation` is many premises and one conclusion. Composing two of them is
+ * the operation design note `docs/planning/Atlas-Phase-3-Design.md` §0 names as
+ * the one that can silently produce a false claim, and it states the invariant
+ * this module exists to enforce:
+ *
+ * > A hyperedge composes only when EVERY premise edge is exact, and the
+ * > composite's premises are the union of the inputs' premises MINUS the
+ * > internal conclusions.
+ *
+ * Four gates enforce it, and each one is a reason to refuse:
+ *
+ * 1. **Consumption.** `second` must actually consume `first`'s conclusion. If
+ *    it does not, the two are unrelated hyperedges and gluing them would
+ *    assert a chain that was never drawn.
+ * 2. **Relation.** `composeRelation` decides, exactly as it does for a binary
+ *    chain. **A hyperedge cannot launder a pair the binary table refuses**
+ *    (§3): if the two relations land on one of the fifty-six
+ *    `'no-composite-claim'` cells, the hyperedge carries no claim either. This
+ *    is also where "only exact hyperedges compose" is enforced — the table's
+ *    eight defined cells ARE that set, and re-deciding exactness here with a
+ *    second rule would be a second place for it to rot.
+ * 3. **Context.** The union over every statement involved must EXIST.
+ *    `statementContextUnion` returns a refusal rather than a merge when it
+ *    does not, and that refusal propagates: no union, no composite.
+ * 4. **Premises.** The composite's premises are `first.premises ∪
+ *    second.premises` minus the internal conclusions — here, `first.conclusion`.
+ *
+ * ## Why the primary API returns a union and does not throw
+ *
+ * The S3.1 brief says composition "throws". The design note (§2) says the
+ * refusal "is the correct output rather than an error", and requires the
+ * result type to make "these do not compose" expressible WITHOUT a number or a
+ * conclusion attached — mirroring `boundPath`'s no-claim. Both are served
+ * here: {@link composeDerivations} returns a discriminated union, and
+ * {@link composeDerivationsOrThrow} is a thin strict wrapper for callers that
+ * genuinely want a failure. The union is primary because it is the shape a
+ * caller cannot misread — a refusal has no `.derivation` to read.
+ *
+ * Pure: no I/O, no registry reads beyond the map a caller passes in.
+ *
+ * @module atlas/derivation
+ */
+import type { ContextUnionResult, Statement, StatementId } from './statement.js';
+import type { RelationType } from './types.js';
+/** A `Derivation` id — `'d-noether-energy'`, … . @internal */
+export type DerivationId = string;
+/**
+ * Many premises, one conclusion.
+ *
+ * `contextUnion` is a FIELD rather than a method because it is checked once,
+ * at construction, and carried: a record whose premises do not pool is a
+ * record that states no claim, and that fact travels with it.
+ *
+ * @internal
+ */
+export interface Derivation {
+    readonly id: DerivationId;
+    readonly relation: RelationType;
+    readonly premises: readonly StatementId[];
+    readonly conclusion: StatementId;
+    readonly sideConditions: readonly string[];
+    /** CHECKED, never merged. A `'no-union'` here means this record claims nothing. */
+    readonly contextUnion: ContextUnionResult;
+}
+/** A `Derivation` without its checked union — what {@link makeDerivation} takes. @internal */
+export type DerivationSpec = Omit<Derivation, 'contextUnion'>;
+/**
+ * Build a `Derivation`, checking the context union of its premises AND its
+ * conclusion.
+ *
+ * The conclusion is included deliberately: a conclusion stated in a context
+ * incompatible with its own premises is exactly the false claim §0 warns
+ * about, and leaving it out would let one through.
+ *
+ * @throws RangeError via `statementContextUnion` if an id does not resolve.
+ * @internal
+ */
+export declare function makeDerivation(spec: DerivationSpec, registry: ReadonlyMap<StatementId, Statement>): Derivation;
+/** Why two hyperedges do not compose. @internal */
+export type NoCompositeReason = 
+/** `second` does not consume `first`'s conclusion. */
+'not-consumed'
+/** The binary composition table refuses the pair of relations. */
+ | 'no-composite-claim'
+/** The statements involved have no context union. */
+ | 'no-context-union'
+/** One of the inputs already states no claim of its own. */
+ | 'input-states-no-claim';
+/** The composite hyperedge. @internal */
+export interface CompositeFormed {
+    readonly kind: 'composite';
+    readonly derivation: Derivation;
+}
+/** The two hyperedges do NOT compose, and this is why. @internal */
+export interface CompositeRefused {
+    readonly kind: 'no-composite';
+    readonly reason: NoCompositeReason;
+    readonly detail: string;
+}
+/** The result of {@link composeDerivations}. @internal */
+export type DerivationCompositionResult = CompositeFormed | CompositeRefused;
+/** Thrown by {@link composeDerivationsOrThrow}. Carries the refusal verbatim. @internal */
+export declare class DerivationCompositionError extends Error {
+    readonly reason: NoCompositeReason;
+    constructor(refusal: CompositeRefused);
+}
+/**
+ * Compose `first` then `second` into one hyperedge, or refuse and say why.
+ *
+ * `D1: {A, B} ⊢ C` composed with `D2: {C, E} ⊢ F` yields `{A, B, E} ⊢ F`:
+ * `C` is the internal conclusion and leaves the composite's premises.
+ *
+ * Premise ORDER is `first`'s surviving premises followed by `second`'s, each
+ * de-duplicated on first appearance. Stable rather than sorted, so a composite
+ * reads in the order the derivation was performed.
+ *
+ * @param id - the composite's id. Supplied by the caller rather than derived
+ *   from the inputs, because a generated id would be a new identifier the
+ *   registry does not know about.
+ * @internal
+ */
+export declare function composeDerivations(id: DerivationId, first: Derivation, second: Derivation, registry: ReadonlyMap<StatementId, Statement>): DerivationCompositionResult;
+/**
+ * {@link composeDerivations}, throwing on refusal.
+ *
+ * For callers that treat a refusal as a failure. Prefer the union-returning
+ * form: a thrown error is easy to catch and discard, and a discarded refusal
+ * is how a composite gets used anyway.
+ *
+ * @throws DerivationCompositionError on any refusal.
+ * @internal
+ */
+export declare function composeDerivationsOrThrow(id: DerivationId, first: Derivation, second: Derivation, registry: ReadonlyMap<StatementId, Statement>): Derivation;
+//# sourceMappingURL=derivation.d.ts.map

package/dist/atlas/derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../../src/atlas/derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;CAC3C;AAED,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5C,UAAU,CAKZ;AAED,mDAAmD;AACnD,MAAM,MAAM,iBAAiB;AAC3B,sDAAsD;AACpD,cAAc;AAChB,kEAAkE;GAChE,oBAAoB;AACtB,qDAAqD;GACnD,kBAAkB;AACpB,4DAA4D;GAC1D,uBAAuB,CAAC;AAE5B,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0DAA0D;AAC1D,MAAM,MAAM,2BAA2B,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAE7E,2FAA2F;AAC3F,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,YAAY,OAAO,EAAE,gBAAgB,EAIpC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5C,2BAA2B,CA2F7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,GAC5C,UAAU,CAIZ"}

package/dist/atlas/derivation.js

@@ -0,0 +1,190 @@
+/**
+ * Atlas Phase 3 — `Derivation` (a hyperedge) and multicategory composition.
+ *
+ * A `Derivation` is many premises and one conclusion. Composing two of them is
+ * the operation design note `docs/planning/Atlas-Phase-3-Design.md` §0 names as
+ * the one that can silently produce a false claim, and it states the invariant
+ * this module exists to enforce:
+ *
+ * > A hyperedge composes only when EVERY premise edge is exact, and the
+ * > composite's premises are the union of the inputs' premises MINUS the
+ * > internal conclusions.
+ *
+ * Four gates enforce it, and each one is a reason to refuse:
+ *
+ * 1. **Consumption.** `second` must actually consume `first`'s conclusion. If
+ *    it does not, the two are unrelated hyperedges and gluing them would
+ *    assert a chain that was never drawn.
+ * 2. **Relation.** `composeRelation` decides, exactly as it does for a binary
+ *    chain. **A hyperedge cannot launder a pair the binary table refuses**
+ *    (§3): if the two relations land on one of the fifty-six
+ *    `'no-composite-claim'` cells, the hyperedge carries no claim either. This
+ *    is also where "only exact hyperedges compose" is enforced — the table's
+ *    eight defined cells ARE that set, and re-deciding exactness here with a
+ *    second rule would be a second place for it to rot.
+ * 3. **Context.** The union over every statement involved must EXIST.
+ *    `statementContextUnion` returns a refusal rather than a merge when it
+ *    does not, and that refusal propagates: no union, no composite.
+ * 4. **Premises.** The composite's premises are `first.premises ∪
+ *    second.premises` minus the internal conclusions — here, `first.conclusion`.
+ *
+ * ## Why the primary API returns a union and does not throw
+ *
+ * The S3.1 brief says composition "throws". The design note (§2) says the
+ * refusal "is the correct output rather than an error", and requires the
+ * result type to make "these do not compose" expressible WITHOUT a number or a
+ * conclusion attached — mirroring `boundPath`'s no-claim. Both are served
+ * here: {@link composeDerivations} returns a discriminated union, and
+ * {@link composeDerivationsOrThrow} is a thin strict wrapper for callers that
+ * genuinely want a failure. The union is primary because it is the shape a
+ * caller cannot misread — a refusal has no `.derivation` to read.
+ *
+ * Pure: no I/O, no registry reads beyond the map a caller passes in.
+ *
+ * @module atlas/derivation
+ */
+import { composeRelation, NO_COMPOSITE_CLAIM } from './composition-table.js';
+import { statementContextUnion } from './statement.js';
+/**
+ * Build a `Derivation`, checking the context union of its premises AND its
+ * conclusion.
+ *
+ * The conclusion is included deliberately: a conclusion stated in a context
+ * incompatible with its own premises is exactly the false claim §0 warns
+ * about, and leaving it out would let one through.
+ *
+ * @throws RangeError via `statementContextUnion` if an id does not resolve.
+ * @internal
+ */
+export function makeDerivation(spec, registry) {
+    return {
+        ...spec,
+        contextUnion: statementContextUnion([...spec.premises, spec.conclusion], registry),
+    };
+}
+/** Thrown by {@link composeDerivationsOrThrow}. Carries the refusal verbatim. @internal */
+export class DerivationCompositionError extends Error {
+    reason;
+    constructor(refusal) {
+        super(refusal.detail);
+        this.name = 'DerivationCompositionError';
+        this.reason = refusal.reason;
+    }
+}
+/**
+ * Compose `first` then `second` into one hyperedge, or refuse and say why.
+ *
+ * `D1: {A, B} ⊢ C` composed with `D2: {C, E} ⊢ F` yields `{A, B, E} ⊢ F`:
+ * `C` is the internal conclusion and leaves the composite's premises.
+ *
+ * Premise ORDER is `first`'s surviving premises followed by `second`'s, each
+ * de-duplicated on first appearance. Stable rather than sorted, so a composite
+ * reads in the order the derivation was performed.
+ *
+ * @param id - the composite's id. Supplied by the caller rather than derived
+ *   from the inputs, because a generated id would be a new identifier the
+ *   registry does not know about.
+ * @internal
+ */
+export function composeDerivations(id, first, second, registry) {
+    // ── Gate 0: an input that claims nothing composes to nothing ──────────────
+    for (const [label, d] of [
+        ['first', first],
+        ['second', second],
+    ]) {
+        if (d.contextUnion.kind === 'no-union') {
+            return {
+                kind: 'no-composite',
+                reason: 'input-states-no-claim',
+                detail: `${label} derivation '${d.id}' has no context union ` +
+                    `(${d.contextUnion.reason}: ${d.contextUnion.detail}), so it states no claim to compose`,
+            };
+        }
+    }
+    // ── Gate 1: `second` must consume `first`'s conclusion ────────────────────
+    if (!second.premises.includes(first.conclusion)) {
+        return {
+            kind: 'no-composite',
+            reason: 'not-consumed',
+            detail: `'${second.id}' does not take '${first.conclusion}' as a premise ` +
+                `(its premises are ${second.premises.map((p) => `'${p}'`).join(', ')}), ` +
+                `so '${first.id}' does not feed it`,
+        };
+    }
+    // ── Gate 2: the binary table governs, and a hyperedge cannot launder it ───
+    const relation = composeRelation(first.relation, second.relation);
+    if (relation === NO_COMPOSITE_CLAIM) {
+        return {
+            kind: 'no-composite',
+            reason: NO_COMPOSITE_CLAIM,
+            detail: `'${first.id}' (${first.relation}) then '${second.id}' (${second.relation}) ` +
+                'composes to no relation; a hyperedge cannot assert what the binary table refuses',
+        };
+    }
+    // ── Gate 4 (computed before gate 3 so the union covers the right set) ─────
+    // The composite's premises: the union of the inputs' premises MINUS the
+    // internal conclusions. `first.conclusion` is the only internal one for a
+    // two-input composition; it is removed from BOTH sides, so a premise that
+    // `first` also happened to require does not survive as an input it no longer
+    // needs.
+    const internal = new Set([first.conclusion]);
+    const premises = [];
+    for (const p of [...first.premises, ...second.premises]) {
+        if (internal.has(p))
+            continue;
+        if (premises.includes(p))
+            continue;
+        premises.push(p);
+    }
+    // ── Gate 3: the pooled context must exist over EVERY statement involved ───
+    // Every statement, not just the surviving premises: the internal conclusion
+    // is what the two halves meet at, and an incompatibility there is exactly
+    // the one that would vanish from the composite's own field.
+    const involved = [
+        ...new Set([
+            ...first.premises,
+            first.conclusion,
+            ...second.premises,
+            second.conclusion,
+        ]),
+    ];
+    const union = statementContextUnion(involved, registry);
+    if (union.kind === 'no-union') {
+        return {
+            kind: 'no-composite',
+            reason: 'no-context-union',
+            detail: `'${first.id}' and '${second.id}' have no context union ` +
+                `(${union.reason}: ${union.detail})`,
+        };
+    }
+    return {
+        kind: 'composite',
+        derivation: {
+            id,
+            relation,
+            premises,
+            conclusion: second.conclusion,
+            sideConditions: [
+                ...new Set([...first.sideConditions, ...second.sideConditions]),
+            ],
+            contextUnion: union,
+        },
+    };
+}
+/**
+ * {@link composeDerivations}, throwing on refusal.
+ *
+ * For callers that treat a refusal as a failure. Prefer the union-returning
+ * form: a thrown error is easy to catch and discard, and a discarded refusal
+ * is how a composite gets used anyway.
+ *
+ * @throws DerivationCompositionError on any refusal.
+ * @internal
+ */
+export function composeDerivationsOrThrow(id, first, second, registry) {
+    const result = composeDerivations(id, first, second, registry);
+    if (result.kind === 'no-composite')
+        throw new DerivationCompositionError(result);
+    return result.derivation;
+}
+//# sourceMappingURL=derivation.js.map

package/dist/atlas/derivation.js.map

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

package/dist/atlas/derive-evidence.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Atlas Phase 1, S1.3 — evidence tags, DERIVED AT READ TIME.
+ *
+ * Design note: `docs/planning/Atlas-Phase-1-Design.md` §3 and §4.
+ *
+ * **The contract of this module: it has no write path.** No record stores an
+ * evidence set; every tag is computed from the artifacts a record actually
+ * carries, each time it is asked for. A tag is emitted ONLY when the artifact
+ * it names is present and passing. There is no default-true tag, no tag
+ * derived from another tag, no tag derived from `reviewStatus`, and no tag
+ * derived from prose. A record carrying no passing witness derives exactly
+ * `{'proposed'}`.
+ *
+ * ## The empty-set trap (design note §3, Adam A1 RED — confirmed by execution)
+ *
+ * `convention-checked` is the ONLY rule in the table whose quantifier is
+ * universal (`every`). Written as "`conventions` is present AND every declared
+ * field is consumed by a witness", it hands the tag to a record with ZERO
+ * witnesses, because `conventions = {}` declares nothing and `[].every(…)` is
+ * vacuously true. {@link deriveEvidence} therefore requires a NON-EMPTY
+ * declaration before the universal runs, and
+ * `tests/atlas/derive-evidence.test.ts` pins the empty-object case.
+ *
+ * **The general rule, for anything added here later:** a universal quantifier
+ * in a tag derivation must be paired with a non-emptiness check, or the tag is
+ * free. The other rules are existentials (`some`), which are false on the
+ * empty set and therefore safe.
+ *
+ * ## What "passing" means, and why the caller supplies it
+ *
+ * `Witness` records an id and the test file that runs it; nothing on the
+ * record says whether that test passed. Proving it is a filesystem act (see
+ * `tests/atlas/evidence-rule.test.ts`, which matches witness ids against test
+ * titles), and this module is pure. So the set of passing witness ids is an
+ * ARGUMENT, and it is REQUIRED — {@link NO_PASSING_WITNESSES} must be passed
+ * explicitly when nothing is verified.
+ *
+ * It used to DEFAULT to empty, which sounds conservative and was in fact a
+ * defect (Eve E1 RED, confirmed by execution). Defaulting the other way, to
+ * "all", would have been the free-tag defect above in a second location — but
+ * defaulting to empty created the mirror-image failure: a forgotten argument
+ * produced an answer identical to a real negative. A catalog-wide check written
+ * that way could only ever report "no row gains evidence", whatever the rows
+ * held, so it could not fail. Requiring the argument makes a vacuous result a
+ * STATED choice, and `tests/atlas/coverage.test.ts` now carries a positive
+ * control so that a negative result carries information.
+ *
+ * @module atlas/derive-evidence
+ * @internal
+ */
+import type { Conventions, EvidenceTag, FormalFidelity } from './types.js';
+/**
+ * The verdict of `adjudicateBridgeEntry` (`src/bridges/membership.ts`),
+ * restated structurally so this module takes no dependency on `src/bridges`
+ * (the dependency must run one way — design note §1).
+ *
+ * `tests/atlas/derive-evidence.test.ts` pins this union against the real
+ * `BridgeVerdict` at compile time AND at runtime over the live catalog, so a
+ * fourth verdict fails the test rather than silently falling through.
+ *
+ * @internal
+ */
+export type MembershipVerdict = 'bridge' | 'not-a-bridge' | 'unadjudicated';
+/**
+ * A witness as this derivation reads it.
+ *
+ * Structural, not an import of `Witness`, for two reasons that are findings in
+ * their own right (both reported to the Lead):
+ *
+ *  - `Witness.kind` is `'symbolic' | 'numeric' | 'formal'` — there is NO
+ *    `'dimensional'` member, so `dimension-checked` has no source on today's
+ *    data. The kind is widened here to include `'dimensional'` so the rule is
+ *    written once and correctly; it simply never fires until such a witness
+ *    exists. Widening it is not inventing evidence: no record carries one.
+ *  - `Witness` records no list of the convention fields a check consumes, so
+ *    `consumes` is optional here. Absent ⇒ the witness consumes nothing ⇒
+ *    `convention-checked` cannot be earned. Conservative by construction.
+ *
+ * @internal
+ */
+export interface WitnessLike {
+    readonly id: string;
+    readonly kind: 'symbolic' | 'numeric' | 'formal' | 'dimensional';
+    /** Convention fields this check actually consumes, when it declares any. */
+    readonly consumes?: readonly (keyof Conventions)[];
+}
+/**
+ * A counterexample as this derivation reads it.
+ *
+ * `Counterexample` (`src/atlas/types.ts`) carries `description` and `witness`
+ * and has NO `resolvedBy` field — so on today's data every counterexample is
+ * unresolved. `resolvedBy` is read here as an optional property rather than
+ * assumed absent, so that adding it later resolves counterexamples without
+ * touching this file. This module adds no field to any type.
+ *
+ * @internal
+ */
+export interface CounterexampleLike {
+    readonly description?: string;
+    readonly witness?: string;
+    /** Present and non-empty ⇒ the counterexample is resolved and does not contradict. */
+    readonly resolvedBy?: string;
+}
+/**
+ * A rejection as this projection reads it — structural, so this module still
+ * imports nothing from `src/bridges`.
+ *
+ * @internal
+ */
+export interface RejectionLike {
+    readonly beId: number;
+    readonly reason: string;
+}
+/**
+ * A row's counterexamples INCLUDING the one its rejection constitutes.
+ *
+ * ROADMAP §7 Phase 1 asks for "a `RejectedBridgeAdjudication` ⇒ `contradicted`
+ * with the counterexample LINKED". The linking half is what matters and was
+ * missing: BE-35 had a counterexample written by hand and earned `contradicted`
+ * honestly, while BE-28, BE-29, BE-32 and BE-40 had none — and an earlier rule
+ * papered over that by FORCING `contradicted` onto every rejected row, which
+ * manufactured a refutation from nothing (Eve E1).
+ *
+ * This is the linking done properly. The rejection's own `reason` IS the
+ * counterexample: a row rejected for being single-regime is refuted AS A BRIDGE
+ * by exactly that argument. Projecting it means `contradicted` is then EARNED
+ * through the ordinary derivation rather than asserted by a special case.
+ *
+ * **It is a projection, not a copy.** The reason string is never duplicated into
+ * a catalog row; `bridges/rejected.ts` remains its single source, which is what
+ * the ROADMAP means by "cross-linked ... rather than duplicating it". The caller
+ * supplies the rejection, so this module still owns no view of WHICH ids are
+ * rejected.
+ *
+ * @internal
+ */
+export declare function counterexamplesWithRejection(record: EvidenceInput, rejection: RejectionLike | undefined): readonly CounterexampleLike[];
+/** The artifacts a record carries, all optional. @internal */
+export interface EvidenceInput {
+    readonly witnesses?: readonly WitnessLike[];
+    readonly conventions?: Conventions;
+    readonly counterexamples?: readonly CounterexampleLike[];
+    /**
+     * The record's formal reference, read ONLY for its fidelity. Structural so a
+     * caller can pass an `AtlasBridge` directly.
+     */
+    readonly formalRef?: {
+        readonly fidelity: FormalFidelity;
+    };
+}
+/**
+ * The empty passing set, for a caller that genuinely has nothing marked passing.
+ *
+ * ⚠ This is EXPORTED and must be passed EXPLICITLY. It used to be a default
+ * parameter value, and that was a defect found by post-implementation review
+ * (Eve, E1) and confirmed by execution: a record carrying three passing
+ * witnesses and a consumed convention derived `{'proposed'}` under the default —
+ * byte-identical to an empty record. A caller who simply forgot the argument got
+ * an answer indistinguishable from a real negative.
+ *
+ * That made a catalog-wide check VACUOUS rather than reassuring. "No row gains
+ * evidence" was the only outcome the call could produce, whatever the rows
+ * contained, so the check could not fail and proved nothing. Requiring the
+ * argument forces the caller to STATE which witnesses were verified, which is
+ * exactly the decision that must never be implicit.
+ */
+export declare const NO_PASSING_WITNESSES: ReadonlySet<string>;
+/**
+ * Derive the evidence set of one record.
+ *
+ * @param record - the artifacts the record carries.
+ * @param passingWitnessIds - ids of witnesses VERIFIED to pass. REQUIRED: pass
+ * {@link NO_PASSING_WITNESSES} explicitly when nothing is verified, so that a
+ * vacuous result is a stated choice rather than a forgotten argument.
+ * @returns a fresh set; never cached, never stored.
+ * @internal
+ */
+export declare function deriveEvidence(record: EvidenceInput, passingWitnessIds: ReadonlySet<string>): ReadonlySet<EvidenceTag>;
+/**
+ * Derive the evidence set of a catalog row, under the adjudication precedence
+ * of design note §4. The verdict is supplied by the caller — it comes from
+ * `adjudicateBridgeEntry`, which owns the rejected-id registry
+ * (`REJECTED_BRIDGE_IDS`). Reading that registry here would make this file a
+ * second source of truth about which ids are rejected.
+ *
+ * | Verdict | Derives |
+ * |---|---|
+ * | `'not-a-bridge'` | {@link deriveEvidence} runs normally — see below |
+ * | `'unadjudicated'` | `{'proposed'}` only — never a refutation, never support |
+ * | `'bridge'` | {@link deriveEvidence} runs normally |
+ *
+ * ## ⚠ `'not-a-bridge'` no longer forces `'contradicted'` (Eve E1, 2026-09-21)
+ *
+ * It used to, "regardless of witnesses", and that rule — written by me in design
+ * note §4 — **violated §3 of the same document.** `contradicted` means THE CLAIM
+ * IS REFUTED. `not-a-bridge` means THE ROW IS NOT A REGIME-CROSSING BRIDGE.
+ * Those are different assertions about different things, and conflating them made
+ * the library report BE-35 as `status: 'established'` and `evidence:
+ * {'contradicted'}` in the same breath — from which a reader cannot tell whether
+ * the equation is a true in-regime identity the bridge graph ignores, or a
+ * refuted statement.
+ *
+ * Measured when the rule was removed: of the five rejected rows, only **BE-35**
+ * carries an actual counterexample, and it derives `{'contradicted'}` NATURALLY
+ * through the normal path. **BE-28, BE-29, BE-32 and BE-40 carry none** — the old
+ * rule was manufacturing a refutation for four rows with no refuting artifact
+ * whatsoever. That is exactly what §3 forbids: a tag is emitted only when the
+ * artifact it names is present and passing.
+ *
+ * Membership already has a single owner — `adjudicateBridgeEntry` — and it does
+ * not need restating in the evidence vocabulary. Removing the case leaves each
+ * fact with exactly one source, which is what §4 was trying to achieve and this
+ * rule was quietly undermining.
+ *
+ * @internal
+ */
+export declare function deriveEvidenceForVerdict(verdict: MembershipVerdict, record: EvidenceInput, passingWitnessIds: ReadonlySet<string>): ReadonlySet<EvidenceTag>;
+//# sourceMappingURL=derive-evidence.d.ts.map

package/dist/atlas/derive-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-evidence.d.ts","sourceRoot":"","sources":["../../src/atlas/derive-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,cAAc,GAAG,eAAe,CAAC;AAE5E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,CAAC;IACjE,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,WAAW,CAAC,EAAE,CAAC;CACpD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,aAAa,GAAG,SAAS,GACnC,SAAS,kBAAkB,EAAE,CAqB/B;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;KAAE,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAqB,CAAC;AAmB3E;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,WAAW,CAAC,WAAW,CAAC,CAyC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,aAAa,EACrB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,WAAW,CAAC,WAAW,CAAC,CAY1B"}