universal-physics-tensor 0.28.0 → 0.30.0

package/dist/cli/commands/derive.js

@@ -0,0 +1,143 @@
+import { registerCommand } from '../command.js';
+import { emitJson } from '../output.js';
+import { UsageError } from '../errors.js';
+const FLAGS = [
+    { name: '--formula', valueStyle: 'next' },
+    { name: '--debug', valueStyle: 'none' },
+    { name: '--json', valueStyle: 'none' },
+];
+const HELP = `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)"`;
+const fmtMono = (m) => Object.entries(m)
+    .filter(([, e]) => Math.abs(e) > 1e-9)
+    .map(([n, e]) => (e === 1 ? n : `${n}^${e}`))
+    .join('·') || '(dimensionless)';
+const BASES = ['L', 'M', 'T', 'I', 'Theta', 'N', 'J'];
+const dimsEqualTol = (a, b) => BASES.every((k) => Math.abs((a[k] || 0) - (b[k] || 0)) < 1e-9);
+async function run(ctx) {
+    const { args, api, out, err } = ctx;
+    const isJson = args.flags.has('json');
+    const debug = args.flags.has('debug');
+    const formulaFlag = args.flags.get('formula');
+    const formula = formulaFlag ? formulaFlag[formulaFlag.length - 1] : undefined;
+    const rest = args.positionals;
+    if (rest.length < 1) {
+        throw new UsageError('upt derive needs a target spec, e.g.  upt derive period:time length:length gravity:acceleration');
+    }
+    let specs;
+    try {
+        specs = rest.map((a) => {
+            const c = a.indexOf(':');
+            if (c < 1)
+                throw new Error(`'${a}' must be name:dimension (e.g. period:time)`);
+            return { name: a.slice(0, c), dim: api.parseDimensionSpec(a.slice(c + 1)) };
+        });
+    }
+    catch (e) {
+        throw new UsageError('  ' + e.message);
+    }
+    const target = specs[0];
+    const governing = specs.slice(1);
+    const det = api.dimensionallyDetermines(target, governing);
+    // Text lines follow the OLD bin's exact interleaving (bin/upt.mjs lines
+    // 340-385): the header/determination block — and the dimensional-check
+    // line — hit stdout BEFORE the formula parse/evaluate error sites, so a
+    // failing formula still leaves the partial report on stdout (the
+    // error-conversion fidelity rule: output emitted before the old
+    // `process.exit(2)` stays emitted before the throw). In --json mode text
+    // is suppressed and errors emit no JSON, so nothing precedes a throw.
+    const textOut = isJson ? () => { } : out;
+    let full;
+    let formulaCheck;
+    let mean;
+    const emitEnvelope = () => {
+        emitJson({
+            command: 'derive',
+            result: {
+                determination: det,
+                ...(full !== undefined ? { buckingham: full } : {}),
+                ...(formulaCheck !== undefined ? { formulaCheck } : {}),
+                ...(mean !== undefined ? { prefactor: mean } : {}),
+            },
+        }, ctx.write);
+    };
+    textOut(`\n● ${target.name}  from {${governing.map((g) => g.name).join(', ')}}`);
+    if (det.determined) {
+        textOut(`  dimensionally determined up to a constant:  ${target.name} ∝ ${fmtMono(det.monomial)}`);
+    }
+    else {
+        full = api.buckinghamPi([target, ...governing]);
+        textOut(`  NOT a unique monomial — ${full.piGroupCount} free dimensionless group(s) (${full.verdict}):`);
+        for (const g of full.piGroups)
+            textOut(`     ${g.formula}`);
+        textOut(`  (${det.reason})`);
+    }
+    if (formula) {
+        const parser = await api.getFormulaParser();
+        if (debug)
+            err(`  [parser: ${await api.getFormulaParserKind()}]`);
+        const checker = await api.getFormulaDimensionChecker();
+        const dims = Object.fromEntries(governing.map((g) => [g.name, g.dim]));
+        const r = checker.check(formula, dims);
+        formulaCheck = r;
+        if (!r.ok) {
+            textOut(`  formula dimensional check: ✗ ${r.error}`);
+        }
+        else {
+            const matches = dimsEqualTol(r.dim, target.dim);
+            textOut(`  formula dimension: ${api.format(r.dim)}`
+                + (matches ? `  ✓ homogeneous, matches target` : `  ⚠ homogeneous but ≠ target ${api.format(target.dim)}`));
+        }
+        let cf;
+        try {
+            cf = parser.parse(formula);
+        }
+        catch (e) {
+            throw new UsageError('  formula parse error: ' + e.message);
+        }
+        if (!det.determined) {
+            textOut('  formula given, but with no unique monomial there is no single prefactor to recover.');
+            if (isJson)
+                emitEnvelope();
+            return 0;
+        }
+        const ratios = [];
+        for (let j = 0; j < 3; j++) {
+            const scope = {};
+            governing.forEach((g, i) => {
+                scope[g.name] = Math.pow(1.7 + i, 1 + 0.3 * j);
+            });
+            let cand = 1;
+            for (const g of governing)
+                cand *= Math.pow(scope[g.name], det.monomial?.[g.name] || 0);
+            try {
+                ratios.push(cf.evaluate(scope) / cand);
+            }
+            catch (e) {
+                throw new UsageError('  formula uses an undeclared variable: ' + e.message);
+            }
+        }
+        mean = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+        const cv = Math.sqrt(ratios.reduce((a, b) => a + (b - mean) ** 2, 0) / ratios.length) / Math.abs(mean);
+        textOut(cv < 1e-9
+            ? `  formula MATCHES the dimensional form — recovered prefactor ≈ ${mean.toExponential(4)}`
+            : `  formula does NOT match the dimensional monomial (different input-dependence — a decoy or different physics).`);
+    }
+    if (isJson)
+        emitEnvelope();
+    return 0;
+}
+export const command = {
+    name: 'derive',
+    aliases: ['dim'],
+    flags: FLAGS,
+    help: HELP,
+    run,
+};
+registerCommand(command);
+//# sourceMappingURL=derive.js.map

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

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

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

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

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

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

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"}