universal-physics-tensor 0.45.2 → 0.47.0

package/dist/atlas/oscillators/models.js

@@ -0,0 +1,160 @@
+/**
+ * The nine oscillator models of design note §3.
+ *
+ * Each model's `regime` carries the π-groups `deriveRegimeGroups` produces
+ * from its own parameters and dimensionless inputs. `inequalities` is EMPTY
+ * on every model: Phase 0 states its inequalities on the BRIDGES (which carry
+ * the regime of validity), and the design note fixes no per-model inequality.
+ * An invented one would be a fabricated constraint, so none is written.
+ *
+ * The Phase 3 fields `boundaryData`, `initialData` and `symmetryGroup`
+ * (`../model.ts`) are ABSENT on all nine for the same reason `inequalities`
+ * is empty: no source records them for these ODE models, and an absent field
+ * says "not recorded" where a present empty one would claim "there are none".
+ *
+ * `canonicalRefs` are restricted to ids that exist in `CANONICAL_EQUATIONS`;
+ * `tests/atlas/models.test.ts` resolves every one of them.
+ *
+ * @module atlas/oscillators/models
+ */
+import { ACCELERATION, LENGTH, MASS, VELOCITY, } from '../../dimensional/types.js';
+import { deriveRegimeGroups } from '../regime.js';
+import { CAPACITANCE, CUBIC_STIFFNESS, DAMPING, INDUCTANCE, RESISTANCE, SPRING_CONSTANT, } from './dimensions.js';
+const FAMILY = 'oscillators';
+function model(spec) {
+    return {
+        ...spec,
+        family: FAMILY,
+        regime: {
+            family: FAMILY,
+            inequalities: [],
+            groupDefinitions: deriveRegimeGroups(FAMILY, spec.parameters, spec.dimensionlessInputs),
+        },
+    };
+}
+/** The nine Phase 0 oscillator models, in design-note §3 order. @internal */
+export const ATLAS_MODELS = [
+    model({
+        id: 'model-spring',
+        stateSpace: '(x, x′) ∈ ℝ²',
+        dynamics: 'm x″ + k x = 0',
+        observables: ['x', 'x′', 'energy'],
+        parameters: [
+            { name: 'm', dim: MASS },
+            { name: 'k', dim: SPRING_CONSTANT },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: [
+            'CE-simple-harmonic-frequency',
+            'CE-spring-potential-energy',
+            'CE-oscillator-energy',
+        ],
+    }),
+    model({
+        id: 'model-lc',
+        stateSpace: '(q, q′) ∈ ℝ²',
+        dynamics: 'L q″ + q/C = 0',
+        observables: ['q', 'q′', 'energy'],
+        parameters: [
+            { name: 'L', dim: INDUCTANCE },
+            { name: 'C', dim: CAPACITANCE },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: ['CE-lc-resonance'],
+    }),
+    model({
+        id: 'model-damped-spring',
+        stateSpace: '(x, x′) ∈ ℝ²',
+        dynamics: 'm x″ + b x′ + k x = 0',
+        observables: ['x', 'x′'],
+        parameters: [
+            { name: 'm', dim: MASS },
+            { name: 'b', dim: DAMPING },
+            { name: 'k', dim: SPRING_CONSTANT },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: [],
+    }),
+    model({
+        id: 'model-rlc',
+        stateSpace: '(q, q′) ∈ ℝ²',
+        dynamics: 'L q″ + R q′ + q/C = 0',
+        observables: ['q', 'q′'],
+        parameters: [
+            { name: 'L', dim: INDUCTANCE },
+            { name: 'R', dim: RESISTANCE },
+            { name: 'C', dim: CAPACITANCE },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: [],
+    }),
+    model({
+        id: 'model-pendulum',
+        stateSpace: '(θ, θ′) ∈ S¹ × ℝ',
+        dynamics: 'θ″ + (g/ℓ) sin θ = 0',
+        observables: ['theta', 'theta′', 'period'],
+        parameters: [
+            { name: 'g', dim: ACCELERATION },
+            { name: 'ell', dim: LENGTH },
+        ],
+        dimensionlessInputs: ['theta0'],
+        canonicalRefs: [],
+    }),
+    model({
+        id: 'model-chain',
+        stateSpace: '(u_n, u_n′) ∈ ℝ^N × ℝ^N',
+        dynamics: 'm u_n″ = κ(u_{n+1} − 2u_n + u_{n−1})',
+        observables: ['u_n', 'u_n′', 'dispersion'],
+        parameters: [
+            { name: 'm', dim: MASS },
+            { name: 'kappa', dim: SPRING_CONSTANT },
+            { name: 'a', dim: LENGTH },
+        ],
+        dimensionlessInputs: ['qa'],
+        canonicalRefs: [],
+    }),
+    model({
+        id: 'model-wave-1d',
+        stateSpace: 'u(x, t), a field on ℝ × ℝ',
+        dynamics: 'u_tt = c² u_xx',
+        observables: ['u', 'u_t', 'dispersion'],
+        parameters: [{ name: 'c', dim: VELOCITY }],
+        dimensionlessInputs: [],
+        canonicalRefs: ['CE-wave-speed'],
+    }),
+    model({
+        id: 'model-cubic-spring',
+        stateSpace: '(x, x′) ∈ ℝ²',
+        dynamics: 'm x″ + k x + β x³ = 0',
+        observables: ['x', 'x′', 'amplitude-dependent period'],
+        parameters: [
+            { name: 'm', dim: MASS },
+            { name: 'k', dim: SPRING_CONSTANT },
+            { name: 'beta', dim: CUBIC_STIFFNESS },
+            { name: 'x0', dim: LENGTH },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: [],
+    }),
+    model({
+        id: 'model-first-order',
+        stateSpace: 'x ∈ ℝ',
+        dynamics: 'b x′ + k x = 0',
+        observables: ['x'],
+        parameters: [
+            { name: 'b', dim: DAMPING },
+            { name: 'k', dim: SPRING_CONSTANT },
+        ],
+        dimensionlessInputs: [],
+        canonicalRefs: [],
+    }),
+];
+const BY_ID = new Map(ATLAS_MODELS.map((m) => [m.id, m]));
+/** Look up a model by id, throwing on an unknown one. @internal */
+export function getAtlasModel(id) {
+    const found = BY_ID.get(id);
+    if (found === undefined)
+        throw new Error(`unknown atlas model id: ${id}`);
+    return found;
+}
+//# sourceMappingURL=models.js.map

package/dist/atlas/oscillators/models.js.map

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

package/dist/atlas/oscillators/rejections.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Phase 0 REJECTION record: a claimed bridge the atlas records as refuted,
+ * together with the witness that refutes it.
+ *
+ * `ax-cubic-spring-lc` claims the cubic (Duffing-type) spring
+ * `m x″ + k x + β x³ = 0` is exactly equivalent to the LC circuit
+ * `L q″ + q/C = 0`. It is not. The cubic spring's variable set
+ * {m, k, β, x0} carries exactly ONE dimensionless group, `β x0² / k`, which
+ * measures the nonlinearity and has no counterpart on the LC side: the LC
+ * variable set is dimensionally independent and admits no group at all. A
+ * surviving group with no image cannot be matched by any change of variables,
+ * so no exact equivalence exists.
+ *
+ * @module atlas/oscillators/rejections
+ */
+import type { AtlasRejection } from '../types.js';
+/** The rejected bridges of the oscillator pilot. @internal */
+export declare const ATLAS_REJECTIONS: readonly AtlasRejection[];
+/** Look up a rejection by id, throwing on an unknown one. @internal */
+export declare function getAtlasRejection(id: string): AtlasRejection;
+//# sourceMappingURL=rejections.d.ts.map

package/dist/atlas/oscillators/rejections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejections.d.ts","sourceRoot":"","sources":["../../../src/atlas/oscillators/rejections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EA8BrD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAI5D"}

package/dist/atlas/oscillators/rejections.js

@@ -0,0 +1,54 @@
+/**
+ * The Phase 0 REJECTION record: a claimed bridge the atlas records as refuted,
+ * together with the witness that refutes it.
+ *
+ * `ax-cubic-spring-lc` claims the cubic (Duffing-type) spring
+ * `m x″ + k x + β x³ = 0` is exactly equivalent to the LC circuit
+ * `L q″ + q/C = 0`. It is not. The cubic spring's variable set
+ * {m, k, β, x0} carries exactly ONE dimensionless group, `β x0² / k`, which
+ * measures the nonlinearity and has no counterpart on the LC side: the LC
+ * variable set is dimensionally independent and admits no group at all. A
+ * surviving group with no image cannot be matched by any change of variables,
+ * so no exact equivalence exists.
+ *
+ * @module atlas/oscillators/rejections
+ */
+/** The rejected bridges of the oscillator pilot. @internal */
+export const ATLAS_REJECTIONS = [
+    {
+        id: 'ax-cubic-spring-lc',
+        claimed: 'exact-equivalence',
+        premises: ['model-cubic-spring'],
+        conclusion: 'model-lc',
+        reason: 'The cubic spring retains one dimensionless group, β x0² / k, that measures ' +
+            'its nonlinearity, and the LC variable set has none (W3). A surviving group ' +
+            'is necessary evidence, not sufficient. The decisive fact is isochrony: the ' +
+            'LC period is the same at every amplitude, the cubic spring period is not ' +
+            '(W3b), and a change of variables that rescales time by a constant multiplies ' +
+            'every period by the same factor. So no such change of variables makes the two ' +
+            'models exactly equivalent.',
+        survivingGroup: 'β x0² / k',
+        witnesses: [
+            {
+                id: 'W3',
+                kind: 'symbolic',
+                test: 'tests/atlas/oscillators-coarse.test.ts',
+                tolerance: 'exact integer π-group exponents; LC verdict dimensionally-independent',
+            },
+            {
+                id: 'W3b',
+                kind: 'numeric',
+                test: 'tests/atlas/oscillators-coarse.test.ts',
+                tolerance: 'linear period 2π within 1e-6 at A = 0.5, 1, 2; cubic-spring periods spread by more than 10% at β x0²/k = 0.1',
+            },
+        ],
+    },
+];
+/** Look up a rejection by id, throwing on an unknown one. @internal */
+export function getAtlasRejection(id) {
+    const found = ATLAS_REJECTIONS.find((r) => r.id === id);
+    if (found === undefined)
+        throw new Error(`unknown atlas rejection id: ${id}`);
+    return found;
+}
+//# sourceMappingURL=rejections.js.map

package/dist/atlas/oscillators/rejections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejections.js","sourceRoot":"","sources":["../../../src/atlas/oscillators/rejections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD;QACE,EAAE,EAAE,oBAAoB;QACxB,OAAO,EAAE,mBAAmB;QAC5B,QAAQ,EAAE,CAAC,oBAAoB,CAAC;QAChC,UAAU,EAAE,UAAU;QACtB,MAAM,EACJ,6EAA6E;YAC7E,6EAA6E;YAC7E,6EAA6E;YAC7E,2EAA2E;YAC3E,+EAA+E;YAC/E,gFAAgF;YAChF,4BAA4B;QAC9B,cAAc,EAAE,WAAW;QAC3B,SAAS,EAAE;YACT;gBACE,EAAE,EAAE,IAAI;gBACR,IAAI,EAAE,UAAU;gBAChB,IAAI,EAAE,wCAAwC;gBAC9C,SAAS,EAAE,uEAAuE;aACnF;YACD;gBACE,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,wCAAwC;gBAC9C,SAAS,EAAE,8GAA8G;aAC1H;SACF;KACF;CACF,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;IAC9E,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/atlas/path-bound.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Routes through an atlas family, and the error bound a route carries.
+ *
+ * Two functions, and the second is the one that can do damage:
+ *
+ * - {@link findPath} is pure graph search. It answers "is there a chain of
+ *   bridges from A to B", and nothing more. A path existing says NOTHING about
+ *   whether that path supports a claim.
+ * - {@link boundPath} answers "what error bound does this chain carry", and its
+ *   default answer is NO BOUND. `docs/planning/Atlas-Phase-2-Design.md` §3:
+ *
+ *   > A path containing any edge whose relation composes to
+ *   > `'no-composite-claim'` has NO bound. It must return an explicit no-claim,
+ *   > never a number. A composed number over an undefined composite would be
+ *   > the most dangerous output this library could produce: precise-looking and
+ *   > unfounded.
+ *
+ * So {@link boundPath} returns a DISCRIMINATED UNION, not a number. A caller
+ * cannot read `.bound` off a no-claim, because a no-claim has no `.bound` — the
+ * refusal is enforced by the type rather than by a documented convention.
+ *
+ * ## Norms — why an exact edge does not compose for free
+ *
+ * `./error-algebra.ts` states the rule this module obeys, and it is narrower
+ * than it first reads:
+ *
+ * > An exact equivalence contributes `IDENTITY_BOUND` **in the norms these
+ * > Phase 0 bridges state** — not in every norm.
+ *
+ * An `exact-equivalence` bridge carries no `bound`, hence states no `norm`. It
+ * therefore contributes `IDENTITY_BOUND` in NO norm, and a path that mixes it
+ * with a normed bound cannot claim the composite holds in that norm. That is a
+ * `'norm-not-stated'` no-claim. The composed NUMBER would be unchanged —
+ * composing with the identity is arithmetically a no-op — which is exactly what
+ * makes the error invisible without this gate: the danger is not a wrong
+ * magnitude, it is a right magnitude attached to the wrong norm.
+ *
+ * ⚠ **Correction to the S2.2 brief.** The brief states that no field records a
+ * norm and that Phase 2 must add `norm?` to `ApproximationBound`. That is
+ * out of date: `ApproximationBound.norm` already exists as a MANDATORY
+ * `string` (Phase 0, `./types.ts`). No type change was needed, and this module
+ * reads the field that is already there.
+ *
+ * **Uniformity is gated here, at use.** `ApproximationBound.uniformity` may
+ * be `null` (or empty — the same state) so a real bound can be recorded
+ * before anyone has analysed what the error is uniform in. Composing such a
+ * bound would attach a number to an unanalysed claim, so {@link boundPath}
+ * returns `'uniformity-unanalysed'` and does not compute one.
+ * `propagateUncertainty` does not read the field and does not fold `delta`
+ * into `sigma`: it stays a statistical-sigma function.
+ *
+ * Pure: no I/O, no registry reads.
+ *
+ * @module atlas/path-bound
+ */
+import { IDENTITY_BOUND } from './error-algebra.js';
+import type { BoundPair } from './error-algebra.js';
+import type { AtlasBridge, RelationType } from './types.js';
+/**
+ * Shortest chain of bridges from `from` to `to`, or `null` if none exists.
+ *
+ * Breadth-first, so the result is a shortest path by edge count. Ties are
+ * broken by `family.bridges` order, which is the design note's order and is
+ * therefore stable across runs.
+ *
+ * A returned path is a ROUTE, not a warrant: ask {@link boundPath} what the
+ * route supports.
+ *
+ * @throws RangeError if `family` is not a known family, or an endpoint is not
+ *   one of its models. An unknown endpoint returning `null` would be
+ *   indistinguishable from a genuinely disconnected pair.
+ * @internal
+ */
+export declare function findPath(family: string, from: string, to: string): readonly AtlasBridge[] | null;
+/** Why a path supports no bound. @internal */
+export type NoClaimReason = 
+/** The relations along the path do not compose to a relation at all. */
+'no-composite-claim'
+/** An edge on the path states no norm, so the composite holds in none. */
+ | 'norm-not-stated'
+/** Two edges state DIFFERENT norms; composing across norms is unsound. */
+ | 'norm-mismatch'
+/**
+ * A bound on the path has `uniformity === null` or an empty list: what the
+ * error is uniform in has not been analysed, so no number is stated.
+ */
+ | 'uniformity-unanalysed';
+/** A path that DOES carry a bound. @internal */
+export interface PathBoundClaim {
+    readonly kind: 'bound';
+    readonly bound: BoundPair;
+    /** True when the path ended on a step with no Lipschitz constant. */
+    readonly terminal: boolean;
+    /** The relation the chain asserts, from {@link composeRelation}. */
+    readonly relation: RelationType;
+    /**
+     * The single norm every bound on the path states, or `null` when the path
+     * carries no bound at all and the claim is the vacuous `terminal` identity
+     * over an empty prefix.
+     */
+    readonly norm: string | null;
+}
+/** A path that carries NO bound, and the reason. @internal */
+export interface PathNoClaim {
+    readonly kind: 'no-claim';
+    readonly reason: NoClaimReason;
+    /** Human-readable specifics: which edge, which norms. */
+    readonly detail: string;
+}
+/** The result of {@link boundPath}: a bound, or an explicit refusal. @internal */
+export type PathBoundResult = PathBoundClaim | PathNoClaim;
+/**
+ * The error bound a chain of bridges carries — or an explicit no-claim.
+ *
+ * Four gates, in this order. Each one is a reason to refuse, and the FIRST
+ * reason found is the one reported; none of them is skippable by a caller.
+ *
+ * 1. **Relation.** `composeRelation` is folded along the path. The moment the
+ *    running composite is `'no-composite-claim'`, the path has no bound. This
+ *    is design note §3 constraint 1 and it is checked before any arithmetic,
+ *    so no number is ever computed for a path that cannot carry one.
+ * 2. **Uniformity.** Any bound whose `uniformity` is `null` or empty is not
+ *    yet analysed. The path returns `'uniformity-unanalysed'` and no Lipschitz
+ *    arithmetic runs. An edge with no `bound` — an exact equivalence, or an
+ *    unbounded coarse-graining — does not fail this gate.
+ * 3. **Lipschitz.** `composeBoundPath` folds the per-edge pairs. A `null` — an
+ *    edge that is neither bounded nor exact — is tolerated only as the LAST
+ *    entry, where it terminates the claim (`terminal: true`); anywhere else it
+ *    throws `MissingLipschitzError` rather than inventing a constant.
+ * 4. **Norm.** Every stated norm on the path must be the SAME norm, and no
+ *    unnormed exact map may carry a normed claim. An `exact-equivalence`
+ *    states no norm (it has no `bound`), so a path mixing one with a normed
+ *    bound is `'norm-not-stated'` — see the module note.
+ *
+ * @throws RangeError on an empty path. Returning `IDENTITY_BOUND` for "no
+ *   edges" would be a bound asserted about nothing.
+ * @throws MissingLipschitzError via {@link composeBoundPath}; see gate 3.
+ * @internal
+ */
+export declare function boundPath(bridges: readonly AtlasBridge[]): PathBoundResult;
+/** Re-exported so a caller need not reach into the algebra module. @internal */
+export { IDENTITY_BOUND };
+//# sourceMappingURL=path-bound.d.ts.map

package/dist/atlas/path-bound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-bound.d.ts","sourceRoot":"","sources":["../../src/atlas/path-bound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAoB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGpD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA+C5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,SAAS,WAAW,EAAE,GAAG,IAAI,CA2C/B;AAED,8CAA8C;AAC9C,MAAM,MAAM,aAAa;AACvB,wEAAwE;AACtE,oBAAoB;AACtB,0EAA0E;GACxE,iBAAiB;AACnB,0EAA0E;GACxE,eAAe;AACjB;;;GAGG;GACD,uBAAuB,CAAC;AAE5B,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,eAAe,CAkG1E;AAED,gFAAgF;AAChF,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/atlas/path-bound.js

@@ -0,0 +1,268 @@
+/**
+ * Routes through an atlas family, and the error bound a route carries.
+ *
+ * Two functions, and the second is the one that can do damage:
+ *
+ * - {@link findPath} is pure graph search. It answers "is there a chain of
+ *   bridges from A to B", and nothing more. A path existing says NOTHING about
+ *   whether that path supports a claim.
+ * - {@link boundPath} answers "what error bound does this chain carry", and its
+ *   default answer is NO BOUND. `docs/planning/Atlas-Phase-2-Design.md` §3:
+ *
+ *   > A path containing any edge whose relation composes to
+ *   > `'no-composite-claim'` has NO bound. It must return an explicit no-claim,
+ *   > never a number. A composed number over an undefined composite would be
+ *   > the most dangerous output this library could produce: precise-looking and
+ *   > unfounded.
+ *
+ * So {@link boundPath} returns a DISCRIMINATED UNION, not a number. A caller
+ * cannot read `.bound` off a no-claim, because a no-claim has no `.bound` — the
+ * refusal is enforced by the type rather than by a documented convention.
+ *
+ * ## Norms — why an exact edge does not compose for free
+ *
+ * `./error-algebra.ts` states the rule this module obeys, and it is narrower
+ * than it first reads:
+ *
+ * > An exact equivalence contributes `IDENTITY_BOUND` **in the norms these
+ * > Phase 0 bridges state** — not in every norm.
+ *
+ * An `exact-equivalence` bridge carries no `bound`, hence states no `norm`. It
+ * therefore contributes `IDENTITY_BOUND` in NO norm, and a path that mixes it
+ * with a normed bound cannot claim the composite holds in that norm. That is a
+ * `'norm-not-stated'` no-claim. The composed NUMBER would be unchanged —
+ * composing with the identity is arithmetically a no-op — which is exactly what
+ * makes the error invisible without this gate: the danger is not a wrong
+ * magnitude, it is a right magnitude attached to the wrong norm.
+ *
+ * ⚠ **Correction to the S2.2 brief.** The brief states that no field records a
+ * norm and that Phase 2 must add `norm?` to `ApproximationBound`. That is
+ * out of date: `ApproximationBound.norm` already exists as a MANDATORY
+ * `string` (Phase 0, `./types.ts`). No type change was needed, and this module
+ * reads the field that is already there.
+ *
+ * **Uniformity is gated here, at use.** `ApproximationBound.uniformity` may
+ * be `null` (or empty — the same state) so a real bound can be recorded
+ * before anyone has analysed what the error is uniform in. Composing such a
+ * bound would attach a number to an unanalysed claim, so {@link boundPath}
+ * returns `'uniformity-unanalysed'` and does not compute one.
+ * `propagateUncertainty` does not read the field and does not fold `delta`
+ * into `sigma`: it stays a statistical-sigma function.
+ *
+ * Pure: no I/O, no registry reads.
+ *
+ * @module atlas/path-bound
+ */
+import { composeBoundPath, IDENTITY_BOUND } from './error-algebra.js';
+import { composeRelation, NO_COMPOSITE_CLAIM } from './composition-table.js';
+import { ATLAS_FAMILIES } from './families.js';
+/**
+ * Families {@link findPath} can search: every registered family. This was the
+ * oscillator family alone, which made the diffusion and wave families
+ * unsearchable once they existed. A route stays INSIDE one family: a bridge
+ * that ends in another family's model is not followed across (stated, not
+ * hidden — cross-family routes are out of this function's scope).
+ *
+ * @internal
+ */
+const FAMILIES = Object.fromEntries(ATLAS_FAMILIES.map((f) => [f.family, f]));
+/** Expand a family's bridges into directed edges. Single-premise chains only. */
+function directedEdges(family) {
+    const edges = [];
+    for (const bridge of family.bridges) {
+        // Sprint 2 scope: a multi-premise bridge is a JOIN, not a link in a chain,
+        // and is skipped rather than silently reduced to its first premise.
+        if (bridge.premises.length !== 1)
+            continue;
+        const from = bridge.premises[0];
+        edges.push({ from, to: bridge.conclusion, bridge });
+        if (bridge.relation === 'exact-equivalence') {
+            edges.push({ from: bridge.conclusion, to: from, bridge });
+        }
+    }
+    return edges;
+}
+/**
+ * Shortest chain of bridges from `from` to `to`, or `null` if none exists.
+ *
+ * Breadth-first, so the result is a shortest path by edge count. Ties are
+ * broken by `family.bridges` order, which is the design note's order and is
+ * therefore stable across runs.
+ *
+ * A returned path is a ROUTE, not a warrant: ask {@link boundPath} what the
+ * route supports.
+ *
+ * @throws RangeError if `family` is not a known family, or an endpoint is not
+ *   one of its models. An unknown endpoint returning `null` would be
+ *   indistinguishable from a genuinely disconnected pair.
+ * @internal
+ */
+export function findPath(family, from, to) {
+    const fam = FAMILIES[family];
+    if (fam === undefined) {
+        throw new RangeError(`findPath: unknown family '${family}'`);
+    }
+    const models = new Set(fam.models.map((m) => m.id));
+    for (const endpoint of [from, to]) {
+        if (!models.has(endpoint)) {
+            throw new RangeError(`findPath: '${endpoint}' is not a model of family '${family}'`);
+        }
+    }
+    if (from === to)
+        return [];
+    const outgoing = new Map();
+    for (const edge of directedEdges(fam)) {
+        const bucket = outgoing.get(edge.from);
+        if (bucket === undefined)
+            outgoing.set(edge.from, [edge]);
+        else
+            bucket.push(edge);
+    }
+    const cameBy = new Map();
+    const seen = new Set([from]);
+    const queue = [from];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        for (const edge of outgoing.get(node) ?? []) {
+            if (seen.has(edge.to))
+                continue;
+            seen.add(edge.to);
+            cameBy.set(edge.to, edge);
+            if (edge.to === to) {
+                const path = [];
+                for (let at = to; at !== from;) {
+                    const step = cameBy.get(at);
+                    path.unshift(step.bridge);
+                    at = step.from;
+                }
+                return path;
+            }
+            queue.push(edge.to);
+        }
+    }
+    return null;
+}
+/**
+ * The error bound a chain of bridges carries — or an explicit no-claim.
+ *
+ * Four gates, in this order. Each one is a reason to refuse, and the FIRST
+ * reason found is the one reported; none of them is skippable by a caller.
+ *
+ * 1. **Relation.** `composeRelation` is folded along the path. The moment the
+ *    running composite is `'no-composite-claim'`, the path has no bound. This
+ *    is design note §3 constraint 1 and it is checked before any arithmetic,
+ *    so no number is ever computed for a path that cannot carry one.
+ * 2. **Uniformity.** Any bound whose `uniformity` is `null` or empty is not
+ *    yet analysed. The path returns `'uniformity-unanalysed'` and no Lipschitz
+ *    arithmetic runs. An edge with no `bound` — an exact equivalence, or an
+ *    unbounded coarse-graining — does not fail this gate.
+ * 3. **Lipschitz.** `composeBoundPath` folds the per-edge pairs. A `null` — an
+ *    edge that is neither bounded nor exact — is tolerated only as the LAST
+ *    entry, where it terminates the claim (`terminal: true`); anywhere else it
+ *    throws `MissingLipschitzError` rather than inventing a constant.
+ * 4. **Norm.** Every stated norm on the path must be the SAME norm, and no
+ *    unnormed exact map may carry a normed claim. An `exact-equivalence`
+ *    states no norm (it has no `bound`), so a path mixing one with a normed
+ *    bound is `'norm-not-stated'` — see the module note.
+ *
+ * @throws RangeError on an empty path. Returning `IDENTITY_BOUND` for "no
+ *   edges" would be a bound asserted about nothing.
+ * @throws MissingLipschitzError via {@link composeBoundPath}; see gate 3.
+ * @internal
+ */
+export function boundPath(bridges) {
+    if (bridges.length === 0) {
+        throw new RangeError('boundPath: an empty path composes nothing; there is no bound to state');
+    }
+    // ── Gate 1: the relation must compose all the way along ───────────────────
+    let relation = bridges[0].relation;
+    for (let i = 1; i < bridges.length; i++) {
+        const next = bridges[i];
+        // The loop RETURNS on the first silent cell, so `relation` is always a
+        // real `RelationType` here — no re-check is needed, and TypeScript proves
+        // it (a guard here is flagged as having no overlap).
+        relation = composeRelation(relation, next.relation);
+        if (relation === NO_COMPOSITE_CLAIM) {
+            return {
+                kind: 'no-claim',
+                reason: NO_COMPOSITE_CLAIM,
+                detail: `'${bridges[i - 1].id}' (${bridges[i - 1].relation}) then '${next.id}' ` +
+                    `(${next.relation}) composes to no relation, so the path carries no bound`,
+            };
+        }
+    }
+    // ── Gate 2: an unanalysed uniformity yields no number ─────────────────────
+    // Before any Lipschitz arithmetic. `null` and `[]` are the same state: an
+    // empty list is a universal over nothing, and counting it as analysed is
+    // the convention-checked empty-object defect. An edge with no bound states
+    // no error, so it does not fail this gate.
+    for (const bridge of bridges) {
+        if (bridge.bound === undefined)
+            continue;
+        const uniformity = bridge.bound.uniformity;
+        if (uniformity === null || uniformity.length === 0) {
+            const how = uniformity === null ? 'null' : 'empty';
+            return {
+                kind: 'no-claim',
+                reason: 'uniformity-unanalysed',
+                detail: `'${bridge.id}' has uniformity ${how} (not yet analysed), so the path carries no numeric bound`,
+            };
+        }
+    }
+    // ── Collect the per-edge pairs the remaining gates read ───────────────────
+    // What each edge contributes. The split that matters: an `exact-equivalence`
+    // with no `bound` is EXACT — it contributes `IDENTITY_BOUND`, not an unknown
+    // constant. Any OTHER relation with no bound has an unknown Lipschitz
+    // constant, and `null` is what says so. Conflating the two would either
+    // invent a constant for a lossy map or throw on an exact one.
+    const pairs = [];
+    const norms = new Set();
+    const unnormedIdentities = [];
+    for (const bridge of bridges) {
+        if (bridge.bound !== undefined) {
+            pairs.push({ K: bridge.bound.K, delta: bridge.bound.delta });
+            norms.add(bridge.bound.norm);
+        }
+        else if (bridge.relation === 'exact-equivalence') {
+            pairs.push(IDENTITY_BOUND);
+            unnormedIdentities.push(bridge.id);
+        }
+        else {
+            pairs.push(null);
+        }
+    }
+    // ── Gate 3: an unknown Lipschitz constant, anywhere but last, is fatal ────
+    // Delegated to `composeBoundPath`, which throws `MissingLipschitzError`
+    // rather than inventing a constant. Run BEFORE the norm gate: an unbounded
+    // composite is a harder failure than an unstatable norm, and reporting the
+    // softer one would mask it.
+    const composed = composeBoundPath(pairs);
+    // ── Gate 4: one norm, and no unnormed map carrying a normed claim ─────────
+    if (norms.size > 1) {
+        return {
+            kind: 'no-claim',
+            reason: 'norm-mismatch',
+            detail: `the path states ${norms.size} different norms (${[...norms].map((n) => `'${n}'`).join(', ')}); ` +
+                'bounds in different norms do not compose',
+        };
+    }
+    if (unnormedIdentities.length > 0 && norms.size > 0) {
+        return {
+            kind: 'no-claim',
+            reason: 'norm-not-stated',
+            detail: `${unnormedIdentities.map((id) => `'${id}'`).join(', ')} state no norm, so they ` +
+                `contribute IDENTITY_BOUND in no norm; the composite cannot be claimed in ` +
+                `'${[...norms][0]}'`,
+        };
+    }
+    return {
+        kind: 'bound',
+        bound: composed.bound,
+        terminal: composed.terminal,
+        relation,
+        norm: [...norms][0] ?? null,
+    };
+}
+/** Re-exported so a caller need not reach into the algebra module. @internal */
+export { IDENTITY_BOUND };
+//# sourceMappingURL=path-bound.js.map