@fangorn-network/westmarch 0.0.1-dev → 0.0.2-dev

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangorn-network/westmarch",
-  "version": "0.0.1-dev",
+  "version": "0.0.2-dev",
   "description": "Publisher and consumer surfaces for a Fangorn app: shape a graph, publish it, read it back as a searchable, agent-drivable catalog",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,7 @@
     "./rank": "./consume/rank.js",
     "./apps": "./consume/apps.js",
     "./agent-card": "./publish/agent-card.js",
+    "./view": "./publish/view.js",
     "./roles": "./consume/roles.js",
     "./directory": "./consume/directory.js",
     "./taste": "./consume/taste.js",
@@ -29,10 +30,11 @@
     "./demand": "./publish/demand.js",
     "./steam": "./consume/steam.js",
     "./tools": "./consume/tools.js",
+    "./x402": "./consume/x402.js",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "test": "node publish/terms.js && node publish/reactions.js && node publish/cohort.js && node publish/vault.js && node publish/graph.js && node publish/envelope.js && node publish/demand.js && node publish/settle.js && node publish/manifest.js && node publish/agent-card.js && node publish/cli.js --selfcheck && node publish/enrich.js && node consume/embed.js && node consume/rank.js && node consume/apps.js && node consume/mcp.js --selfcheck && node consume/roles.js && node consume/shard.js && node consume/directory.js && node consume/taste.js && node consume/steam.js && node consume/taste-doc.js && node consume/corpora.js && node consume/ui.js && node consume/lint.js && node consume/tools.js",
+    "test": "node publish/terms.js && node publish/reactions.js && node publish/cohort.js && node publish/vault.js && node publish/graph.js && node publish/envelope.js && node publish/demand.js && node publish/settle.js && node publish/manifest.js && node publish/agent-card.js && node publish/view.js && node publish/ship.js --selfcheck && node publish/cli.js --selfcheck && node publish/enrich.js && node consume/embed.js && node consume/rank.js && node consume/apps.js && node consume/mcp.js --selfcheck && node consume/roles.js && node consume/shard.js && node consume/directory.js && node consume/taste.js && node consume/steam.js && node consume/taste-doc.js && node consume/corpora.js && node consume/ui.js && node consume/lint.js && node consume/tools.js && node consume/x402.js && node site/feed.js",
     "lint": "node consume/lint.js"
   },
   "peerDependencies": {
@@ -54,12 +56,17 @@
   },
   "bin": {
     "westmarch-publish": "./publish/cli.js",
-    "fangorn-mcp": "./consume/mcp.js"
+    "fangorn-mcp": "./consume/mcp.js",
+    "westmarch-view": "./publish/view-cli.js",
+    "westmarch-ship": "./publish/ship.js"
   },
   "files": [
     "consume",
     "publish",
-    "docs/app-to-agent.md"
+    "docs/app-to-agent.md",
+    "site/agent.js",
+    "site/dist",
+    "site/feed.js"
   ],
   "engines": {
     "node": ">=20"

package/publish/agent-card.js

@@ -73,7 +73,7 @@ export function agentCard({ name, description, url, version = "0.0.0", tools = [
 
 /** The params `discoverApp` reads, validated the same way it validates them.
  *  A malformed card should fail the build, not the first reader. */
-export function fangornExtension({ app, fromBlock, namespaces = [], views = [], config = FangornConfig }) {
+export function fangornExtension({ app, fromBlock, namespaces = [], views = [], paid, config = FangornConfig }) {
     if (!app) throw new Error("fangorn.app is required");
     const id = HEX32.test(app) ? app : hashAppId(app);
     const from = String(fromBlock ?? "");
@@ -83,6 +83,14 @@ export function fangornExtension({ app, fromBlock, namespaces = [], views = [],
         const u = new URL(v);   // throws on garbage
         if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`fangorn.views: not http(s): ${v}`);
     }
+    // `paid`: records sold over x402. `url` has an `{id}` for the record's id; `price` is in
+    // the token's base units. Readers only offer to buy; the 402 itself is the quote.
+    if (paid) {
+        const u = new URL(paid.url.replace("{id}", "x"));
+        if (!/^https?:$/.test(u.protocol) || !paid.url.includes("{id}")) throw new Error(`fangorn.paid.url must be http(s) with {id}: ${paid.url}`);
+        if (!/^\d+$/.test(String(paid.price))) throw new Error(`fangorn.paid.price must be base units, got ${paid.price}`);
+        if (!/^0x[0-9a-fA-F]{40}$/.test(paid.asset ?? "")) throw new Error(`fangorn.paid.asset must be a token address`);
+    }
     return {
         uri: FANGORN_APP_EXTENSION,
         description: "The Fangorn app this agent fronts.",
@@ -92,12 +100,14 @@ export function fangornExtension({ app, fromBlock, namespaces = [], views = [],
             appRegistry: config.appRegistryContractAddress,
             dataRegistry: config.dataRegistryContractAddress,
             appId: id, fromBlock: from, namespaces, views,
+            ...(paid ? { paid: { url: paid.url, price: String(paid.price), asset: paid.asset, network: paid.network,
+                                 symbol: paid.symbol ?? "USDC", decimals: paid.decimals ?? 6, description: paid.description ?? "" } } : {}),
         },
     };
 }
 
 // ── self-check: `node publish/agent-card.js` ────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/agent-card.js")) {
     const eq = (a, b, m) => { if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${m}: ${JSON.stringify(a)} != ${JSON.stringify(b)}`); };
     const throws = (f, re, m) => { try { f(); } catch (e) { if (re.test(e.message)) return; throw e; } throw new Error(`must throw: ${m}`); };
 

package/publish/cohort.js

@@ -247,7 +247,7 @@ export function readout(total, cohort, { minSupport = MIN_SUPPORT } = {}) {
 }
 
 // ── self-check: `node publish/cohort.js` ──────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/cohort.js")) {
     const vec = (a, b) => { const v = new Float32Array(STAT_DIM); v[0] = a; v[1] = b; return v; };
     const log = (n, seed) => Array.from({ length: n }, (_, i) => ({
         id: `row-${seed}-${i}`, corpus: "films", reaction: i % 4 === 3 ? "skip" : "like",

package/publish/demand.js

@@ -383,7 +383,7 @@ export function brief(rep, { title = "demand" } = {}) {
 }
 
 // ── self-check: `node publish/demand.js` ────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/demand.js")) {
     const { keypair, statistics, contribute, aggregate, readout } = await import("./cohort.js");
 
     // A shelf with two genuine regions and a hole between them. 128 dims so the

package/publish/enrich.js

@@ -155,7 +155,7 @@ export function enrichText({ name, path, desc, mime, abs = null }) {
 // in the same browser that already runs the embedder at publish time.
 
 // ── self-check: `node server/enrich.js` — no files, no model ──────────────────
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/enrich.js")) {
     const { deflateSync } = await import("node:zlib");
     const eq = (got, want, msg) => { if (got !== want) throw new Error(`${msg}: got ${JSON.stringify(got)}`); };
 

package/publish/envelope.js

@@ -157,7 +157,7 @@ export async function deleteResource({ workerUrl, uploadToken, resourceId, chunk
 // every resourceId ever minted by fangorn.tv is derived by this function, and a
 // change here that shifts one byte makes ciphertext already in R2 unreachable from
 // the resource anyone paid for. If this fails, the extraction broke money.
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/envelope.js")) {
     const owner = `0x${"11".repeat(20)}`;
     const uid = "Show/S1/a.mp4";
 

package/publish/graph.js

@@ -183,7 +183,7 @@ export function treeFromGraph(contents) {
 // `process` doesn't exist in the browser, and consumers import nest() from here
 // to build a viewer tree — so this guard has to survive being evaluated by a
 // browser.
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/graph.js")) {
     // sond3r's pinned names, which is also the case with every option exercised.
     const SOND3R = {
         file: "video",

package/publish/manifest.js

@@ -90,7 +90,7 @@ export function manifestFromTree(files, { defaultPrice = "1000", newUid: uid = n
 }
 
 // ── self-check: `node publish/manifest.js` ───────────────────────────────────
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/manifest.js")) {
     const assert = (c, m) => { if (!c) throw new Error(m); };
 
     // PINNED. sond3r's manifests are already in R2 under this exact key; if this

package/publish/reactions.js

@@ -53,7 +53,9 @@
 import { packVec } from "../consume/embed.js";
 import { lineage } from "./terms.js";
 
-export const COVERAGE_K = 8;
+// 32, not 8: on Kingsfoil the top 3 of 23 views held 92% of the true top 10 with 32
+// centroids and 86% with 8, and 8 missed whole topics (ALS → neurology).
+export const COVERAGE_K = 32;
 export const COVERAGE_DIM = 128;
 /** Fewest reactions that may stand behind one published centroid. */
 export const MIN_PER_CENTROID = 8;
@@ -235,7 +237,7 @@ export function reactionCorpus(events = [], {
 }
 
 // ── self-check: `node publish/reactions.js` ────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/reactions.js")) {
     const { splitPayment } = await import("./terms.js");
     const A = (n) => `0x${String(n).repeat(40).slice(0, 40)}`;
     const vec = (a, b) => { const v = new Float32Array(256); v[0] = a; v[1] = b; return v; };

package/publish/settle.js

@@ -70,7 +70,7 @@ export async function encryptAndUpload({ file, resourceId, workerUrl, uploadToke
 // under test here is the ENCRYPTOR: chunk addressing, the AAD index binding, the
 // ragged tail, and that pack/unpack round trip. An app's full publisher→buyer
 // round trip belongs in that app, against its own buyer.
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/settle.js")) {
     const { writeFileSync, rmSync } = await import("node:fs");
     const { unseal } = await import("@fangorn-network/sdk");
     const { x25519 } = await import("@noble/curves/ed25519");

package/publish/ship.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+// westmarch-ship: one config, one command, a live Fangorn app.
+//
+//   westmarch-ship app.json [--no-crawl] [--no-deploy] [--dry-run]
+//
+// Every step checks the chain (or Cloudflare) first and only acts on a difference, so
+// re-running is how you update: new data, a changed schema, a new source, a moved site.
+//
+//   1. claim the app (first run only; the claim block becomes the card's fromBlock)
+//   2. join it as a publisher
+//   3. commit the schema, if the one on chain differs from app.json's `types`
+//   4. run each source, which crawls and publishes straight into the app
+//   5. westmarch-view: the app's commits → site/view
+//   6. the stock page, the card and _headers → site/
+//   7. deploy to Cloudflare Pages
+//   8. register the ERC-8004 agent and bind the card, if the chain points elsewhere
+//
+// Chain writes go through the `fangorn` CLI (its configured wallet signs, and
+// `fangorn wallet` shows which). Reads go through the SDK. State lives in `.ship/` next
+// to app.json: the site, the view (its own state, see view.js) and a small state.json.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const USDC = { "arbitrum-sepolia": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", arbitrum: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+               "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", base: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" };
+const STOCK = join(HERE, "../site/dist");
+const log = (s) => console.error(`[ship] ${s}`);
+
+// ── config ────────────────────────────────────────────────────────────────────
+//
+// {
+//   "app": "quorum", "name": "Quorum", "description": "…", "tags": ["civic"],
+//   "site": { "project": "quorum", "account": "<cloudflare account id>" },
+//   "types": { "<tag>": { "description": "…", "role_map": {…}, "presentation": {…} } },
+//   "relations": [{ "rel": "…", "from": "<tag>", "to": "<tag>" }],
+//   "sources": [{ "namespace": "…", "cwd": "…", "command": ["python", "-m", "…", …] }],
+//   "fangorn": "fangorn",     // the CLI that signs; e.g. "node ~/fangorn/fangorn/lib/cli/cli.js"
+//   "paid": { "price": "0.01", "network": "arbitrum-sepolia", "description": "…" }
+// }
+//
+// `paid` sells per-record detail over x402 (site/paid-worker.js): each source that names a
+// `paid_dir` gets `--paid-dir` and writes one JSON per record there; they are deployed
+// behind the worker, and the price goes in the card. The payee is the app owner unless
+// `paid.payTo` says otherwise; the asset is USDC on `paid.network` unless `paid.asset` does.
+//
+// A source is any command that publishes into `--namespace` when given `--publish`:
+// quickbeam's scraper harness does, so every quickbeam Source is a source here. It runs
+// with FANGORN_APP_ID set, so it publishes into this app whatever the CLI's saved app is.
+
+/** `{field}`, `{field|slug}` and `{field|lower}` from a row; an argv item that is exactly
+ *  `{args...}` splices the row's own `args` array (for flags only some rows need). */
+export function fill(template, row) {
+    const one = (s) => s.replace(/\{(\w+)(?:\|(slug|lower))?\}/g, (_, k, f) => {
+        if (row[k] == null) throw new Error(`template needs "${k}", which ${JSON.stringify(row)} lacks`);
+        const v = String(row[k]);
+        return f === "slug" ? v.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") : f === "lower" ? v.toLowerCase() : v;
+    });
+    return Array.isArray(template) ? template.flatMap((t) => (t === "{args...}" ? row.args ?? [] : [one(t)])) : one(template);
+}
+
+/** A source with `each: "towns.json"` is a template: one source per row of that file
+ *  (rows with `"skip": true` are left out). Adding a town is adding a row. */
+export function expandSources(sources, base) {
+    return sources.flatMap((s) => {
+        if (!s.each) return [s];
+        const rows = JSON.parse(readFileSync(resolve(base, s.each), "utf8")).filter((r) => !r.skip);
+        return rows.map((r) => ({ ...s, each: undefined, row: r, namespace: fill(s.namespace, r), command: fill(s.command, r),
+                                  ...(s.paid_dir ? { paid_dir: fill(s.paid_dir, r) } : {}) }));
+    });
+}
+
+export function loadConfig(path) {
+    const c = JSON.parse(readFileSync(path, "utf8"));
+    c.sources = expandSources(c.sources ?? [], dirname(resolve(path)));
+    for (const k of ["app", "name", "description", "types", "sources", "site"])
+        if (!c[k]) throw new Error(`${path}: missing "${k}"`);
+    if (!c.site.project) throw new Error(`${path}: site.project names the Cloudflare Pages project`);
+    for (const s of c.sources) if (!s.namespace || !Array.isArray(s.command))
+        throw new Error(`${path}: each source needs a namespace and a command (an argv array)`);
+    return { relations: [], tags: [], ...c };
+}
+
+/** The schema commit for `types` + `relations`: one fangorn.type.v1 vertex per type,
+ *  one edge per allowed relation. */
+export function schemaGraph(types, relations = []) {
+    const id = (tag) => `type:${tag}`;
+    return {
+        vertices: Object.entries(types).map(([tag, t]) => ({ id: id(tag), tag: "fangorn.type.v1", payload: {
+            tag, description: t.description ?? "", role_map: t.role_map ?? {}, presentation: t.presentation ?? {} } })),
+        edges: relations.map((r) => ({ rel: r.rel, from: id(r.from), to: id(r.to) })),
+    };
+}
+
+/** Keys sorted at every depth: the chain stores dag-cbor, whose maps come back in
+ *  canonical key order, not the order app.json wrote them in. */
+const stable = (v) => Array.isArray(v) ? v.map(stable)
+    : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, stable(v[k])])) : v;
+
+/** Same shape parseSchema returns, so a config and the chain compare directly. */
+const canonical = (types, relations = []) => JSON.stringify(stable({
+    types: Object.fromEntries(Object.entries(types).sort(([a], [b]) => a.localeCompare(b))
+        .map(([tag, t]) => [tag, { description: t.description ?? "", role_map: t.role_map ?? {}, presentation: t.presentation ?? {} }])),
+    relations: [...relations].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+}));
+
+// ── processes ─────────────────────────────────────────────────────────────────
+
+/** `${VAR}` and `${VAR:-default}` from the environment, so one app.json runs on a laptop
+ *  and in CI (e.g. `"${PYTHON:-python3}"`). */
+export const expandEnv = (s) => s.replace(/\$\{(\w+)(?::-([^}]*))?\}/g, (_, k, d) => process.env[k] ?? d ?? "");
+
+function run(cmd, args, { cwd, env, capture = false, dry = false } = {}) {
+    cmd = expandEnv(cmd); args = args.map(expandEnv);
+    log(`$ ${[cmd, ...args].join(" ")}${cwd ? `   (in ${cwd})` : ""}`);
+    if (dry) return "";
+    const r = spawnSync(cmd, args, { cwd, env: { ...process.env, ...env }, encoding: "utf8",
+        stdio: capture ? ["ignore", "pipe", "inherit"] : "inherit" });
+    if (r.status !== 0) throw new Error(`${cmd} ${args[0]} failed (exit ${r.status})`);
+    return r.stdout ?? "";
+}
+const expand = (p) => p.replace(/^~(?=\/|$)/, homedir());
+const cliArgv = (cfg) => expandEnv(process.env.FANGORN_CLI ?? cfg.fangorn ?? "fangorn").split(/\s+/).filter(Boolean).map(expand);
+let CLI = ["fangorn"];
+const fangornCli = (app, args, opts = {}) => run(CLI[0], [...CLI.slice(1), "--app", app, ...args], { capture: true, ...opts });
+
+/** The CLI must be the SDK version westmarch reads with. A different one signs against
+ *  another deployment's contracts: its claim and commits land where nothing here looks,
+ *  and every read says the app is unclaimed. (It happened: a global 2026.08.18-dev CLI
+ *  claimed and published onto the previous registries.) */
+function assertSameDeployment(cli) {
+    const which = (c) => spawnSync("sh", ["-c", `command -v ${c}`], { encoding: "utf8" }).stdout.trim();
+    const script = cli.length > 1 && /(^|\/)node$/.test(cli[0]) ? cli[1] : which(cli[0]);
+    if (!script) throw new Error(`fangorn CLI not found: ${cli.join(" ")}`);
+    let d = dirname(realpathSync(script)), cliVersion = null;
+    for (; d !== dirname(d); d = dirname(d)) {
+        const pj = join(d, "package.json");
+        if (existsSync(pj)) { const p = JSON.parse(readFileSync(pj, "utf8")); if (p.name === "@fangorn-network/sdk") { cliVersion = p.version; break; } }
+    }
+    const ours = createRequire(import.meta.url)("@fangorn-network/sdk/package.json").version;
+    if (cliVersion !== ours) throw new Error(`the fangorn CLI (${cli.join(" ")}) is SDK ${cliVersion ?? "?"}, westmarch reads with ${ours}: ` +
+        "they talk to different contracts. Point app.json's \"fangorn\" at a matching CLI.");
+}
+
+// ── the steps ─────────────────────────────────────────────────────────────────
+
+export async function ship(configPath, { crawl = true, deploy = true, dry = false, replace = false } = {}) {
+    const cfg = loadConfig(configPath);
+    CLI = cliArgv(cfg);
+    assertSameDeployment(CLI);
+    const base = dirname(resolve(configPath));
+    const dir = join(base, ".ship");
+    const statePath = join(dir, "state.json");
+    mkdirSync(dir, { recursive: true });
+    const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, "utf8")) : {};
+    const save = () => !dry && writeFileSync(statePath, JSON.stringify(state, null, 1));
+
+    const [{ FangornConfig }, { createPublicClient, http }, { env }, view, card] = await Promise.all([
+        import("@fangorn-network/sdk"), import("viem"),
+        import("@huggingface/transformers"), import("./view.js"), import("./agent-card.js"),
+    ]);
+    env.cacheDir = `${homedir()}/.cache/fangorn-mcp/models`;
+    const fangorn = await view.readOnlyFangorn();
+    fangorn.setAppId(cfg.app);
+    const appId = fangorn.getAppId();
+    const registry = fangorn.getAppRegistry();
+
+    // 1. claim
+    const me = (fangornCli(cfg.app, ["wallet"]).match(/Address:\s+(0x[0-9a-fA-F]{40})/) ?? [])[1]?.toLowerCase();
+    if (!me) throw new Error("`fangorn wallet` shows no address; run `fangorn init`");
+    let owner = (await registry.getAppOwner()).toLowerCase();
+    if (/^0x0+$/.test(owner)) {
+        const block = await createPublicClient({ transport: http(FangornConfig.rpcUrl) }).getBlockNumber();
+        state.fromBlock = String(block);
+        log(`${cfg.app} is unclaimed; claiming it for ${me} (fromBlock ${block})`);
+        fangornCli(cfg.app, ["app", "claim"], { dry });
+        owner = me;
+        save();
+    } else if (owner !== me) {
+        throw new Error(`${cfg.app} belongs to ${owner}, not this wallet (${me}); pick another name`);
+    }
+    state.fromBlock ??= String(cfg.fromBlock ?? 0);
+    log(`app ${cfg.app} = ${appId}, owner ${owner}, fromBlock ${state.fromBlock}`);
+
+    // 2. join
+    // Both registries: claiming joins the owner to the app, but commits also need the
+    // wallet's global DataRegistry standing, or every push reverts NotRegistered().
+    const info = fangornCli(cfg.app, ["app", "info"]);
+    if (!/DataRegistry:\s+registered/.test(info) || !/This app:\s+joined/.test(info)) fangornCli(cfg.app, ["register"], { dry });
+
+    // 3. schema
+    let onChain = null;
+    try { onChain = view.parseSchema((await fangorn.readNamespace(owner, view.SCHEMA_NAMESPACE)).contents); } catch { /* none yet */ }
+    if (!onChain || canonical(onChain.types, onChain.relations) !== canonical(cfg.types, cfg.relations)) {
+        const sdir = join(dir, "schema");
+        mkdirSync(sdir, { recursive: true });
+        writeFileSync(join(sdir, "graph.json"), JSON.stringify(schemaGraph(cfg.types, cfg.relations), null, 1));
+        log(`schema ${onChain ? "changed" : "is new"}: committing ${Object.keys(cfg.types).join(", ")}`);
+        fangornCli(cfg.app, ["repo", "init", view.SCHEMA_NAMESPACE], { cwd: sdir, dry });
+        fangornCli(cfg.app, ["commit", "graph.json", "-m", "schema", "--replace"], { cwd: sdir, dry });
+        fangornCli(cfg.app, ["push"], { cwd: sdir, dry });
+    } else log("schema unchanged");
+
+    // 4. sources: crawl + publish straight into the app
+    if (crawl) for (const s of cfg.sources) {
+        const cwd = s.cwd ? resolve(base, s.cwd.replace(/^~/, homedir())) : base;
+        const paidArgs = cfg.paid && s.paid_dir ? ["--paid-dir", resolve(cwd, s.paid_dir)] : [];
+        run(s.command[0], [...s.command.slice(1), ...paidArgs, ...(replace ? ["--replace"] : []),
+                           "--publish", "--namespace", s.namespace, "--fangorn-bin", CLI.join(" ")],
+            { cwd, env: { FANGORN_APP_ID: cfg.app }, dry });
+    }
+
+    // 5. the view. Its files are its state: on a fresh machine (CI), start from the deployed
+    // copy rather than re-embed everything. shard.js checks each shard against its manifest.
+    const site = join(dir, "site");
+    if (!existsSync(join(site, "view/cdn/catalog")) && state.url && !dry) await mirrorView(`${state.url}/view`, join(site, "view"));
+    const namespaces = [...new Set(cfg.sources.map((s) => s.namespace))];
+    const report = dry ? {} : await view.publishView({ fangorn, app: cfg.app, namespaces, out: join(site, "view"),
+        fromBlock: BigInt(state.fromBlock), log });
+
+    // 6. the page, the card, the headers
+    if (!existsSync(join(STOCK, "index.html"))) throw new Error(`no stock page at ${STOCK}; run \`npx vite build\` in westmarch/site`);
+    mkdirSync(site, { recursive: true });
+    for (const f of readdirSync(site, { withFileTypes: true })) if (f.name !== "view" && f.name !== "_paid") rmSync(join(site, f.name), { recursive: true, force: true });
+    cpSync(STOCK, site, { recursive: true });
+    const url = deploy && !dry ? pagesUrl(cfg) : state.url ?? `https://${cfg.site.project}.pages.dev`;
+    // Paid records: every source's paid_dir → site/_paid (served only through the worker).
+    let paid = null;
+    if (cfg.paid) {
+        const network = cfg.paid.network ?? "arbitrum-sepolia";
+        const asset = cfg.paid.asset ?? USDC[network];
+        if (!asset) throw new Error(`paid.network ${network}: no default USDC address; set paid.asset`);
+        const decimals = cfg.paid.decimals ?? 6;
+        const [whole, frac = ""] = String(cfg.paid.price).split(".");
+        const price = (BigInt(whole) * 10n ** BigInt(decimals) + BigInt((frac + "0".repeat(decimals)).slice(0, decimals) || "0")).toString();
+        paid = { url: `${url}/paid/{id}`, price, asset, network, decimals, symbol: cfg.paid.symbol ?? "USDC", description: cfg.paid.description ?? "" };
+        // Only records a live row vouches for (its committed paid_sha256): one left over from
+        // an item since removed or re-extracted is not for sale, whatever is still on disk.
+        rmSync(join(site, "_paid"), { recursive: true, force: true });
+        mkdirSync(join(site, "_paid"), { recursive: true });
+        const vouched = new Set(view.liveFields(join(site, "view")).map((f) => f.paid_sha256).filter(Boolean));
+        let n = 0;
+        for (const s of cfg.sources) {
+            const d = s.paid_dir && resolve(s.cwd ? resolve(base, s.cwd.replace(/^~/, homedir())) : base, s.paid_dir);
+            if (d && existsSync(d)) for (const f of readdirSync(d)) {
+                const bytes = readFileSync(join(d, f));
+                if (!vouched.has(createHash("sha256").update(bytes).digest("hex"))) continue;
+                writeFileSync(join(site, "_paid", f), bytes); n++;
+            }
+        }
+        const worker = readFileSync(join(HERE, "../site/paid-worker.js"), "utf8").replace(/\/\*CONFIG\*\/[\s\S]*?\/\*END\*\//, JSON.stringify({
+            price, network, asset, payTo: cfg.paid.payTo ?? owner, facilitator: cfg.paid.facilitator ?? "https://facilitator.payai.network",
+            name: cfg.paid.tokenName ?? "USD Coin", version: cfg.paid.tokenVersion ?? "2", description: paid.description }));
+        writeFileSync(join(site, "_worker.js"), worker);
+        log(`paid: ${n} record(s) at ${cfg.paid.price} ${paid.symbol} on ${network}, to ${cfg.paid.payTo ?? owner}`);
+    }
+    const { registerAgent } = await import("../site/agent.js");
+    const agentCard = card.agentCard({
+        name: cfg.name, description: cfg.description, url: `${url}/`, version: new Date().toISOString().slice(0, 10),
+        tools: await card.captureTools(() => registerAgent({})), tags: cfg.tags,
+        fangorn: { app: cfg.app, fromBlock: state.fromBlock, namespaces, views: [`${url}/view`], ...(paid ? { paid } : {}) },
+    });
+    mkdirSync(join(site, ".well-known"), { recursive: true });
+    writeFileSync(join(site, ".well-known/agent-card.json"), JSON.stringify(agentCard, null, 1));
+    const immutable = "  Cache-Control: public, max-age=31536000, immutable\n";
+    const domains = existsSync(join(site, "view/cdn/domains")) ? readdirSync(join(site, "view/cdn/domains")) : [];
+    writeFileSync(join(site, "_headers"),
+        "/.well-known/agent-card.json\n  Access-Control-Allow-Origin: *\n"
+        + "/view/*\n  Access-Control-Allow-Origin: *\n"
+        + `/assets/*\n${immutable}`
+        // An hour, not immutable: a shard is deleted when a record is retracted (see view.js).
+        + domains.map((d) => `/view/cdn/domains/${d}/shards/*\n  Cache-Control: public, max-age=3600\n`).join(""));
+
+    // 7. deploy
+    if (deploy) {
+        run("npx", ["wrangler", "pages", "deploy", site, "--project-name", cfg.site.project, "--branch", "main", "--commit-dirty=true"],
+            { env: cfg.site.account ? { CLOUDFLARE_ACCOUNT_ID: cfg.site.account } : {}, dry });
+        state.url = url;
+        save();
+    }
+
+    // 8. ERC-8004 + the binding
+    const cardUrl = `${url}/.well-known/agent-card.json`;
+    const bound = await registry.appAgentUri(appId).catch(() => "");
+    if (deploy && bound !== cardUrl) {
+        log(`binding ${cardUrl} (on chain: ${bound || "nothing"})`);
+        const out = dry ? "" : fangornCli(cfg.app, ["app", "agent", cardUrl]);
+        state.agentId = (out.match(/Agent ID:\s+(\S+)/) ?? [])[1] ?? state.agentId;
+        save();
+    } else if (deploy) log("card already bound");
+
+    const added = Object.values(report).reduce((n, r) => n + r.added, 0);
+    log(`done: ${url}  ·  card ${cardUrl}  ·  agent ${state.agentId ?? "(unchanged)"}  ·  +${added} records embedded`);
+    return { url, cardUrl, agentId: state.agentId, report };
+}
+
+/** Copy a deployed view (catalog, manifests, shards) to `dir`, so the next publish appends. */
+async function mirrorView(base, dir) {
+    const get = async (p) => { const r = await fetch(`${base}/${p}`); if (!r.ok) throw new Error(`${base}/${p}: HTTP ${r.status}`); return r; };
+    let catalog;
+    try { catalog = await (await get("cdn/catalog")).json(); } catch (e) { log(`no deployed view to start from (${e.message})`); return; }
+    const { createHash } = await import("node:crypto");
+    let files = 0;
+    for (const d of catalog.domains ?? []) {
+        const m = await (await get(`cdn/domains/${d.name}/manifest`)).json();
+        mkdirSync(join(dir, "cdn/domains", d.name, "shards"), { recursive: true });
+        writeFileSync(join(dir, "cdn/domains", d.name, "manifest"), JSON.stringify(m, null, 1));
+        for (const s of m.shards ?? []) {
+            const buf = Buffer.from(await (await get(`cdn/domains/${d.name}/shards/${s.file}`)).arrayBuffer());
+            if (s.sha256 && createHash("sha256").update(buf).digest("hex") !== s.sha256) throw new Error(`${s.file} does not match its manifest`);
+            writeFileSync(join(dir, "cdn/domains", d.name, "shards", s.file), buf);
+            files++;
+        }
+    }
+    writeFileSync(join(dir, "cdn/catalog"), JSON.stringify(catalog, null, 1));
+    log(`started from the deployed view: ${catalog.domains?.length ?? 0} domain(s), ${files} shard(s)`);
+}
+
+/** The project's pages.dev URL, creating the project on first use. Pages appends a
+ *  suffix when the name is taken elsewhere, so the URL is read back, never assumed. */
+function pagesUrl(cfg) {
+    const env = cfg.site.account ? { CLOUDFLARE_ACCOUNT_ID: cfg.site.account } : {};
+    const find = () => {
+        const out = run("npx", ["wrangler", "pages", "project", "list"], { env, capture: true });
+        const row = out.split("\n").find((l) => l.split("│")[1]?.trim() === cfg.site.project);
+        const host = row?.match(/([a-z0-9-]+\.pages\.dev)/)?.[1];
+        return host ? `https://${host}` : null;
+    };
+    let url = find();
+    if (!url) {
+        run("npx", ["wrangler", "pages", "project", "create", cfg.site.project, "--production-branch", "main"], { env });
+        url = find();
+    }
+    if (!url) throw new Error(`could not read the pages.dev URL of project ${cfg.site.project}`);
+    return url;
+}
+
+// ── cli ───────────────────────────────────────────────────────────────────────
+if (process.argv[1]?.endsWith("ship.js") || process.argv[1]?.endsWith("westmarch-ship")) {
+    if (process.argv[2] === "--selfcheck") {
+        // The schema as committed, read back the way the chain returns it, must compare
+        // equal to the config, or every run re-commits an unchanged schema.
+        const { parseSchema } = await import("./view.js");
+        const types = { "t.v1": { description: "d", role_map: { title: "name", text: ["body"] }, presentation: { externalUrl: { "t.v1": "{url}" } } },
+                        "u.v1": { description: "e", role_map: { title: "label" } } };
+        const relations = [{ rel: "cites", from: "t.v1", to: "u.v1" }];
+        const g = schemaGraph(types, relations);
+        // Keys reversed at every depth, as a canonical (sorted) encoding hands them back.
+        const reverse = (v) => Array.isArray(v) ? v.map(reverse)
+            : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).reverse().map((k) => [k, reverse(v[k])])) : v;
+        const readBack = parseSchema({
+            vertices: g.vertices.map((v) => ({ cid: `cid-${v.id}`, schemaId: v.tag, payload: reverse(v.payload) })),
+            edges: g.edges.map((e) => ({ relation: e.rel, sourceCid: `cid-${e.from}`, targetCid: `cid-${e.to}` })),
+        });
+        if (canonical(readBack.types, readBack.relations) !== canonical(types, relations)) throw new Error("schema does not round-trip");
+        if (canonical(readBack.types, readBack.relations) === canonical({ ...types, "v.v1": {} }, relations)) throw new Error("a new type must count as a change");
+        const row = { city: "Wisconsin Rapids", state: "WI", site: "https://x", args: ["--archive-page", "/569/A"] };
+        const cmd = fill(["py", "--site", "{site}", "--city", "{city}", "{args...}", "--ns", "us-{state|lower}-{city|slug}"], row);
+        if (JSON.stringify(cmd) !== JSON.stringify(["py", "--site", "https://x", "--city", "Wisconsin Rapids", "--archive-page", "/569/A", "--ns", "us-wi-wisconsin-rapids"]))
+            throw new Error(`template fill: ${JSON.stringify(cmd)}`);
+        console.log("ship.js self-check ok — a committed schema reads back equal to its config, a new type counts as a change, and a source template fills per row");
+        process.exit(0);
+    }
+    const [path, ...flags] = process.argv.slice(2);
+    if (!path || flags.includes("--help")) {
+        console.error("usage: westmarch-ship app.json [--no-crawl] [--no-deploy] [--dry-run] [--replace]");
+        process.exit(path ? 0 : 2);
+    }
+    await ship(path, { crawl: !flags.includes("--no-crawl"), deploy: !flags.includes("--no-deploy"), dry: flags.includes("--dry-run"),
+                       replace: flags.includes("--replace") })
+        .catch((e) => { console.error(`[ship] ✗ ${e.message}`); process.exit(1); });
+}

package/publish/terms.js

@@ -137,7 +137,7 @@ export function splitPayment(amount, { terms, publisher, lineage: up = [] } = {}
 export const label = (base, currency = "USDC") => `${(Number(base) / 1e6).toFixed(2)} ${currency}`;
 
 // ── self-check: `node publish/terms.js` ────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/terms.js")) {
     const A = "0x" + "a".repeat(40);   // app owner
     const P = "0x" + "b".repeat(40);   // publisher
     const S1 = "0x" + "c".repeat(40);  // a source

package/publish/vault.js

@@ -105,7 +105,7 @@ export function tasteFrom(vertices = []) {
 }
 
 // ── self-check: `node publish/vault.js` ───────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/vault.js")) {
     const { privateKeyToAccount } = await import("viem/accounts");
     const KEY_A = `0x${"11".repeat(32)}`, KEY_B = `0x${"22".repeat(32)}`;
     // A "machine": a fresh client over the same key, holding no state at all.

package/publish/view-cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// westmarch-view: publish an app's committed data as a view (see view.js).
+//
+//   westmarch-view --app my-app --namespace my-app --out site/view [--from-block N] [--rebake]
+//
+// Reads only; needs no key. Deploy <out> with the site, and put its URL in the card's
+// `views`. Run it after every push, by hand, in CI, or from an agent.
+
+import { homedir } from "node:os";
+
+const flags = { namespace: [] };
+for (let i = 2; i < process.argv.length; i++) {
+    const a = process.argv[i];
+    const m = /^--([^=]+)(?:=(.*))?$/.exec(a);
+    if (!m) { console.error(`unexpected argument: ${a}`); process.exit(2); }
+    const v = m[2] ?? (["rebake", "help"].includes(m[1]) ? true : process.argv[++i]);
+    if (m[1] === "namespace") flags.namespace.push(v); else flags[m[1]] = v;
+}
+if (flags.help || !flags.app || !flags.namespace.length || !flags.out) {
+    console.error("usage: westmarch-view --app <name|0xid> --namespace <ns> [--namespace …] --out <dir> [--from-block N] [--rebake]");
+    process.exit(flags.help ? 0 : 2);
+}
+
+const [{ env }, { publishView, readOnlyFangorn }] = await Promise.all([
+    import("@huggingface/transformers"), import("./view.js"),
+]);
+// Shared with fangorn-mcp, so a machine downloads the model once.
+env.cacheDir = `${homedir()}/.cache/fangorn-mcp/models`;
+const fangorn = await readOnlyFangorn();
+
+const t0 = Date.now();
+const report = await publishView({
+    fangorn, app: flags.app, namespaces: flags.namespace, out: flags.out,
+    fromBlock: BigInt(flags["from-block"] ?? 0), rebake: !!flags.rebake,
+    log: (s) => console.error(s),
+});
+const sum = Object.values(report).reduce((a, r) => ({ added: a.added + r.added, removed: a.removed + r.removed }), { added: 0, removed: 0 });
+console.error(`done in ${((Date.now() - t0) / 1000).toFixed(1)}s: ${Object.keys(report).length} domain(s), +${sum.added} -${sum.removed}`);
+console.log(JSON.stringify(report));