universal-physics-tensor 0.47.0 → 1.0.1

package/dist/cli/commands/map.js

@@ -14,10 +14,14 @@
  */
 import { writeFileSync } from 'node:fs';
 import { registerCommand } from '../command.js';
-import { resolveGraph } from '../graphs.js';
+import { resolveGraph, coreAnchor, coreLine, groundTruthAnchor, groundTruthLine } from '../graphs.js';
 import { emitJson } from '../output.js';
 import { UsageError, CliError, EXIT_CHECK_FAILED } from '../errors.js';
 import { parseDiscoveryOpts } from './_discovery-opts.js';
+import * as atlasMap from './_atlas-map.js';
+import { canonicalCheckFailed, conventionLines } from '../conventions.js';
+import { naturalConstantOverrides } from '../../dimensional/natural-units.js';
+import { withCatalogEvidence } from '../map-evidence.js';
 const FLAGS = [
     { name: '--source', valueStyle: 'attached' },
     { name: '--format', valueStyle: 'attached' },
@@ -27,49 +31,143 @@ const FLAGS = [
     { name: '--proposed', valueStyle: 'none' },
     { name: '--relation', valueStyle: 'attached' },
     { name: '--evidence', valueStyle: 'attached' },
+    { name: '--around', valueStyle: 'either' },
+    { name: '--depth', valueStyle: 'attached' },
+    { name: '--route', valueStyle: 'either' },
+    { name: '--all-routes', valueStyle: 'none' },
+    { name: '--max-routes', valueStyle: 'attached' },
+    { name: '--family', valueStyle: 'either' },
+    { name: '--observable', valueStyle: 'either' },
+    { name: '--stored', valueStyle: 'none' },
+    { name: '--run', 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: '--equation-only', valueStyle: 'none' },
+    { name: '--verbose', valueStyle: 'none' },
+    { name: '--bind-short', valueStyle: 'none' },
+    { name: '--natural', valueStyle: 'none' },
+    { name: '--geometrized', valueStyle: 'none' },
     { name: '--json', valueStyle: 'none' },
 ];
-const HELP = `upt map [--source=catalog|canonical|both|poster] [--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.
-        --source defaults to 'both' (catalog + canonical) — a pure
-        connectivity question gets the honest, all-known-physics answer by
-        default; --source=catalog shows the bridge-catalog view alone.
-        --source=poster draws the ATLAS PHASE 3 POSTER INDEX instead of the
-        bridge graph: nodes are STATEMENTS (including the hidden supporting
-        nodes — action principle, Noether, the full Maxwell system, the
-        Lorentz group, the central limit theorem) and boxes are DERIVATIONS
-        (premises in, conclusion out). Associations are drawn DASHED because
-        they assert no relation at all. It also reports any premise naming a
-        statement the registry does not define, and says so out loud when the
-        index is not registered in this build rather than printing an empty
-        map as an answer.
-        --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).
-        --relation=TYPE keeps only edges whose recorded Atlas relation is that
-        type; --evidence=TAG keeps only edges whose evidence set, DERIVED from
-        the catalog row at read time, contains that tag.
-        ⚠ Filtering changes what a missing overlay means: unfiltered, an edge
-        with no overlay is KEPT; filtered, it is DROPPED, because nothing shows
-        it satisfies the filter. Those drops are counted and printed separately
-        from the edges that simply did not match — an unaudited graph must not
-        render as a complete answer.
-        e.g.  upt map --relation=derivation --source=both`;
+const HELP = `upt map [--source=catalog|canonical|both|poster] [--format=text|mermaid|dot|svg]
+        [--proposed [--anchor=k=v,...] [--max-orders=N]] [--out=PATH]
+        [--equation "TARGET = EXPR" [--equation-only] [--verbose] [--bind-short]
+        [--natural] [--geometrized]] [--around=QUANTITY [--depth=N]]
+        [--relation=TYPE] [--evidence=TAG] [--route=FROM,TO [--all-routes
+        [--max-routes=N]]] [--family=NAME] [--observable=NAME] [--stored | --run]
+        Map how the equations LINK: connected components (clusters) of the
+        graph by shared quantities, the anchored core, the link hubs, and
+        the isolated tail.
+        --source defaults to 'both' (catalog + canonical) — a pure
+        connectivity question gets the honest, all-known-physics answer by
+        default; --source=catalog shows the bridge-catalog view alone.
+        --source=poster draws the ATLAS PHASE 3 POSTER INDEX instead of the
+        bridge graph: nodes are STATEMENTS (including the hidden supporting
+        nodes — action principle, Noether, the full Maxwell system, the
+        Lorentz group, the central limit theorem) and boxes are DERIVATIONS
+        (premises in, conclusion out). Associations are drawn DASHED because
+        they assert no relation at all. It also reports any premise naming a
+        statement the registry does not define, and says so out loud when the
+        index is not registered in this build rather than printing an empty
+        map as an answer.
+        --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); --anchor and --max-orders
+        tune the discovery funnel that derives them, as in \`upt discover\`.
+        --out writes to a file (default stdout).
+        --equation "TARGET = EXPR" injects YOUR OWN equation as a violet 'user'
+        node, dimensionally checks it, compares with the canonical registry, and
+        reports nearest equations by shared-quantity overlap (not a full edge
+        dump). Multi-word names may use underscores or catalog hyphens
+        (planck_length / planck-length). Unknown names get a "did you mean?",
+        and a registered constant of the inferred dimension (sigma → sigma_sb);
+        a one-letter catalog name (a, r, …) is reported and not bound; --bind-short
+        binds it. The alias T → temperature still binds.
+        An all-constant right-hand side (the Planck length) is compared at the
+        SI constant values when its target is a catalog quantity.
+        With --equation, the default is the verdict only. --verbose prints the
+        linkage map after it. --equation-only is the same verdict and errors
+        when --equation is missing (with --json: no "linkage" field).
+        A bare e in the formula is the elementary charge. E is energy.
+        Euler's number is exp(1) or euler.
+        --natural sets ħ = c = 1 for a dimension difference that is a power of
+        those constants; --geometrized also allows powers of G. The SI default
+        still refuses rest_energy = mass.
+        --relation=TYPE keeps only edges whose recorded Atlas relation is that
+        type; --evidence=TAG keeps only edges whose evidence set, DERIVED from
+        the catalog row at read time, contains that tag.
+        ⚠ Filtering changes what a missing overlay means: unfiltered, an edge
+        with no overlay is KEPT; filtered, it is DROPPED, because nothing shows
+        it satisfies the filter. Those drops are counted and printed separately
+        from the edges that simply did not match — an unaudited graph must not
+        render as a complete answer.
+        --around=QUANTITY [--depth=N] keeps only the edges within N
+        shared-quantity hops of QUANTITY (default 1: the edges that use it),
+        in every output form, and prints how many of the source's edges it
+        kept: the others are omitted from the view, not absent from the graph.
+        --route=FROM,TO and --family=NAME map the ATLAS instead: models and
+        the recorded bridges between them, not shared quantities. --route
+        shows the route \`upt path\` reports, each bridge's relation,
+        assumptions, regime, bound and derived evidence, the composition
+        step by step (and where the table yields no composite claim), and
+        the equations each model records. --family shows one family's
+        models, its bridges, the bridges from other families that touch it,
+        and its rejections; --relation/--evidence filter its bridges, and a
+        bridge whose tag depends on witness results is counted as undecided,
+        not as a mismatch. A model's equations are only those its
+        canonicalRefs record; nothing is inferred from shared quantities.
+        --route=FROM,TO --all-routes lists every simple route (no model
+        visited twice), shortest first, each with its composition and route
+        claim, and counts the claims; --max-routes=N (default 20, at most
+        1000) bounds the list, and a list cut short says so and says up to
+        which bridge count it is complete.
+        --observable=NAME maps the bridges whose RECORDED preserves text, or
+        declared bound translation, names that observable (a whole-word text
+        match, nothing inferred), lists apart those recording it as NOT
+        preserved, and counts the bridges that record nothing about it;
+        --relation/--evidence filter it as they filter a family.
+        --stored derives evidence from the committed witness results
+        (data/atlas/witness-results.json; a repository file, not shipped),
+        labelled with the last commit that touched it; --run runs the shown
+        bridges' in-process registered witnesses now (exit 3 if any is
+        refuted). Either resolves a tag once its witnesses have results; a
+        witness with no result leaves it undecided, and checked, refuted and
+        unresolved are counted apart.
+        Every atlas view states how many of the atlas's models and bridges it
+        shows, in text, --json and --format=mermaid|dot|svg.
+        e.g.  upt map --relation=derivation --source=both
+              upt map --around=temperature --depth=2 --source=catalog
+              upt map --route=model-pendulum,model-lc
+              upt map --route=model-string,model-dalembert --all-routes --stored
+              upt map --family=oscillators --evidence=formally-proved
+              upt map --observable=frequency --run`;
+/**
+ * The edges within `depth` shared-quantity hops of `quantity`: hop 1 is every
+ * edge that has it as a source or target, and each further hop adds the edges
+ * sharing a quantity with one already kept.
+ * @internal
+ */
+export function neighbourhood(graph, quantity, depth) {
+    const names = (e) => [...e.sources.map((q) => q.name), e.target.name];
+    const reached = new Set([quantity]);
+    const kept = new Set();
+    for (let hop = 0; hop < depth; hop++) {
+        const frontier = graph.filter((e) => !kept.has(e) && names(e).some((n) => reached.has(n)));
+        if (frontier.length === 0)
+            break;
+        for (const e of frontier) {
+            kept.add(e);
+            for (const n of names(e))
+                reached.add(n);
+        }
+    }
+    return graph.filter((e) => kept.has(e));
+}
 const RELATION_TYPES = [
     'derivation',
     'exact-equivalence',
@@ -88,6 +186,8 @@ const EVIDENCE_TAGS = [
     'symbolically-checked',
     'numerically-supported',
     'formally-proved',
+    'formally-proved-property',
+    'formally-proved-cross-check',
     'empirically-supported',
     'contradicted',
     'unresolved',
@@ -125,41 +225,71 @@ function proposedJunctions(api, graph, flags) {
 // 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) {
+async function analyzeEquation(api, equation, graph, options) {
     const catalogDims = new Map();
     for (const e of graph) {
         for (const q of [...e.sources, e.target])
             catalogDims.set(q.name, q.dim);
     }
-    const user = await api.analyzeUserEquation(equation, catalogDims);
+    const user = await api.analyzeUserEquation(equation, catalogDims, options);
     // Dimensions cannot see a prefactor: compare with the canonical equation the
     // user's one restates, when the registry holds one (persona finding L2).
-    const comparisons = user.parseError ? [] : await api.compareUserEquation(equation, catalogDims);
+    const comparisons = user.parseError
+        ? []
+        : await api.compareUserEquation(equation, catalogDims, {
+            bindShortNames: options?.bindShortNames,
+            ...(options?.units === undefined ? {} : { constantOverrides: naturalConstantOverrides(options.units) }),
+        });
     return { user, comparisons };
 }
 // 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, comparisons = []) {
     out('');
+    const placeholderNames = [
+        ...(user.placeholders ?? []),
+        ...(user.shortBindings ?? []).filter((b) => b.bound === false).map((b) => b.name),
+    ];
+    const unresolved = [...new Set([...(user.hints ?? []).map((h) => h.name), ...placeholderNames])];
     if (user.consistent === true) {
         out(`  ✓ dimensionally consistent: ${api.format(user.rhsDimension)}`);
     }
+    else if (user.consistent === false && unresolved.length > 0) {
+        // An unknown name is checked as a dimensionless placeholder, so this mismatch is not a real
+        // check and does not fail the command (exit 0). Say so on the line itself (persona finding N3).
+        const names = unresolved.map((n) => `'${n}'`).join(', ');
+        out(`  · UNKNOWN: RHS is ${api.format(user.rhsDimension)} but the target is ${api.format(user.targetDimension)}; ` +
+            `the mismatch involves the unresolved placeholder${unresolved.length > 1 ? 's' : ''} ${names} ` +
+            `(taken as dimensionless), so it is not a failed check`);
+    }
     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 && (user.placeholders ?? []).length > 0) {
+        const names = user.placeholders.map((n) => `'${n}'`).join(', ');
+        out(`  · UNKNOWN: RHS is ${api.format(user.rhsDimension)} only because ${names} ` +
+            `${user.placeholders.length === 1 ? 'was' : 'were'} taken as dimensionless. ` +
+            'That is not the dimension of the formula, and the target is not a bound catalog name, so nothing was checked');
+    }
     else if (user.rhsDimension) {
         out(`  · RHS dimension: ${api.format(user.rhsDimension)} (target not in the catalog, so no comparison)`);
     }
     for (const line of api.describeComparisons(comparisons))
         out(`  ${line}`);
+    for (const line of conventionLines(comparisons.map((c) => c.id)))
+        out(`  ${line}`);
+    if (user.naturalNote)
+        out(`  ${user.naturalNote}`);
     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(', ')}`);
+        // W3/I3: do not dump ~100 edge ids — that made shared length/temperature look
+        // like a physics claim. Summarise nearest equations by shared-quantity overlap.
+        for (const line of api.formatConnectedSummary(model, L))
+            out(line);
     }
     for (const h of user.hints ?? []) {
         if (!h.suggestions.length) {
@@ -171,10 +301,152 @@ function printEquationReport(api, model, user, out, comparisons = []) {
         else {
             out(`  ⚠ '${h.name}' did not match a catalog quantity — did you mean: ${h.suggestions.join(', ')}?`);
         }
+        // Persona finding L5: `sigma` for the Stefan–Boltzmann constant `sigma_sb`.
+        if ((h.constants ?? []).length > 0) {
+            const list = h.constants.join(', ');
+            out(`    '${h.name}' has the inferred dimension of the registered constant${h.constants.length > 1 ? 's' : ''} ${list}; ` +
+                'write that name to use its SI value');
+        }
+    }
+    // Persona finding W6: a one-letter name binds to whatever the catalog calls that letter.
+    for (const b of user.shortBindings ?? []) {
+        const users = model.junctions
+            .filter((j) => j.id !== 'user-equation' && (j.target === b.quantity || j.sources.includes(b.quantity)))
+            .map((j) => j.id)
+            .sort();
+        const shown = users.slice(0, 3).join(', ') + (users.length > 3 ? `, +${users.length - 3} more` : '');
+        const used = users.length > 0 ? ` (used by ${shown})` : '';
+        if (b.bound === false) {
+            out(`  · '${b.name}' matches the catalog quantity ${b.quantity} ${api.format(b.dim)}${used}, a one-letter name, and is not bound. ` +
+                'Pass --bind-short to bind it, or write the full name you meant');
+        }
+        else {
+            out(`  · '${b.name}' is bound to the catalog quantity ${b.quantity} ${api.format(b.dim)}, a one-letter name` +
+                `${used}; if you meant another quantity, write its full name`);
+        }
+    }
+}
+/** Flags that shape the equation graph, and so mean nothing on an atlas view. */
+const GRAPH_ONLY_FLAGS = ['source', 'around', 'depth', 'equation', 'equation-only', 'proposed', 'max-orders', 'anchor'];
+/** Flags that only an atlas view reads. */
+const ATLAS_ONLY_FLAGS = ['all-routes', 'max-routes', 'stored', 'run'];
+async function runAtlasView(ctx, route, family, observable) {
+    const { args, api, err, write } = ctx;
+    const chosen = [route !== undefined, family !== undefined, observable !== undefined].filter(Boolean).length;
+    if (chosen > 1)
+        throw new CliError('upt map: pick one atlas view: --route, --family or --observable');
+    const view = route !== undefined ? '--route' : family !== undefined ? '--family' : '--observable';
+    const stray = GRAPH_ONLY_FLAGS.filter((f) => args.flags.has(f));
+    if (stray.length > 0) {
+        throw new CliError(`upt map: ${view} maps the atlas, not the equation graph; ${stray.map((f) => `--${f}`).join(', ')} do${stray.length === 1 ? 'es' : ''} not apply`);
+    }
+    const relation = parseFilter(lastValue(args.flags, 'relation'), RELATION_TYPES, '--relation');
+    const evidence = parseFilter(lastValue(args.flags, 'evidence'), EVIDENCE_TAGS, '--evidence');
+    if (route !== undefined && (relation !== undefined || evidence !== undefined)) {
+        throw new CliError('upt map: a route is composed whole, so --relation/--evidence do not filter it; filter a family view instead (--family=NAME)');
+    }
+    const allRoutes = args.flags.has('all-routes');
+    if (allRoutes && route === undefined)
+        throw new CliError('upt map: --all-routes needs --route=FROM,TO');
+    const maxRaw = lastValue(args.flags, 'max-routes');
+    if (maxRaw !== undefined && !allRoutes)
+        throw new CliError('upt map: --max-routes needs --all-routes');
+    const maxRoutes = maxRaw === undefined ? atlasMap.DEFAULT_MAX_ROUTES : Number(maxRaw);
+    if (!Number.isInteger(maxRoutes) || maxRoutes < 1 || maxRoutes > atlasMap.MAX_ROUTES_CEILING) {
+        throw new CliError(`upt map: --max-routes=${maxRaw} must be an integer from 1 to ${atlasMap.MAX_ROUTES_CEILING}`);
+    }
+    if (args.flags.has('stored') && args.flags.has('run')) {
+        throw new CliError('upt map: pick one witness-results source: --stored (the committed artifact) or --run (run now)');
+    }
+    const fmt = lastValue(args.flags, 'format') ?? 'text';
+    const isJson = args.flags.has('json');
+    if (isJson && fmt !== 'text')
+        throw new UsageError('upt: pick one output form: --json or --format');
+    if (!['text', 'mermaid', 'dot', 'svg'].includes(fmt)) {
+        throw new CliError(`upt: unknown --format='${fmt}' (expected: text | mermaid | dot | svg)`);
+    }
+    const filter = {
+        ...(relation !== undefined ? { relation } : {}),
+        ...(evidence !== undefined ? { evidence } : {}),
+    };
+    const endpoints = route === undefined ? null : atlasMap.parseRoute(route);
+    const build = (results) => endpoints !== null
+        ? allRoutes
+            ? atlasMap.buildRoutesView(api, ...endpoints, maxRoutes, results)
+            : atlasMap.buildRouteView(api, ...endpoints, results)
+        : family !== undefined
+            ? atlasMap.buildFamilyView(api, family, filter, results)
+            : atlasMap.buildObservableView(api, observable, filter, results);
+    let results = null;
+    if (args.flags.has('stored'))
+        results = atlasMap.loadStoredResults();
+    else if (args.flags.has('run')) {
+        // Unfiltered first: a filter's verdict depends on the results, so every candidate bridge is run.
+        const candidates = endpoints === null
+            ? atlasMap.bridgeIdsOf(family !== undefined ? atlasMap.buildFamilyView(api, family, {}) : atlasMap.buildObservableView(api, observable, {}))
+            : atlasMap.bridgeIdsOf(build(null));
+        results = await atlasMap.runResults(api, candidates);
+    }
+    const v = build(results);
+    const exitCode = results?.mode === 'run' && results.rows.some((r) => r.status === 'refuted') ? EXIT_CHECK_FAILED : 0;
+    if (isJson) {
+        emitJson({ command: 'map', source: 'atlas', result: v }, write);
+        return exitCode;
+    }
+    if (fmt === 'text') {
+        const lines = v.view === 'route'
+            ? atlasMap.routeText(v)
+            : v.view === 'routes'
+                ? atlasMap.routesText(v)
+                : v.view === 'family'
+                    ? atlasMap.familyText(v)
+                    : atlasMap.observableText(v);
+        for (const line of lines)
+            ctx.out(line);
+        return exitCode;
+    }
+    let src;
+    if (fmt === 'svg') {
+        try {
+            src = await api.renderDotToSvg(atlasMap.toDot(v));
+        }
+        catch (e) {
+            throw new CliError(e && e.message ? e.message : String(e));
+        }
+    }
+    else {
+        src = fmt === 'mermaid' ? atlasMap.toMermaid(v) : atlasMap.toDot(v);
+    }
+    const path = lastValue(args.flags, 'out');
+    if (path !== undefined) {
+        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} to ${path}`);
     }
+    else {
+        write(src);
+    }
+    err(`upt: ${atlasMap.viewLegend(v)}`);
+    return exitCode;
 }
 async function run(ctx) {
     const { args, api, out, err, write } = ctx;
+    const route = lastValue(args.flags, 'route');
+    const family = lastValue(args.flags, 'family');
+    const observable = lastValue(args.flags, 'observable');
+    if (route !== undefined || family !== undefined || observable !== undefined)
+        return runAtlasView(ctx, route, family, observable);
+    const atlasOnly = ATLAS_ONLY_FLAGS.filter((f) => args.flags.has(f));
+    if (atlasOnly.length > 0) {
+        throw new CliError(`upt map: ${atlasOnly.map((f) => `--${f}`).join(', ')} appl${atlasOnly.length === 1 ? 'ies' : 'y'} to an atlas view ` +
+            '(--route, --family or --observable), not to the equation graph');
+    }
     // map asks a pure connectivity question, so it defaults to --source=both
     // (catalog + canonical) rather than graphs.ts's catalog fallback used by
     // the other --source commands (e.g. discover, which keeps catalog).
@@ -189,7 +461,32 @@ async function run(ctx) {
     const resolved = posterMode
         ? { graph: [], label: 'poster (Atlas Phase 3 index)', source: 'poster' }
         : resolveGraph(api, sourceFlags);
-    const { graph: fullGraph, label, source } = resolved;
+    const { graph: wholeGraph, label, source } = resolved;
+    const around = lastValue(args.flags, 'around');
+    const depthRaw = lastValue(args.flags, 'depth');
+    if (depthRaw !== undefined && around === undefined)
+        throw new CliError('upt map: --depth needs --around');
+    let focus = null;
+    let fullGraph = wholeGraph;
+    if (around !== undefined) {
+        if (posterMode)
+            throw new CliError('upt map: --around focuses a quantity graph; the poster index has statements, not quantities');
+        const depth = depthRaw === undefined ? 1 : Number(depthRaw);
+        if (!Number.isInteger(depth) || depth < 1 || depth > 10)
+            throw new CliError(`upt map: --depth=${depthRaw} must be an integer from 1 to 10`);
+        const known = new Set(wholeGraph.flatMap((e) => [...e.sources.map((q) => q.name), e.target.name]));
+        const name = api.resolveToCatalogName(around, known);
+        if (name === null) {
+            const near = api.suggestQuantities(around, known);
+            throw new CliError(`upt map: '${around}' is not a quantity of the ${label} graph` + (near.length > 0 ? `; did you mean: ${near.join(', ')}?` : ''));
+        }
+        fullGraph = neighbourhood(wholeGraph, name, depth);
+        focus = { around: name, depth, kept: fullGraph.length, of: wholeGraph.length };
+    }
+    const focusLine = focus === null
+        ? null
+        : `focused: ${focus.kept} of ${focus.of} edges within ${focus.depth} hop(s) of '${focus.around}' [${label}]; ` +
+            'the rest are omitted from this view, not absent from the graph';
     // The poster's own report line: what it contributed, or why it contributed
     // nothing (design note §6). Computed once; printed by every output form.
     const posterValidation = posterMode ? api.validatePoster(api.POSTER_GRAPH) : null;
@@ -200,10 +497,10 @@ async function run(ctx) {
     // value costs nothing and always exits 1.
     const relation = parseFilter(lastValue(args.flags, 'relation'), RELATION_TYPES, '--relation');
     const evidence = parseFilter(lastValue(args.flags, 'evidence'), EVIDENCE_TAGS, '--evidence');
-    const filterOpts = {
+    const filterOpts = withCatalogEvidence({
         ...(relation !== undefined ? { relation } : {}),
         ...(evidence !== undefined ? { evidence } : {}),
-    };
+    });
     // The TEXT and JSON paths filter the edge list here, because `linkageMap`
     // consumes edges. The VISUAL path hands `buildVizModel` the FULL graph with
     // the same options, so the model also judges the --proposed / --equation
@@ -211,6 +508,13 @@ async function run(ctx) {
     // One predicate, two callers: they cannot disagree about what a filter
     // selects, only about how much they were asked to count.
     const { kept: graph, stats: edgeStats } = api.filterEdges(fullGraph, filterOpts);
+    // Audit I3: what "anchored" means here, and the discovery ground truth when --proposed ran the funnel.
+    const anchor = posterMode
+        ? null
+        : {
+            core: coreAnchor(graph),
+            ...(args.flags.has('proposed') ? { groundTruth: groundTruthAnchor(api, parseDiscoveryOpts(args.flags)) } : {}),
+        };
     const edgeLegend = api.formatFilterLegend(edgeStats);
     const fmtValues = args.flags.get('format');
     const fmt = fmtValues && fmtValues.length > 0 ? fmtValues[fmtValues.length - 1] : 'text';
@@ -223,12 +527,27 @@ async function run(ctx) {
     let comparisons = [];
     const equationValues = args.flags.get('equation');
     const equation = equationValues && equationValues.length > 0 ? equationValues[equationValues.length - 1] : null;
+    // Persona finding L7: the verdict alone, without the linkage map after it.
+    const equationOnly = args.flags.has('equation-only');
+    if (equationOnly && equation == null)
+        throw new UsageError('upt map: --equation-only needs --equation "TARGET = EXPR"');
+    if (equationOnly && fmt !== 'text') {
+        throw new UsageError(`upt map: --equation-only prints the verdict as text or --json; it does not apply to --format=${fmt}`);
+    }
     if (equation != null) {
         if (!equation.trim()) {
             throw new UsageError('upt: --equation requires "TARGET = EXPR"');
         }
         try {
-            ({ user, comparisons } = await analyzeEquation(api, equation, graph)); // throws UserEquationError on malformed structure
+            const units = args.flags.has('geometrized')
+                ? 'geometrized'
+                : args.flags.has('natural')
+                    ? 'natural'
+                    : undefined;
+            ({ user, comparisons } = await analyzeEquation(api, equation, graph, {
+                bindShortNames: args.flags.has('bind-short'),
+                ...(units === undefined ? {} : { units }),
+            })); // throws UserEquationError on malformed structure
         }
         catch (e) {
             throw new UsageError('upt: ' + (e && e.message ? e.message : String(e)));
@@ -242,15 +561,18 @@ async function run(ctx) {
     // mismatch counts only when every name resolved: an unknown name is checked
     // as a dimensionless placeholder, so its "mismatch" is not a real check.
     const exitCode = user !== null &&
-        ((user.consistent === false && (user.hints ?? []).length === 0) ||
-            comparisons.some((c) => c.kind === 'factor' || c.kind === 'form'))
+        ((user.consistent === false &&
+            (user.hints ?? []).length === 0 &&
+            (user.placeholders ?? []).length === 0 &&
+            !(user.shortBindings ?? []).some((b) => b.bound === false)) ||
+            canonicalCheckFailed(comparisons))
         ? EXIT_CHECK_FAILED
         : 0;
     const overlay = (extra) => [
         // Ranked from the UNFILTERED graph: the proposal set is a property of the
         // whole catalog, and the model then judges each overlay junction under the
         // same filter as every other junction.
-        ...(args.flags.has('proposed') ? proposedJunctions(api, fullGraph, args.flags) : []),
+        ...(args.flags.has('proposed') ? proposedJunctions(api, wholeGraph, args.flags) : []),
         // The poster enters as an overlay for exactly the reason the design note
         // gives: an overlay is FILTERED, clustered and legended like every other
         // junction, so a poster source cannot quietly bypass --relation/--evidence.
@@ -274,16 +596,20 @@ async function run(ctx) {
                 rhsDimension: user.rhsDimension,
                 targetDimension: user.targetDimension,
                 hints: user.hints,
+                shortBindings: user.shortBindings,
+                ...(user.placeholders.length === 0 ? {} : { placeholders: user.placeholders }),
                 canonicalComparisons: comparisons,
             };
         }
         emitJson({
             command: 'map',
             source,
+            ...(anchor !== null ? { anchor } : {}),
             result: {
-                linkage,
+                ...(equation != null && (equationOnly || !args.flags.has('verbose')) ? {} : { linkage }),
                 ...(posterMode ? { poster: { note: posterNote, ...posterValidation } } : {}),
                 ...(edgeLegend !== null ? { filter: edgeStats } : {}),
+                ...(focus !== null ? { focus } : {}),
                 ...(user ? { landing, userEquation } : {}),
             },
         }, write);
@@ -330,6 +656,8 @@ async function run(ctx) {
         // source. The diagram itself also carries the legend (see `buildVizModel`).
         if (posterNote !== null)
             err(`upt: ${posterNote}`);
+        if (focusLine !== null)
+            err(`upt: ${focusLine}`);
         if (model.filterLegend !== null)
             err(`upt: ${model.filterLegend}`);
         if (user)
@@ -345,7 +673,7 @@ async function run(ctx) {
             extraJunctions: overlay(user ? [user.junction] : []),
             ...filterOpts,
         });
-        out(`
+        out(`
 Poster index — statements and the derivations between them  [source: ${label}]`);
         out(`  ${posterNote}`);
         out(`  (${model.junctions.length} junctions over ${model.clusters.length} clusters; ` +
@@ -357,18 +685,37 @@ Poster index — statements and the derivations between them  [source: ${label}]
             out(`  ⚠ '${d.derivation}' names '${d.missing}' as a ${d.role}, and nothing defines it.`);
         }
         if (user) {
-            out(`
+            out(`
 Your equation:  ${user.junction.label}`);
             printEquationReport(api, model, user, out, comparisons);
         }
         return exitCode;
     }
+    // --equation: the verdict on the user's equation is the answer asked for, so it
+    // comes BEFORE the linkage map, not after ~45 lines of it (persona finding N4).
+    if (user) {
+        const model = api.buildVizModel(fullGraph, {
+            title: `UPT physics map — ${label}`,
+            extraJunctions: overlay([user.junction]),
+            ...filterOpts,
+        });
+        out(`\nYour equation:  ${user.junction.label}`);
+        printEquationReport(api, model, user, out, comparisons);
+        if (equationOnly || !args.flags.has('verbose'))
+            return exitCode;
+    }
     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`);
+    out(`(${m.componentCount} components over ${graph.length} edges; ${m.compositions} compose into chains)`);
+    out(`  ${coreLine(anchor.core)}`);
+    if (anchor.groundTruth)
+        out(`  proposals: ${groundTruthLine(anchor.groundTruth)}`);
+    out('');
+    if (focusLine !== null)
+        out(`  ${focusLine}`);
     if (edgeLegend !== null)
         out(`  ${edgeLegend}`);
     for (const c of m.clusters.filter((x) => x.size > 1)) {
@@ -380,16 +727,6 @@ Your equation:  ${user.junction.label}`);
     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(fullGraph, {
-            title: `UPT physics map — ${label}`,
-            extraJunctions: overlay([user.junction]),
-            ...filterOpts,
-        });
-        out(`\nYour equation:  ${user.junction.label}`);
-        printEquationReport(api, model, user, out, comparisons);
-    }
     return exitCode;
 }
 export const command = {