universal-physics-tensor 0.5.1 → 0.7.0

package/dist/core/cell.js

@@ -0,0 +1,166 @@
+/**
+ * Typed `Cell` discriminated union for `UniversalTensor`'s cell storage.
+ *
+ * Three variants — `LawCell`, `BridgeCell`, `EmergenceCell` — each
+ * carrying a `kind` discriminator that lets TypeScript narrow to the
+ * specific variant at every consumption site. Mirrors the v0.6.1
+ * validator-registry's discriminated-union pattern at
+ * `src/dimensional/validator-registry.ts`.
+ *
+ * Design doc: `docs/planning/v0.7-Proposal-3-Design.md`.
+ * Review findings: `docs/planning/v0.7-Proposal-3-Review-Findings.md`.
+ *
+ * Migration relationship to `src/core/types.ts`:
+ *   - `PhysicalLaw` ↔ `LawCell` (field-shape faithful; `confidence`
+ *     flips `number` → string-literal union)
+ *   - `BridgeEquation` ↔ `BridgeCell` (same migration)
+ *   - `EmergentPhenomenon` ↔ `EmergenceCell` (same migration)
+ *
+ * The old interfaces are NOT deleted and NOT `@deprecated`-tagged in
+ * this sprint (per Eve-R2 + the Phase 0 consumer-import census:
+ * 4 in-repo sites still use them). A future v0.7.x sprint migrates
+ * those consumers and then adds `@deprecated`.
+ *
+ * **No `confidenceToStatus` adapter is shipped** (per Eve-R3). The
+ * 42-bridge catalog has BOTH a numeric `confidence` AND a curated
+ * string `status` field, set independently; an adapter would
+ * produce labels that contradict the catalog curation
+ * (e.g. `status: 'established'` + `confidence: 0.7` → adapter
+ * returns `'speculative'`). Callers must pass the string explicitly
+ * at cell-construction sites.
+ *
+ * @module core/cell
+ */
+import { UniversalTensor } from './tensor.js';
+/**
+ * Factory: build a populated `UniversalTensor` from three typed cell
+ * arrays plus a `TensorConfig`.
+ *
+ * Makes the "'+' in Π = L + B + E is disjoint union, not algebraic"
+ * invariant concrete: the only way to construct a populated
+ * `UniversalTensor` from typed cells is to pass three typed arrays.
+ * There is no `add(c1: Cell, c2: Cell): Cell` because cells never
+ * compose at the cell level — composition happens at the tensor
+ * level (Proposals 2 and 6 territory).
+ *
+ * **Provenance note**: the proposals doc §4.2 line 299 sketches
+ * `compose(L, B, E): UniversalTensor` without a `config` argument.
+ * This signature closes a proposals-doc gap — `UniversalTensor`'s
+ * constructor requires `rank` / `scales` / `forces`, none of which
+ * can be inferred from the three cell arrays alone. `compose` is
+ * this sprint's invention, not a proposals-doc commitment.
+ *
+ * @public
+ */
+export function compose(laws, bridges, emergences, config) {
+    const tensor = new UniversalTensor(config);
+    for (const law of laws)
+        tensor.addCell(law);
+    for (const bridge of bridges)
+        tensor.addCell(bridge);
+    for (const emergence of emergences)
+        tensor.addCell(emergence);
+    return tensor;
+}
+// ---------------------------------------------------------------------------
+// Inverse adapters (legacy interface → Cell variant)
+// ---------------------------------------------------------------------------
+// Used by UniversalTensor.populatedCells() (Phase 2 Task 2.1) to resolve
+// stored cell-IDs back to Cell objects. Counterparts to the forward
+// adapters (cellToLaw / cellToBridge / cellToEmergence) at tensor.ts.
+//
+// The numeric `confidence: number` from the legacy interfaces is bucketed
+// back into the string vocabulary via `numberToCellConfidence`. This is
+// the lossy direction Eve-R3 flagged — but in THIS direction, the call
+// site is "we have a legacy entry that was already in the tensor; bucket
+// its numeric confidence into the closest string label". Per Decision #6
+// fan-out semantics, this can only happen for entries that round-tripped
+// through `addCell` (where the original string was authoritative) OR
+// entries added via the legacy `addLaw`/`addBridge`/`addEmergence` paths
+// (where the consumer chose a number directly). The bucketing matches
+// the forward `statusToConfidenceNumber` in tensor.ts: 0.95→established,
+// 0.6→speculative, 0.3→highly-speculative; thresholds chosen to make
+// the standard round-trip exact.
+/**
+ * Inverse of `statusToConfidenceNumber` at tensor.ts:48-58. Buckets a
+ * numeric confidence in [0,1] back to the string vocabulary. Used by
+ * the inverse adapters below.
+ *
+ * @internal
+ */
+export function numberToCellConfidence(n) {
+    if (n >= 0.8)
+        return 'established';
+    if (n >= 0.4)
+        return 'speculative';
+    return 'highly-speculative';
+}
+/**
+ * Adapter: `PhysicalLaw` (legacy) → `LawCell`. Used by
+ * `UniversalTensor.populatedCells()`.
+ *
+ * @internal
+ */
+export function lawToCell(law) {
+    return {
+        kind: 'law',
+        id: law.id,
+        name: law.name,
+        equation: law.equation,
+        confidence: numberToCellConfidence(law.confidence),
+        scales: law.scales,
+        forces: law.forces,
+        symmetries: law.symmetries,
+        ...(law.informationMeasures ? { informationMeasures: law.informationMeasures } : {}),
+        ...(law.dimensions ? { dimensions: law.dimensions } : {}),
+        ...(law.topologies ? { topologies: law.topologies } : {}),
+        ...(law.references ? { references: law.references } : {}),
+    };
+}
+/**
+ * Adapter: `BridgeEquation` (legacy) → `BridgeCell`. Used by
+ * `UniversalTensor.populatedCells()`.
+ *
+ * @internal
+ */
+export function bridgeToCell(b) {
+    return {
+        kind: 'bridge',
+        id: b.id,
+        name: b.name,
+        equation: b.equation,
+        confidence: numberToCellConfidence(b.confidence),
+        source: b.source,
+        target: b.target,
+        validated: b.validated,
+        description: b.description,
+    };
+}
+/**
+ * Adapter: `EmergentPhenomenon` (legacy) → `EmergenceCell`. The
+ * legacy `description` field holds the mathematical content (LaTeX);
+ * we surface it as `equation` and leave `description` undefined
+ * unless the legacy entry had a "math\n\nprose" split (per the
+ * forward `cellToEmergence` adapter convention).
+ *
+ * @internal
+ */
+export function emergenceToCell(p) {
+    // Split convention: if description contains "\n\n", treat the part
+    // before as equation and after as prose; otherwise the whole field
+    // is the equation.
+    const splitIdx = p.description.indexOf('\n\n');
+    const equation = splitIdx === -1 ? p.description : p.description.slice(0, splitIdx);
+    const description = splitIdx === -1 ? undefined : p.description.slice(splitIdx + 2);
+    return {
+        kind: 'emergence',
+        id: p.id,
+        name: p.name,
+        equation,
+        confidence: numberToCellConfidence(p.confidence),
+        order: p.order,
+        indices: p.indices,
+        ...(description ? { description } : {}),
+    };
+}
+//# sourceMappingURL=cell.js.map

package/dist/core/cell.js.map

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

package/dist/core/flux-rules.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Flux-rule scaffolding for v0.7 Proposal 2 — Sparse Semantic Catalog.
+ *
+ * Defines:
+ *   - `FluxRuleKind` discriminated tag (@internal)
+ *   - `FluxRule`, `FluxRuleResult` registry shapes (@internal)
+ *   - `FluxDiagnostic`, `FluxReport` consumer shapes (@public)
+ *   - `FluxViolationError` (@public) thrown on ERROR-tier rule failures
+ *   - Rule 2 (L/B/E coordinate matching) and Rule 3 (Causality) — pure
+ *     functions over `Cell` / `BridgeCell`
+ *   - `runRules(cell, rules)` dispatcher with `_exhaustive: never`
+ *
+ * Rule 1 (Dimensional Consistency) ships in Phase 3 alongside the
+ * catalog adapter — it operates on `BridgeEquationEntry`, not `Cell`,
+ * per Decision #3 (resolves Adam-V3).
+ *
+ * Design: docs/planning/v0.7-Proposal-2-Design.md (redraft commit
+ * 01632b5). Decisions #5, #6, #8 are load-bearing here.
+ *
+ * @module core/flux-rules
+ */
+import type { Cell } from './cell.js';
+/**
+ * A single rule-evaluation outcome surfaced to consumers via
+ * `fluxDiagnostics()` or `FluxViolationError`. Severity follows the
+ * info/warning/error tiering pinned in the design.
+ *
+ * @public
+ */
+export interface FluxDiagnostic {
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly ruleName: FluxRuleKind;
+    readonly cellId: string;
+    readonly message: string;
+}
+/**
+ * Aggregated report returned by `runRules()` / consumer-facing
+ * `fluxDiagnostics()`. Per-tier counts are pre-computed for cheap
+ * consumer-side branching.
+ *
+ * @public
+ */
+export interface FluxReport {
+    readonly diagnostics: ReadonlyArray<FluxDiagnostic>;
+    readonly errorCount: number;
+    readonly warningCount: number;
+    readonly infoCount: number;
+}
+/**
+ * Thrown from `UniversalTensor.addCell` (Phase 2) when a Rule 2
+ * (L/B/E coordinate-matching) violation fires. Rule 2 is ERROR-tier:
+ * a `BridgeCell` with `source === target`, a `LawCell` with empty
+ * `scales × forces`, or an `EmergenceCell` with `indices.length < 2`
+ * fail-atomic.
+ *
+ * Rule 3 (Causality) does NOT throw — it's WARNING-tier in v0.7 per
+ * the proposals doc §3.3.3 (promotion to ERROR deferred to v0.8).
+ *
+ * @public
+ */
+export declare class FluxViolationError extends Error {
+    readonly ruleName: FluxRuleKind;
+    readonly cellId: string;
+    constructor(ruleName: FluxRuleKind, cellId: string, message: string);
+}
+/**
+ * Discriminated tag for the in-tree flux rules. Adding a new rule
+ * kind forces a compile-time update to every `switch` over this
+ * union via the `_exhaustive: never` discipline.
+ *
+ * - v0.7 (P2): `'dimensional-consistency' | 'lbe-coordinate' | 'causality'`
+ * - v0.8 (P5): adds `'regime-consistency'` — fires from `addCell`
+ *   when a cell's attached regimes contradict the cell's coordinate
+ *   axes (e.g., a `LawCell` with `scales: ['classical']` attached
+ *   to a `quantum` regime via `attachRegimesToCell`).
+ *
+ * @internal — coupled to the registry's dispatch shape; not part of
+ * the v0.7 public-API contract.
+ */
+export type FluxRuleKind = 'dimensional-consistency' | 'lbe-coordinate' | 'causality' | 'regime-consistency';
+/**
+ * Result returned by a single rule's `check()` body. `ok: true` means
+ * the rule passed; `ok: false` means the rule violated. A diagnostic
+ * may be attached on either path (`'info'` diagnostics ride with
+ * `ok: true`; `'warning'` and `'error'` diagnostics ride with
+ * `ok: false`).
+ *
+ * @internal
+ */
+export interface FluxRuleResult {
+    readonly ok: boolean;
+    readonly diagnostic?: FluxDiagnostic;
+}
+/**
+ * A registered rule. The `check()` body is a pure function over
+ * `Cell` (or a sub-variant if the rule only fires on one `kind`).
+ *
+ * @internal
+ */
+export interface FluxRule {
+    readonly kind: FluxRuleKind;
+    readonly check: (cell: Cell) => FluxRuleResult;
+}
+/**
+ * Pure dispatcher for Rule 2 over the `Cell` discriminated union.
+ * The three arms enforce the cell-shape invariants:
+ *
+ *   - `LawCell` is diagonal: `scales × forces` cross-product must be
+ *     non-empty.
+ *   - `BridgeCell` is off-diagonal: `source !== target` by at least
+ *     one axis (already enforced by the legacy `addBridge` —
+ *     Rule 2 piggybacks for registry exhaustiveness).
+ *   - `EmergenceCell` spans multi-coordinate: `indices.length >= 2`.
+ *
+ * @internal
+ */
+export declare function checkLBECoordinate(cell: Cell): FluxRuleResult;
+/**
+ * Pure dispatcher for Rule 3 over the `Cell` discriminated union.
+ * Rule 3 only fires on `'bridge'`; the other arms always pass.
+ *
+ * Body for the bridge arm per Decision #5:
+ *   1. Read `src = cell.source.scale`, `dst = cell.target.scale`.
+ *   2. If either is `undefined`, emit `'info'` ("scale-unspecified
+ *      skip"); the rule still passes (`ok: true`).
+ *   3. If `arrow = classifyArrow(src, dst) === 'reverse'`, emit a
+ *      `'warning'` diagnostic recommending audit. Rule still passes
+ *      (Rule 3 is WARNING tier in v0.7; promotion to ERROR deferred
+ *      to v0.8).
+ *   4. Suppression via the private `causalityWhitelist` (empty in
+ *      v0.7).
+ *
+ * @internal
+ */
+export declare function checkCausality(cell: Cell): FluxRuleResult;
+/**
+ * Run a set of rules against a single `cell` and aggregate the
+ * diagnostics into a `FluxReport`. Pure function — no I/O, no
+ * shared-state mutation.
+ *
+ * The switch over `FluxRuleKind` is exhaustive via the
+ * `_exhaustive: never` default arm (Decision #8). Adding a new rule
+ * kind forces a compile-time update here AND at every consumer
+ * site that branches on `FluxRuleKind`.
+ *
+ * @internal
+ */
+export declare function runRules(cell: Cell, rules: ReadonlyArray<FluxRule>): FluxReport;
+/**
+ * The two v0.7 in-tree rules registered for Phase 2 `addCell`
+ * dispatch. Rule 1 (Dimensional Consistency) is NOT here — it
+ * operates on `BridgeEquationEntry`, not `Cell`, and ships in
+ * Phase 3 alongside the catalog adapter.
+ *
+ * @internal
+ */
+export declare const V07_CELL_RULES: ReadonlyArray<FluxRule>;
+type RegimeRuleBody = (cell: Cell) => FluxRuleResult;
+/**
+ * Install P5's regime-consistency rule body. Called by
+ * `src/core/regime-rule-install.ts` at its module load. If P5's
+ * module is never imported, the regime check stays a no-op
+ * (returns `ok: true` silently).
+ *
+ * @internal
+ */
+export declare function installRegimeConsistencyRule(body: RegimeRuleBody): void;
+/**
+ * Pure dispatcher for Rule 4 over `Cell`. Delegates to the body
+ * installed by P5 if present; otherwise a permissive no-op.
+ *
+ * @internal
+ */
+export declare function checkRegimeConsistency(cell: Cell): FluxRuleResult;
+export {};
+//# sourceMappingURL=flux-rules.d.ts.map

package/dist/core/flux-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux-rules.d.ts","sourceRoot":"","sources":["../../src/core/flux-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,IAAI,EAIL,MAAM,WAAW,CAAC;AAOnB;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,QAAQ,EAAE,YAAY,CAAC;IACvC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMpE;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GACpB,yBAAyB,GACzB,gBAAgB,GAChB,WAAW,GACX,oBAAoB,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,cAAc,CAAC;CAChD;AAoDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAc7D;AAuED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAkCzD;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,GAC7B,UAAU,CAgDZ;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,QAAQ,CAIlD,CAAC;AAYF,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,cAAc,CAAC;AAIrD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAGjE"}

package/dist/core/flux-rules.js

@@ -0,0 +1,329 @@
+/**
+ * Flux-rule scaffolding for v0.7 Proposal 2 — Sparse Semantic Catalog.
+ *
+ * Defines:
+ *   - `FluxRuleKind` discriminated tag (@internal)
+ *   - `FluxRule`, `FluxRuleResult` registry shapes (@internal)
+ *   - `FluxDiagnostic`, `FluxReport` consumer shapes (@public)
+ *   - `FluxViolationError` (@public) thrown on ERROR-tier rule failures
+ *   - Rule 2 (L/B/E coordinate matching) and Rule 3 (Causality) — pure
+ *     functions over `Cell` / `BridgeCell`
+ *   - `runRules(cell, rules)` dispatcher with `_exhaustive: never`
+ *
+ * Rule 1 (Dimensional Consistency) ships in Phase 3 alongside the
+ * catalog adapter — it operates on `BridgeEquationEntry`, not `Cell`,
+ * per Decision #3 (resolves Adam-V3).
+ *
+ * Design: docs/planning/v0.7-Proposal-2-Design.md (redraft commit
+ * 01632b5). Decisions #5, #6, #8 are load-bearing here.
+ *
+ * @module core/flux-rules
+ */
+/**
+ * Thrown from `UniversalTensor.addCell` (Phase 2) when a Rule 2
+ * (L/B/E coordinate-matching) violation fires. Rule 2 is ERROR-tier:
+ * a `BridgeCell` with `source === target`, a `LawCell` with empty
+ * `scales × forces`, or an `EmergenceCell` with `indices.length < 2`
+ * fail-atomic.
+ *
+ * Rule 3 (Causality) does NOT throw — it's WARNING-tier in v0.7 per
+ * the proposals doc §3.3.3 (promotion to ERROR deferred to v0.8).
+ *
+ * @public
+ */
+export class FluxViolationError extends Error {
+    ruleName;
+    cellId;
+    constructor(ruleName, cellId, message) {
+        super(`FluxRule '${ruleName}' violated for cell '${cellId}': ${message}`);
+        this.name = 'FluxViolationError';
+        this.ruleName = ruleName;
+        this.cellId = cellId;
+    }
+}
+// ---------------------------------------------------------------------------
+// SCALE_ARROW — the partial-order on `PhysicalScale` used by Rule 3
+// ---------------------------------------------------------------------------
+/**
+ * Ordered list of scales from finest to coarsest. The index encodes
+ * the partial-order: lower index = finer (quantum), higher index =
+ * coarser (cosmological). Used by Rule 3 (Causality) to classify
+ * bridge direction as forward / lateral / reverse.
+ */
+const SCALE_ORDER = [
+    'quantum',
+    'mesoscopic',
+    'classical',
+    'cosmological',
+];
+function scaleIndex(s) {
+    return SCALE_ORDER.indexOf(s);
+}
+/**
+ * Classify a bridge direction by source/target scale. `'reverse'` =
+ * coarser→finer (e.g., classical→quantum), `'forward'` =
+ * finer→coarser (the canonical emergent direction), `'lateral'` =
+ * same scale. Per Decision #5, `'reverse'` triggers a warning
+ * diagnostic.
+ */
+function classifyArrow(src, dst) {
+    const i = scaleIndex(src);
+    const j = scaleIndex(dst);
+    if (i === j)
+        return 'lateral';
+    return i < j ? 'forward' : 'reverse';
+}
+/**
+ * Private per-cell-ID suppression list for Rule 3 (Causality). Empty
+ * in v0.7; entries earn their place via design review (Decision #5
+ * — the original "timeReversalAnnotation: true" on BridgeCell was
+ * rejected as public-type contamination per Eve-R12).
+ */
+const causalityWhitelist = new Set();
+// ---------------------------------------------------------------------------
+// Rule 2 — L/B/E coordinate matching (ERROR tier)
+// ---------------------------------------------------------------------------
+/**
+ * Pure dispatcher for Rule 2 over the `Cell` discriminated union.
+ * The three arms enforce the cell-shape invariants:
+ *
+ *   - `LawCell` is diagonal: `scales × forces` cross-product must be
+ *     non-empty.
+ *   - `BridgeCell` is off-diagonal: `source !== target` by at least
+ *     one axis (already enforced by the legacy `addBridge` —
+ *     Rule 2 piggybacks for registry exhaustiveness).
+ *   - `EmergenceCell` spans multi-coordinate: `indices.length >= 2`.
+ *
+ * @internal
+ */
+export function checkLBECoordinate(cell) {
+    switch (cell.kind) {
+        case 'law':
+            return checkLawCoordinate(cell);
+        case 'bridge':
+            return checkBridgeCoordinate(cell);
+        case 'emergence':
+            return checkEmergenceCoordinate(cell);
+        default: {
+            const _exhaustive = cell;
+            void _exhaustive;
+            throw new Error(`checkLBECoordinate: unknown cell kind`);
+        }
+    }
+}
+function checkLawCoordinate(cell) {
+    if (cell.scales.length === 0 || cell.forces.length === 0) {
+        return {
+            ok: false,
+            diagnostic: {
+                severity: 'error',
+                ruleName: 'lbe-coordinate',
+                cellId: cell.id,
+                message: `LawCell '${cell.id}' has empty scales × forces cross-product ` +
+                    `(scales=[${cell.scales.join(',')}], forces=[${cell.forces.join(',')}]). ` +
+                    `A law must occupy at least one (scale, force) coordinate.`,
+            },
+        };
+    }
+    return { ok: true };
+}
+function checkBridgeCoordinate(cell) {
+    // A BridgeCell must differ between source and target on at least one
+    // populated axis. The legacy `addBridge` at tensor.ts:217-226 already
+    // enforces this; we re-implement here for registry exhaustiveness.
+    const s = cell.source;
+    const t = cell.target;
+    const same = s.scale === t.scale &&
+        s.force === t.force &&
+        s.symmetry === t.symmetry &&
+        s.information === t.information &&
+        s.dimension === t.dimension &&
+        s.topology === t.topology;
+    if (same) {
+        return {
+            ok: false,
+            diagnostic: {
+                severity: 'error',
+                ruleName: 'lbe-coordinate',
+                cellId: cell.id,
+                message: `BridgeCell '${cell.id}' has identical source and target ` +
+                    `coordinates. A bridge must connect two distinct regime axes.`,
+            },
+        };
+    }
+    return { ok: true };
+}
+function checkEmergenceCoordinate(cell) {
+    if (cell.indices.length < 2) {
+        return {
+            ok: false,
+            diagnostic: {
+                severity: 'error',
+                ruleName: 'lbe-coordinate',
+                cellId: cell.id,
+                message: `EmergenceCell '${cell.id}' has only ${cell.indices.length} ` +
+                    `index group(s); emergence requires at least 2 (higher-order ` +
+                    `correlations span multiple coordinates).`,
+            },
+        };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Rule 3 — Causality (WARNING tier in v0.7)
+// ---------------------------------------------------------------------------
+/**
+ * Pure dispatcher for Rule 3 over the `Cell` discriminated union.
+ * Rule 3 only fires on `'bridge'`; the other arms always pass.
+ *
+ * Body for the bridge arm per Decision #5:
+ *   1. Read `src = cell.source.scale`, `dst = cell.target.scale`.
+ *   2. If either is `undefined`, emit `'info'` ("scale-unspecified
+ *      skip"); the rule still passes (`ok: true`).
+ *   3. If `arrow = classifyArrow(src, dst) === 'reverse'`, emit a
+ *      `'warning'` diagnostic recommending audit. Rule still passes
+ *      (Rule 3 is WARNING tier in v0.7; promotion to ERROR deferred
+ *      to v0.8).
+ *   4. Suppression via the private `causalityWhitelist` (empty in
+ *      v0.7).
+ *
+ * @internal
+ */
+export function checkCausality(cell) {
+    if (cell.kind !== 'bridge')
+        return { ok: true };
+    if (causalityWhitelist.has(cell.id))
+        return { ok: true };
+    const src = cell.source.scale;
+    const dst = cell.target.scale;
+    if (src === undefined || dst === undefined) {
+        return {
+            ok: true,
+            diagnostic: {
+                severity: 'info',
+                ruleName: 'causality',
+                cellId: cell.id,
+                message: `scale axis unspecified; causality check skipped`,
+            },
+        };
+    }
+    const arrow = classifyArrow(src, dst);
+    if (arrow === 'reverse') {
+        return {
+            ok: true, // WARNING tier in v0.7; rule does not throw
+            diagnostic: {
+                severity: 'warning',
+                ruleName: 'causality',
+                cellId: cell.id,
+                message: `BridgeCell '${cell.id}' goes ${src}→${dst} (coarser→finer); ` +
+                    `the canonical emergence direction is finer→coarser. ` +
+                    `Recommend audit.`,
+            },
+        };
+    }
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Registry dispatcher
+// ---------------------------------------------------------------------------
+/**
+ * Run a set of rules against a single `cell` and aggregate the
+ * diagnostics into a `FluxReport`. Pure function — no I/O, no
+ * shared-state mutation.
+ *
+ * The switch over `FluxRuleKind` is exhaustive via the
+ * `_exhaustive: never` default arm (Decision #8). Adding a new rule
+ * kind forces a compile-time update here AND at every consumer
+ * site that branches on `FluxRuleKind`.
+ *
+ * @internal
+ */
+export function runRules(cell, rules) {
+    const diagnostics = [];
+    let errorCount = 0;
+    let warningCount = 0;
+    let infoCount = 0;
+    for (const rule of rules) {
+        // Exhaustive dispatch on rule.kind. Even though `check` is the
+        // same shape across kinds, branching here gives us the
+        // compile-time guarantee that every kind is handled — a new
+        // FluxRuleKind variant forces a compile error.
+        let result;
+        switch (rule.kind) {
+            case 'dimensional-consistency':
+                result = rule.check(cell);
+                break;
+            case 'lbe-coordinate':
+                result = rule.check(cell);
+                break;
+            case 'causality':
+                result = rule.check(cell);
+                break;
+            case 'regime-consistency':
+                result = rule.check(cell);
+                break;
+            default: {
+                const _exhaustive = rule.kind;
+                void _exhaustive;
+                throw new Error(`runRules: unknown rule kind`);
+            }
+        }
+        if (result.diagnostic) {
+            diagnostics.push(result.diagnostic);
+            switch (result.diagnostic.severity) {
+                case 'error':
+                    errorCount++;
+                    break;
+                case 'warning':
+                    warningCount++;
+                    break;
+                case 'info':
+                    infoCount++;
+                    break;
+            }
+        }
+    }
+    return {
+        diagnostics,
+        errorCount,
+        warningCount,
+        infoCount,
+    };
+}
+/**
+ * The two v0.7 in-tree rules registered for Phase 2 `addCell`
+ * dispatch. Rule 1 (Dimensional Consistency) is NOT here — it
+ * operates on `BridgeEquationEntry`, not `Cell`, and ships in
+ * Phase 3 alongside the catalog adapter.
+ *
+ * @internal
+ */
+export const V07_CELL_RULES = [
+    { kind: 'lbe-coordinate', check: checkLBECoordinate },
+    { kind: 'causality', check: checkCausality },
+    { kind: 'regime-consistency', check: checkRegimeConsistency },
+];
+let registeredRegimeRule = null;
+/**
+ * Install P5's regime-consistency rule body. Called by
+ * `src/core/regime-rule-install.ts` at its module load. If P5's
+ * module is never imported, the regime check stays a no-op
+ * (returns `ok: true` silently).
+ *
+ * @internal
+ */
+export function installRegimeConsistencyRule(body) {
+    registeredRegimeRule = body;
+}
+/**
+ * Pure dispatcher for Rule 4 over `Cell`. Delegates to the body
+ * installed by P5 if present; otherwise a permissive no-op.
+ *
+ * @internal
+ */
+export function checkRegimeConsistency(cell) {
+    if (registeredRegimeRule)
+        return registeredRegimeRule(cell);
+    return { ok: true };
+}
+//# sourceMappingURL=flux-rules.js.map