universal-physics-tensor 0.29.0 → 0.30.0

package/dist/cli/commands/discover.js

@@ -0,0 +1,137 @@
+import { registerCommand } from '../command.js';
+import { resolveGraph } from '../graphs.js';
+import { emitJson } from '../output.js';
+import { parseDiscoveryOpts } from './_discovery-opts.js';
+const FLAGS = [
+    { name: '--source', valueStyle: 'attached' },
+    { name: '--max-orders', valueStyle: 'attached' },
+    { name: '--anchor', valueStyle: 'attached', repeatable: true },
+    { name: '--derive', valueStyle: 'none' },
+    { name: '--json', valueStyle: 'none' },
+];
+const HELP = `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.`;
+const EPISTEMICS = '⚠ a REVIEW SURFACE: `promising` means "worth a physicist\'s minute", not "true".\n' +
+    '  Each candidate hypothesises an identification a≡b and tests its consequences.';
+// ── discover --derive (identity-consequence proposals) ────────────────────
+function deriveReport(api, ranked, label, out) {
+    const proposals = api.deriveProposedBridges(ranked);
+    out(`\nDerived identity-consequence PROPOSALS — UNADJUDICATED, math-only  [source: ${label}]`);
+    out('⚠ Each is the ALGEBRAIC CONSEQUENCE of an unadjudicated identification — NOT a new');
+    out('  relation and NOT a bridge. No mechanism asserted. Promotion to the catalog needs');
+    out('  adversarial + literature review (Part-VI §XXVII-B). The enumerator proposes; humans dispose.\n');
+    if (!proposals.length) {
+        out('  no admissible proposal (need two fully-quantitative, monomial canonical targets).');
+        return;
+    }
+    for (const p of proposals) {
+        let approx = '';
+        try {
+            const vals = Object.fromEntries((p.governing || []).map((g) => [g.name, 300]));
+            const at = (p.governing || []).map((g) => `${g.name}=300`).join(', ');
+            approx = `  ≈ ${p.evaluate(vals).toExponential(2)}${at ? ` (${at})` : ''}`;
+        }
+        catch {
+            approx = '';
+        }
+        out(`  ${p.id}`);
+        out(`      ${p.formulaLatex}      ${p.dimensionalSignature}${approx}`);
+        out(`      from: ${p.derivedFrom.identification.a} ≟ ${p.derivedFrom.identification.b}` +
+            `  (${p.derivedFrom.sourceEquationIds[0]} = ${p.derivedFrom.sourceEquationIds[1]}); solved for ${p.derivedFrom.solvedFor}`);
+        if (p.alsoDerivableFrom && p.alsoDerivableFrom.length) {
+            out(`      also derivable from: ${p.alsoDerivableFrom.join('; ')}`);
+        }
+    }
+    out('');
+}
+async function run(ctx) {
+    const { args, api, out } = ctx;
+    const { graph, label, source } = resolveGraph(api, args.flags);
+    const opts = parseDiscoveryOpts(args.flags);
+    const ranked = api.rankDiscoveries(graph, opts);
+    const isDerive = args.flags.has('derive');
+    if (args.flags.has('json')) {
+        const result = isDerive ? api.deriveProposedBridges(ranked) : ranked;
+        emitJson({ command: 'discover', source, options: opts, epistemics: EPISTEMICS, result }, ctx.write);
+        return 0;
+    }
+    if (Object.keys(opts).length) {
+        const bits = [];
+        if (opts.maxOrdersOfMagnitude !== undefined)
+            bits.push(`max-orders=${opts.maxOrdersOfMagnitude}`);
+        if (opts.groundTruth) {
+            bits.push(`anchor={${Object.entries(opts.groundTruth).map(([k, v]) => `${k}=${v}`).join(', ')}}`);
+        }
+        out(`  [discovery options: ${bits.join('; ')}]`);
+    }
+    if (isDerive) {
+        deriveReport(api, ranked, label, out);
+        return 0;
+    }
+    const by = (v) => ranked.filter((r) => r.verdict === v);
+    const promising = by('promising');
+    const inert = by('inert');
+    const contra = by('contradictory');
+    const clash = by('magnitude-clash');
+    out(`\nDiscovery — link candidates VETTED through the inference suite  [source: ${label}]`);
+    out('⚠ a REVIEW SURFACE: `promising` means "worth a physicist\'s minute", not "true".');
+    out('  Each candidate hypothesises an identification a≡b and tests its consequences.\n');
+    out(`  funnel:  ${ranked.length} candidates  →  ${promising.length} promising  ` +
+        `·  ${inert.length} inert  ·  ${clash.length} magnitude-clash  ` +
+        `·  ${contra.length} contradictory (falsified)\n`);
+    if (promising.length) {
+        out('  PROMISING (merges disconnected physics, unlocks quantities, stays consistent):');
+        for (const r of promising) {
+            out(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} [${r.dim}]  score ${r.score}`);
+            out(`        unlocks: ${r.unlocksFromAnchor.join(', ') || '—'}`);
+        }
+    }
+    else {
+        out('  no candidate is `promising` from the default {mass} anchor.');
+    }
+    if (clash.length) {
+        out(`\n  MAGNITUDE-CLASH (representative values differ by > N orders — a falsifier):`);
+        for (const r of clash) {
+            const basis = r.magnitudeUsedAnchor ? '  (anchor-derived)' : '';
+            out(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} ~${r.ordersApart.toFixed(1)} orders apart${basis}`);
+        }
+    }
+    const subsumed = inert.filter((r) => r.subsuming);
+    if (subsumed.length) {
+        out(`\n  SUBSUMING (generic ≟ specialization — tautological, barred from promising):`);
+        for (const r of subsumed) {
+            out(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} [${r.dim}]`);
+        }
+    }
+    if (contra.length) {
+        out(`\n  CONTRADICTORY (the identification falsifies itself numerically):`);
+        for (const r of contra) {
+            out(`    ${(r.a + ' ≟ ' + r.b).padEnd(52)} disagreeing node(s): ${r.inconsistentNodes.join(', ')}`);
+        }
+    }
+    out('\n  (magnitude gate abstains where a representative value is unknown; weak priors on dimension.)');
+    return 0;
+}
+export const command = {
+    name: 'discover',
+    aliases: ['discovery'],
+    flags: FLAGS,
+    help: HELP,
+    run,
+};
+registerCommand(command);
+//# sourceMappingURL=discover.js.map

package/dist/cli/commands/discover.js.map

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

package/dist/cli/commands/eval.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const command: Command;
+//# sourceMappingURL=eval.d.ts.map

package/dist/cli/commands/eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/eval.ts"],"names":[],"mappings":"AASA,OAAO,EAAmB,KAAK,OAAO,EAAmB,MAAM,eAAe,CAAC;AAiE/E,eAAO,MAAM,OAAO,EAAE,OAMrB,CAAC"}

package/dist/cli/commands/eval.js

@@ -0,0 +1,64 @@
+import { registerCommand } from '../command.js';
+import { emitJson } from '../output.js';
+import { UsageError } from '../errors.js';
+const FLAGS = [
+    { name: '--debug', valueStyle: 'none' },
+    { name: '--json', valueStyle: 'none' },
+];
+const HELP = `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`;
+async function run(ctx) {
+    const { args, api, out, err } = ctx;
+    const debug = args.flags.has('debug');
+    const isJson = args.flags.has('json');
+    const positionals = args.positionals;
+    const expr = positionals[0];
+    if (!expr) {
+        throw new UsageError('upt eval needs a formula, e.g.  upt eval "a*b^2" a=2 b=3');
+    }
+    const parser = await api.getFormulaParser();
+    if (debug)
+        err(`[parser: ${await api.getFormulaParserKind()}]`);
+    let cf;
+    try {
+        cf = parser.parse(expr);
+    }
+    catch (e) {
+        throw new UsageError('parse error: ' + e.message);
+    }
+    const scope = {};
+    for (const a of positionals.slice(1)) {
+        const i = a.indexOf('=');
+        if (i > 0)
+            scope[a.slice(0, i)] = Number(a.slice(i + 1));
+    }
+    const missing = cf.variables.filter((v) => !(v in scope));
+    if (missing.length) {
+        throw new UsageError(`missing values for: ${missing.join(', ')}   (free variables: ${cf.variables.join(', ') || 'none'})`);
+    }
+    let value;
+    try {
+        value = cf.evaluate(scope);
+    }
+    catch (e) {
+        throw new UsageError(e.message);
+    }
+    if (isJson) {
+        emitJson({ command: 'eval', result: { value } }, ctx.write);
+        return 0;
+    }
+    out(String(value));
+    return 0;
+}
+export const command = {
+    name: 'eval',
+    aliases: ['calc'],
+    flags: FLAGS,
+    help: HELP,
+    run,
+};
+registerCommand(command);
+//# sourceMappingURL=eval.js.map

package/dist/cli/commands/eval.js.map

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

package/dist/cli/commands/explain.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const command: Command;
+//# sourceMappingURL=explain.d.ts.map

package/dist/cli/commands/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAeA,OAAO,EAAmB,KAAK,OAAO,EAAmB,MAAM,eAAe,CAAC;AAoF/E,eAAO,MAAM,OAAO,EAAE,OAMrB,CAAC"}

package/dist/cli/commands/explain.js

@@ -0,0 +1,81 @@
+import { registerCommand } from '../command.js';
+import { resolveGraph } from '../graphs.js';
+import { emitJson } from '../output.js';
+import { UsageError } from '../errors.js';
+const FLAGS = [
+    { name: '--source', valueStyle: 'attached' },
+    { name: '--json', valueStyle: 'none' },
+];
+const HELP = `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`;
+/**
+ * Two modes, never mixed: bare names (structural analysis) OR name=value
+ * (adds value recovery). Malformed inputs are rejected with a `UsageError`
+ * rather than silently coerced — `mass=abc`→dropped, `mass=`→0,
+ * `mass=1e500`→∞, and a bare name alongside a valued one were all silent
+ * wrong-physics footguns.
+ */
+function parseKnown(args) {
+    const valued = args.filter((a) => a.includes('='));
+    if (valued.length === 0)
+        return [...args]; // names mode
+    if (valued.length !== args.length) {
+        const bare = args.filter((a) => !a.includes('=')).join(', ');
+        throw new UsageError(`upt: cannot mix bare names (${bare}) with name=value inputs. `
+            + 'Use all names (structural) or all name=value (with recovery). See `upt help`.');
+    }
+    const values = {};
+    for (const a of args) {
+        const eq = a.indexOf('=');
+        const name = a.slice(0, eq);
+        const raw = a.slice(eq + 1);
+        const num = Number(raw);
+        if (raw === '' || !Number.isFinite(num)) {
+            throw new UsageError(`upt: '${a}' is not a finite number. Expected ${name}=<number>. See \`upt help\`.`);
+        }
+        values[name] = num;
+    }
+    return values;
+}
+async function run(ctx) {
+    const { args, api, out } = ctx;
+    const { graph, source } = resolveGraph(api, args.flags);
+    const [target, ...rest] = args.positionals;
+    if (!target) {
+        throw new UsageError('upt explain needs a quantity name. See `upt help`.');
+    }
+    const known = parseKnown(rest);
+    const x = api.explainQuantity(graph, target, known);
+    if (args.flags.has('json')) {
+        emitJson({ command: 'explain', source, result: x }, ctx.write);
+        return 0;
+    }
+    out(`\n● ${target}`);
+    out(`  ${x.summary}`);
+    if (x.derivations.length) {
+        out('  derivations:');
+        for (const d of x.derivations) {
+            const val = d.value !== undefined ? ` = ${d.value.toExponential(4)}` : '';
+            const chain = d.leafInputs.join(',') !== d.sources.join(',') ? `  [from leaves: ${d.leafInputs.join(', ')}]` : '';
+            out(`    - ${d.edge} (${d.label})${val}${chain}`);
+            if (d.dimensionalForm)
+                out(`        ${d.dimensionalForm.formula}`);
+        }
+    }
+    if (x.blockingFrontier.length) {
+        out(`  to determine it, also supply: ${x.blockingFrontier.join(', ')}`);
+    }
+    return 0;
+}
+export const command = {
+    name: 'explain',
+    aliases: [],
+    flags: FLAGS,
+    help: HELP,
+    run,
+};
+registerCommand(command);
+//# sourceMappingURL=explain.js.map

package/dist/cli/commands/explain.js.map

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

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Side-effect barrel: importing this module registers every ported CLI
+ * command (each command module calls `registerCommand` at load time).
+ * `main.ts` imports this once so `runCli`'s dispatch body never needs to
+ * change as commands are added.
+ */
+import './priority.js';
+import './audit.js';
+import './coverage.js';
+import './canonical.js';
+import './recover.js';
+import './connectors.js';
+import './predict.js';
+import './candidates.js';
+import './explain.js';
+import './symbolic.js';
+import './eval.js';
+import './derive.js';
+import './map.js';
+import './discover.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,eAAe,CAAC;AACvB,OAAO,YAAY,CAAC;AACpB,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AACxB,OAAO,cAAc,CAAC;AACtB,OAAO,iBAAiB,CAAC;AACzB,OAAO,cAAc,CAAC;AACtB,OAAO,iBAAiB,CAAC;AACzB,OAAO,cAAc,CAAC;AACtB,OAAO,eAAe,CAAC;AACvB,OAAO,WAAW,CAAC;AACnB,OAAO,aAAa,CAAC;AACrB,OAAO,UAAU,CAAC;AAClB,OAAO,eAAe,CAAC"}

package/dist/cli/commands/index.js

@@ -0,0 +1,21 @@
+/**
+ * Side-effect barrel: importing this module registers every ported CLI
+ * command (each command module calls `registerCommand` at load time).
+ * `main.ts` imports this once so `runCli`'s dispatch body never needs to
+ * change as commands are added.
+ */
+import './priority.js';
+import './audit.js';
+import './coverage.js';
+import './canonical.js';
+import './recover.js';
+import './connectors.js';
+import './predict.js';
+import './candidates.js';
+import './explain.js';
+import './symbolic.js';
+import './eval.js';
+import './derive.js';
+import './map.js';
+import './discover.js';
+//# sourceMappingURL=index.js.map

package/dist/cli/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,eAAe,CAAC;AACvB,OAAO,YAAY,CAAC;AACpB,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AACxB,OAAO,cAAc,CAAC;AACtB,OAAO,iBAAiB,CAAC;AACzB,OAAO,cAAc,CAAC;AACtB,OAAO,iBAAiB,CAAC;AACzB,OAAO,cAAc,CAAC;AACtB,OAAO,eAAe,CAAC;AACvB,OAAO,WAAW,CAAC;AACnB,OAAO,aAAa,CAAC;AACrB,OAAO,UAAU,CAAC;AAClB,OAAO,eAAe,CAAC"}

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

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const command: Command;
+//# sourceMappingURL=map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/map.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAmB,KAAK,OAAO,EAAmB,MAAM,eAAe,CAAC;AAyP/E,eAAO,MAAM,OAAO,EAAE,OAMrB,CAAC"}

package/dist/cli/commands/map.js

@@ -0,0 +1,245 @@
+/**
+ * `upt map` — how the equations LINK: the text linkage map, the visual
+ * (mermaid/dot/svg) physics map, and the `--equation` user-junction
+ * injection. Transposed verbatim from bin/upt.mjs's `proposedJunctions()`/
+ * `analyzeEquation()`/`printEquationReport()`/`mapCmd()` (lines 387-545),
+ * plus `--json` and the `--json`/`--format` conflict guard.
+ *
+ * `parseEquationFlag` is REPLACED by the `either`-style `--equation` FlagSpec
+ * (`args.ts` already extracts `--equation=...` or `--equation "..."` into
+ * `flags.get('equation')`). `parseDiscoveryOpts` moved to `_discovery-opts.ts`
+ * — the old CLI's `proposedJunctions` fed `map`'s raw args through it
+ * (bin/upt.mjs line 392), so `--proposed` shares `discover`'s
+ * `--max-orders`/`--anchor` validation here too.
+ */
+import { writeFileSync } from 'node:fs';
+import { registerCommand } from '../command.js';
+import { resolveGraph } from '../graphs.js';
+import { emitJson } from '../output.js';
+import { UsageError, CliError } from '../errors.js';
+import { parseDiscoveryOpts } from './_discovery-opts.js';
+const FLAGS = [
+    { name: '--source', valueStyle: 'attached' },
+    { name: '--format', valueStyle: 'attached' },
+    { name: '--out', valueStyle: 'attached' },
+    { name: '--max-orders', valueStyle: 'attached' },
+    { name: '--anchor', valueStyle: 'attached', repeatable: true },
+    { name: '--proposed', valueStyle: 'none' },
+    // optionalValue: a bare trailing --equation stores '' so the empty-check in
+    // run() owns the diagnostic (old-CLI fidelity: bin/upt.mjs did `a[i+1] ?? ''`
+    // and let mapCmd emit `upt: --equation requires "TARGET = EXPR"`, exit 2).
+    { name: '--equation', valueStyle: 'either', optionalValue: true },
+    { name: '--json', valueStyle: 'none' },
+];
+const HELP = `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)"`;
+// Convert the derived identity-consequence proposals into viz junctions
+// (gray-dashed, status 'proposed'). The library never imports proposed-bridges;
+// the CLI does the conversion, keeping the epistemic firewall intact.
+function proposedJunctions(api, graph, flags) {
+    const opts = parseDiscoveryOpts(flags);
+    const ranked = api.rankDiscoveries(graph, opts);
+    return api.deriveProposedBridges(ranked).map((p) => ({
+        id: p.id,
+        label: p.id,
+        status: 'proposed',
+        sources: (p.governing || []).map((g) => g.name),
+        target: p.target.name,
+    }));
+}
+// Build the catalog quantity name→dimension map for the chosen graph, then run
+// the (testable) library analysis: parse + dimensional validation + "did you
+// mean?" hints. The library owns the physics (constants' dimensions, inference);
+// the CLI only formats.
+async function analyzeEquation(api, equation, graph) {
+    const catalogDims = new Map();
+    for (const e of graph) {
+        for (const q of [...e.sources, e.target])
+            catalogDims.set(q.name, q.dim);
+    }
+    return api.analyzeUserEquation(equation, catalogDims);
+}
+// Print the dimensional verdict, where the equation landed, and any hints.
+// `out` is ctx.out (text mode → stdout) or ctx.err (visual → stderr).
+function printEquationReport(api, model, user, out) {
+    out('');
+    if (user.consistent === true) {
+        out(`  ✓ dimensionally consistent: ${api.format(user.rhsDimension)}`);
+    }
+    else if (user.consistent === false) {
+        out(`  ⚠ dimensional MISMATCH: RHS is ${api.format(user.rhsDimension)} but the target is ${api.format(user.targetDimension)}`);
+    }
+    else if (user.rhsDimension) {
+        out(`  · RHS dimension: ${api.format(user.rhsDimension)} (target not in the catalog, so no comparison)`);
+    }
+    const L = api.equationLanding(model, 'user-equation');
+    if (L.isolated) {
+        out('  ⚠ your equation is ISOLATED — it shares no quantity with this graph.');
+    }
+    else {
+        out(`  ● your equation joins ${L.anchored ? 'the ANCHORED cluster' : 'a cluster'} of ${L.clusterSize} via {${L.sharedQuantities.join(', ')}}`);
+        if (L.connectedJunctionIds.length)
+            out(`     connects to: ${L.connectedJunctionIds.join(', ')}`);
+    }
+    for (const h of user.hints ?? []) {
+        if (!h.suggestions.length) {
+            out(`  ⚠ '${h.name}' did not match a catalog quantity (run \`upt canonical\` for the vocabulary).`);
+        }
+        else if (h.byDimension) {
+            out(`  ⚠ '${h.name}' is unknown — by its inferred dimension, did you mean: ${h.suggestions.join(', ')}?`);
+        }
+        else {
+            out(`  ⚠ '${h.name}' did not match a catalog quantity — did you mean: ${h.suggestions.join(', ')}?`);
+        }
+    }
+}
+async function run(ctx) {
+    const { args, api, out, err, write } = ctx;
+    const { graph, label, source } = resolveGraph(api, args.flags);
+    const fmtValues = args.flags.get('format');
+    const fmt = fmtValues && fmtValues.length > 0 ? fmtValues[fmtValues.length - 1] : 'text';
+    const isJson = args.flags.has('json');
+    if (isJson && fmt !== 'text') {
+        throw new UsageError('upt: pick one output form: --json or --format');
+    }
+    // --equation injects a user-supplied "TARGET = EXPR" as a 'user' junction.
+    let user = null;
+    const equationValues = args.flags.get('equation');
+    const equation = equationValues && equationValues.length > 0 ? equationValues[equationValues.length - 1] : null;
+    if (equation != null) {
+        if (!equation.trim()) {
+            throw new UsageError('upt: --equation requires "TARGET = EXPR"');
+        }
+        try {
+            user = await analyzeEquation(api, equation, graph); // throws UserEquationError on malformed structure
+        }
+        catch (e) {
+            throw new UsageError('upt: ' + (e && e.message ? e.message : String(e)));
+        }
+        if (user.parseError) {
+            throw new UsageError('upt: ' + user.parseError); // dimensionally malformed RHS
+        }
+    }
+    const overlay = (extra) => [
+        ...(args.flags.has('proposed') ? proposedJunctions(api, graph, args.flags) : []),
+        ...extra,
+    ];
+    if (isJson) {
+        const linkage = api.linkageMap(graph);
+        let landing;
+        let userEquation;
+        if (user) {
+            const model = api.buildVizModel(graph, {
+                title: `UPT physics map — ${label}`,
+                extraJunctions: overlay([user.junction]),
+            });
+            landing = api.equationLanding(model, 'user-equation');
+            userEquation = {
+                equation: user.junction.label,
+                consistent: user.consistent,
+                rhsDimension: user.rhsDimension,
+                targetDimension: user.targetDimension,
+                hints: user.hints,
+            };
+        }
+        emitJson({
+            command: 'map',
+            source,
+            result: { linkage, ...(user ? { landing, userEquation } : {}) },
+        }, write);
+        return 0;
+    }
+    if (fmt === 'mermaid' || fmt === 'dot' || fmt === 'svg') {
+        const extraJunctions = overlay(user ? [user.junction] : []);
+        const model = api.buildVizModel(graph, {
+            title: `UPT physics map — ${label}`,
+            extraJunctions,
+        });
+        // svg is the dot layout rendered by the optional @viz-js/viz peer.
+        let src;
+        if (fmt === 'svg') {
+            try {
+                src = await api.renderDotToSvg(model.toDot());
+            }
+            catch (e) {
+                throw new CliError(e && e.message ? e.message : String(e));
+            }
+        }
+        else {
+            src = fmt === 'mermaid' ? model.toMermaid() : model.toDot();
+        }
+        const outValues = args.flags.get('out');
+        if (outValues && outValues.length > 0) {
+            const path = outValues[outValues.length - 1];
+            if (!path) {
+                throw new CliError('upt: --out= requires a non-empty PATH');
+            }
+            try {
+                writeFileSync(path, src);
+            }
+            catch (e) {
+                throw new CliError(e.message);
+            }
+            err(`upt: wrote ${fmt} (${model.junctions.length} junctions, ${model.clusters.length} clusters) to ${path}`);
+        }
+        else {
+            write(src);
+        }
+        // Landing report goes to stderr so stdout/--out stays pure diagram source.
+        if (user)
+            printEquationReport(api, model, user, err);
+        return 0;
+    }
+    if (fmt !== 'text') {
+        throw new CliError(`upt: unknown --format='${fmt}' (expected: text | mermaid | dot | svg)`);
+    }
+    const m = api.linkageMap(graph);
+    const mix = (s) => Object.entries(s)
+        .map(([k, v]) => `${v} ${k}`)
+        .join(', ');
+    out(`\nLinkage map — how the equations connect via shared quantities  [source: ${label}]`);
+    out(`(${m.componentCount} components over ${graph.length} edges; ${m.compositions} compose into chains)\n`);
+    for (const c of m.clusters.filter((x) => x.size > 1)) {
+        out(`  ● cluster of ${c.size}${c.anchored ? '  [ANCHORED to known physics]' : ''}`);
+        out(`     edges:  ${c.edges.join(', ')}`);
+        out(`     status: ${mix(c.statusMix)}`);
+        out(`     link hubs: ${c.hubs.join(', ')}\n`);
+    }
+    out(`  ○ isolated (${m.isolated.length}) — share no quantity with any other edge:`);
+    out(`     ${m.isolated.join(', ')}`);
+    out('\n  (a structural map — shared-quantity connectivity, NOT a credibility signal)');
+    // --equation: where does the user's equation land in this graph?
+    if (user) {
+        const model = api.buildVizModel(graph, {
+            title: `UPT physics map — ${label}`,
+            extraJunctions: overlay([user.junction]),
+        });
+        out(`\nYour equation:  ${user.junction.label}`);
+        printEquationReport(api, model, user, out);
+    }
+    return 0;
+}
+export const command = {
+    name: 'map',
+    aliases: ['linkage'],
+    flags: FLAGS,
+    help: HELP,
+    run,
+};
+registerCommand(command);
+//# sourceMappingURL=map.js.map