@ouronet/talos-registry 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+## 1.1.0 — 2026-09-26
+
+**Ghost values: 40 account-shaped parameters stopped rendering as `"example"`.**
+
+Surface `67c0979111eb156b` → `7e59e59d4c5b7257`. No contract changed — the module hashes are
+identical, verified by `_registrylive.py` (12 modules, 0 drifted). What moved is the ghost
+dictionary, and the surface hash moves with it because the snapshot is the whole artefact.
+
+**Why it mattered.** A consumer previewing `ATS|C_Coil` got
+`No value found in table … for key: example` — true, and useless. The ghost dictionary keyed
+account values on `patron` / `executor` / `executee` / `account` / `buyer` / `receiver`, and the
+contracts' own vocabulary is much wider: `coiler`, `curler`, `brumator`, `constricter`, `culler`,
+`fueler`, `kickstarter`, `awaker`, `hibernator`, `wrapper`, `unwrapper`, `vester`, `redeemer`,
+`transmuter`, `donor`, `owner-konto`, `redemption-payer` … Every one fell through to the generic
+string ghost.
+
+**Not guessed.** The names were matched against `_executorplan.ACCT` — the curated account-vs-
+entity vocabulary the patron/executor canon sweep already maintains in the Pact repo, for exactly
+this distinction. Reusing it means there is one list, not two that drift.
+
+**227 slots are still generic, and deliberately so.** They are entity ids — `fvt-id`, `pool-id`,
+`score-id`, `collectable-id` — where a plausible-looking fake would produce a confident number for
+an entity nobody owns. An obviously-fake `"example"` is the better failure.
+
+### `params` on every spec
+
+Consumers merging real values into a preview need the **preview's** parameter names, and
+**410 of 423 previews take a different parameter list from their entrypoint** —
+`INFO_DPTF|Transfer` is `(patron id sender receiver transfer-amount)` against `C_Transfer`'s
+`(patron executor executee id transfer-amount method)`. Merging on the execution signature would
+put an account in an `id` slot on 97% of calls, silently, with a cost beside it.
+
+# @ouronet/talos-registry
+
+## 1.0.0
+
+First release. 423 entrypoints, 428 previews, surface `67c0979111eb156b`, generated against
+mainnet by `REPL/tools/_registry.py --probe`.
+
+* `buildCall` / `buildPreviewCall` / `buildGhostCall` — arguments by NAME, rendered in the
+  contract's declared order and checked against the deployed signature.
+* `planCall` / `explainCall` — preflight reads, capability reader, signers, transaction count
+  and the warnings that live in different keys of the record.
+* `capabilityRecipe` / `parseCapabilities` — the four launchpad buys.
+* `formatForType` — Pact literal rules: decimals never bare, lists space-separated, glyph
+  strings verbatim, guards as `(read-keyset "name")`.
+* Full types for the record.
+
+450 tests, including one per entrypoint asserting its ghost builds.

package/README.md

@@ -0,0 +1,168 @@
+# @ouronet/talos-registry
+
+The Ouronet callable surface, generated from the **deployed** contracts.
+
+A consumer supplies **values**. It never types a function name, an argument order, or an arity.
+
+```ts
+import { buildCall, planCall, explainCall } from "@ouronet/talos-registry";
+
+buildCall("TS01-C1.DPTF|C_Transfer", {
+  patron: "Σ.…", executor: "Σ.…", executee: "Σ.…",
+  id: "OURO-8Nh-JO8JO4F5", "transfer-amount": 1, method: false,
+});
+// (ouronet-ns.TS01-C1.DPTF|C_Transfer "Σ.…" "Σ.…" "Σ.…" "OURO-8Nh-JO8JO4F5" 1.0 false)
+```
+
+Note `1` became `1.0`. Pact's decimal lexer rejects a bare integer in a decimal slot, and that
+is the least interesting thing this package stops you getting wrong.
+
+**This build:** 423 entrypoints, 428 previews, surface `7e59e59d4c5b7257`, generated against mainnet.
+Every figure in this file is asserted by `tests/readme.test.ts` against the bundled snapshot, so
+a stale number fails the suite rather than misleading a reader.
+
+---
+
+## Why it exists
+
+Every consumer bug that led to this was a hand-written Pact template that drifted from the
+contract, and **none of them failed loudly**:
+
+- **A missing module member is a RESOLUTION error.** `try` cannot catch it, so consumers render
+  it as a default. Thirty-four stale names made Awake and Slumber report "no hibernated nonces"
+  against three live ones — it looked like missing data, not a broken call.
+- **A short call is not rejected.** Pact **partially applies** and yields a closure. A launchpad
+  read passing four arguments to a five-parameter reader returned *"Evaluation did not reduce to
+  a value"*; the capabilities came back null and the purchase silently could not be funded.
+- **An argument can move without the count changing.** `SWP|C_ChangeOwnership` kept four
+  parameters and moved the pool id to last. No arity check catches that.
+
+`buildCall` takes arguments **by name** and renders them in the contract's declared order, so
+both classes are impossible.
+
+---
+
+## What an entry knows
+
+Nine things, for all 423 entrypoints:
+
+| | |
+|---|---|
+| **shape** | parameters in order, with declared types, and the return type when one is declared |
+| **preview** | the `INFO_` reader that prices the call — it lives on a *different module* |
+| **ownership** | whose key the caller must sign for, marked `ALWAYS` or `CONDITIONAL` |
+| **provenance** | deployed vs repo-only, module hash, and any deployed/repo divergence |
+| **capabilities** | the reader that computes required `coin.TRANSFER` caps, and how to map its arguments |
+| **sponsorship** | whether the gas station pays — and for a `defpact`, that it pays for step 0 only |
+| **formula** | same field: the capability reader *is* the formula, because the amounts cannot be derived client-side |
+| **ghost** | a worked example for every parameter, shapes read from mainnet |
+| **execution** | how it runs — below |
+
+### Execution modes
+
+| mode | n | meaning |
+|---|---|---|
+| `direct` | 396 | the inputs suffice |
+| `defpact` | 10 | multi-transaction by **continuation** |
+| `indirect-parallel` | 9 | a preflight cut into slices — order-independent, fire together |
+| `indirect-single` | 5 | one transaction, but a preflight supplies an argument |
+| `indirect-sequential` | 3 | a preflight reports progress; each call advances a **stored cursor** |
+
+The last two both wear the `p` suffix in Pact and **only one is parallel**. Firing a cursor
+pager's pages concurrently races its own counter. `planCall()` says which you have.
+
+---
+
+## Three things that surprise people
+
+**Continuations are not gas-sponsored.** Chainweb injects `exec-code` only for `exec` payloads.
+`DALOS.GAS_PAYER` binds it *eagerly*, so on a `cont` it raises before any check runs. Step 0 is
+sponsored; the **customer account** pays every later step. All ten `defpact` entrypoints have a
+single-transaction twin with a byte-identical parameter list — `preferInstead` names it, and
+`buildCall` refuses the defpact route unless you pass `{ allowUnsupported: true }`.
+
+**An entity id is not an account.** `swpair` is a pool id; nobody holds its key. The account is
+whatever `UR_OwnerKonto` returns for it. `ownership.requires[].via` says `"parameter"` or
+`"reader"`, and never conflates them.
+
+**Four names resolve to two modules.** `SWP|C_AddFrozenLiquidity` and three siblings exist on
+both `TS01-C3` (direct) and `TS01-CP` (defpact), with identical signatures. `resolveByName()`
+**refuses** rather than guessing — picking wrong is silent in both directions.
+
+---
+
+## API
+
+```ts
+// lookup
+getEntrypoint(key)            // throws, and names near matches, on a stale key
+resolveByName(fn)             // refuses an ambiguous bare name
+entrypointKeys() / modules() / entrypointsOfModule(m)
+registry / surfaceHash / namespace
+
+// build — checked against the deployed signature
+buildCall(key, argsByName, opts?)
+buildPreviewCall(key, argsByName, opts?)
+buildGhostCall(key)           // the worked example. Illustrative, never submittable.
+
+// plan
+planCall(key)   -> CallPlan   // preflight, capabilities, signers, tx count, warnings
+explainCall(key) -> string    // the same, as text
+
+// capabilities
+capabilityRecipe(key)         // null when GAS_PAYER alone suffices
+parseCapabilities(strings)    // <(coin.TRANSFER "a" "b" 1.0)> -> signer args
+
+// rendering
+formatForType(value, declaredType)
+```
+
+### A launchpad buy, end to end
+
+```ts
+const KEY = "TS02-CPAD.SPARK|C_BuySparks";
+const recipe = capabilityRecipe(KEY)!;        // DEMIPAD-SPARK.URC_Acquire
+
+const raw  = await pactRead(buildCall(recipe.reader, {
+  buyer, amount: sparks, "iz-native": true, slippage: 1.0,
+}));
+const caps = parseCapabilities(raw);          // attach to the PAYER signer
+
+const code = buildCall(KEY, {
+  patron, buyer, "sparks-amount": sparks, "iz-native": true, "max-cost": maxCost,
+});
+```
+
+Call the reader. **Do not recompute the amounts** — they depend on live price, the
+native/wrapped split and a slippage pad, and a self-derived figure signs a capability the
+contract will not match.
+
+---
+
+## The snapshot is pinned, deliberately
+
+The registry is **bundled at build time**, not fetched at runtime. Refreshing live would add a
+trust surface (whatever a node returns) and a failure mode (offline means no registry) that a
+pinned artefact does not have. `surfaceHash` identifies exactly which surface a build was
+compiled against.
+
+`npm run sync` copies it from the Pact repo and **refuses** a snapshot that was not generated
+against the chain, or that carries deployed/repo divergences — a truncated or repo-only copy
+would be worse than none, because consumers would validate against it and get confident wrong
+answers.
+
+Regenerate upstream with `python3 REPL/tools/_registry.py --probe`, then `npm run build` here.
+
+## Ghost values
+
+Every parameter has a worked example. They are keyed by **parameter name**, then by type, then
+derived from the contract's own `defschema` — 423 entrypoints share 2,182 slots but only 276
+distinct names, and four of those cover half of them. Authoring per entrypoint would mean
+writing the same account into 416 `patron` slots by hand.
+
+Every id was read from **mainnet**, so the *shape* is real: you can see that a swpair is a
+four-segment pipe-joined string and an account is a glyph string, not a `k:` address.
+
+**They are not submittable.** The accounts are not yours to sign for, and an amount of `1.0` is
+a placeholder. A preflight-fed parameter is `null` with a note naming the read — the registry
+will not invent a value it has just told you cannot be constructed.

package/dist/build.d.ts

@@ -0,0 +1,41 @@
+export interface BuildOptions {
+    /**
+     * Build even when `execution.supported` is false. The ten `defpact` entrypoints each have a
+     * single-transaction twin with an identical parameter list, and the owner's 2026-09-15 ruling
+     * is that the defpact paths are historical. Pass this only when exercising one deliberately.
+     */
+    allowUnsupported?: boolean;
+    /** Override the namespace. Defaults to the registry's own (`ouronet-ns`). */
+    namespace?: string;
+}
+/**
+ * Build the Pact code for a call, CHECKED against the deployed signature.
+ *
+ * This is the whole point of the package. Every consumer bug this registry was built after was
+ * a hand-written template that drifted from the contract:
+ *
+ *   * five builders passed three arguments to entrypoints that take four, after the
+ *     patron/executor sweep added `executor` -- the UI stopped compiling and nobody noticed
+ *     because the repo's typecheck ran against a config that checked zero files;
+ *   * a launchpad read passed four arguments to a five-parameter reader. Pact does not raise
+ *     "wrong arity" for that: it PARTIALLY APPLIES and yields a closure, so the caller saw
+ *     "Evaluation did not reduce to a value" and the buy silently could not be funded.
+ *
+ * Arguments are supplied BY NAME and rendered in the contract's declared order, so an argument
+ * cannot be transposed either -- `C_ChangeOwnership` moved its pool id to last while keeping
+ * the same arity, which no count check would catch.
+ */
+export declare function buildCall(key: string, args: Record<string, unknown>, opts?: BuildOptions): string;
+/**
+ * Build the cost-preview (`INFO_`) call for an entrypoint.
+ *
+ * The preview lives on a DIFFERENT module by design, and assuming otherwise is how a consumer
+ * ended up calling INFO-ZERO for previews that had moved to INFO-ONE. The pairing is recorded,
+ * not guessed.
+ */
+export declare function buildPreviewCall(key: string, args: Record<string, unknown>, opts?: BuildOptions): string;
+/** Build the example call from the registry's ghost values. Illustrative, never submittable. */
+export declare function buildGhostCall(key: string): {
+    code: string;
+    warning: string;
+};

package/dist/build.js

@@ -0,0 +1,100 @@
+import { formatForType } from "./format.js";
+import { getEntrypoint, namespace, RegistryError, registry } from "./registry.js";
+/**
+ * Build the Pact code for a call, CHECKED against the deployed signature.
+ *
+ * This is the whole point of the package. Every consumer bug this registry was built after was
+ * a hand-written template that drifted from the contract:
+ *
+ *   * five builders passed three arguments to entrypoints that take four, after the
+ *     patron/executor sweep added `executor` -- the UI stopped compiling and nobody noticed
+ *     because the repo's typecheck ran against a config that checked zero files;
+ *   * a launchpad read passed four arguments to a five-parameter reader. Pact does not raise
+ *     "wrong arity" for that: it PARTIALLY APPLIES and yields a closure, so the caller saw
+ *     "Evaluation did not reduce to a value" and the buy silently could not be funded.
+ *
+ * Arguments are supplied BY NAME and rendered in the contract's declared order, so an argument
+ * cannot be transposed either -- `C_ChangeOwnership` moved its pool id to last while keeping
+ * the same arity, which no count check would catch.
+ */
+export function buildCall(key, args, opts = {}) {
+    const ep = getEntrypoint(key);
+    if (ep.source === "repo-only") {
+        throw new RegistryError(`"${key}" is not callable: no live code is deployed for it. ${ep.note ?? ""}`.trim());
+    }
+    if (ep.execution.supported === false && !opts.allowUnsupported) {
+        throw new RegistryError(`"${key}" is not the supported route. ${ep.execution.supportedNote ?? ""} ` +
+            `Pass { allowUnsupported: true } to build it anyway.`);
+    }
+    const declared = ep.params.map(p => p.name);
+    const given = Object.keys(args);
+    const missing = declared.filter(n => !(n in args));
+    const extra = given.filter(n => !declared.includes(n));
+    if (missing.length || extra.length) {
+        const lines = [`Arguments do not match ${key}.`];
+        if (missing.length)
+            lines.push(`  missing: ${missing.join(", ")}`);
+        if (extra.length)
+            lines.push(`  unexpected: ${extra.join(", ")}`);
+        lines.push(`  declared: (${ep.params.map(p => `${p.name}:${p.type}`).join(" ")})`);
+        // Say it plainly: a short call does not error on chain, it partially applies.
+        if (missing.length)
+            lines.push(`  A short call is NOT rejected by Pact -- it partially applies and yields a closure, ` +
+                `so the transaction "succeeds" having done nothing.`);
+        throw new RegistryError(lines.join("\n"));
+    }
+    // A preflight-fed parameter must carry the READ's output. The registry marks these because a
+    // client cannot construct them; passing null here would build a call that cannot work.
+    for (const fed of ep.execution.fedParams ?? []) {
+        if (args[fed.param] === null || args[fed.param] === undefined) {
+            throw new RegistryError(`"${fed.param}" is the output of a preflight read and must be supplied.\n` +
+                `  run: ${fed.producedBy.join(" or ")}\n` +
+                `  ${ep.execution.note}`);
+        }
+    }
+    const ns = opts.namespace ?? namespace;
+    const rendered = ep.params.map(p => formatForType(args[p.name], p.type));
+    return `(${ns}.${key} ${rendered.join(" ")})`;
+}
+/**
+ * Build the cost-preview (`INFO_`) call for an entrypoint.
+ *
+ * The preview lives on a DIFFERENT module by design, and assuming otherwise is how a consumer
+ * ended up calling INFO-ZERO for previews that had moved to INFO-ONE. The pairing is recorded,
+ * not guessed.
+ */
+export function buildPreviewCall(key, args, opts = {}) {
+    const ep = getEntrypoint(key);
+    if (!ep.preview) {
+        throw new RegistryError(`"${key}" has no cost preview. ${ep.previewMissing ?? ""}`.trim());
+    }
+    const pv = registry.previews[ep.preview];
+    const declared = pv.params.map(p => p.name);
+    const missing = declared.filter(n => !(n in args));
+    if (missing.length) {
+        throw new RegistryError(`Preview ${ep.preview} is missing: ${missing.join(", ")}\n` +
+            `  declared: (${pv.params.map(p => `${p.name}:${p.type}`).join(" ")})\n` +
+            `  note: a preview's parameters are NOT always the entrypoint's -- it may omit a ` +
+            `ceiling the user chooses, or name the same slot differently.`);
+    }
+    const ns = opts.namespace ?? namespace;
+    const rendered = pv.params.map(p => formatForType(args[p.name], p.type));
+    return `(${ns}.${ep.preview} ${rendered.join(" ")})`;
+}
+/** Build the example call from the registry's ghost values. Illustrative, never submittable. */
+export function buildGhostCall(key) {
+    const ep = getEntrypoint(key);
+    const fed = new Set((ep.execution.fedParams ?? []).map(f => f.param));
+    const args = {};
+    for (const p of ep.params) {
+        args[p.name] = fed.has(p.name)
+            ? `<from ${(ep.execution.preflight ?? ["preflight"]).join(" / ")}>`
+            : ep.ghost.args[p.name];
+    }
+    return {
+        code: `(${namespace}.${key} ${ep.params
+            .map(p => (fed.has(p.name) ? String(args[p.name]) : formatForType(args[p.name], p.type)))
+            .join(" ")})`,
+        warning: ep.ghost.warning,
+    };
+}

package/dist/caps.d.ts

@@ -0,0 +1,42 @@
+/** One capability, parsed out of what a capability reader returned. */
+export interface ParsedCapability {
+    /** fully-qualified, e.g. `coin.TRANSFER` */
+    name: string;
+    /** positional arguments, already typed for a Kadena signer */
+    args: (string | {
+        decimal: string;
+    })[];
+}
+/**
+ * Parse the strings a capability reader returns.
+ *
+ * `URC_Acquire` returns `[string]`, each wrapped in angle brackets:
+ *
+ *     <(coin.TRANSFER "from" "to" 9.595000000000)>
+ *
+ * The brackets are the contract's own quoting; they are not part of the capability. Parsing
+ * this by hand is where a consumer drops a leg and signs for less than the transaction moves.
+ */
+export declare function parseCapability(raw: string): ParsedCapability;
+export declare function parseCapabilities(raws: readonly string[]): ParsedCapability[];
+/** What a caller must do to obtain this entrypoint's extra capabilities. */
+export interface CapabilityRecipe {
+    reader: string;
+    /** reader parameter -> where its value comes from */
+    argsFrom: Record<string, string>;
+    readerParams: {
+        name: string;
+        type: string;
+    }[];
+    attachTo: string;
+    note: string;
+}
+/**
+ * The recipe for an entrypoint's required capabilities, or null when GAS_PAYER is enough.
+ *
+ * Only four entrypoints need this -- the launchpad buys -- and the reader that computes them
+ * lives on the SALE module, not on the Talos module the entrypoint belongs to. Looking in the
+ * entrypoint's own module finds nothing, which reads as "no capabilities required" rather than
+ * as a failed lookup.
+ */
+export declare function capabilityRecipe(key: string): CapabilityRecipe | null;

package/dist/caps.js

@@ -0,0 +1,44 @@
+import { getEntrypoint, RegistryError } from "./registry.js";
+/**
+ * Parse the strings a capability reader returns.
+ *
+ * `URC_Acquire` returns `[string]`, each wrapped in angle brackets:
+ *
+ *     <(coin.TRANSFER "from" "to" 9.595000000000)>
+ *
+ * The brackets are the contract's own quoting; they are not part of the capability. Parsing
+ * this by hand is where a consumer drops a leg and signs for less than the transaction moves.
+ */
+export function parseCapability(raw) {
+    const cleaned = raw.replace(/^\s*<\s*/, "").replace(/\s*>\s*$/, "").trim();
+    const m = cleaned.match(/^\(([^\s()]+)\s+"([^"]*)"\s+"([^"]*)"\s+([\d.]+)\)$/);
+    if (!m) {
+        throw new RegistryError(`Unrecognised capability string: ${raw}\n` +
+            `  expected: <(NAME "from" "to" amount)>`);
+    }
+    const [, name, from, to, amount] = m;
+    return { name, args: [from, to, { decimal: amount }] };
+}
+export function parseCapabilities(raws) {
+    return raws.map(parseCapability);
+}
+/**
+ * The recipe for an entrypoint's required capabilities, or null when GAS_PAYER is enough.
+ *
+ * Only four entrypoints need this -- the launchpad buys -- and the reader that computes them
+ * lives on the SALE module, not on the Talos module the entrypoint belongs to. Looking in the
+ * entrypoint's own module finds nothing, which reads as "no capabilities required" rather than
+ * as a failed lookup.
+ */
+export function capabilityRecipe(key) {
+    const ec = getEntrypoint(key).externalCaps;
+    if (!ec)
+        return null;
+    return {
+        reader: ec.computedBy,
+        argsFrom: ec.argsFrom,
+        readerParams: ec.readerParams,
+        attachTo: ec.attachTo,
+        note: ec.note,
+    };
+}