universal-physics-tensor 0.5.0 → 0.7.0

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

package/dist/core/flux-rules.js.map

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

package/dist/core/labeled-tensor.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `LabeledTensor` — engine-level tensor wrapped with
+ * `UniversalIndex`-tagged metadata. The catalog-facing surface
+ * for physics-axis-aware contractions.
+ *
+ * Phase 2 + Phase 3 of v0.7 Proposal 1 (Intelligent Index Layer).
+ *
+ * Composition (Decision #5): `LabeledTensor` owns an `EngineTensor`,
+ * a `TensorEngine`, and a labels record. The engine handle is the
+ * boundary — `LabeledTensor` doesn't reach into the underlying
+ * Float64Array / MathTS handle. Contract matching is strictly
+ * `UniversalIndexId` equality (Decision #3) — two indices with the
+ * same `axis` and `name` but distinct `id`s do NOT contract.
+ *
+ * Design: `docs/planning/v0.7-Proposal-1-Design.md` Decisions
+ * #1, #3, #5, #6, #7, #9.
+ *
+ * Cross-Phase Invariants preserved:
+ *   - #1 adapter-on-top: this module does NOT import
+ *     `src/dimensional/tensor.ts` or `src/numerical/lowering.ts`.
+ *   - #4 `TensorSymbolNode` + `computeContraction` UNCHANGED.
+ *   - #5 `TensorEngine` interface UNCHANGED (consumes, doesn't
+ *     extend).
+ *
+ * @module core/labeled-tensor
+ */
+import type { EngineTensor, TensorEngine } from '../numerical/tensor-engine.js';
+import { UPTError } from '../dimensional/errors.js';
+import type { AxisName, UniversalIndex, UniversalIndexId } from './universal-index.js';
+/**
+ * Thrown by the `LabeledTensor` constructor when the labels record
+ * doesn't agree with the underlying tensor's rank
+ * (`Object.keys(labels).length !== tensor.shape.length`).
+ *
+ * @public
+ */
+export declare class LabeledTensorConstructionError extends UPTError {
+    readonly labelCount: number;
+    readonly tensorRank: number;
+    constructor(labelCount: number, tensorRank: number);
+}
+/**
+ * Thrown by `contract` when two `UniversalIndex` values share an
+ * `id` but disagree on `axis`. Per Decision #7, this is a physics
+ * error caught at the wrapper level. Impossible if both operands
+ * use the `Axes` registry; defensive against off-registry
+ * `makeIndex` consumers.
+ *
+ * @public
+ */
+export declare class AxisMismatchError extends UPTError {
+    readonly indexId: UniversalIndexId;
+    readonly leftAxis: AxisName;
+    readonly rightAxis: AxisName;
+    constructor(indexId: UniversalIndexId, leftAxis: AxisName, rightAxis: AxisName);
+}
+/**
+ * Thrown by `contract` when the same `UniversalIndexId` appears in
+ * more than one non-contracted (free) position across the two
+ * operands. Same physical axis showing up free on both sides is
+ * physically meaningful (joint distribution) but the einsum
+ * machinery has no canonical way to disambiguate.
+ *
+ * @public
+ */
+export declare class IdentityConflictError extends UPTError {
+    readonly indexId: UniversalIndexId;
+    constructor(indexId: UniversalIndexId);
+}
+/**
+ * Thrown by `reshape` when the requested shape would change the
+ * tensor rank. v0.7.0 allows only axis-by-axis size change;
+ * rank-changing reshape is deferred to v0.8.0+ (`mergeAxes` /
+ * `splitAxis` helpers).
+ *
+ * @public
+ */
+export declare class RankPreservationError extends UPTError {
+    readonly fromRank: number;
+    readonly toRank: number;
+    constructor(fromRank: number, toRank: number);
+}
+/**
+ * Stable lexicographic ordering of label keys. JavaScript's
+ * `Object.entries` preserves string-key insertion order, but we
+ * route all label-key→axis-position mapping through this helper
+ * so the contract algorithm doesn't accidentally depend on
+ * constructor-call ordering.
+ *
+ * @internal
+ */
+export declare function canonicalLabelOrder<L extends Record<string, UniversalIndex<AxisName>>>(labels: L): string[];
+/**
+ * Engine-agnostic wrapper carrying physics-axis-tagged metadata over
+ * an opaque `EngineTensor`. Two `LabeledTensor`s contract over
+ * shared `UniversalIndexId` values; non-shared ids become the
+ * result's free axes.
+ *
+ * Construction enforces `Object.keys(labels).length === tensor.shape.length`.
+ *
+ * @public
+ */
+export declare class LabeledTensor<L extends Record<string, UniversalIndex<AxisName>> = Record<string, UniversalIndex<AxisName>>> {
+    readonly tensor: EngineTensor;
+    readonly engine: TensorEngine;
+    readonly labels: L;
+    constructor(tensor: EngineTensor, engine: TensorEngine, labels: L);
+    /**
+     * Identity-aware contraction (Decision #3): match labels by
+     * `UniversalIndexId` equality only. Returns a new `LabeledTensor`
+     * whose free labels are the union of both operands' free labels
+     * minus the contracted ids, evaluated in `this`-first,
+     * `other`-second canonical order.
+     *
+     * Throws:
+     *   - `AxisMismatchError` if a shared id disagrees on axis.
+     *   - `IdentityConflictError` if a non-shared id appears free on
+     *     both operands.
+     *
+     * @public
+     */
+    contract<R extends Record<string, UniversalIndex<AxisName>>>(other: LabeledTensor<R>): LabeledTensor;
+    /**
+     * Reorder axes per the given permutation of label keys. The new
+     * label record reflects the new axis order; the engine handles
+     * the storage-level permutation via `engine.transpose`.
+     *
+     * @public
+     */
+    transpose(newKeyOrder: ReadonlyArray<keyof L & string>): LabeledTensor<L>;
+    /**
+     * Per-axis size change. Rank must be preserved (Decision #5);
+     * rank-changing reshape throws `RankPreservationError`. v0.8.0+
+     * may add `mergeAxes` / `splitAxis` for rank-changing operations.
+     *
+     * Labels survive unchanged (axis identity is preserved across a
+     * size-only reshape).
+     *
+     * @public
+     */
+    reshape(shape: ReadonlyArray<number>): LabeledTensor<L>;
+}
+//# sourceMappingURL=labeled-tensor.d.ts.map

package/dist/core/labeled-tensor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labeled-tensor.d.ts","sourceRoot":"","sources":["../../src/core/labeled-tensor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAc,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAOvF;;;;;;GAMG;AACH,qBAAa,8BAA+B,SAAQ,QAAQ;IAC1D,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;gBACvB,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAWnD;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,SAAgB,OAAO,EAAE,gBAAgB,CAAC;IAC1C,SAAgB,QAAQ,EAAE,QAAQ,CAAC;IACnC,SAAgB,SAAS,EAAE,QAAQ,CAAC;gBAElC,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,QAAQ;CAatB;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,SAAgB,OAAO,EAAE,gBAAgB,CAAC;gBAC9B,OAAO,EAAE,gBAAgB;CAUtC;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBACnB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAW7C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,EACpF,MAAM,EAAE,CAAC,GACR,MAAM,EAAE,CAEV;AAMD;;;;;;;;;GASG;AACH,qBAAa,aAAa,CACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE7F,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,MAAM,EAAE,YAAY,CAAC;IACrC,SAAgB,MAAM,EAAE,CAAC,CAAC;gBAEd,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;IAUjE;;;;;;;;;;;;;OAaG;IACI,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,EAChE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GACtB,aAAa;IAkEhB;;;;;;OAMG;IACI,SAAS,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IAuBhF;;;;;;;;;OASG;IACI,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;CAO/D"}