feat: l-ecart entre l-arbre cite et la version compilee devient une tache

2026-09-21 14:34:29 +02:00
parent 5d2899157f
commit 55c918dd4b
4 changed files with 57 additions and 3 deletions
@@ -43,6 +43,7 @@ The polyfill's published surface has drifted from the SDK's: invented names, inv

 - T01.i Clear two mechanical leftovers from the removal (deps: T01.h)
 - T01.j A read that cannot reach its document must fail, not answer empty (deps: T01.i)
+- T01.k A provenance citation must say which version it describes (deps: T01.i)

 ## Learnings digest

@@ -4,8 +4,8 @@ title: Clear two mechanical leftovers from the removal
 parent: T01
 depends_on: [T01.h]
 created: 2026-09-21
-claimed_by: null
-claimed_at: null
+claimed_by: worker-agent
+claimed_at: 2026-09-21
 blocked: false
 ---

@@ -2,7 +2,7 @@
 id: T01.g
 title: Adversarial review of the whole published surface
 parent: T01
-depends_on: [T01.a, T01.b, T01.c, T01.d, T01.e, T01.f, T01.h, T01.i, T01.j]
+depends_on: [T01.a, T01.b, T01.c, T01.d, T01.e, T01.f, T01.h, T01.i, T01.j, T01.k]
 created: 2026-09-16
 claimed_by: null
 claimed_at: null
@@ -0,0 +1,53 @@
+---
+id: T01.k
+title: A provenance citation must say which version it describes
+parent: T01
+depends_on: [T01.i]
+created: 2026-09-21
+claimed_by: null
+claimed_at: null
+blocked: false
+---
+
+## Description
+
+The provenance mechanism cites a source tree that is THREE RELEASES BEHIND what this repo compiles against, and nothing in an annotation says so. A citation therefore proves "this was true at orm alpha.18", while a reader takes it for "this is true of what we build against".
+
+### The established facts - VERIFIED, do not re-derive
+
+Scanning every remote branch of `/home/sylvain/projects/nextgraph/nextgraph-rs`:
+
+| source | `@ng-org/orm` version |
+|---|---|
+| `upstream/main` (the real upstream) | `0.1.2-alpha.18` |
+| `origin/main` (a fork) | `0.1.2-alpha.15` |
+| local checkout HEAD `213338f6` | `0.1.2-alpha.18` |
+| what this repo compiles against | `0.1.2-alpha.21` |
+
+So the local checkout is ALREADY at the newest source that exists anywhere reachable. alpha.19, 20 and 21 are published to npm from source that is in no branch of that repository. **There is nothing to re-anchor to, and updating the checkout is not the answer.** Do not spend time looking for a newer tree; that question is closed.
+
+`grep -rho "ref=[^ ]*" packages/polyfill/src/ | grep -cE "engine/|sdk/"` counts 96 citations into that tree.
+
+### The second-order trap, which has already fired
+
+A claim about alpha.21 REFUTED by reading the pinned tree is refuted against alpha.18 - which is not the same statement. This happened during T01.h: the agent first wrote that alpha.21's `where`/`orderBy`/`pageSize` "became reachable", then retracted it because the pinned engine still has `start_orm` as `json!({})` behind a TODO. The retraction may be right, but the EVIDENCE does not support it at the strength claimed, because the pinned engine is not alpha.21. **Re-examine that specific correction** in `.project/concepts/app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md` and state what can honestly be said about it. A true citation attached to a claim it does not support is the exact failure `.project/rules/nextgraph/surface-mirrors-the-sdk.md` names.
+
+### What to establish - the design is yours
+
+The question is where the version belongs, and the obvious economy is worth weighing before anything else: **the version is a property of the CHECKOUT, not of each citation.** 96 annotations do not each need to carry it; one place that says "citations into `engine/` and `sdk/` are anchored at `213338f6` = orm alpha.18, while the build is alpha.21" may carry the whole fact. Weigh that against the alternative, do not assume it.
+
+Then decide what the mechanism should ENFORCE, if anything. `packages/polyfill/test/provenance.test.ts` already checks that a `ref` resolves when the sibling checkout is present, and deliberately does NOT check that a claim is true. Adding a version check is a real option; so is deciding that this is doctrine, not a test. Read `.project/rules/nextgraph/no-divergence-from-nextgraph.md` for the taxonomy before proposing anything, and remember `announced-not-written` already exists for "the target is stated but the tree carries nothing" - part of this gap may be the same shape.
+
+**Do NOT mass-rewrite 96 annotations** unless you have established that the fact cannot be carried in one place. A 96-site sweep is a large, risky, low-information change, and this repo's doctrine is explicitly that a good repair usually leaves a leaf SHORTER.
+
+**Where a citation genuinely describes something that alpha.21 changed**, that is a real finding: record it. But establish it from the published package's own shipped types (`node_modules/@ng-org/orm`), not by guessing - and say plainly when the shipped artifact cannot settle the question, which it often will not since it carries types, not behaviour.
+
+### Verification
+
+**Hard gate:** `bun test` -> 0 fail; `bunx tsc --noEmit -p packages/polyfill/tsconfig.json` -> exit 0; `bunx tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> exit 0; `python3 ~/.claude/skills/concept/lint.py` -> 0 ERROR. Anti-cheat: no `any`, no `@ts-ignore`, no deleted or skipped test, no weakened assertion.
+
+**An adversarial review is part of this task.** Angles: a citation that still claims more than its anchor supports; a version statement that is itself already stale; and whether whatever is added would survive the checkout moving. A finding counts only with a concrete scenario.
+
+## Progress
+
+## Result