universal-physics-tensor 0.45.2 → 0.47.0

package/dist/atlas/conventions.js

@@ -0,0 +1,93 @@
+/**
+ * Atlas Phase 1 — convention comparison.
+ *
+ * `Conventions` (`src/atlas/types.ts`) records the sign and unit choices a
+ * record depends on. Two records that disagree on one of those choices are not
+ * directly comparable, and this module says WHICH keys disagree.
+ *
+ * **`undefined` is "unknown", never "mismatch", and that asymmetry is the
+ * whole design.** A record that declares nothing about the metric signature
+ * has not chosen `'+---'`; it has not said. Reporting the absence as a
+ * disagreement would manufacture conflicts out of missing data — and because
+ * almost every record in the repo declares nothing today, it would manufacture
+ * them at scale. The same reasoning that makes design note §3 require a
+ * NON-EMPTY `conventions` before `convention-checked` can be derived applies
+ * in the mirror here: absence earns neither a tag nor an accusation.
+ *
+ * A mismatch is therefore reported only when BOTH sides declare the key and
+ * the declared values differ.
+ *
+ * @module atlas/conventions
+ */
+/**
+ * Every key of `Conventions`, as values. Written out rather than derived,
+ * because a type has no runtime extent; `tests/atlas/conventions.test.ts`
+ * pins this list against the interface so a new field cannot be added to
+ * `Conventions` and silently skipped by the comparison.
+ */
+const CONVENTION_KEYS = [
+    'heatWorkSign',
+    'metricSignature',
+    'fourierNormalization',
+    'unitSystem',
+    'capacitorChargeSign',
+];
+/**
+ * The convention keys on which `a` and `b` DECLARE different values.
+ *
+ * Returns an empty list when they agree, when either side is absent, and when
+ * neither declares a key in common.
+ *
+ * ⚠ **An empty list is NOT a statement that the two are compatible** — it means
+ * no DECLARED pair disagrees. Eve (E1, 2026-09-21) flagged that this conflates
+ * the safe case with the dangerous one: record A declaring `metricSignature:
+ * '-+++'` while B simply never declared it returns `[]`, exactly like genuine
+ * agreement, and a caller printing nothing leads a reader to infer "checked, no
+ * conflict". Silence is not agreement. Use {@link unknownConventionKeys} to
+ * surface that case, and prefer reporting the two together.
+ *
+ * @param a - one record's conventions, or `undefined` when it declares none.
+ * @param b - the other record's conventions, or `undefined`.
+ * @returns the mismatched keys, in `Conventions` declaration order.
+ *
+ * @internal
+ */
+export function checkConventions(a, b) {
+    if (a === undefined || b === undefined)
+        return [];
+    return CONVENTION_KEYS.filter((k) => {
+        const av = a[k];
+        const bv = b[k];
+        // Either side silent ⇒ unknown, not disagreement.
+        if (av === undefined || bv === undefined)
+            return false;
+        return av !== bv;
+    });
+}
+/**
+ * The convention keys where exactly ONE side declares a value — the cases
+ * {@link checkConventions} deliberately does not call mismatches.
+ *
+ * This exists because "no declared pair disagrees" and "these two are
+ * compatible" are different claims, and only the first is checkable from the
+ * data. A key listed here is a question, not a conflict: the records MIGHT use
+ * opposite sign conventions and one simply never said. Reporting it separately
+ * lets a reader distinguish *verified agreement* from *nobody wrote it down*,
+ * which is the distinction an empty mismatch list destroys.
+ *
+ * Both sides absent is NOT unknown — it is simply a key nobody uses, so it is
+ * omitted. Only an asymmetric declaration is reported.
+ *
+ * @internal
+ */
+export function unknownConventionKeys(a, b) {
+    const av = a ?? {};
+    const bv = b ?? {};
+    return CONVENTION_KEYS.filter((k) => {
+        const x = av[k];
+        const y = bv[k];
+        // Exactly one declared: the asymmetric case. Neither declared ⇒ not a question.
+        return (x === undefined) !== (y === undefined);
+    });
+}
+//# sourceMappingURL=conventions.js.map

package/dist/atlas/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/atlas/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH;;;;;GAKG;AACH,MAAM,eAAe,GAA6B;IAChD,cAAc;IACd,iBAAiB;IACjB,sBAAsB;IACtB,YAAY;IACZ,qBAAqB;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAA0B,EAC1B,CAA0B;IAE1B,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,kDAAkD;QAClD,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACvD,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACnC,CAA0B,EAC1B,CAA0B;IAE1B,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IACnB,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAClC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAChB,gFAAgF;QAChF,OAAO,CAAC,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/atlas/coverage.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Atlas Phase 1, S1.3 — evidence coverage, counted BY TAG.
+ *
+ * Design note `docs/planning/Atlas-Phase-1-Design.md` §3: *"Any future commit
+ * that appears to raise a row's evidence without adding a witness is a bug,
+ * and the coverage report is what makes it visible: it reports counts BY TAG,
+ * so a jump is legible."*
+ *
+ * A single "how many records have evidence" total would hide exactly the
+ * movement this report exists to expose — one tag inflating while another
+ * drains reads as no change at all. So the report is per tag, every tag is
+ * present with an explicit zero, and `records` is reported beside the counts
+ * (the counts do not sum to it: a record carries several tags).
+ *
+ * Pure: no I/O, no catalog import, no caching — every function here takes
+ * what it counts as an argument, so it can never disagree with a registry.
+ *
+ * @module atlas/coverage
+ * @internal
+ */
+import type { EvidenceTag } from './types.js';
+export { ALL_EVIDENCE_TAGS } from './types.js';
+/** Counts by tag over a set of records. @internal */
+export interface EvidenceCoverage {
+    /** How many records were counted. */
+    readonly records: number;
+    /** One entry per `EvidenceTag`, zero included. Counts overlap by design. */
+    readonly byTag: Readonly<Record<EvidenceTag, number>>;
+}
+/**
+ * Count derived evidence sets by tag.
+ *
+ * @param evidenceSets - one derived set per record, e.g. the output of
+ * `deriveEvidence` mapped over a catalog. Deriving is the caller's job; this
+ * function never derives, so it cannot disagree with the derivation.
+ * @internal
+ */
+export declare function summarizeEvidence(evidenceSets: Iterable<ReadonlySet<EvidenceTag>>): EvidenceCoverage;
+/**
+ * How much of the catalog carries the Phase 1 overlay.
+ *
+ * `summarizeEvidence` above answers "what support do these records have";
+ * this answers the different question "how much has anyone LOOKED at". The two
+ * must not be conflated: a row can be `verified` (its derived tag set is
+ * non-empty, which a machine check produces) while nobody has recorded a
+ * `relation` for it at all.
+ *
+ * - `schema` — the denominator: the 55 catalog rows plus the canonical
+ *   registry. The atlas families are NOT in it; they are reported separately,
+ *   because a nine-model pilot would otherwise dilute a catalog-wide fraction.
+ * - `audited` — a HUMAN set `relation` or `conventions` on the record.
+ * - `verified` — a derived evidence tag set is non-empty. Passed IN, never
+ *   derived here, for the same reason `summarizeEvidence` never derives.
+ * - `notYetAudited` — `schema − audited`, stated rather than left to arithmetic.
+ *
+ * @internal
+ */
+export interface OverlayCoverage {
+    readonly schema: number;
+    readonly audited: number;
+    readonly verified: number;
+    readonly notYetAudited: number;
+    /** The atlas pilot, reported beside the catalog and never mixed into it. */
+    readonly atlas: {
+        readonly bridges: number;
+        readonly reviewed: number;
+    };
+}
+/** A record that may carry the Phase 1 overlay. Structural, so this module
+ * imports no registry and cannot become a second source of truth. @internal */
+export interface OverlayBearing {
+    readonly relation?: unknown;
+    readonly conventions?: unknown;
+}
+/** An atlas bridge, reduced to the one field this report reads. @internal */
+export interface ReviewStatusBearing {
+    readonly reviewStatus: 'proposed' | 'reviewed';
+}
+/**
+ * Count overlay coverage over the catalog rows and canonical entries.
+ *
+ * Every input is PASSED IN. The module stays pure and importless, so it can
+ * never disagree with the registries — the caller states which registries it
+ * counted, exactly as `summarizeEvidence` requires its caller to state which
+ * evidence sets it derived.
+ *
+ * @param schemaRecords - the catalog rows and canonical entries, concatenated.
+ * @param verifiedCount - how many of them have a non-empty derived tag set.
+ * @param atlasBridges - the atlas pilot's bridges, reported separately.
+ * @internal
+ */
+export declare function overlayCoverage(schemaRecords: readonly OverlayBearing[], verifiedCount: number, atlasBridges: readonly ReviewStatusBearing[]): OverlayCoverage;
+//# sourceMappingURL=coverage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/atlas/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,GAC/C,gBAAgB,CAWlB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,UAAU,CAAC;CAChD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,SAAS,cAAc,EAAE,EACxC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,SAAS,mBAAmB,EAAE,GAC3C,eAAe,CAcjB"}

package/dist/atlas/coverage.js

@@ -0,0 +1,69 @@
+/**
+ * Atlas Phase 1, S1.3 — evidence coverage, counted BY TAG.
+ *
+ * Design note `docs/planning/Atlas-Phase-1-Design.md` §3: *"Any future commit
+ * that appears to raise a row's evidence without adding a witness is a bug,
+ * and the coverage report is what makes it visible: it reports counts BY TAG,
+ * so a jump is legible."*
+ *
+ * A single "how many records have evidence" total would hide exactly the
+ * movement this report exists to expose — one tag inflating while another
+ * drains reads as no change at all. So the report is per tag, every tag is
+ * present with an explicit zero, and `records` is reported beside the counts
+ * (the counts do not sum to it: a record carries several tags).
+ *
+ * Pure: no I/O, no catalog import, no caching — every function here takes
+ * what it counts as an argument, so it can never disagree with a registry.
+ *
+ * @module atlas/coverage
+ * @internal
+ */
+import { ALL_EVIDENCE_TAGS } from './types.js';
+// Moved to `types.ts`: the derived-tag literals may appear under `src/atlas/`
+// only there and in `derive-evidence.ts`. Re-exported so callers are unchanged.
+export { ALL_EVIDENCE_TAGS } from './types.js';
+/**
+ * Count derived evidence sets by tag.
+ *
+ * @param evidenceSets - one derived set per record, e.g. the output of
+ * `deriveEvidence` mapped over a catalog. Deriving is the caller's job; this
+ * function never derives, so it cannot disagree with the derivation.
+ * @internal
+ */
+export function summarizeEvidence(evidenceSets) {
+    const byTag = Object.fromEntries(ALL_EVIDENCE_TAGS.map((t) => [t, 0]));
+    let records = 0;
+    for (const set of evidenceSets) {
+        records += 1;
+        for (const tag of set)
+            byTag[tag] += 1;
+    }
+    return { records, byTag };
+}
+/**
+ * Count overlay coverage over the catalog rows and canonical entries.
+ *
+ * Every input is PASSED IN. The module stays pure and importless, so it can
+ * never disagree with the registries — the caller states which registries it
+ * counted, exactly as `summarizeEvidence` requires its caller to state which
+ * evidence sets it derived.
+ *
+ * @param schemaRecords - the catalog rows and canonical entries, concatenated.
+ * @param verifiedCount - how many of them have a non-empty derived tag set.
+ * @param atlasBridges - the atlas pilot's bridges, reported separately.
+ * @internal
+ */
+export function overlayCoverage(schemaRecords, verifiedCount, atlasBridges) {
+    const audited = schemaRecords.filter((r) => r.relation !== undefined || r.conventions !== undefined).length;
+    return {
+        schema: schemaRecords.length,
+        audited,
+        verified: verifiedCount,
+        notYetAudited: schemaRecords.length - audited,
+        atlas: {
+            bridges: atlasBridges.length,
+            reviewed: atlasBridges.filter((b) => b.reviewStatus === 'reviewed').length,
+        },
+    };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/atlas/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/atlas/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG/C,8EAA8E;AAC9E,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAU/C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAgD;IAEhD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAGpE,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,CAAC;QACb,KAAK,MAAM,GAAG,IAAI,GAAG;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AA8CD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,aAAwC,EACxC,aAAqB,EACrB,YAA4C;IAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,CAC/D,CAAC,MAAM,CAAC;IACT,OAAO;QACL,MAAM,EAAE,aAAa,CAAC,MAAM;QAC5B,OAAO;QACP,QAAQ,EAAE,aAAa;QACvB,aAAa,EAAE,aAAa,CAAC,MAAM,GAAG,OAAO;QAC7C,KAAK,EAAE;YACL,OAAO,EAAE,YAAY,CAAC,MAAM;YAC5B,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,UAAU,CAAC,CAAC,MAAM;SAC3E;KACF,CAAC;AACJ,CAAC"}

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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"}