Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: T01 est close, la surface publiee est alignee

Browse Source
This commit is contained in:
Sylvain Duchesne
2026-09-28 14:08:54 +02:00
parent e0dcf93035
commit acdaf8b246
2 changed files with 7 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.tasks/INDEX.md
+2 -2
View File
@@ -2,7 +2,7 @@
_Generated from filesystem._ _Generated from filesystem._
## T01 Align the published surface on the NextGraph SDK - doing ## T01 Align the published surface on the NextGraph SDK - done
- T01.a A provenance annotation for a target announced but not yet written - done - T01.a A provenance annotation for a target announced but not yet written - done
- T01.b What the ORM offers for writing and deleting, and what the three remaining symbols are - done - T01.b What the ORM offers for writing and deleting, and what the three remaining symbols are - done
- T01.c watchShape becomes useShapeQuery and takes the SDK's Scope - done - T01.c watchShape becomes useShapeQuery and takes the SDK's Scope - done
@@ -18,4 +18,4 @@ _Generated from filesystem._
- T01.m There must be ONE answer to whether a document is open in this session - done - T01.m There must be ONE answer to whether a document is open in this session - done
- T01.n The polyfill's peer ranges exclude exactly the versions it needs - done - T01.n The polyfill's peer ranges exclude exactly the versions it needs - done
- T01.o The read filter is bypassed by plain properties, and no fake shows it - done - T01.o The read filter is bypassed by plain properties, and no fake shows it - done
- T01.p Four minor faults on the published surface - todo - T01.p Four minor faults on the published surface - done
.tasks/doing/T01-align-the-published-surface.md → .tasks/done/T01-align-the-published-surface.md
+5
View File
@@ -51,6 +51,10 @@ The polyfill's published surface has drifted from the SDK's: invented names, inv
- T01.o The read filter is bypassed by plain properties, and no fake shows it - T01.o The read filter is bypassed by plain properties, and no fake shows it
- T01.p Four minor faults on the published surface (deps: T01.o) - T01.p Four minor faults on the published surface (deps: T01.o)
## Result
The published surface now mirrors the SDK's names, parameters and returns, or carries an annotation that says why not and can be checked. Sixteen children, ten of them reviewed adversarially - the read path alone took six rounds before being split, and the rights leak the closing review found took five more. Two rights defects closed, both from the same cause: a written justification about a value nobody had executed, now the project rule `justify-a-return-value-by-running-it`. One item stays open and is the owner's: whether `ShapeObservable` survives migration.
## Learnings digest ## Learnings digest
- T01.a — the taxonomy gains `announced-not-written`: its `ref` points at the `.md` in THIS repo where the statement is on record, never a source file, plus `announced-by=<who>@<date>`. Upstream citations now resolve-check only when the sibling checkout is present; announced records always. Two latent defects fell out: the test's closed set was missing `reserved-name`, and the rule said "five kinds" over six rows. All 92 existing refs already resolved. - T01.a — the taxonomy gains `announced-not-written`: its `ref` points at the `.md` in THIS repo where the statement is on record, never a source file, plus `announced-by=<who>@<date>`. Upstream citations now resolve-check only when the sibling checkout is present; announced records always. Two latent defects fell out: the test's closed set was missing `reserved-name`, and the rule said "five kinds" over six rows. All 92 existing refs already resolved.
@@ -69,3 +73,4 @@ The polyfill's published surface has drifted from the SDK's: invented names, inv
- T01.n - the four `@ng-org` peer ranges fixed, VERIFIED BY RESOLUTION against the registry with the real node-semver engine rather than by reading. WORSE THAN THE TASK STATED: `@ng-org/orm`'s `"*"` admitted ZERO of its 22 published versions - that library publishes no bare `0.1.2` at all, so the range was UNSATISFIABLE, not merely wrong. The other three admitted exactly 1, the stale bare `0.1.2` of 2025, and excluded every alpha. After: web `>=0.1.2-alpha.14 <0.1.2` (2 admitted, maxSatisfying alpha.15), orm `>=0.1.2-alpha.21 <0.1.2` (2), shex-orm `>=0.1.2-alpha.9 <0.1.2` (2), alien-deepsignals `>=0.1.2-alpha.13 <0.1.2` (2). The floor was taken PER PACKAGE from its own devDependencies pin rather than copying the sibling package's `alpha.13` that the task offered as an example - that floor predates its own devDep bump and is a stale artifact, not a rule. `peerDependenciesMeta: optional` confirmed correct for all four and VERIFIED rather than assumed: every `@ng-org/*` reference in `packages/polyfill/src` is `import type` only, zero runtime imports, the application injecting the real functions through `bootstrap.ts`. `examples/notebook` gained the `typecheck` script it lacked. Fresh install ends with ONE `.pnpm` store entry per package and every consuming project's realpath matching. `462 pass / 0 fail`. It also caught an error of MINE: the task file I wrote carried a baseline of 449 while the measurement says 462 - written before T01.m added its tests and never refreshed. That is the second of my own specs to carry a wrong number, after T01.m's unachievable acceptance test. Left alone, reported: `ng-e2e-helpers`' own floor looks stale for the same reason (INFERRED, out of scope). - T01.n - the four `@ng-org` peer ranges fixed, VERIFIED BY RESOLUTION against the registry with the real node-semver engine rather than by reading. WORSE THAN THE TASK STATED: `@ng-org/orm`'s `"*"` admitted ZERO of its 22 published versions - that library publishes no bare `0.1.2` at all, so the range was UNSATISFIABLE, not merely wrong. The other three admitted exactly 1, the stale bare `0.1.2` of 2025, and excluded every alpha. After: web `>=0.1.2-alpha.14 <0.1.2` (2 admitted, maxSatisfying alpha.15), orm `>=0.1.2-alpha.21 <0.1.2` (2), shex-orm `>=0.1.2-alpha.9 <0.1.2` (2), alien-deepsignals `>=0.1.2-alpha.13 <0.1.2` (2). The floor was taken PER PACKAGE from its own devDependencies pin rather than copying the sibling package's `alpha.13` that the task offered as an example - that floor predates its own devDep bump and is a stale artifact, not a rule. `peerDependenciesMeta: optional` confirmed correct for all four and VERIFIED rather than assumed: every `@ng-org/*` reference in `packages/polyfill/src` is `import type` only, zero runtime imports, the application injecting the real functions through `bootstrap.ts`. `examples/notebook` gained the `typecheck` script it lacked. Fresh install ends with ONE `.pnpm` store entry per package and every consuming project's realpath matching. `462 pass / 0 fail`. It also caught an error of MINE: the task file I wrote carried a baseline of 449 while the measurement says 462 - written before T01.m added its tests and never refreshed. That is the second of my own specs to carry a wrong number, after T01.m's unachievable acceptance test. Left alone, reported: `ng-e2e-helpers`' own floor looks stale for the same reason (INFERRED, out of scope).
- T01.g - the closing review REFUTED the parent's success criterion, which is what it was for. 8 findings over 53 published symbols (not the 25 the orchestrator's naive grep counted - it measured export STATEMENTS), 41 clean. THE BLOCKING ONE IS A RIGHTS LEAK, and it is this batch's whole failure mode applied to access control: `read-filter.ts` returned non-function members RAW on the written ground that "a plain property carries no items" - true of the CITED tree (orm alpha.18, a bare `DeepSignalSet`), FALSE of the INSTALLED alpha.21, whose `useShape` returns a `UseShapeResult` carrying every identity's items on the plain properties `data`, `promise` and `subscription`. A stranger read the owner's data through all three and nothing threw. It became T01.o. Three majors: the contract instructed an injection that does not resolve (`@ng-org/orm`'s `.` maps to `core.d.ts`, which has no `useShape`); four present-tense claims that the SDK returns a bare `DeepSignalSet` are false of alpha.21, TWO of them load-bearing provenance grounds - the `readUnion` failure mode again, invisible to `provenance.test.ts` by construction; and the only live gate for the published `useShape` injects a HAND-WRITTEN substitute, so no fake in the repository returned the shipped shape, which is exactly why every gate was green. Four minors became T01.p. THE LESSON FOR THE ORCHESTRATOR, not the code: ten adversarial passes and every re-run gate of this batch were blind to this, because the only artifact exercising that path was a fake that had never been checked against what ships. A green suite is worth what its fakes are faithful to, and nobody had asked. - T01.g - the closing review REFUTED the parent's success criterion, which is what it was for. 8 findings over 53 published symbols (not the 25 the orchestrator's naive grep counted - it measured export STATEMENTS), 41 clean. THE BLOCKING ONE IS A RIGHTS LEAK, and it is this batch's whole failure mode applied to access control: `read-filter.ts` returned non-function members RAW on the written ground that "a plain property carries no items" - true of the CITED tree (orm alpha.18, a bare `DeepSignalSet`), FALSE of the INSTALLED alpha.21, whose `useShape` returns a `UseShapeResult` carrying every identity's items on the plain properties `data`, `promise` and `subscription`. A stranger read the owner's data through all three and nothing threw. It became T01.o. Three majors: the contract instructed an injection that does not resolve (`@ng-org/orm`'s `.` maps to `core.d.ts`, which has no `useShape`); four present-tense claims that the SDK returns a bare `DeepSignalSet` are false of alpha.21, TWO of them load-bearing provenance grounds - the `readUnion` failure mode again, invisible to `provenance.test.ts` by construction; and the only live gate for the published `useShape` injects a HAND-WRITTEN substitute, so no fake in the repository returned the shipped shape, which is exactly why every gate was green. Four minors became T01.p. THE LESSON FOR THE ORCHESTRATOR, not the code: ten adversarial passes and every re-run gate of this batch were blind to this, because the only artifact exercising that path was a fake that had never been checked against what ships. A green suite is worth what its fakes are faithful to, and nobody had asked.
- T01.o - THE RIGHTS LEAK IS CLOSED, after FIVE independent adversarial rounds. Delivered: two views (collection and result envelope) sharing one rule and one set of write traps in a single object so neither can be repaired without the other; DECIDED-OR-REFUSED as the default, which is the round-4 inversion - what the file has decided it serves is served, everything else refuses whatever its type; nine traps per view all routed through one `read` so `get`, descriptors, `has` and `ownKeys` cannot diverge; all three mutations gated on the same question with `add` additionally requiring the object to NAME a held document; every member `@ng-org/alien-deepsignals` declares non-mutating served over the readable items, pinned by a test that PARSES the shipped `dist/iteratorHelpers.js` and asserts a PARTITION (union equal, parts disjoint, exception set exactly one member) so neither a dropped member nor a smuggled second exception can pass. `1.0.0-dev.11`, `491 pass / 0 fail` exit 0, e2e exit 0 47/47, orm-live-read exit 0. WHAT THE FIVE ROUNDS FOUND, in order: three read leaks through plain properties; `add` returning the raw collection because `Set.prototype.add` returns `this`; the write side unsound plus 18 owner members broken by an over-broad refusal; a COUNT leaking through any member not spelled `size`/`length`, with the suite ASSERTING that as correct six lines above a test calling it the defect; and finally the record contradicting the code plus a gate that could not fail. THE CAUSE WAS ONE THING EVERY TIME - a justification about a value nobody executed: "a plain property carries no items" (true of the cited release, false of the built one), "the `get` trap is the read" (false for `getOwnPropertyDescriptor`), "they return void or a boolean" (false for `add`), "a primitive cannot reach an item" (false for a count), "upstream's `readOnlyArray` throws on `copyWithin`" (false - MEASURED: it runs and DESTROYS an element, while push/splice/sort/reverse/fill/shift all do throw, so refusing it is STRICTER than the target and is now recorded as a deliberate divergence), and the ECMAScript carve-out reasoning that the spec closes the KEY SET rather than the VALUE. Now a project rule, `justify-a-return-value-by-running-it`. TWO THINGS THE ORCHESTRATOR OWES: my own exit-code check read `$?` after a pipeline and measured `tail`, and every e2e figure I relayed before this task came off a SUMMARY LINE while the runner intermittently hangs after printing a clean verdict - pre-existing, now a named follow-up. AND THE STRUCTURAL LESSON: ten adversarial passes and every re-run gate were blind to the original leak because the only artifact exercising that path was a HAND-WRITTEN fake nobody had compared to the shipped shape - which then diverged twice more, once too correct (it fixed upstream's inverted `isLoading`), once too permissive (a plain array where `readOnlyArray` refuses). A green suite is worth exactly the fidelity of its doubles. Also recorded, unclosable: `console.log(result)` prints every identity's items from behind the proxy - host introspection no trap can prevent - so the contract now says not to inspect what a shape read hands you when several identities share a page. - T01.o - THE RIGHTS LEAK IS CLOSED, after FIVE independent adversarial rounds. Delivered: two views (collection and result envelope) sharing one rule and one set of write traps in a single object so neither can be repaired without the other; DECIDED-OR-REFUSED as the default, which is the round-4 inversion - what the file has decided it serves is served, everything else refuses whatever its type; nine traps per view all routed through one `read` so `get`, descriptors, `has` and `ownKeys` cannot diverge; all three mutations gated on the same question with `add` additionally requiring the object to NAME a held document; every member `@ng-org/alien-deepsignals` declares non-mutating served over the readable items, pinned by a test that PARSES the shipped `dist/iteratorHelpers.js` and asserts a PARTITION (union equal, parts disjoint, exception set exactly one member) so neither a dropped member nor a smuggled second exception can pass. `1.0.0-dev.11`, `491 pass / 0 fail` exit 0, e2e exit 0 47/47, orm-live-read exit 0. WHAT THE FIVE ROUNDS FOUND, in order: three read leaks through plain properties; `add` returning the raw collection because `Set.prototype.add` returns `this`; the write side unsound plus 18 owner members broken by an over-broad refusal; a COUNT leaking through any member not spelled `size`/`length`, with the suite ASSERTING that as correct six lines above a test calling it the defect; and finally the record contradicting the code plus a gate that could not fail. THE CAUSE WAS ONE THING EVERY TIME - a justification about a value nobody executed: "a plain property carries no items" (true of the cited release, false of the built one), "the `get` trap is the read" (false for `getOwnPropertyDescriptor`), "they return void or a boolean" (false for `add`), "a primitive cannot reach an item" (false for a count), "upstream's `readOnlyArray` throws on `copyWithin`" (false - MEASURED: it runs and DESTROYS an element, while push/splice/sort/reverse/fill/shift all do throw, so refusing it is STRICTER than the target and is now recorded as a deliberate divergence), and the ECMAScript carve-out reasoning that the spec closes the KEY SET rather than the VALUE. Now a project rule, `justify-a-return-value-by-running-it`. TWO THINGS THE ORCHESTRATOR OWES: my own exit-code check read `$?` after a pipeline and measured `tail`, and every e2e figure I relayed before this task came off a SUMMARY LINE while the runner intermittently hangs after printing a clean verdict - pre-existing, now a named follow-up. AND THE STRUCTURAL LESSON: ten adversarial passes and every re-run gate were blind to the original leak because the only artifact exercising that path was a HAND-WRITTEN fake nobody had compared to the shipped shape - which then diverged twice more, once too correct (it fixed upstream's inverted `isLoading`), once too permissive (a plain array where `readOnlyArray` refuses). A green suite is worth exactly the fidelity of its doubles. Also recorded, unclosable: `console.log(result)` prints every identity's items from behind the proxy - host introspection no trap can prevent - so the contract now says not to inspect what a shape read hands you when several identities share a page.
- T01.p - three items closed on the first pass, one BLOCKED correctly and then split. `Schema` and `DeepSignalSet` unpublished (VERIFIED unused by any published signature across `src`, `test`, `e2e` and `examples`), following the `ReadCap`/`InboxScope` precedent - MAJOR, `1.0.0-dev.12`. `docChangeType` joined the concept contract's `## Surface`, and that block is now PINNED by a test, verified by removing the export and watching it fail. The stray `@provenance` on `storeRegistry.resolveScopeGraph`, unpublished since `1.0.0-dev.5`, deleted. Item 2 - seven `kind=invention level=none ref=none` symbols above the polyfill-era divider - was blocked for the right reason (it decides what an application must DELETE at migration) and split into three: the five `EventuallyConfig` field types moved BELOW the divider after VERIFYING the precondition that `configure`/`EventuallyConfig` already sit there, a PATCH per the contract's own policy since no signature changed and neither doc ever listed them standalone, `1.0.0-dev.13`; `ShapeQuery` re-kinded from `invention` to `announced-not-written` because the record EXISTS and was checked, not assumed - `surface-mirrors-the-sdk.md` states the announced shape `{ data, isPending, isSuccess, isError, error }` field-for-field identical to the declared interface, so it now cites the same `announced-by=nextgraph-developers@2026-09-16` as `useShapeQuery`. STILL OPEN AND THE OWNER'S: `ShapeObservable` keeps `kind=invention level=none ref=none` while sitting ABOVE a divider that promises a target counterpart. That inconsistency is deliberate and unresolved - its `getSnapshot`/`subscribe`/`refetch` wrapper has no textual grounding in any announcement, so whether an application deletes it at migration is unknowable from this repository. Three fates are open: polyfill-era (below the divider), `announced-not-written` (needs a who and a when only the owner can attest), or an honestly labelled bet. Also confirmed and left alone: seven imports in `account-registry.ts` appear only in their import line, pre-existing, invisible to `tsc` because `noUnusedLocals` is off in both tsconfigs.