@ouronet/talos-registry 2.0.0 → 2.2.0

package/README.md

@@ -17,7 +17,7 @@ buildCall("TS01-C1.DPTF|C_Transfer", {
 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 `9091592ba15520f4`, generated against mainnet.
+**This build:** 423 entrypoints, 428 previews, surface `8107265a0be6edc3`, 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.
 
@@ -178,10 +178,12 @@ import { tooltipModel, signatureRows } from "@ouronet/talos-registry";
 const m = tooltipModel("TS01-C1.DPTF|C_Transfer", { id: '"OURO-8Nh-JO8JO4F5"' });
 // m.slots -> EVERY execution parameter, in order, with type, value and flags
 // m.preview -> the INFO_ call with ITS OWN parameter list
-// m.kind -> "ouronet" | "stoa" | "kadena"   (only ouronet has a cost section)
+// m.kind       -> "ouronet" | "stoa" | "kadena"  (only ouronet has a cost section)
+// m.chainColor -> the CANONICAL border colour for that chain
+// m.consumer   -> who is rendering, for the caller zone
 ```
 
-Seven rules, each there because it was got wrong first — most recently a six-parameter transfer
+Ten rules, each there because it was got wrong first — most recently a six-parameter transfer
 whose tooltip showed five arguments, because it was rendering the preview's list under the
 execution's heading. Read the canon before building one.
 

package/TOOLTIP-CANON.md

@@ -126,21 +126,61 @@ header comment. The claim had been *inferred* from "this is not an Ouronet opera
 nothing about who pays the host chain — and it was wrong in the direction that matters, telling a
 user they were about to spend when they were not.
 
-**Make the two visually distinct — the palette is yours.** The distinction is mandatory because
-the two differ in what they cost and what can be previewed; the specific colour is presentation,
-and this package does not get a vote on your design language. A rule that mandates a palette in
-someone else's application is a rule that gets ignored, and an ignored rule weakens the ones that
-matter.
+### The palette is canon — `CHAIN_PALETTE`
+
+| chain | colour | |
+|---|---|---|
+| `ouronet` | `#3b82f6` | **blue** |
+| `stoa` | `#ceac5f` | **gold** |
+| `kadena` | `#22c55e` | **green** |
+
+**This reverses the 1.4.0 position**, which said the palette was each app's business. The
+reasoning then — that a package should not dictate colours inside someone else's design language —
+was right about *decoration* and wrong about *this*. The colour encodes **which chain your money
+is on**. Two apps teaching different meanings for the same colour is worse than neither using
+colour at all, because a user believes whichever they learned first, and these two apps share
+users.
+
+`m.chainColor` and `m.chainLabel` are on the model so a renderer cannot quietly pick a different
+one, and a test asserts every chain has both — if `Chain` ever gains a member without a colour,
+that fails rather than rendering `undefined`, which CSS ignores and which therefore looks like
+"no border rule" instead of a bug.
+
+Colours were taken from what was already in use rather than invented: gold is OuronetUI's STOA
+accent, blue its established `#3b82f6`, green its success green — unused on any tooltip surface
+and therefore free to carry this meaning.
 
-In practice:
+**Make the distinction run in every direction.** We coloured `stoa` gold and left `ouronet` on the
+panel's ordinary grey, so it only existed one way: a reader who never hovered a native button
+learned no rule at all, and gold read as "something is odd about this one" rather than as a
+category. Every kind gets a colour *and* a label.
 
-| | `stoa` | `ouronet` | `kadena` |
-|---|---|---|---|
-| OuronetUI | gold `#ceac5f` | blue `#3b82f6` | *(not surfaced)* |
-| Codex | *its own* | violet | **green** |
+And **say what is missing** rather than leaving the cost panel empty — an empty panel reads as
+"the price failed to load".
+
+## Rule 4b — say who is rendering
+
+Two applications draw this tooltip, and a Codex panel can open over an OuronetUI page. That is
+exactly the case where "whose tooltip is this" is hardest to infer from chrome and most useful to
+state.
+
+**Carry a caller zone naming the consumer.** One line, its own accent:
+
+```ts
+tooltipModel(key, values, CONSUMERS.Codex)      // m.consumer -> { name, accent }
+```
+
+| consumer | accent | |
+|---|---|---|
+| `OuronetUI` | `#d2d3d4` | neutral |
+| `Codex` | `#8b5cf6` | **violet** |
+
+**Two axes, deliberately.** The border says *what you are looking at*; the caller zone says *who
+is showing it to you*. A consumer accent is therefore never a chain colour, and a test asserts the
+two sets do not intersect — the moment they do, the two meanings merge and both become unreadable.
 
-Whatever you choose, make it carry meaning rather than decoration, and **say what is missing**
-rather than leaving the cost panel empty — an empty panel reads as "the price failed to load".
+`name` matches the `consumerName` each app already uses for its codex settings, so the workspace
+has one spelling of "OuronetUI" rather than two.
 
 Suggested footer, which is what OuronetUI ships:
 
@@ -152,11 +192,6 @@ a StoaChain `coin` call, so nothing prices it. Gas is still sponsored.
 Signatures are in `STOA_SIGNATURES` and `KADENA_SIGNATURES`, transcribed from the deployed
 contracts with line numbers. Use them rather than typing your own.
 
-**Make the distinction run in every direction.** We coloured `stoa` gold and left `ouronet` on the
-panel's ordinary grey — so the distinction existed one way only, and a reader who never hovered a
-native button learned no rule at all. Gold then reads as "something is odd about this one" rather
-than as a category. Give every kind a colour and a label, not just the exceptional ones.
-
 ## Rule 5 — a ghost is not data
 
 Every parameter has a worked example. The shapes are real — read from mainnet — so you can see
@@ -202,6 +237,81 @@ which is why there are two. `tooltipModel` applies both for you.
 
 ---
 
+## Rule 7 — fill every parameter you can, and prove it
+
+A tooltip that leaves a fillable slot showing the registry's example is not "partially
+implemented". It is **wrong**, and it is wrong in the way that does not announce itself: the
+examples are real ids read from mainnet, so the panel looks like data and the preview succeeds
+against somebody else's entity.
+
+Four separate bugs came from this, all on buttons that looked fine:
+
+| what showed | what it meant |
+|---|---|
+| `ats = "Auryndex-O136CBn22ncY"` on a **SilverStoa** button | a genuine fee, for the wrong pool |
+| `patron` = the example account | `INFO_ATS\|ColdRecovery` read an empty ledger and reported a table error |
+| `rt = <no live example>` | the page knew the token and never passed it |
+| `ats1`/`ats2` = `<no live example>` | on a button whose whole question is "from where, to where" |
+
+### Fill BY ROLE, not by name
+
+Pact types cannot help: `patron`, `id`, `ats` and `swpair` are all `string`, and a value of the
+wrong kind in any of them type-checks, renders plausibly and prices the wrong thing.
+
+```ts
+paramRole("ats")      // "ats-pool"
+paramRole("rt")       // "token-id"
+paramRole("patron")   // "ouronet-account"
+paramsByRole()        // the whole vocabulary, grouped
+```
+
+Roles are **derived from the shape of each ghost**, which was read from mainnet — an Ouronet
+account is a glyph string, a pool is `Name-O136CBn22ncY`, a swap pair starts `W|`, a hibernated
+DPOF starts `H|`. Not a hand-written list of 332 names: hand-classifying the vocabulary is the
+same act that caused the bugs, a human deciding `ats` looks like a token because both are strings.
+
+**A name whose ghost is the generic `"example"` gets no role**, and nothing should be inferred
+about it. Those stay visible placeholders. As of this writing 35 names classify and the rest do
+not, which is an honest answer rather than a gap to be filled with plausible-looking values.
+
+### The check
+
+```ts
+unfilledFillable(model)   // slots with a known role and no supplied value
+```
+
+**A conformant consumer asserts this is empty for every button it renders.** That is the
+difference between "we fixed the tooltip someone complained about" and "this class cannot recur".
+
+Note what it deliberately does *not* report: placeholders (honestly unresolved) and preflight-fed
+slots (must not be invented). It answers *what did you leave on the table*, not *what is missing*.
+
+### One fill map, not one per page
+
+If two value-builders exist, they will diverge, and the divergence will be a whole category. In
+OuronetUI the dashboard's builder had an account list from day one and the token pages' had none
+at all — which is exactly why Cold Recovery errored on three pages and nowhere else. It surfaced
+only because one preview out of two happened to read a table.
+
+Derive the fill map from `paramsByRole()` once, and give every page the same one.
+
+## Rule 8 — a refusal is an answer; render it as one
+
+`No value found in table ouronet-ns.ATS_ATS|Ledger for key: SilverStoa…` is not a crash. It is the
+chain saying *this subject has no row here* — often the most useful thing the tooltip could tell
+you, and it looks like a bug.
+
+Classify before rendering:
+
+- **missing row** (`No value found in table … for key …`) → say what it means: *"no position in
+  this pool yet"*. The operation is real; the subject simply has nothing to act on.
+- **placeholder argument** → name the argument, do not show the refusal. The read was never going
+  to succeed and that is not the contract's fault.
+- **anything else** → show it. An unclassified failure is worth seeing raw.
+
+And do not fire a read that cannot succeed: `m.shouldRead` is already false when an argument is a
+placeholder.
+
 ## Placement and behaviour
 
 Not expressible in the model, so they are stated here and they are not optional.