From 5c50ca67c0b8cd80de90b41b0f613c2f8502f296 Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Thu, 24 Sep 2026 20:24:24 +0200 Subject: [PATCH] docs: une affirmation sur ce qu-une valeur retourne doit etre executee --- .project/rules/INDEX.md | 7 ++-- .../justify-a-return-value-by-running-it.md | 32 +++++++++++++++++++ 2 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 .project/rules/nextgraph/justify-a-return-value-by-running-it.md diff --git a/.project/rules/INDEX.md b/.project/rules/INDEX.md index 35ce61c..a2fae51 100644 --- a/.project/rules/INDEX.md +++ b/.project/rules/INDEX.md @@ -1,8 +1,9 @@ # Rules (local) -Each rule lists its one-line summary. **Read the full file** when a rule looks relevant — it contains the *why* and *how to apply* needed to use the rule with judgment. +Each rule lists its one-line summary. **Read the full file** when a rule looks relevant - it contains the *why* and *how to apply* needed to use the rule with judgment. ## nextgraph -- **no-divergence-from-nextgraph** — Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled → `.project/rules/nextgraph/no-divergence-from-nextgraph.md` -- **surface-mirrors-the-sdk** — Publish the SDK's names, parameters and returns — a difference must be justified beside the code → `.project/rules/nextgraph/surface-mirrors-the-sdk.md` +- **justify-a-return-value-by-running-it** - Never justify what a value returns without running it - five defects here, two of them rights leaks -> `.project/rules/nextgraph/justify-a-return-value-by-running-it.md` +- **no-divergence-from-nextgraph** - Never diverge from NextGraph — ask "does the target do this?" FIRST, and only then how badly a caller would be misled -> `.project/rules/nextgraph/no-divergence-from-nextgraph.md` +- **surface-mirrors-the-sdk** - Publish the SDK's names, parameters and returns — a difference must be justified beside the code -> `.project/rules/nextgraph/surface-mirrors-the-sdk.md` diff --git a/.project/rules/nextgraph/justify-a-return-value-by-running-it.md b/.project/rules/nextgraph/justify-a-return-value-by-running-it.md new file mode 100644 index 0000000..a2d1411 --- /dev/null +++ b/.project/rules/nextgraph/justify-a-return-value-by-running-it.md @@ -0,0 +1,32 @@ +--- +name: justify-a-return-value-by-running-it +summary: Never justify what a value returns without running it - five defects here, two of them rights leaks +group: nextgraph +scope: local +created: 2026-09-24 +--- + +# A claim about what a value returns must be RUN before it is written + +**Rule:** Before writing a comment, a docstring or a contract clause that says a value is safe to pass on, forward, skip or trust BECAUSE OF WHAT IT RETURNS OR CARRIES, execute it. One line against the real artifact - the installed package's shipped `dist`, not the checkout this repo cites, and not the language semantics you remember. If the claim cannot be run, it is a bet: label it one, and name the version you did not check. + +**Why:** Five defects in this repository had one cause, and each was found only after the justification had been written, reviewed and shipped. Two of them were RIGHTS LEAKS in a package whose central promise is that one identity of a shared wallet cannot read another's data. + +- *"A plain property carries no items"* - true of the orm release this repo CITES, false of the one it BUILDS AGAINST, whose `useShape` hangs every identity's items off `data`, `promise` and `subscription`. A stranger read all three. +- *"The `get` trap is the read"* - false for `Object.getOwnPropertyDescriptor`, which handed back the raw collection and the refused handle. +- *"They take an item and return void or a boolean, so they yield nothing to leak"* - `Set.prototype.add` returns `this`. One line in a REPL says so. Holding what it returned also unlocked destruction. +- *"A primitive cannot reach an item"* - a COUNT is a primitive that describes the items, so any count member not spelled `size` or `length` published how many the holder may not read. The test suite asserted that as CORRECT, six lines above a test calling the same thing the defect. +- *"`$?` after a pipeline gives the command's status"* - it gives the LAST command's, so an exit-code check measured `tail`. Written by the agent that had just explained this failure mode to its user. + +Adjacent and the same shape: *"the summary line says 46 passed, so the suite is green"* - the runner prints a clean verdict and then intermittently hangs until its own deadline aborts it, so the summary is not the exit code. + +Every one of these was reasonable, was written with confidence, and was never executed. That is the whole pattern: not carelessness, but a plausible sentence about a value nobody ran. + +**How to apply:** The tell is a comment whose grammar is *"X is safe because it returns/carries Y"* - forwarding, passing through, skipping, trusting, not filtering. Those are the sentences to run, and they are cheap to run: `bun -e` or a throwaway probe, against `node_modules//dist`, takes less time than writing the justification did. + +Three corollaries, each earned: +- **Verify against what SHIPS, not what is cited.** This repo's provenance annotations point at a `nextgraph-rs` checkout that is three releases behind the packages it compiles against. A claim about the installed release refuted by reading that tree is refuted against the wrong version - which happened twice, and was caught twice. +- **A fake that has never been compared to the shipped shape makes every gate meaningless.** The first rights leak above survived ten adversarial passes and every re-run suite, because the only artifact exercising that path was hand-written and nobody had asked whether it resembled what the SDK returns. A green suite is worth exactly the fidelity of its doubles - in BOTH directions: one of these fakes was later found more CORRECT than the target, and another more permissive. +- **A default that passes the unknown breaks silently at the next version; one that refuses it breaks loudly.** The prohibition worth keeping is not on enumerating - it is on letting an unrecognised member through. Prefer decided-or-refused. + +Read through [[rules-allow-judgment]]. The sibling rule [[surface-mirrors-the-sdk]] covers the same gap at the level of CITATIONS (a true reference attached to a false claim); this one covers it at the level of RUNTIME. A claim you have run needs no hedging - the target is the claim nobody executed.