universal-physics-tensor 0.22.0 → 0.24.0

package/dist/composition/proposed-bridges.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Identity-consequence surfacer — turns a `promising` discovery identification
+ * into the ONE algebraic relation it implies, as an UNADJUDICATED proposal.
+ *
+ * When the discovery funnel flags `a ≟ b` (two canonical quantities of equal
+ * dimension), and `a`, `b` are the TARGETS of two canonical equations `Eₐ`, `E_b`,
+ * the hypothesised identity `a ≡ b` makes their right-hand sides equal:
+ *
+ *     Eₐ.scalarAst  =  E_b.scalarAst
+ *
+ * Eliminating (isolating) one free variable yields a relation among the union of
+ * the two governing sets — e.g. Landauer `k_B T ln2` ≟ Planck–Einstein `h ν`
+ * gives `ν = (k_B ln2 / h) · T`, the "Landauer photon".
+ *
+ * CRITICAL — this is NOT new physics and NOT a bridge. It is the algebraic
+ * consequence of an UNADJUDICATED identification, surfaced for a physicist to
+ * judge (Part-VI §XXVII-B: the enumerator proposes, humans dispose). Every
+ * emitted record carries `status: 'unadjudicated'` — a literal that is NOT a
+ * member of `BridgeEquationStatus`, so a proposal can never be assigned where a
+ * catalog entry is expected. The generator NEVER writes `BRIDGE_EQUATIONS` and a
+ * proposal is NEVER added to `CANONICAL_GRAPH` (no coincidence-amplifying loop).
+ *
+ * Scope (v0.24.0 pilot): canonical-only `promising` candidates whose BOTH source
+ * equations (a) have a non-null `dimensional.monomial` (determinate) and (b) are
+ * `epistemicStatus: 'fully-quantitative'` (so the eliminated prefactor is a
+ * closed numeric constant, not an operator-valued stub — this gates out
+ * `CE-jarzynski`). See `docs/planning/v0.24.0-{Design,Review-Findings}.md`.
+ *
+ * INTERNAL tooling — deliberately NOT re-exported from `src/index.ts`.
+ *
+ * @module composition/proposed-bridges
+ */
+import type { ExprNode } from '../dimensional/validator.js';
+import type { Dimension } from '../dimensional/types.js';
+import type { DimensionalVariable } from '../dimensional/buckingham.js';
+import type { BridgeEquationStatus } from '../bridges/index.js';
+import type { KnownIssue } from '../bridges/index.js';
+import type { VettedCandidate } from './discovery.js';
+/** A flat monomial: leaf name → its dimension and (signed, possibly rational)
+ *  exponent. `k_B·T·ln2 / h` ⇒ {k_B:+1, T:+1, ln2:+1, h:-1}. */
+type Mono = Map<string, {
+    dim: Dimension;
+    exp: number;
+}>;
+/** Thrown when an AST is not a product / quotient / integer-power of symbols. */
+export declare class NotAMonomialError extends Error {
+    constructor(message: string);
+}
+/**
+ * Decompose a flat-monomial `ExprNode` into a leaf→exponent map. Throws
+ * `NotAMonomialError` on sums, differences, or non-symbol bases — this is the
+ * AST-level monomial gate.
+ */
+export declare function toMonomial(ast: ExprNode): Mono;
+/** Rebuild a flat-monomial `ExprNode` from a leaf→exponent map (numerator =
+ *  positive exponents, denominator = negative). Zero exponents drop out. */
+export declare function fromMonomial(m: Mono): ExprNode;
+/**
+ * A machine-DERIVED candidate bridge — the MATH ONLY. The algebraic consequence
+ * of an UNADJUDICATED identification; never a status claim. Structurally distinct
+ * from `BridgeEquationEntry` (omits every physics-judgment field) and carries the
+ * literal `status: 'unadjudicated'`, which is NOT a `BridgeEquationStatus`.
+ *
+ * @internal
+ */
+export interface ProposedBridge {
+    /** `IC-<sorted-a>--<sorted-b>--<solvedFor>`. */
+    readonly id: string;
+    readonly derivedFrom: {
+        readonly identification: {
+            readonly a: string;
+            readonly b: string;
+            readonly dim: string;
+        };
+        readonly sourceEquationIds: readonly [string, string];
+        readonly solvedFor: string;
+    };
+    readonly target: DimensionalVariable;
+    /** Free (non-constant) inputs of the derived relation. */
+    readonly governing: readonly DimensionalVariable[];
+    readonly formulaLatex: string;
+    /** Dimensionally-VALIDATED derived RHS (round-trips to `dimensionalSignature`). */
+    readonly scalarAst: ExprNode;
+    /** `format()` of the inferred dimension — same convention as the catalog. */
+    readonly dimensionalSignature: string;
+    /** Mechanical derivation description — NO physics claim. */
+    readonly provenance: string;
+    /** Other identifications that derive the SAME relation (same normal form, up
+     *  to dimensionless constants), collapsed into this proposal by the dedup pass.
+     *  Empty unless a wider candidate scope produced structural duplicates. */
+    readonly alsoDerivableFrom: readonly string[];
+    /** ALWAYS the literal 'unadjudicated'. NOT a BridgeEquationStatus. */
+    readonly status: 'unadjudicated';
+    /** Numerically evaluate the derived RHS; constants auto-resolve, supply the
+     *  free `governing` leaves (e.g. `{ T: 300 }`). */
+    evaluate(values: Readonly<Record<string, number>>): number;
+}
+/**
+ * An admissible source for the elimination: a target name backed by a flat
+ * monomial `scalarAst` whose prefactor is a closed constant. Canonical equations
+ * and bridge edges both project to this shape, so the generator no longer needs
+ * to know which it came from.
+ */
+export interface EquationSource {
+    /** `CE-…` (canonical) or `BE-<n>` (bridge). */
+    readonly id: string;
+    readonly kind: 'canonical' | 'bridge';
+    readonly scalarAst: ExprNode;
+    readonly targetDim: Dimension;
+    /** `epistemicStatus` (canonical) or `confidence` (bridge) — recorded, not gated. */
+    readonly grade: string;
+}
+/** ALL admissible sources for `name` — every canonical equation AND every bridge
+ *  edge whose target is `name` and whose form is a clean monomial. A target with
+ *  several sources (e.g. BE-42 Hawking's two parametrisations) is DE-AMBIGUATED by
+ *  enumeration, not skipped; coinciding derivations collapse later under dedup. */
+export declare function resolveSources(name: string): EquationSource[];
+/**
+ * Derive the implied relation for each `promising` identification in `candidates`.
+ * Returns ONE proposal per admissible candidate (Adam M2), structurally
+ * de-duplicated (`dedupByNormalForm`).
+ *
+ * Candidate-set-agnostic: pass `rankDiscoveries(CANONICAL_GRAPH)` (default),
+ * `…(CATALOG_GRAPH)`, or `…([...CATALOG_GRAPH, ...CANONICAL_GRAPH])` to widen the
+ * source — the CLI `discover --derive` forwards whichever `--source=` graph is
+ * selected. Each endpoint is resolved by `resolveSource` to a canonical equation
+ * OR a bridge edge with a clean-monomial `symbolic` form, so a candidate yields a
+ * proposal when BOTH endpoints resolve (the Landauer photon, for instance, is
+ * derivable both from `CE-landauer` and — at `--source=both` — from the BE-16
+ * bridge). A target with SEVERAL admissible sources (BE-42 Hawking's two
+ * parametrisations, or a canonical + bridge pair) is de-ambiguated by ENUMERATION
+ * — every source pair is tried and coincidences collapse under dedup. HONEST
+ * BOUNDARY: an endpoint with no clean-monomial source (a bridge with no `symbolic`
+ * form or a non-monomial one) yields nothing.
+ *
+ * Pure; reads the registries, writes nothing.
+ *
+ * @internal
+ */
+export declare function deriveProposedBridges(candidates?: readonly VettedCandidate[]): readonly ProposedBridge[];
+/**
+ * Collapse proposals that derive the SAME relation — equal `normalForm` (up to
+ * dimensionless constants) AND equal target dimension — into the first, recording
+ * the others' identifications in `alsoDerivableFrom`. Distinct stubs do NOT
+ * collapse (e.g. Landauer's dropped `ln2` vs an operator stub hash differently),
+ * so this only merges genuine structural twins that a wider candidate scope can
+ * produce (Design §9 #2). Deterministic: input order is preserved.
+ */
+export declare function dedupByNormalForm(proposals: readonly ProposedBridge[]): readonly ProposedBridge[];
+/** The human inputs a proposal CANNOT supply — fabricating them is forbidden. */
+export interface PromotionEvidence {
+    /** Literature anchor establishing the relation (appears / contradicts / neither). */
+    readonly citation: string;
+    /** Human-chosen catalog status — never defaulted. */
+    readonly status: BridgeEquationStatus;
+    /** Path to the recorded adversarial + literature review. */
+    readonly reviewRef: string;
+}
+/** A review-ready promotion request — the artifact a human turns into a catalog
+ *  entry. Holding one does NOT mutate `BRIDGE_EQUATIONS`. */
+export interface PromotionRequest {
+    readonly proposal: ProposedBridge;
+    readonly evidence: PromotionEvidence;
+}
+export declare class MissingEvidenceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Gate a proposal toward the catalog. THROWS `MissingEvidenceError` unless every
+ * human input is present and non-blank (operationalises "null, not guessed").
+ * Returns a `PromotionRequest`; it deliberately does NOT synthesise a
+ * `BridgeEquationEntry` — the physics-judgment fields are human work.
+ *
+ * @internal
+ */
+export declare function promoteProposal(proposal: ProposedBridge, evidence: PromotionEvidence): PromotionRequest;
+/**
+ * A derived proposal in the catalog's field SHAPE, for review — but in its OWN
+ * registry and carrying `status: 'unadjudicated'` (NOT a `BridgeEquationStatus`).
+ * This is deliberately NOT a `BridgeEquationEntry`: it omits the spec-only fields
+ * (`source_part`/`source_section`/numeric `id`) and never enters `BRIDGE_EQUATIONS`,
+ * which stays the faithful 44-bridge encoding of the specification.
+ *
+ * @internal
+ */
+export interface ProposedBridgeEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly category: 'Z';
+    readonly category_name: 'Machine-Derived Identity Consequences (UNADJUDICATED)';
+    /** The two regimes bridged — the source equations' domains. */
+    readonly bridges: readonly [string, string];
+    /** ALWAYS 'unadjudicated' — not a catalog status. */
+    readonly status: 'unadjudicated';
+    readonly context: string;
+    readonly formula_latex: string;
+    readonly dimensional_signature: string;
+    /** Honest references: a derivation note + the SOURCE equations' citations,
+     *  never a fabricated citation for the derived relation itself. */
+    readonly references: readonly string[];
+    readonly known_issues: readonly KnownIssue[];
+    readonly derivedFrom: ProposedBridge['derivedFrom'];
+    readonly notes: string;
+}
+/** Render a `ProposedBridge` into the catalog field-shape, filled honestly. */
+export declare function toProposedEntry(p: ProposedBridge): ProposedBridgeEntry;
+/**
+ * The PROPOSED-BRIDGE review surface: derived identity-consequences in the
+ * catalog's field shape, in their OWN registry, every entry `status:
+ * 'unadjudicated'`. Separate from `BRIDGE_EQUATIONS` (the faithful 44-bridge spec
+ * encoding), which this never mutates. Default scope: canonical-only — widen with
+ * `deriveProposedBridges(rankDiscoveries(graph)).map(toProposedEntry)`.
+ *
+ * @internal
+ */
+export declare const PROPOSED_BRIDGES: readonly ProposedBridgeEntry[];
+export {};
+//# sourceMappingURL=proposed-bridges.d.ts.map

package/dist/composition/proposed-bridges.d.ts.map

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