unitbob 0.2.7 → 0.3.0

package/dist/surfaces/routeInventory.js

@@ -0,0 +1,448 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { runProcess } from "../proc.js";
+import { firstErrorLine } from "../runner/bootcheck.js";
+import { graphPath } from "../files/mapBuild.js";
+// Reading a router means booting the application, which on a large Rails app is
+// tens of seconds. The same budget the other boot-shaped step uses.
+const ROUTES_TIMEOUT_MS = 120_000;
+const defaultDeps = {
+    runCmd: (command, args, options) => runProcess(command, args, {
+        cwd: options.cwd,
+        timeoutMs: ROUTES_TIMEOUT_MS,
+        env: { ...process.env, ...options.env },
+    }),
+};
+export function routeInventoryPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'map-build', 'route_inventory.json');
+}
+// Ask this project's router, and write what it says. Rails today; the design
+// records why Django, FastAPI and Flask come next and why Express cannot follow
+// at all (its addresses are registered by arbitrary code at run time).
+export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
+    if (!looksLikeRails(projectRoot))
+        return silent(projectRoot, 'unsupported_stack');
+    const asked = await askTheRouter(projectRoot, deps);
+    if ('reason' in asked)
+        return silent(projectRoot, asked.reason, asked.detail);
+    const rows = parseExpandedRoutes(asked.result.stdout);
+    // Zero rows is far likelier to mean "this output is not what we know how to
+    // read" than "this application has no addresses". Claiming the second would
+    // hand the map a confident, empty answer, so we claim neither.
+    if (rows.length === 0)
+        return silent(projectRoot, 'no_routes');
+    const nodes = graphNodes(projectRoot);
+    const surfaces = rows.map((row) => toSurface(projectRoot, row, nodes));
+    // The inventory, and only the inventory. `surfaces.json` is not written here,
+    // however tempting: the recipe turns this file into that one with a single
+    // command — no output spent retyping addresses, and the file still does not
+    // exist until the model has begun. That absence is a check we would otherwise
+    // throw away, because `put-map-build` refuses a build whose `surfaces.json` is
+    // missing, and a pre-written file full of routes looks finished enough for the
+    // job, table and external surfaces never to be looked for.
+    const path = routeInventoryPath(projectRoot);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails routes', environment: asked.environment, surfaces }, null, 2)}\n`);
+    }
+    catch (err) {
+        // A read-only checkout or a full disk is not a reason to take the whole map
+        // build down: without an inventory the recipe reads the source, exactly as
+        // on every stack we cannot ask.
+        return silent(projectRoot, 'could_not_write', err.message);
+    }
+    return {
+        status: 'written',
+        path,
+        routes: surfaces.length,
+        linked: surfaces.filter((surface) => surface.handler_symbol).length,
+        environment: asked.environment,
+    };
+}
+// One question, up to two environments. Everything that can be decided from the
+// first answer is decided there; only "this environment refused to load" is
+// worth asking again, because that is the one failure an environment can own.
+async function askTheRouter(projectRoot, deps) {
+    const first = await runRailsRoutes(projectRoot, deps, 'test');
+    if (first === null) {
+        // The command is not on this machine. A second environment cannot conjure it.
+        return { reason: 'app_did_not_load', detail: 'the command did not run on this machine' };
+    }
+    if (first.code === 0)
+        return { result: first, environment: 'test' };
+    // Rails learned `--expanded` in 5.1. Older ones reject the flag before they
+    // load anything, and saying "your application did not load" there sends
+    // somebody to debug an application that is perfectly fine — the same reason
+    // the boot check grew `runner_too_old` rather than calling vitest missing.
+    // The flag is refused the same way in every environment, so there is nothing
+    // to retry.
+    if (rejectedTheFlag(first))
+        return { reason: 'router_too_old' };
+    // No exit code at all means the process was stopped rather than finished —
+    // our own timeout, or a signal from outside. An application too large to
+    // enumerate its routes in the time we allow has told us nothing about whether
+    // it is healthy, and "it did not load" would be us inventing the answer.
+    // Retrying would spend the same budget twice for the same silence.
+    if (first.code === null)
+        return { reason: 'did_not_finish' };
+    const second = await runRailsRoutes(projectRoot, deps, 'default');
+    if (second !== null && second.code === 0)
+        return { result: second, environment: 'default' };
+    if (second !== null && second.code === null)
+        return { reason: 'did_not_finish' };
+    // `rails routes` loads the application, so running it *is* the check: an app
+    // that will not boot cannot print its routes. We do not ask the boot check
+    // from spec 32-6 first — that would boot the app twice to learn the same
+    // thing — but we do answer in its currency, quoting the runner's own first
+    // error line rather than a paraphrase of it. The default environment's words
+    // are the ones quoted: if even that one will not load, the application does
+    // not load, and the test database is not what is missing.
+    const output = `${second?.stdout ?? first.stdout}\n${second?.stderr ?? first.stderr}`.trim();
+    return {
+        reason: 'app_did_not_load',
+        detail: output ? firstErrorLine(output) : 'the command did not run on this machine',
+    };
+}
+// Every way of saying nothing goes through here, and every one of them takes
+// yesterday's inventory with it. Silence must leave no answer behind: a file
+// full of the addresses of a previous run sits in the folder the map build
+// reads, under an authoritative name, and nothing on it says how old it is.
+// `request.json` would not point at it, but a stale answer that looks current
+// is the same failure this spec exists to remove — only quieter, because it was
+// true once.
+function silent(projectRoot, reason, detail) {
+    try {
+        rmSync(routeInventoryPath(projectRoot), { force: true });
+    }
+    catch {
+        // Nothing to clear, or a path we cannot touch. Either way the answer below
+        // stands: this run declares no addresses.
+    }
+    return detail === undefined ? { status: 'silent', reason } : { status: 'silent', reason, detail };
+}
+// The one sentence a vibecoder reads about all this: how many addresses came
+// back, or why none did. It lives beside the closed list of reasons rather than
+// in the verb, because both the verb and `map-prepare` print it and neither owns
+// the vocabulary.
+export function describeRouteInventory(result) {
+    if (result.status === 'written') {
+        return (`Route inventory written to ${result.path}: ${result.routes} ${plural(result.routes, 'address', 'addresses')} ` +
+            `from the router${result.environment === 'default' ? ' (read in the default environment — the test one ' +
+                'would not load)' : ''}, ${result.linked} tied to a graph node. The extract_surfaces recipe turns ` +
+            'this file into surfaces.json with one command, then adds the job, table and external surfaces to it.');
+    }
+    return `No route inventory: ${becauseOf(result)}. The extract_surfaces recipe reads the source instead.`;
+}
+// Why we stayed quiet, in the vibecoder's words. A closed list, so the sentence
+// is the same from run to run and a test can pin it.
+function becauseOf(result) {
+    switch (result.reason) {
+        case 'unsupported_stack':
+            return 'this project has no router Unitbob can ask yet (Rails is the only one so far)';
+        case 'router_too_old':
+            return '`rails routes --expanded` needs Rails 5.1 or newer, and this Rails refused the flag ' +
+                '(nothing is wrong with the application)';
+        case 'app_did_not_load':
+            return `\`rails routes\` did not get through — ${result.detail}`;
+        case 'did_not_finish':
+            // No exit code means stopped, and we do not know by whom: our own
+            // ${minutes}-minute limit, or something outside this process. Naming only
+            // the timeout would put a duration on a run that may have been killed in
+            // ten seconds — a claim we cannot make.
+            return `\`rails routes\` was stopped before it finished — either it ran past the ` +
+                `${ROUTES_TIMEOUT_MS / 60_000}-minute limit or something else killed it (nothing here says the ` +
+                'application is unhealthy)';
+        case 'no_routes':
+            return '`rails routes` printed nothing this version knows how to read';
+        case 'could_not_write':
+            return `the inventory could not be written — ${result.detail}`;
+    }
+}
+function plural(count, one, many) {
+    return count === 1 ? one : many;
+}
+function looksLikeRails(projectRoot) {
+    return existsSync(join(projectRoot, 'config', 'routes.rb'));
+}
+// `--expanded` rather than the default table: one field per line, so nothing
+// depends on guessing column widths, and a long URI pattern cannot run into its
+// neighbour. `test` is asked first because that is the environment the guardrail
+// suite boots in, so the routes read there are the routes the suite would see;
+// `default` means we leave RAILS_ENV alone and take whatever the project's own
+// setup chooses.
+async function runRailsRoutes(projectRoot, deps, environment) {
+    const local = join(projectRoot, 'bin', 'rails');
+    const [command, args] = existsSync(local)
+        ? [local, ['routes', '--expanded']]
+        : ['bundle', ['exec', 'rails', 'routes', '--expanded']];
+    try {
+        return await deps.runCmd(command, args, {
+            cwd: projectRoot,
+            env: environment === 'test'
+                ? { RAILS_ENV: 'test', UNITBOB_REPO_ROOT: projectRoot }
+                : { UNITBOB_REPO_ROOT: projectRoot },
+        });
+    }
+    catch {
+        return null; // the command is not on this machine
+    }
+}
+// Ruby's own OptionParser wording, and Thor's — whichever layer of the `rails`
+// command line sees the flag first. Both name the flag they refused, and the
+// name has to be part of the match: "invalid option" is ordinary Ruby wording
+// that also turns up inside a failing initializer, and reading that as an old
+// Rails would tell somebody their application is fine while it is broken —
+// exactly the wrong-errand this reason exists to prevent, pointing the other way.
+function rejectedTheFlag(result) {
+    return /(?:invalid option|unknown switches?|unrecognized option)[^\n]*expanded/i.test(`${result.stdout}\n${result.stderr}`);
+}
+// The `--expanded` record:
+//
+//   --[ Route 1 ]------------------------------
+//   Prefix            | settings
+//   Verb              | GET
+//   URI               | /settings(.:format)
+//   Controller#Action | settings#index
+//
+// The path field is `URI` on Rails 7 and `URI Pattern` on older versions — both
+// are read, because which one we get is decided by the user's Gemfile. Fields we
+// do not use (Prefix, Source Location) are ignored rather than rejected, so a
+// newer Rails printing more of them still reads.
+export function parseExpandedRoutes(stdout) {
+    const rows = [];
+    const seen = new Set();
+    let record = {};
+    const flush = () => {
+        for (const row of rowsFrom(record)) {
+            const key = `${row.verb} ${row.path}`;
+            // The same address can be drawn under several prefixes. It is one address.
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            rows.push(row);
+        }
+        record = {};
+    };
+    for (const line of stdout.split('\n')) {
+        if (/^--\[ Route /.test(line)) {
+            flush();
+            continue;
+        }
+        const separator = line.indexOf('|');
+        if (separator === -1)
+            continue;
+        record[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+    }
+    flush();
+    return rows;
+}
+function rowsFrom(record) {
+    const pattern = record.URI ?? record['URI Pattern'];
+    const verb = record.Verb ?? '';
+    // No verb means a mounted Rack application (`mount Sidekiq::Web at: '/sidekiq'`),
+    // not an address of this application. Its own routes live in its own router.
+    if (!pattern || !verb)
+        return [];
+    const handler = /^([A-Za-z0-9_/]+)#([A-Za-z0-9_]+)$/.exec(record['Controller#Action'] ?? '');
+    const path = pattern.replace(/\(\.:format\)$/, '');
+    // `match via: [:get, :post]` prints one record with both verbs. They are two
+    // addresses, and the map should say so.
+    return verb.split('|').map((one) => ({
+        verb: one.trim(),
+        path,
+        controller: handler?.[1],
+        action: handler?.[2],
+    }));
+}
+function graphNodes(projectRoot) {
+    const path = graphPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    try {
+        const graph = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(graph.nodes))
+            return [];
+        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
+    }
+    catch {
+        return []; // an unreadable graph costs us the links, not the addresses
+    }
+}
+function toSurface(projectRoot, row, nodes) {
+    const surface = { kind: 'route', id: `${row.verb} ${row.path}` };
+    if (!row.controller || !row.action)
+        return surface;
+    const file = join('app', 'controllers', `${row.controller}_controller.rb`);
+    const node = findNode(nodes, file, row.action);
+    // The node's own path when we found it; otherwise the file the convention
+    // names, and only if it is really there — a route from a gem has neither.
+    //
+    // This second branch is the one place the module answers with something the
+    // router did not print, so it is worth being plain about what it claims and
+    // what it does not. It claims: Rails resolves `settings#index` to
+    // `app/controllers/settings_controller.rb`, and that file exists here. It does
+    // not claim the method lives in that file — an inherited action's controller
+    // is on disk while the code that serves it is in a parent class elsewhere.
+    // That is why the same branch leaves `handler_symbol` out: the file is where
+    // Rails looks, the link is where the code is, and only the second one is
+    // allowed to be a guess-free fact.
+    if (node?.source_file)
+        surface.source_file = node.source_file;
+    else if (existsSync(join(projectRoot, file)))
+        surface.source_file = file;
+    if (node)
+        surface.handler_symbol = node.id;
+    // What the router printed, not a class name we built from it.
+    surface.handler_label = `${row.controller}#${row.action}`;
+    return surface;
+}
+// The link is *searched for*, never spelled. graphify names its node ids by an
+// internal rule, it is a third-party package (`pip install graphifyy`), and that
+// rule may change in any release. Rebuilding the rule here would make us
+// responsible for somebody else's private detail and would break in a way we
+// could not see. So we look the node up by the two things the router already
+// knows — which file, which method — and copy the id it carries, whole.
+//
+// Not finding one is ordinary: the action may be drawn by a template with no
+// method behind it, inherited from a parent class in another file, or come from
+// a gem graphify never saw. Then the address keeps its place with no link. The
+// router said it exists, so it exists; an empty field says "we do not know
+// where this is served", while dropping the address would say it is not there
+// at all.
+// A wrong link is worse than no link — the address would send a later trace
+// into somebody else's code, and nothing downstream could tell: the node it
+// names really does exist, so the host's check passes. Hence the ranking below
+// rather than "first node that fits".
+function findNode(nodes, file, action) {
+    const candidates = nodes.filter((node) => typeof node.source_file === 'string' &&
+        typeof node.label === 'string' &&
+        methodNameOf(node.label) === action &&
+        pathsMatch(node.source_file, file) !== 'no');
+    // The path the graph gives may be relative to the project or absolute, so an
+    // exact match cannot be the only rule. But when one node names exactly the
+    // file the router pointed at, it wins outright: an engine, a second app in
+    // the monorepo or a vendored copy can end with the same
+    // `app/controllers/users_controller.rb` and would otherwise be picked by
+    // nothing better than graph order.
+    //
+    // One, though — not "the first of several". Two nodes can name the same file
+    // and the same method: two classes in one file, or a graph that lists a
+    // definition more than once. Taking the earlier one there is the very rule
+    // this branch was written to replace, one level down, so the same answer
+    // applies as below: we do not know, and we say so by staying quiet.
+    const exact = candidates.filter((node) => pathsMatch(node.source_file, file) === 'exact');
+    if (exact.length > 0)
+        return exact.length === 1 ? exact[0] : undefined;
+    // Ends with the right path and is the only one that does. Two or more and we
+    // cannot tell which file the router meant, so we say nothing — the address
+    // still ships, without a link.
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function pathsMatch(candidate, file) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    const wanted = file.replace(/\\/g, '/');
+    if (normalised === wanted)
+        return 'exact';
+    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
+}
+// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
+// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
+// them are read the same way — drop the call parentheses, then take the last
+// name — so the match survives the decoration without depending on which form
+// this release of graphify happens to use. The id itself is never rebuilt from
+// any of this; it is copied.
+function methodNameOf(label) {
+    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
+    return parts[parts.length - 1] ?? '';
+}
+// What `surfaces.json` must contain for every address the router declared, and
+// what it must not contain on top of them. Used before upload (`put-map-build`):
+// the inventory removed the model's chance to invent an address, and this
+// removes its chance to lose or rename one on the way to the map. The same move
+// spec 32-6 made for suites — check the answer against the request locally,
+// while both files are still on this machine.
+//
+// Routes only. Whether the grouping is sensible, whether the human names are
+// good, what the jobs and tables are — none of that is this function's business.
+export function inventoryProblems(inventory, surfaces) {
+    const declared = routeEntriesIn(inventory);
+    if (declared === null) {
+        return ['the route inventory is not readable, so what the router declared cannot be confirmed'];
+    }
+    const written = routeEntriesIn(surfaces);
+    if (written === null)
+        return ['surfaces.json has no readable `surfaces` array'];
+    const problems = [];
+    const missing = [...declared.keys()].filter((id) => !written.has(id));
+    const invented = [...written.keys()].filter((id) => !declared.has(id));
+    if (missing.length > 0) {
+        problems.push(`surfaces.json is missing ${missing.length} address the router declared: ${list(missing)}. ` +
+            'Copy every entry of the route inventory across unchanged.');
+    }
+    if (invented.length > 0) {
+        problems.push(`surfaces.json carries ${invented.length} route the router never declared: ${list(invented)}. ` +
+            'The router is the authority on what exists; an address it does not know is either a typo ' +
+            'in a copied id or invented.');
+    }
+    // Two sentences rather than one, because the two kinds of rewrite are not the
+    // same mistake and the person reading has to fix the right thing: one sends a
+    // later trace into the wrong code, the other only renames what is shown.
+    const relinked = alteredFields(declared, written, LINK_FIELDS);
+    if (relinked.length > 0) {
+        problems.push(`surfaces.json rewrote ${relinked.length} field that points at code: ${list(relinked)}. ` +
+            'Copy each entry as it stands — a field the inventory leaves out is an answer too, ' +
+            '"we do not know where this is served", and filling it in makes one up.');
+    }
+    const relabelled = alteredFields(declared, written, LABEL_FIELDS);
+    if (relabelled.length > 0) {
+        problems.push(`surfaces.json reworded ${relabelled.length} handler_label: ${list(relabelled)}. ` +
+            'That name is what the router itself printed; the human names for the map are the ' +
+            'capability titles in the next step, not this field.');
+    }
+    return problems;
+}
+// The id says the address exists; these say where it is served, and both were
+// either printed by the router or copied out of the graph. A blank is not a gap
+// to be helpfully filled — an invented `source_file` is the same failure as an
+// invented address, one field over, and a `handler_symbol` swapped for another
+// node that happens to exist passes the host's check while sending spec 35's
+// trace into the wrong code.
+const LINK_FIELDS = ['source_file', 'handler_symbol'];
+// Not a link and nothing downstream reads it — but spec 32-7 took the authoring
+// of names away from the model on purpose, and `settings#index` as the router
+// printed it is the whole of what we claim. A prettier `Api::V1::UsersController`
+// is simply wrong on a project with its own inflections.
+const LABEL_FIELDS = ['handler_label'];
+function alteredFields(declared, written, fields) {
+    const altered = [];
+    for (const [id, entry] of declared) {
+        const copy = written.get(id);
+        if (!copy)
+            continue; // already reported as missing
+        for (const field of fields) {
+            if (entry[field] !== copy[field])
+                altered.push(`${id} → ${field}`);
+        }
+    }
+    return altered;
+}
+function routeEntriesIn(document) {
+    const surfaces = document?.surfaces;
+    if (!Array.isArray(surfaces))
+        return null;
+    const entries = new Map();
+    for (const surface of surfaces) {
+        if (!surface || surface.kind !== 'route')
+            continue;
+        const id = surface.id;
+        if (typeof id !== 'string' || entries.has(id))
+            continue;
+        entries.set(id, surface);
+    }
+    return entries;
+}
+// Enough ids to recognise the mistake, not so many that the message scrolls off.
+function list(ids) {
+    const shown = ids.slice(0, 10);
+    return ids.length > shown.length ? `${shown.join(', ')}, … (+${ids.length - shown.length})` : shown.join(', ');
+}

package/dist/verbs/extractSurfaces.js

@@ -0,0 +1,17 @@
+import { ensureUnitbobIgnored } from "../proc.js";
+import { describeRouteInventory, extractRouteInventory } from "../surfaces/routeInventory.js";
+// Spec 32-7. `unitbob extract-surfaces` asks the framework's own router for the
+// application's addresses and writes them down. It has the right to say nothing,
+// and says nothing far more often than it speaks: only Rails can be asked today,
+// and only when the application loads.
+//
+// Silence exits 0. Nothing is wrong when a stack has no router to ask — the
+// map is still built, by the path that has always built it.
+export async function extractSurfaces(config, _args = []) {
+    // Run on its own, this verb is the first thing to write into `.unitbob/`, so
+    // it owes the project the same courtesy `map-prepare` does: the folder is our
+    // bookkeeping and must not turn up in the vibecoder's commit.
+    ensureUnitbobIgnored(config.projectRoot);
+    const result = await extractRouteInventory(config.projectRoot);
+    process.stdout.write(`${describeRouteInventory(result)}\n`);
+}

package/dist/verbs/mapPrepare.js

@@ -1,5 +1,6 @@
 import { ensureUnitbobIgnored, requireGraphify, runGraphifyExtractKeyless } from "../proc.js";
 import { readFreshGraph, writeMapBuildRequest } from "../files/mapBuild.js";
+import { describeRouteInventory, extractRouteInventory, } from "../surfaces/routeInventory.js";
 import { Wire } from "../wire.js";
 export async function mapPrepare(config, _args = [], deps) {
     const wire = new Wire(config);
@@ -7,6 +8,7 @@ export async function mapPrepare(config, _args = [], deps) {
         requireGraphify,
         ensureUnitbobIgnored,
         runGraphifyExtractKeyless,
+        extractRouteInventory,
         getRecipe: (name) => wire.getRecipe(name),
         ...deps,
     };
@@ -20,6 +22,17 @@ export async function mapPrepare(config, _args = [], deps) {
         throw new Error(`graphify update failed: ${detail}`);
     }
     readFreshGraph(config.projectRoot);
+    // Asked here rather than left to the workflow as a step of its own (spec
+    // 32-7). The graph has just been refreshed, which is what the addresses are
+    // linked against, and a step an instruction can skip is a step that gets
+    // skipped — the lesson spec 32-4 paid for. Silence costs nothing: the request
+    // simply carries no inventory and the recipe reads the source.
+    //
+    // Said out loud first, because asking a router means booting the application
+    // and that can take a minute or two with nothing on the screen. Silence from
+    // us there reads as a hang.
+    process.stdout.write('Asking this project for the addresses it declares (this boots the application)…\n');
+    const inventory = await actual.extractRouteInventory(config.projectRoot);
     const [decompose, relate, extractSurfaces, decomposeSurfaces] = await Promise.all([
         actual.getRecipe('decompose'),
         actual.getRecipe('relate'),
@@ -31,8 +44,9 @@ export async function mapPrepare(config, _args = [], deps) {
         relate,
         extract_surfaces: extractSurfaces,
         decompose_surfaces: decomposeSurfaces,
-    });
+    }, inventory.status === 'written' ? inventory.path : undefined);
     process.stdout.write(`Map build request written to ${packet.project_root}/.unitbob/map-build/request.json\n`);
+    process.stdout.write(`${describeRouteInventory(inventory)}\n`);
     process.stdout.write(`Next: build BOTH lenses following the recipes in that request — the decompose map at ` +
         `${packet.output_path} (recipes.decompose, recipes.relate), and the surface map at ` +
         `${packet.surface_output_path} (recipes.extract_surfaces → ${packet.surfaces_path}, then ` +

package/dist/verbs/putMapBuild.js

@@ -1,5 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { readHostMapOutput, readMapBuildRequest, readSurfaceDocument, readSurfacesInventory, } from "../files/mapBuild.js";
+import { enterUrl } from "../links.js";
+import { inventoryProblems } from "../surfaces/routeInventory.js";
 import { Wire } from "../wire.js";
 export async function putMapBuild(config, _args = [], deps) {
     const packet = readMapBuildRequest(config.projectRoot);
@@ -10,6 +13,8 @@ export async function putMapBuild(config, _args = [], deps) {
     const mapDocument = readHostMapOutput(packet.output_path);
     const surfaces = readSurfacesInventory(packet.surfaces_path);
     const surfaceDocument = readSurfaceDocument(packet.surface_output_path);
+    refuseAlteredAddresses(packet.route_inventory_path, surfaces);
+    refuseSurfacesWithoutStorage(config.projectRoot, surfaces);
     const actual = {
         putMapBuild: (payload) => new Wire(config).putMapBuild(payload),
         ...deps,
@@ -22,5 +27,67 @@ export async function putMapBuild(config, _args = [], deps) {
     });
     process.stdout.write(`Map uploaded (map ${result.map_digest}, surface ${result.surface_digest}, graph ${result.graph_digest}) ` +
         `${result.reused ? 'reused' : 'created'} version ${result.map_version_id}.\n` +
-        `${result.map_url}\n`);
+        // The server hands back a clean address; the token is added here, at the
+        // moment of printing, so it never rides in a response body or a server log.
+        `${enterUrl(config, result.map_url)}\n`);
+}
+// Spec 32-7. Where the router could be asked, the addresses are a fact, and the
+// only thing standing between that fact and the map was an instruction in a
+// prompt — the same kind of instruction that already said "never spell an id
+// yourself" while a2time's map grew an address no router had. So the two files
+// are compared here, where both are still on this machine, and a mismatch stops
+// the upload with the ids named.
+//
+// This decides nothing about the map: it does not group, rank or judge a single
+// surface. It compares the answer with the request, which is the line spec 32-6
+// drew for `validate-build`, and refuses to send an answer that contradicts a
+// fact we already hold.
+function refuseAlteredAddresses(inventoryPath, surfaces) {
+    if (!inventoryPath)
+        return; // no router was asked; there is nothing to hold the answer to
+    if (!existsSync(inventoryPath)) {
+        throw new Error(`${inventoryPath} is named by the build request but is not there. Run \`unitbob map-prepare\` ` +
+            'again so the addresses come from the router, then rebuild the surface map.');
+    }
+    let inventory = null;
+    try {
+        inventory = JSON.parse(readFileSync(inventoryPath, 'utf8'));
+    }
+    catch {
+        inventory = null; // unreadable is itself a problem, and reads as one below
+    }
+    const problems = inventoryProblems(inventory, surfaces);
+    if (problems.length === 0)
+        return;
+    throw new Error(`The routes in surfaces.json do not match the ones this project's router declared, so nothing ` +
+        `was uploaded and the previous map stays current:\n- ${problems.join('\n- ')}`);
+}
+// Spec 32-7, Task 1.11. The addresses are now a command's answer rather than the
+// model's, and the recipe turns that answer into `surfaces.json` with one line
+// of `node -e`. Ten seconds in, the file is full of routes and looks like a
+// finished inventory — and the surfaces no router declares (`table`, `job`,
+// `external`) are found only if the model keeps reading after that point.
+//
+// The spec spent five rounds establishing that "the prompt says so" is not a
+// guarantee, then left exactly this one resting on it. So the cheapest half is
+// checked here: a project that keeps a schema on disk and reports not a single
+// table did not finish the file. Jobs and externals a project may genuinely not
+// have, and no honest check exists for them; tables it either stores or does not.
+//
+// A refusal, not a warning — the same standing as an altered address above, and
+// for the same reason: an inventory missing every table sails through the rest
+// of the pipeline agreeing with itself.
+function refuseSurfacesWithoutStorage(projectRoot, surfaces) {
+    const schema = ['db/schema.rb', 'db/structure.sql'].find((file) => existsSync(join(projectRoot, ...file.split('/'))));
+    if (!schema)
+        return; // nothing on disk says this project stores anything
+    const list = surfaces?.surfaces;
+    if (!Array.isArray(list))
+        return; // shape is the host's complaint to make, not ours
+    if (list.some((surface) => surface?.kind === 'table'))
+        return;
+    throw new Error(`surfaces.json declares no \`table\` surface, but this project has ${schema}, so nothing was ` +
+        'uploaded and the previous map stays current. The routes are only one of the four kinds: read ' +
+        'the schema for `table` surfaces, and the source for `job` and `external` ones, then run ' +
+        '`unitbob put-map-build` again.');
 }