universal-physics-tensor 0.29.0 → 0.31.0

package/dist/cli/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Typed error classes for the UPT CLI.
+ *
+ * `UsageError` signals a malformed invocation (bad flags, missing values,
+ * unknown flags) — callers map it to exit code 2. `CliError` signals a
+ * runtime failure within an otherwise well-formed invocation — exit code 1.
+ */
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CliError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cli/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/cli/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/cli/graphs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared `--source=catalog|canonical|both` graph resolution — replaces
+ * `bin/upt.mjs`'s `resolveGraph` (lines 53-67). Every analysis command
+ * (`discover` / `candidates` / `map` / ...) that accepts `--source` calls
+ * this once to get the graph + a human-readable label for its banner.
+ */
+import type { BridgeEdge } from '../composition/edge.js';
+import type { ParsedArgs } from './args.js';
+import type { CommandCtx } from './command.js';
+export type SourceName = 'catalog' | 'canonical' | 'both';
+export declare function resolveGraph(api: CommandCtx['api'], flags: ParsedArgs['flags']): {
+    graph: BridgeEdge[];
+    label: string;
+    source: SourceName;
+};
+//# sourceMappingURL=graphs.d.ts.map

package/dist/cli/graphs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1D,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,EACtB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,GACzB;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAsB5D"}

package/dist/cli/graphs.js

@@ -0,0 +1,30 @@
+/**
+ * Shared `--source=catalog|canonical|both` graph resolution — replaces
+ * `bin/upt.mjs`'s `resolveGraph` (lines 53-67). Every analysis command
+ * (`discover` / `candidates` / `map` / ...) that accepts `--source` calls
+ * this once to get the graph + a human-readable label for its banner.
+ */
+import { CliError } from './errors.js';
+export function resolveGraph(api, flags) {
+    const values = flags.get('source');
+    const src = values && values.length > 0 ? values[values.length - 1] : 'catalog';
+    switch (src) {
+        case 'catalog':
+            return { graph: [...api.CATALOG_GRAPH], label: 'catalog (44-bridge)', source: 'catalog' };
+        case 'canonical':
+            return {
+                graph: [...api.CANONICAL_GRAPH],
+                label: 'canonical (standard-physics L-layer, bridges excluded)',
+                source: 'canonical',
+            };
+        case 'both':
+            return {
+                graph: [...api.CATALOG_GRAPH, ...api.CANONICAL_GRAPH],
+                label: 'catalog + canonical',
+                source: 'both',
+            };
+        default:
+            throw new CliError(`upt: unknown --source='${src}' (expected: catalog | canonical | both)`);
+    }
+}
+//# sourceMappingURL=graphs.js.map

package/dist/cli/graphs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphs.js","sourceRoot":"","sources":["../../src/cli/graphs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,MAAM,UAAU,YAAY,CAC1B,GAAsB,EACtB,KAA0B;IAE1B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhF,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAC5F,KAAK,WAAW;YACd,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,eAAe,CAAC;gBAC/B,KAAK,EAAE,wDAAwD;gBAC/D,MAAM,EAAE,WAAW;aACpB,CAAC;QACJ,KAAK,MAAM;YACT,OAAO;gBACL,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,aAAa,EAAE,GAAG,GAAG,CAAC,eAAe,CAAC;gBACrD,KAAK,EAAE,qBAAqB;gBAC5B,MAAM,EAAE,MAAM;aACf,CAAC;QACJ;YACE,MAAM,IAAI,QAAQ,CAAC,0BAA0B,GAAG,0CAA0C,CAAC,CAAC;IAChG,CAAC;AACH,CAAC"}

package/dist/cli/main.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Verb-first dispatcher for the UPT CLI — `upt <command> [args...]`.
+ *
+ * Owns: top-level `help`/`version` handling, the no-args demo, unknown-verb
+ * exit-2 contract, and per-command dispatch (parse -> run -> map thrown
+ * UsageError/CliError to the documented exit codes). Individual commands are
+ * plain data (see `command.ts`) registered via `registerCommand`; this file
+ * never special-cases a command by name, so later tasks add commands without
+ * touching `runCli`'s body.
+ *
+ * `main.ts` is the one place that imports the real `cli-api.js` barrel and
+ * wires `out`/`err`/`write` to real stdio — every `Command.run` receives
+ * those as an injected `CommandCtx`, never reaching for `process.*` itself,
+ * which is what makes commands testable in-process against `dist/cli/*.js`.
+ */
+import './commands/index.js';
+/** Writer surface `runCli` needs. In production these wrap `process.stdout`/
+ * `process.stderr` with exact `console.log`/`console.error` semantics; tests
+ * pass a capturing stand-in as the optional second argument. Kept as an
+ * unexported inline shape (not part of the CLI's public surface). */
+type Io = {
+    out: (line?: string) => void;
+    err: (line?: string) => void;
+    write: (s: string) => void;
+};
+/**
+ * Verb-first CLI entry point. `argv` is the command + its arguments (NOT
+ * `process.argv` — callers slice off the node/script prefix themselves, as
+ * `bin/upt.mjs` did with `process.argv.slice(2)`).
+ */
+export declare function runCli(argv: string[], io?: Io): Promise<number>;
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,qBAAqB,CAAC;AAE7B;;;qEAGqE;AACrE,KAAK,EAAE,GAAG;IACR,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAwIF;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,EAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAmEhF"}

package/dist/cli/main.js

@@ -0,0 +1,219 @@
+/**
+ * Verb-first dispatcher for the UPT CLI — `upt <command> [args...]`.
+ *
+ * Owns: top-level `help`/`version` handling, the no-args demo, unknown-verb
+ * exit-2 contract, and per-command dispatch (parse -> run -> map thrown
+ * UsageError/CliError to the documented exit codes). Individual commands are
+ * plain data (see `command.ts`) registered via `registerCommand`; this file
+ * never special-cases a command by name, so later tasks add commands without
+ * touching `runCli`'s body.
+ *
+ * `main.ts` is the one place that imports the real `cli-api.js` barrel and
+ * wires `out`/`err`/`write` to real stdio — every `Command.run` receives
+ * those as an injected `CommandCtx`, never reaching for `process.*` itself,
+ * which is what makes commands testable in-process against `dist/cli/*.js`.
+ */
+import * as api from '../cli-api.js';
+import { UsageError, CliError } from './errors.js';
+import { parseArgs } from './args.js';
+import { packageVersion } from './version.js';
+import { resolveCommand } from './command.js';
+// Side-effect import: registers every ported command (see commands/index.ts).
+import './commands/index.js';
+function stdoutLine(line) {
+    process.stdout.write((line ?? '') + '\n');
+}
+function stderrLine(line) {
+    process.stderr.write((line ?? '') + '\n');
+}
+function stdoutRaw(s) {
+    process.stdout.write(s);
+}
+const defaultIo = { out: stdoutLine, err: stderrLine, write: stdoutRaw };
+const unknownCommandMessage = (name) => `Unknown command '${name}'. See \`upt help\`.`;
+// Verbatim from bin/upt.mjs's `help()` (lines 71-179), plus two lines at the
+// end documenting `upt version` and the global `--json` flag. Do NOT hand-edit
+// tests/cli/golden/help.txt against this — that golden pins the OLD bin/upt.mjs
+// and is only regenerated in Task 8, once main.ts becomes the live CLI.
+const HELP_TEXT = `upt — Universal Physics Tensor bridge-inference CLI
+
+Usage:
+  upt explain <quantity> [name=value | name] ...
+        Explain how the graph determines a quantity: the identifiability
+        verdict, recovered value, derivation chains, and whether the inputs
+        are dimensionally sufficient.
+        e.g.  upt explain hawking-temperature mass=1.989e30
+
+  upt priority
+        Triage the speculative bridges by structural DECIDABILITY against
+        established physics (Tiers 1-3). NOT a credibility ranking.
+
+  upt audit
+        Try to derive every built-in bridge equation by dimensions: which
+        re-derive as a recognized monomial (with the prefactor recovered),
+        which are decoys, which are dimensionally open.
+
+  upt map [--source=catalog|canonical|both] [--format=text|mermaid|dot|svg]
+          [--proposed] [--out=PATH] [--equation "TARGET = EXPR"]
+        Map how the equations LINK: connected components (clusters) of the
+        graph by shared quantities, the anchored core, the link hubs, and
+        the isolated tail.
+        --format=mermaid|dot|svg emits the VISUAL map (quantities = nodes,
+        equations = junctions colored by status, one subgraph per component).
+        text (default) is the unchanged linkage printout. svg renders the dot
+        layout via the optional @viz-js/viz peer (npm i @viz-js/viz; or pipe
+        dot through "dot -Tsvg"). --proposed overlays the unadjudicated
+        identity-consequence relations (gray dashed). --out writes to a file
+        (default stdout).
+        --equation "TARGET = EXPR" injects YOUR OWN equation as a violet 'user'
+        node and reports where it lands (which cluster / shared quantities), with
+        a "did you mean?" hint for names that miss the catalog vocabulary. Use
+        underscores for multi-word quantities (photon_energy -> photon-energy).
+        e.g.  upt map --equation "period = 2*pi*sqrt(length/gravity)"
+
+  upt candidates [--source=catalog|canonical|both]
+        Propose candidate cross-cluster links (quantities of the same
+        dimension in different clusters) for PHYSICIST REVIEW — a
+        coincidence-heavy surface, not discovered bridges.
+
+  upt predict
+        Project the catalog onto the (scale × force) regime plane and rank
+        the EMPTY regime cells as undiscovered-connection hypotheses
+        (triadic closure). Makes the namesake tensor operational. Review
+        surface, not discovered bridges.
+
+  upt discover [--source=catalog|canonical|both]
+        VET the link candidates through the inference suite: hypothesise
+        each identification a≡b and test whether it merges disconnected
+        physics, unlocks quantities, and stays numerically consistent.
+        Ranks promising / inert / contradictory.
+        --source=canonical runs the funnel on the standard-physics L-layer
+        ALONE (bridges excluded) — new candidates from established physics,
+        and a self-consistency check (expect 0 contradictory).
+        --derive emits, for each 'promising' identification, the ONE algebraic
+        relation it implies (monomial elimination) as an UNADJUDICATED, math-only
+        proposal — NOT a bridge (Part-VI §XXVII-B). Pairs with --source=canonical.
+        --max-orders=N tunes the magnitude-clash threshold (default 3); looser N
+        keeps more candidates 'promising', tighter N falsifies more as clashes.
+        --anchor=k=v[,k2=v2] overrides the numeric anchor (default mass=M_sun)
+        for the consistency/closure check. Both reshape the candidate pool that
+        --derive consumes.
+
+  upt connectors
+        Of the 20 ISOLATED bridges, which could connect to the anchored
+        core via a same-dimension identification? The structural frontier —
+        same-kind connectors are the motivated set for physicist review.
+
+  upt coverage
+        Audit the catalog's empirical grounding — which bridges are
+        data-confronted vs graph-computable vs encoded-only vs thin — to
+        target the physicist review. Fabricates nothing.
+
+  upt canonical
+        List the canonical-equation registry — the standard-physics L-layer
+        (textbook "answer key") with each entry's fidelity (L0/L1/L2),
+        domain, and bridge partners, plus the coverage gap.
+
+  upt recover
+        Validate bridges against standard physics: classify each bridge↔
+        canonical link as restates-canonical (F4 circularity — NOT a
+        discovery), recovers (undeclared structural match), or
+        dimensional-only.
+
+  upt symbolic [--simplify]
+        Compose bridges' SYMBOLIC (AST) forms, not just their numeric
+        evaluators (the Observable contract). Shows the CT-1 / CT-1b chains
+        composed by substitution, dimensionally validated and evaluable.
+        With --simplify, folds the composed AST via MathTS (k_B cancels),
+        re-validated dimensionally + numerically.
+
+  upt eval "<formula>" name=value ...
+        Evaluate YOUR OWN scalar formula (safe — arithmetic only). Knows
+        pi/tau and sqrt/exp/ln/sin/...; any other name must be supplied.
+        e.g.  upt eval "hbar*c^3/(8*pi*G*M*k_B)" hbar=1.054571817e-34 \\
+                       c=299792458 G=6.6743e-11 M=1.989e30 k_B=1.380649e-23
+
+  upt derive <target:dim> <var:dim> ... [--formula "<expr>"]
+        Derive YOUR OWN equation's dimensional form. <dim> is a named
+        dimension (length, time, mass, velocity, ...), a constant (hbar, c,
+        G, k_B, e), or explicit (L^3.M^-1.T^-2). With --formula, also verify
+        it and recover the dimensionless prefactor.
+        e.g.  upt derive period:time length:length gravity:acceleration \\
+                       --formula "2*pi*sqrt(length/gravity)"
+
+  upt help        Show this message.
+
+Run with no arguments for a short demo.
+
+  upt version     Show the installed CLI/package version.
+  --json          Global flag: emit a machine-readable JSON envelope instead of
+                  text (where the command supports it).`;
+/**
+ * Verb-first CLI entry point. `argv` is the command + its arguments (NOT
+ * `process.argv` — callers slice off the node/script prefix themselves, as
+ * `bin/upt.mjs` did with `process.argv.slice(2)`).
+ */
+export async function runCli(argv, io = defaultIo) {
+    const { out, err, write } = io;
+    try {
+        const [cmd, ...rest] = argv;
+        if (cmd === undefined) {
+            // Byte-identical to bin/upt.mjs's `case undefined` (lines 861-865): a
+            // banner line, then dispatch to the registered `explain` + `priority`
+            // commands with their historical demo arguments.
+            out('upt — bridge-inference CLI. Demo (run `upt help` for usage):');
+            const explainCmd = resolveCommand('explain');
+            if (!explainCmd) {
+                throw new CliError("upt: the demo needs the 'explain' command, which is not registered yet");
+            }
+            const explainArgs = parseArgs('explain', ['hawking-temperature', 'mass=1.989e30'], explainCmd.flags);
+            const explainCtx = { args: explainArgs, api, out, err, write };
+            const explainStatus = await explainCmd.run(explainCtx);
+            if (explainStatus !== 0)
+                return explainStatus;
+            const priorityCmd = resolveCommand('priority');
+            if (!priorityCmd) {
+                throw new CliError("upt: the demo needs the 'priority' command, which is not registered yet");
+            }
+            const priorityArgs = parseArgs('priority', [], priorityCmd.flags);
+            const priorityCtx = { args: priorityArgs, api, out, err, write };
+            return await priorityCmd.run(priorityCtx);
+        }
+        if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+            const target = rest[0];
+            if (target !== undefined) {
+                const command = resolveCommand(target);
+                if (!command)
+                    throw new UsageError(unknownCommandMessage(target));
+                out(command.help);
+                return 0;
+            }
+            out(HELP_TEXT);
+            return 0;
+        }
+        if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+            out(packageVersion());
+            return 0;
+        }
+        const command = resolveCommand(cmd);
+        if (!command) {
+            err(unknownCommandMessage(cmd));
+            return 2;
+        }
+        const parsed = parseArgs(command.name, rest, command.flags);
+        const ctx = { args: parsed, api, out, err, write };
+        return await command.run(ctx);
+    }
+    catch (e) {
+        if (e instanceof UsageError) {
+            err(e.message);
+            return 2;
+        }
+        if (e instanceof CliError) {
+            err(e.message);
+            return 1;
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

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

package/dist/cli/output.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JSON output envelope for the UPT CLI.
+ *
+ * Physics results genuinely contain non-finite numbers (e.g. `anchoring:
+ * Infinity` in the priority board). `JSON.stringify` silently turns those
+ * into `null`, which is indistinguishable from an absent value. `sanitize`
+ * deep-copies a value into a JSON-safe shape first, encoding NaN/Infinity
+ * as explicit strings so round-tripping through JSON preserves them.
+ */
+export interface JsonEnvelope {
+    command: string;
+    source?: 'catalog' | 'canonical' | 'both';
+    options?: Record<string, unknown>;
+    epistemics?: string;
+    result: unknown;
+}
+export declare function sanitize(v: unknown): unknown;
+export declare function emitJson(env: JsonEnvelope, write?: (s: string) => void): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA2C5C;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAqC,GAAG,IAAI,CAE7G"}

package/dist/cli/output.js

@@ -0,0 +1,57 @@
+/**
+ * JSON output envelope for the UPT CLI.
+ *
+ * Physics results genuinely contain non-finite numbers (e.g. `anchoring:
+ * Infinity` in the priority board). `JSON.stringify` silently turns those
+ * into `null`, which is indistinguishable from an absent value. `sanitize`
+ * deep-copies a value into a JSON-safe shape first, encoding NaN/Infinity
+ * as explicit strings so round-tripping through JSON preserves them.
+ */
+export function sanitize(v) {
+    if (typeof v === 'number') {
+        if (Number.isNaN(v))
+            return 'NaN';
+        if (v === Infinity)
+            return 'Infinity';
+        if (v === -Infinity)
+            return '-Infinity';
+        return v;
+    }
+    if (typeof v === 'function') {
+        // Caller decides how to represent "no value here" (omit vs. null) based
+        // on context (object key vs. array slot); signal via undefined and let
+        // the array/object branches below handle it.
+        return undefined;
+    }
+    if (Array.isArray(v)) {
+        const out = [];
+        for (const item of v) {
+            const sanitized = sanitize(item);
+            out.push(typeof item === 'function' ? null : sanitized);
+        }
+        return out;
+    }
+    if (v instanceof Map) {
+        const out = {};
+        for (const [key, value] of v) {
+            if (typeof value === 'function')
+                continue;
+            out[String(key)] = sanitize(value);
+        }
+        return out;
+    }
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const [key, value] of Object.entries(v)) {
+            if (value === undefined || typeof value === 'function')
+                continue;
+            out[key] = sanitize(value);
+        }
+        return out;
+    }
+    return v;
+}
+export function emitJson(env, write = (s) => process.stdout.write(s)) {
+    write(JSON.stringify(sanitize(env), null, 2) + '\n');
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAClC,IAAI,CAAC,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,QAAQ;YAAE,OAAO,WAAW,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;QAC5B,wEAAwE;QACxE,uEAAuE;QACvE,6CAA6C;QAC7C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,GAAG,GAAc,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjC,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,SAAS;YAC1C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACxC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,SAAS;YACjE,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAiB,EAAE,QAA6B,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACrG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime package-version lookup for the UPT CLI (`upt --version`, etc.).
+ *
+ * Reads `package.json` relative to this module's own location rather than
+ * importing a generated constant, so it stays correct without a build step
+ * re-stamping a version string. From `dist/cli/version.js`, `../../package.json`
+ * resolves to the package root in both the dev checkout and the installed
+ * npm layout (`dist/` ships as part of the published package).
+ */
+export declare function packageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/cli/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/cli/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,cAAc,IAAI,MAAM,CAIvC"}

package/dist/cli/version.js

@@ -0,0 +1,16 @@
+/**
+ * Runtime package-version lookup for the UPT CLI (`upt --version`, etc.).
+ *
+ * Reads `package.json` relative to this module's own location rather than
+ * importing a generated constant, so it stays correct without a build step
+ * re-stamping a version string. From `dist/cli/version.js`, `../../package.json`
+ * resolves to the package root in both the dev checkout and the installed
+ * npm layout (`dist/` ships as part of the published package).
+ */
+import { readFileSync } from 'node:fs';
+export function packageVersion() {
+    const pkgPath = new URL('../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+}
+//# sourceMappingURL=version.js.map

package/dist/cli/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/cli/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAwB,CAAC;IAC7E,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC"}

package/dist/cli-api.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CLI-facing barrel — the single stable entrypoint `bin/upt.mjs` imports.
+ *
+ * The CLI needs a handful of `@internal` analysis/composition/canonical
+ * functions that are deliberately NOT on the public surface (so they are not in
+ * the root `index.ts`). Previously `bin/upt.mjs` reached into ~10 deep `dist/`
+ * module paths to get them, coupling the CLI to the internal file layout — any
+ * module move silently broke the CLI. This barrel re-exports everything the CLI
+ * uses from one place, so layout changes touch only this file and `bin/upt.mjs`
+ * imports a single `dist/cli-api.js`.
+ *
+ * @internal — a CLI-support barrel; NOT re-exported from the root index, so it
+ * stays off the consumer-facing public surface.
+ *
+ * @module cli-api
+ */
+export { explainQuantity, CATALOG_GRAPH, CANONICAL_GRAPH, M_SUN_KG, composeSymbolic, be42Edge, be16Edge, lawSchwarzschildRadius, be42ViaRsEdge, format, buildVizModel, renderDotToSvg, equationLanding, analyzeUserEquation, buckinghamPi, dimensionallyDetermines, } from './index.js';
+export { bridgePriority, attemptDerivation, dimensionalFreedom, linkageMap, proposeLinkCandidates, proposeOrphanConnectors, } from './composition/bridge-analysis.js';
+export { getFormulaParser, getFormulaParserKind, getFormulaDimensionChecker, } from './numerical/formula-registry.js';
+export { parseDimensionSpec } from './dimensional/dimension-spec.js';
+export { predictMissingBridges } from './composition/bridge-prediction.js';
+export { rankDiscoveries } from './composition/discovery.js';
+export { auditCoverage } from './bridges/confrontation-coverage.js';
+export { simplifyObservable } from './composition/expr-simplify.js';
+export { CANONICAL_EQUATIONS, bridgesWithoutCanonicalPartner, } from './canonical/registry.js';
+export { scanLinkages } from './canonical/linkage.js';
+export { deriveProposedBridges } from './composition/proposed-bridges.js';
+export { annotateAdjudications, adjudicationFor, candidateId, ADJUDICATIONS, } from './composition/adjudication.js';
+export type { AnnotatedCandidate, CandidateAdjudication } from './composition/adjudication.js';
+//# sourceMappingURL=cli-api.d.ts.map

package/dist/cli-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-api.d.ts","sourceRoot":"","sources":["../src/cli-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EACL,eAAe,EACf,aAAa,EACb,eAAe,EACf,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,aAAa,EACb,MAAM,EACN,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAI1E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,aAAa,GACd,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/cli-api.js

@@ -0,0 +1,34 @@
+/**
+ * CLI-facing barrel — the single stable entrypoint `bin/upt.mjs` imports.
+ *
+ * The CLI needs a handful of `@internal` analysis/composition/canonical
+ * functions that are deliberately NOT on the public surface (so they are not in
+ * the root `index.ts`). Previously `bin/upt.mjs` reached into ~10 deep `dist/`
+ * module paths to get them, coupling the CLI to the internal file layout — any
+ * module move silently broke the CLI. This barrel re-exports everything the CLI
+ * uses from one place, so layout changes touch only this file and `bin/upt.mjs`
+ * imports a single `dist/cli-api.js`.
+ *
+ * @internal — a CLI-support barrel; NOT re-exported from the root index, so it
+ * stays off the consumer-facing public surface.
+ *
+ * @module cli-api
+ */
+// Public-API symbols (already on the root surface).
+export { explainQuantity, CATALOG_GRAPH, CANONICAL_GRAPH, M_SUN_KG, composeSymbolic, be42Edge, be16Edge, lawSchwarzschildRadius, be42ViaRsEdge, format, buildVizModel, renderDotToSvg, equationLanding, analyzeUserEquation, buckinghamPi, dimensionallyDetermines, } from './index.js';
+// Internal analysis surface (bridge-analysis.ts).
+export { bridgePriority, attemptDerivation, dimensionalFreedom, linkageMap, proposeLinkCandidates, proposeOrphanConnectors, } from './composition/bridge-analysis.js';
+// Other internal modules the CLI drives.
+export { getFormulaParser, getFormulaParserKind, getFormulaDimensionChecker, } from './numerical/formula-registry.js';
+export { parseDimensionSpec } from './dimensional/dimension-spec.js';
+export { predictMissingBridges } from './composition/bridge-prediction.js';
+export { rankDiscoveries } from './composition/discovery.js';
+export { auditCoverage } from './bridges/confrontation-coverage.js';
+export { simplifyObservable } from './composition/expr-simplify.js';
+export { CANONICAL_EQUATIONS, bridgesWithoutCanonicalPartner, } from './canonical/registry.js';
+export { scanLinkages } from './canonical/linkage.js';
+export { deriveProposedBridges } from './composition/proposed-bridges.js';
+// Adjudication ledger (composition/adjudication.ts) — annotates discovery
+// candidates with recorded human verdicts; never mutates the funnel.
+export { annotateAdjudications, adjudicationFor, candidateId, ADJUDICATIONS, } from './composition/adjudication.js';
+//# sourceMappingURL=cli-api.js.map

package/dist/cli-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-api.js","sourceRoot":"","sources":["../src/cli-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oDAAoD;AACpD,OAAO,EACL,eAAe,EACf,aAAa,EACb,eAAe,EACf,QAAQ,EACR,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,aAAa,EACb,MAAM,EACN,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAEpB,kDAAkD;AAClD,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,yCAAyC;AACzC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,0EAA0E;AAC1E,qEAAqE;AACrE,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,aAAa,GACd,MAAM,+BAA+B,CAAC"}

package/dist/composition/adjudication.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Adjudication ledger for machine-surfaced discovery candidates.
+ *
+ * Human verdicts on identification hypotheses (`a ≟ b`) are REVIEW MEMORY:
+ * once a physicist has disposed of a candidate, the funnel must not
+ * re-surface it as fresh. Verdicts NEVER mutate the catalog or graphs
+ * (the epistemic firewall) — they annotate discovery output only.
+ *
+ * Keyed by the order-normalized quantity-name pair. Proposed equations
+ * (`upt discover --derive`) inherit the verdict of the identification they
+ * were derived from (`derivedFrom.identification`).
+ *
+ * @module composition/adjudication
+ */
+import type { VettedCandidate } from './discovery.js';
+/**
+ * Stable identity for an identification hypothesis: the two quantity names,
+ * sorted, joined with `~`. Deliberately excludes score/verdict/dimension so
+ * ids survive funnel-internal changes. NOT rename-proof: a quantity rename
+ * (alias disposition) must update `ADJUDICATIONS` in the SAME commit — the
+ * calibration benchmark's seed-resolution test enforces this.
+ *
+ * @public
+ */
+export declare function candidateId(a: string, b: string): string;
+/**
+ * Verdict of a human adjudication OF THE IDENTIFICATION `a ≡ b` (never of a
+ * specific derived equation — derived equations inherit this as context):
+ * - `genuine`  — real physics AND a new link (nothing seeded qualifies yet).
+ * - `entailed` — real physics already carried by the L-layer; not a new link.
+ * - `decoy`    — dimensional coincidence / no mechanism; includes trivial and
+ *                definitional identifications.
+ * - `deferred` — reviewed and consciously parked (≠ absent entry, which means
+ *                never reviewed).
+ *
+ * @public
+ */
+export type AdjudicationVerdict = 'genuine' | 'decoy' | 'entailed' | 'deferred';
+/** One adjudicated identification hypothesis. @public */
+export interface CandidateAdjudication {
+    /** `candidateId(a, b)` of the identification. */
+    readonly id: string;
+    readonly verdict: AdjudicationVerdict;
+    /** Why — condensed from the adjudication record; never machine-generated. */
+    readonly grounds: string;
+    /** Repo-relative path of the adjudication document. */
+    readonly source: string;
+    /** ISO date the verdict was recorded. */
+    readonly date: string;
+}
+/**
+ * The seeded ledger — 2026-06 Adam+Eve adjudication rounds (8 → 0 genuine).
+ * Append-only by convention; entries are corrected, never silently removed.
+ *
+ * @public
+ */
+export declare const ADJUDICATIONS: readonly CandidateAdjudication[];
+/** Look up the verdict for an identification, order-insensitive. @public */
+export declare function adjudicationFor(a: string, b: string): CandidateAdjudication | undefined;
+/**
+ * A `VettedCandidate` with its recorded verdict attached, when the ledger has
+ * one for `a ≟ b`. The identification funnel (`rankDiscoveries`) never sees
+ * this — annotation is a command-layer concern (the epistemic firewall).
+ *
+ * @public
+ */
+export type AnnotatedCandidate = VettedCandidate & {
+    readonly adjudication?: CandidateAdjudication;
+};
+/**
+ * Attach each candidate's recorded verdict, if any. A pure map: preserves
+ * order and length, and leaves candidates without a ledger entry untouched
+ * (no `adjudication` key added).
+ *
+ * The discovery funnel's candidate pool is NOT guaranteed to be kebab-case
+ * slugs (`candidates` command sources plain quantity names like `A` or
+ * `impact_parameter` straight off `BridgeEdge`/canonical governing sets) —
+ * `candidateId` intentionally THROWS on those (the `~`-collision guard, see
+ * its docstring). A non-slug name can never be a ledger key (every
+ * `ADJUDICATIONS` entry is a valid slug), so such candidates are
+ * pre-filtered out of lookup rather than routed through the throwing path.
+ *
+ * @public
+ */
+export declare function annotateAdjudications(candidates: readonly VettedCandidate[]): readonly AnnotatedCandidate[];
+//# sourceMappingURL=adjudication.d.ts.map

package/dist/composition/adjudication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adjudication.d.ts","sourceRoot":"","sources":["../../src/composition/adjudication.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMtD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAEhF,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,qBAAqB,EAiEzD,CAAC;AAMF,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,qBAAqB,GAAG,SAAS,CAEnC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,eAAe,GAAG;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,eAAe,EAAE,GACrC,SAAS,kBAAkB,EAAE,CAM/B"}