@ouronet/talos-registry 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -16,6 +16,6 @@ export type { CallPlan } from "./plan.js";
 export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js";
 export type { ParsedCapability, CapabilityRecipe } from "./caps.js";
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
-export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
-export type { TooltipModel, TooltipSlot, TooltipPreview } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, CHAIN_PALETTE, CHAIN_LABEL, CONSUMERS, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES, paramRole, paramsByRole, unfilledFillable } from "./tooltip.js";
+export type { TooltipModel, TooltipSlot, TooltipPreview, Chain, ConsumerIdentity, ParamRole } from "./tooltip.js";
 export type * from "./types.js";

package/dist/index.js

@@ -15,4 +15,4 @@ export { parseCapability, parseCapabilities, capabilityRecipe } from "./caps.js"
 export { formatForType, formatDecimal, formatInteger, formatString, formatBool } from "./format.js";
 // THE TOOLTIP CANON. Shared implementation rather than a shared document -- see TOOLTIP-CANON.md
 // for why each rule exists, and `tooltip.ts` for the rules themselves.
-export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES } from "./tooltip.js";
+export { tooltipModel, tooltipModels, signatureRows, chainOf, isOffRegistryKey, isNativeKey, isPlaceholder, PLACEHOLDER, CHAIN_PALETTE, CHAIN_LABEL, CONSUMERS, STOA_SIGNATURES, KADENA_SIGNATURES, NATIVE_SIGNATURES, paramRole, paramsByRole, unfilledFillable } from "./tooltip.js";

package/dist/tooltip.d.ts

@@ -1,3 +1,41 @@
+/** The three worlds a tooltip can describe. See rule 4. */
+export type Chain = "ouronet" | "stoa" | "kadena";
+/**
+ * The canonical border colour per chain. USE THESE.
+ *
+ * Not styling: the colour tells a user which chain their money is on, and that vocabulary is
+ * shared between the applications that render it. Two apps teaching different meanings for the
+ * same colour is worse than neither using colour at all, because the user believes the first one
+ * they learned.
+ *
+ *   ouronet  blue    the ouronet-ns surface -- priced, IGNIS, sponsored
+ *   stoa     gold    StoaChain's own coin -- unpriced, no IGNIS, still sponsored
+ *   kadena   green   a DIFFERENT CHAIN -- its own gas, its own balances
+ *
+ * Chosen from what was already in use rather than invented: gold is OuronetUI's STOA accent and
+ * blue its established `#3b82f6`; green is the app's existing success green, which is unused on
+ * any other tooltip surface and therefore free to carry this meaning.
+ */
+export declare const CHAIN_PALETTE: Readonly<Record<Chain, string>>;
+/** Human label for the chain, for the border-adjacent marker. */
+export declare const CHAIN_LABEL: Readonly<Record<Chain, string>>;
+/**
+ * Who is drawing the tooltip -- rule 4b.
+ *
+ * Two applications render this, and a Codex panel can open over an OuronetUI page, which is
+ * exactly the case where "whose tooltip is this" is hardest to infer from chrome and most useful
+ * to state. The accent is the CONSUMER's identity and is deliberately a different axis from
+ * `CHAIN_PALETTE`: one says what you are looking at, the other says who is showing it to you.
+ *
+ * `name` matches the `consumerName` key each app already uses for its codex settings, so there is
+ * one spelling of "OuronetUI" across the workspace rather than two.
+ */
+export interface ConsumerIdentity {
+    name: string;
+    /** the app's own accent for the caller zone. NOT a chain colour. */
+    accent: string;
+}
+export declare const CONSUMERS: Readonly<Record<"OuronetUI" | "Codex", ConsumerIdentity>>;
 /** One parameter of the execution, with everything a renderer needs about it. */
 export interface TooltipSlot {
     /** 1-based, so a renderer never has to decide whether to add one. */
@@ -13,6 +51,14 @@ export interface TooltipSlot {
     isPreflightFed: boolean;
     /** false = never prefill into an input that can reach a signed transaction (guards). */
     prefillable: boolean;
+    /**
+     * The CALLER supplied this value; it is not a ghost.
+     *
+     * Tracked in the model rather than left to each renderer, because "is this the user's data or
+     * an example?" is the question every one of this module's bugs turned on, and two consumers
+     * answering it separately is two chances to answer it differently.
+     */
+    supplied: boolean;
     /** the registry's own note about this argument, when it has one. */
     note?: string;
 }
@@ -33,11 +79,8 @@ export interface TooltipModel {
      *   kadena   Kadena mainnet's `coin`. A DIFFERENT CHAIN -- different gas, different accounts,
      *            and nothing about Ouronet applies to it.
      *
-     * A renderer MUST make these visually distinct, because they differ in what they cost and what
-     * can be previewed. It is NOT told how: OuronetUI uses gold/blue, the Codex violet for Ouronet
-     * and green for Kadena, and all are conformant. Mandating a palette in a package consumed by
-     * applications with their own design languages is a rule that gets ignored, and an ignored rule
-     * weakens the ones that matter.
+     * Each has a canonical colour in `CHAIN_PALETTE`, and a renderer should use it: the colour
+     * encodes which chain the user's money is on, which is shared vocabulary rather than styling.
      *
      * RENAMED from `"native"` in 2.0.0. With only two worlds "native" was unambiguous; with three
      * it silently invited the question "native to WHAT" -- and both candidate answers are a
@@ -57,6 +100,12 @@ export interface TooltipModel {
      * latency the user pays for a foregone conclusion. Rule 5.
      */
     shouldRead: boolean;
+    /** the canonical border colour for `kind`. Convenience -- identical to CHAIN_PALETTE[kind]. */
+    chainColor: string;
+    /** the label to print beside it: OURONET / STOA NATIVE / KADENA. */
+    chainLabel: string;
+    /** who is rendering, for the caller zone. Undefined when the caller did not say. */
+    consumer?: ConsumerIdentity;
     /** things a renderer may want to surface. Never thrown; a tooltip must not take a page down. */
     warnings: string[];
 }
@@ -110,7 +159,7 @@ export declare const isNativeKey: (key: string) => boolean;
  * unresolvable argument becomes a visible placeholder rather than an exception, because a tooltip
  * must never take down the page it annotates.
  */
-export declare function tooltipModel(key: string, values?: Readonly<Record<string, string>>): TooltipModel;
+export declare function tooltipModel(key: string, values?: Readonly<Record<string, string>>, consumer?: ConsumerIdentity): TooltipModel;
 /**
  * Models for a button that fronts a CHOICE of executions, in the order the ZBOM presents them.
  *
@@ -119,7 +168,7 @@ export declare function tooltipModel(key: string, values?: Readonly<Record<strin
  * caller instead -- and if nothing survives, the caller renders no tooltip, which is the correct
  * outcome and not a crash.
  */
-export declare function tooltipModels(keys: readonly string[], values?: Readonly<Record<string, string>>): TooltipModel[];
+export declare function tooltipModels(keys: readonly string[], values?: Readonly<Record<string, string>>, consumer?: ConsumerIdentity): TooltipModel[];
 /**
  * The type row -- rule 3.
  *
@@ -130,3 +179,30 @@ export declare function signatureRows(m: TooltipModel): {
     names: string[];
     types: string[];
 };
+/**
+ * What KIND of thing a parameter holds.
+ *
+ * Pact types cannot answer this -- `patron`, `id`, `ats` and `swpair` are all `string`, and a
+ * value of the wrong kind in any of them type-checks, renders plausibly, and makes the preview
+ * succeed against the wrong entity. That is the defect class this whole module exists to prevent,
+ * and it has now produced four separate bugs.
+ */
+export type ParamRole = "ouronet-account" | "kadena-account" | "token-id" | "dpof-id" | "ats-pool" | "swap-pool" | "other";
+/** The role of a parameter name, or undefined when nothing is known about it. */
+export declare function paramRole(name: string): ParamRole | undefined;
+/** Every name this registry can classify, grouped. Useful for building a consumer's fill map. */
+export declare function paramsByRole(): Record<ParamRole, string[]>;
+/**
+ * RULE 7, as a check: which slots the consumer COULD have filled and did not.
+ *
+ * A slot qualifies when its role is known and the caller supplied no value for it. Those are the
+ * ones that silently show somebody else's real id -- `ats = "Auryndex-…"` on a SilverStoa button,
+ * an example account whose pool ledger is empty, a reward token rendered as "no live example".
+ *
+ * Placeholders and preflight-fed slots are NOT reported: the first is honestly unresolved and the
+ * second must not be invented. This answers "what did you leave on the table", not "what is
+ * missing".
+ *
+ * A conformant consumer asserts this is empty for every button it renders.
+ */
+export declare function unfilledFillable(m: TooltipModel): TooltipSlot[];

package/dist/tooltip.js

@@ -22,12 +22,22 @@
  * 3. TYPES GO ON THEIR OWN ROW. `patron:string executor:string ...` doubles the width of the
  *    widest line in the panel. A parallel row under the names costs one line and reads better.
  *
- * 4. THREE WORLDS, and they must be distinguishable at a glance. `ouronet` (the ouronet-ns
- *    surface), `stoa` (StoaChain's own `coin` contract) and `kadena` (Kadena mainnet's `coin`).
- *    They differ in what they cost and what can be previewed. Only `ouronet` has an INFO_ reader
- *    and collects IGNIS; gas is sponsored on the Stoa side regardless -- claiming otherwise tells
- *    a user they are about to spend when they are not. HOW you distinguish them is yours: `kind`
- *    is the canon, the palette is not.
+ * 4. THREE WORLDS, WITH A CANONICAL COLOUR EACH. `ouronet` (blue), `stoa` (gold), `kadena`
+ *    (green). They differ in what they cost and what can be previewed. Only `ouronet` has an
+ *    INFO_ reader and collects IGNIS; gas is sponsored on the Stoa side regardless -- claiming
+ *    otherwise tells a user they are about to spend when they are not.
+ *
+ *    THE PALETTE IS NOW CANON, reversing the 1.4.0 position that it was each app's business.
+ *    The argument then was that a package should not dictate colours inside somebody else's
+ *    design language, and that was right about DECORATION and wrong about this: the colour
+ *    encodes WHICH CHAIN YOUR MONEY IS ON. A user who learns green-means-Kadena in one app and
+ *    meets green-means-something-else in the other has been taught a falsehood by the
+ *    inconsistency, and the two apps share users. A shared vocabulary has to be shared.
+ *
+ * 4b. SAY WHO IS RENDERING. Two applications draw this tooltip, and they draw it over different
+ *    surfaces for the same chains. A caller zone naming the consumer costs one line and answers
+ *    "which app am I looking at" without the user having to infer it from chrome -- which matters
+ *    most in exactly the case where it is hardest, a Codex panel over an OuronetUI page.
  *
  * 0. CHAINWEB ONLY -- the rule that decides whether a tooltip exists at all. This model describes
  *    a PACT call on a Chainweb chain: what function, what arguments, what it costs. A button that
@@ -41,6 +51,37 @@
  */
 import { getEntrypoint, getPreview, tryGetEntrypoint, registry } from "./registry.js";
 import { formatForType } from "./format.js";
+/**
+ * The canonical border colour per chain. USE THESE.
+ *
+ * Not styling: the colour tells a user which chain their money is on, and that vocabulary is
+ * shared between the applications that render it. Two apps teaching different meanings for the
+ * same colour is worse than neither using colour at all, because the user believes the first one
+ * they learned.
+ *
+ *   ouronet  blue    the ouronet-ns surface -- priced, IGNIS, sponsored
+ *   stoa     gold    StoaChain's own coin -- unpriced, no IGNIS, still sponsored
+ *   kadena   green   a DIFFERENT CHAIN -- its own gas, its own balances
+ *
+ * Chosen from what was already in use rather than invented: gold is OuronetUI's STOA accent and
+ * blue its established `#3b82f6`; green is the app's existing success green, which is unused on
+ * any other tooltip surface and therefore free to carry this meaning.
+ */
+export const CHAIN_PALETTE = {
+    ouronet: "#3b82f6",
+    stoa: "#ceac5f",
+    kadena: "#22c55e",
+};
+/** Human label for the chain, for the border-adjacent marker. */
+export const CHAIN_LABEL = {
+    ouronet: "OURONET",
+    stoa: "STOA NATIVE",
+    kadena: "KADENA",
+};
+export const CONSUMERS = {
+    OuronetUI: { name: "OuronetUI", accent: "#d2d3d4" },
+    Codex: { name: "Codex", accent: "#8b5cf6" },
+};
 /** The registry's generic placeholder: an entity id for something that does not exist on chain. */
 export const PLACEHOLDER = '"example"';
 export const isPlaceholder = (rendered) => rendered === PLACEHOLDER;
@@ -124,7 +165,7 @@ const KADENA_GHOST = {
     bool: "false",
     guard: '(read-keyset "ks")',
 };
-function offRegistryModel(key, kind, values) {
+function offRegistryModel(key, kind, values, consumer) {
     const sig = (kind === "stoa" ? STOA_SIGNATURES : KADENA_SIGNATURES)[key];
     if (!sig)
         throw new Error(`offRegistryModel: no signature for "${key}"`);
@@ -132,6 +173,9 @@ function offRegistryModel(key, kind, values) {
     return {
         kind,
         exec: key,
+        chainColor: CHAIN_PALETTE[kind],
+        chainLabel: CHAIN_LABEL[kind],
+        consumer,
         slots: sig.map(([name, type], i) => ({
             index: i + 1,
             name,
@@ -141,6 +185,7 @@ function offRegistryModel(key, kind, values) {
             isPreflightFed: false,
             // A guard is never prefillable, on any chain. Same rule, same reason.
             prefillable: type !== "guard",
+            supplied: values[name] !== undefined,
         })),
         // No preview, deliberately. Neither chain's `coin` has a reader that prices a call, so there
         // is no cost to show -- and a renderer must SAY that rather than leaving an empty panel,
@@ -160,10 +205,10 @@ function offRegistryModel(key, kind, values) {
  * unresolvable argument becomes a visible placeholder rather than an exception, because a tooltip
  * must never take down the page it annotates.
  */
-export function tooltipModel(key, values = {}) {
+export function tooltipModel(key, values = {}, consumer) {
     const chain = chainOf(key);
     if (chain === "stoa" || chain === "kadena")
-        return offRegistryModel(key, chain, values);
+        return offRegistryModel(key, chain, values, consumer);
     if (chain === undefined && isOffRegistryKey(key))
         throw new Error(`tooltipModel: "${key}" matched no chain. This is a bug in chainOf.`);
     const ep = getEntrypoint(key); // throws, and names near matches, on a stale key
@@ -213,6 +258,7 @@ export function tooltipModel(key, values = {}) {
             isPlaceholder,
             isPreflightFed,
             prefillable: u?.zbom !== false,
+            supplied: supplied !== undefined,
             note: ep.ghost.notes?.[p.name],
         };
     });
@@ -249,6 +295,9 @@ export function tooltipModel(key, values = {}) {
     return {
         kind: "ouronet",
         exec: `${registry.namespace}.${key}`,
+        chainColor: CHAIN_PALETTE.ouronet,
+        chainLabel: CHAIN_LABEL.ouronet,
+        consumer,
         slots,
         preview,
         // RULE 5: do not fire a read whose answer is a foregone refusal.
@@ -264,10 +313,10 @@ export function tooltipModel(key, values = {}) {
  * caller instead -- and if nothing survives, the caller renders no tooltip, which is the correct
  * outcome and not a crash.
  */
-export function tooltipModels(keys, values = {}) {
+export function tooltipModels(keys, values = {}, consumer) {
     return keys
         .filter((k) => chainOf(k) !== undefined)
-        .map((k) => tooltipModel(k, values));
+        .map((k) => tooltipModel(k, values, consumer));
 }
 /**
  * The type row -- rule 3.
@@ -278,3 +327,81 @@ export function tooltipModels(keys, values = {}) {
 export function signatureRows(m) {
     return { names: m.slots.map((s) => s.name), types: m.slots.map((s) => s.type) };
 }
+/**
+ * DERIVED FROM THE GHOST'S SHAPE, not from a hand-written list of 332 names.
+ *
+ * Hand-classifying the vocabulary would be the same act that produced the bugs: a human deciding
+ * that `ats` looks like a token because both are strings. The registry's ghosts were each resolved
+ * for their own parameter and READ FROM MAINNET, so the value's shape is evidence rather than
+ * opinion -- an Ouronet account is a glyph string, a pool is `Name-O136CBn22ncY`, a swap pair
+ * starts `W|`, a hibernated DPOF starts `H|`.
+ *
+ * A name whose ghost is the generic `"example"` gets NO role, and that is correct: nothing is
+ * known about it, so nothing should be inferred. Those render as visible placeholders.
+ */
+const ROLE_PATTERNS = [
+    [/^k:/, "kadena-account"],
+    [/^[^\u0000-\u007F]\./, "ouronet-account"],
+    [/^W\|/, "swap-pool"],
+    [/^H\|/, "dpof-id"],
+    [/^[A-Za-z]+-O136CBn22ncY$/, "ats-pool"],
+    [/^[A-Z0-9]+-[A-Za-z0-9]{3}-[A-Za-z0-9]+$/, "token-id"],
+];
+let ROLES = null;
+function buildRoles() {
+    const out = new Map();
+    const reg = registry;
+    for (const coll of [reg.entrypoints, reg.previews]) {
+        for (const v of Object.values(coll)) {
+            const args = v?.ghost?.args ?? {};
+            for (const p of v?.params ?? []) {
+                if (p.type !== "string" || out.has(p.name))
+                    continue;
+                const g = args[p.name];
+                if (typeof g !== "string" || g === "example")
+                    continue;
+                for (const [re, role] of ROLE_PATTERNS)
+                    if (re.test(g)) {
+                        out.set(p.name, role);
+                        break;
+                    }
+            }
+        }
+    }
+    return out;
+}
+/** The role of a parameter name, or undefined when nothing is known about it. */
+export function paramRole(name) {
+    if (!ROLES)
+        ROLES = buildRoles();
+    return ROLES.get(name);
+}
+/** Every name this registry can classify, grouped. Useful for building a consumer's fill map. */
+export function paramsByRole() {
+    if (!ROLES)
+        ROLES = buildRoles();
+    const out = {};
+    for (const [n, r] of ROLES)
+        (out[r] ??= []).push(n);
+    for (const k of Object.keys(out))
+        out[k].sort();
+    return out;
+}
+/**
+ * RULE 7, as a check: which slots the consumer COULD have filled and did not.
+ *
+ * A slot qualifies when its role is known and the caller supplied no value for it. Those are the
+ * ones that silently show somebody else's real id -- `ats = "Auryndex-…"` on a SilverStoa button,
+ * an example account whose pool ledger is empty, a reward token rendered as "no live example".
+ *
+ * Placeholders and preflight-fed slots are NOT reported: the first is honestly unresolved and the
+ * second must not be invented. This answers "what did you leave on the table", not "what is
+ * missing".
+ *
+ * A conformant consumer asserts this is empty for every button it renders.
+ */
+export function unfilledFillable(m) {
+    return m.slots.filter((s) => !s.supplied
+        && !s.isPlaceholder && !s.isPreflightFed
+        && paramRole(s.name) !== undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouronet/talos-registry",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "The Ouronet callable surface, generated from the deployed contracts. Supply values; never type a function name.",
   "type": "module",
   "main": "./dist/index.js",