chore: T01.p bloque sur l-item 2, trois items sur quatre sont clos
Items 1, 3 et 4 verifies, corriges et commits separement. Item 2 (sept symboles invention/none/none au-dessus de la barriere polyfill-era) demande une decision de conception que la tache reservait explicitement a un humain - deux des sept symboles ont une reponse claire (ShapeQuery devrait etre re-annote, cinq types de champs de EventuallyConfig devraient descendre sous la barriere) mais ShapeObservable depend d-un fait que rien dans ce depot ne permet de verifier (la forme reelle du futur useShapeQuery annonce). Renvoyee en todo avec l-analyse complete pour eviter de la refaire.
This commit is contained in:
Sylvain Duchesne
@@ -4,9 +4,9 @@ title: Four minor faults on the published surface
|
|||||||
parent: T01
|
parent: T01
|
||||||
depends_on: [T01.o]
|
depends_on: [T01.o]
|
||||||
created: 2026-09-24
|
created: 2026-09-24
|
||||||
claimed_by: null
|
claimed_by: T01p-agent
|
||||||
claimed_at: null
|
claimed_at: 2026-09-24T18:50:06Z
|
||||||
blocked: false
|
blocked: true
|
||||||
---
|
---
|
||||||
|
|
||||||
## Description
|
## Description
|
||||||
@@ -22,4 +22,166 @@ The four minor findings of T01.g, all CONFIRMED there. None is a rights or corre
|
|||||||
|
|
||||||
## Progress
|
## Progress
|
||||||
|
|
||||||
|
Items 1, 3 and 4 verified, fixed and committed. Item 2 investigated in full but NOT
|
||||||
|
changed - it carries a design decision, exactly the case the task called out. Details
|
||||||
|
and the precise open question are in `## Result` below, so a resumer does not have to
|
||||||
|
redo the investigation - only decide the divider placement for the remaining symbols
|
||||||
|
and, if `ShapeQuery`/`ShapeObservable` are split as recommended, apply the annotation
|
||||||
|
fix and re-run `test/provenance.test.ts` and `test/vocabulary.test.ts`.
|
||||||
|
|
||||||
|
Commits made (chronological): `fix!:` unpublish Schema/DeepSignalSet + version bump to
|
||||||
|
`1.0.0-dev.12` (item 1); `docs:` add docChangeType to the concept contract's Surface and
|
||||||
|
pin the block with a new test (item 3); `fix:` drop the stray provenance annotation on
|
||||||
|
`resolveScopeGraph` (item 4).
|
||||||
|
|
||||||
## Result
|
## Result
|
||||||
|
|
||||||
|
**Status: blocked**
|
||||||
|
**Blocker:** Item 2 requires a design decision the task explicitly reserves for a
|
||||||
|
human - moving a symbol across the polyfill-era divider changes what an application is
|
||||||
|
told it must delete at migration, and the seven symbols split into cases with different,
|
||||||
|
non-mechanical answers (see below). Items 1, 3 and 4 are done, committed, and the hard
|
||||||
|
gate is green on the current state.
|
||||||
|
|
||||||
|
### Item 1 - Schema / DeepSignalSet (DONE)
|
||||||
|
|
||||||
|
VERIFIED by grep across `src`, `test`, `e2e`, `examples`: neither is used as an actual
|
||||||
|
TypeScript type anywhere in this repo outside the re-export itself (`DeepSignalSet` only
|
||||||
|
appears inside prose/JSDoc). Unpublished both from `packages/polyfill/src/index.ts`
|
||||||
|
(removed the `export type` lines and their `@provenance` annotations), following the
|
||||||
|
exact precedent already set for `ReadCap`/`InboxScope` - except neither has an internal
|
||||||
|
use to stay DEFINED for, so they are simply gone rather than moved to `model/types.ts`.
|
||||||
|
|
||||||
|
Checked the sibling task's note about `ShapeResult`: VERIFIED that `useShape` now
|
||||||
|
declares a literal `ShapeResult` return type (changed today, replacing `any`), but
|
||||||
|
`ShapeResult` staying unpublished is an EXISTING, DOCUMENTED, deliberate pattern (its own
|
||||||
|
comment in `model/types.ts:81-99` says "Same discipline as {@link OrmSubscriptionHandle}"
|
||||||
|
- a published call returning an unpublished, package-invented result type, matching the
|
||||||
|
contract's own `## Surface` entry `useShape(...): ShapeResult`). This does not violate
|
||||||
|
the rule at `index.ts:78` (which is one-directional: a published TYPE needs a published
|
||||||
|
signature using it - not the reverse). Concluded this does NOT belong in item 1; no
|
||||||
|
change made.
|
||||||
|
|
||||||
|
This is a MAJOR (published symbol removed). Version bumped `1.0.0-dev.11` ->
|
||||||
|
`1.0.0-dev.12` in `packages/polyfill/package.json`, a new dated entry added to the
|
||||||
|
concept contract's `## Change policy`, and `docs/api-contract.md` updated (the "Today"
|
||||||
|
code block in §4, the §14 ruling with a new paragraph matching the ReadCap/InboxScope
|
||||||
|
one, and the appendix's `direct:` inventory line) - in the SAME commit as the code
|
||||||
|
change.
|
||||||
|
|
||||||
|
### Item 2 - seven `invention/none/none` symbols above the divider (BLOCKED, not changed)
|
||||||
|
|
||||||
|
VERIFIED the exact seven, by grepping every `kind=invention level=none ref=none`
|
||||||
|
annotation in `src` and checking which are published above the `POLYFILL-ERA` divider in
|
||||||
|
`index.ts`: `NgLike`, `UseShapeLike`, `OrmSubscriptionLike`, `GetObjectsLike`,
|
||||||
|
`InsertObjectLike` (all in `model/types.ts`, all typing fields of `EventuallyConfig`) and
|
||||||
|
`ShapeQuery`, `ShapeObservable` (both in `surface/use-shape-query.ts`, the return shape of
|
||||||
|
`useShapeQuery`).
|
||||||
|
|
||||||
|
They do NOT all resolve the same way:
|
||||||
|
|
||||||
|
- **The five `EventuallyConfig` field types.** Each one's own comment says it "exists
|
||||||
|
only to describe what `configure` receives" - and `configure`/`EventuallyConfig` are
|
||||||
|
themselves already, unambiguously, on the deletion list (`knowledge_what-an-app-deletes-
|
||||||
|
at-migration.md`: "Deleted... today that is `configure` and its config type"). Their
|
||||||
|
`invention/none/none` annotation is honest (no kind in the closed set fits better).
|
||||||
|
INFERRED, with strong textual support: these five belong BELOW the divider, beside
|
||||||
|
`EventuallyConfig` - but moving them is the exact action the task names as requiring a
|
||||||
|
decision, so left untouched.
|
||||||
|
- **`ShapeQuery`.** VERIFIED: its declared shape - `{ data, isPending, isSuccess,
|
||||||
|
isError, error }` - is the LITERAL shape `.project/rules/nextgraph/surface-mirrors-the-
|
||||||
|
sdk.md` records as NextGraph developers' announced direction for `useShapeQuery`
|
||||||
|
(the same document `useShapeQuery` itself cites with `kind=announced-not-written`). The
|
||||||
|
word "ShapeQuery" appears in that record. Its `invention/none/none` annotation looks
|
||||||
|
like the wrong kind - `announced-not-written`, citing the same record, would be
|
||||||
|
consistent and would keep it above the divider with no relocation. Not applied: still a
|
||||||
|
change to a load-bearing annotation on a currently-blocked item, held for the same
|
||||||
|
decision.
|
||||||
|
- **`ShapeObservable`.** VERIFIED: the word "ShapeObservable" does NOT appear anywhere in
|
||||||
|
the announcement record, and VERIFIED in `examples/notebook/app.ts:192-217` that this
|
||||||
|
package's `useShapeQuery` is called as a plain factory (not a React hook) returning an
|
||||||
|
object the caller manually `.subscribe()`s and `.getSnapshot()`s - i.e. the
|
||||||
|
getSnapshot/subscribe/refetch wrapper is this package's OWN framework-agnostic
|
||||||
|
composition, not something NextGraph announced. Its `invention/none/none` annotation is
|
||||||
|
therefore honest. Whether this wrapper is deleted at migration (if the real,
|
||||||
|
eventually-shipped `useShapeQuery` is itself a plain hook returning the snapshot
|
||||||
|
directly, the way `useShape` does) or survives (if the real one needs the same kind of
|
||||||
|
wrapper) cannot be determined from anything in this repo - this is the irreducible
|
||||||
|
design question.
|
||||||
|
|
||||||
|
No code or annotation changed for item 2. Recommend, for whoever picks this up: decide
|
||||||
|
`ShapeObservable`'s fate first (it decides how much of the divider question is even
|
||||||
|
open), then decide the five `EventuallyConfig` field types (probably move, per the
|
||||||
|
argument above) and `ShapeQuery` (probably re-annotate `announced-not-written`, per the
|
||||||
|
argument above) as two smaller, more mechanical follow-ups.
|
||||||
|
|
||||||
|
### Item 3 - docChangeType absent from the concept contract's Surface (DONE, and pinned)
|
||||||
|
|
||||||
|
VERIFIED: `docChangeType` (lowercase, the function) is exported from `index.ts` but was
|
||||||
|
absent from `.project/concepts/app-contract/polyfill-surface/contract_polyfill-
|
||||||
|
surface.md`'s `## Surface` block. Also VERIFIED that `docs/api-contract.md` (a separate,
|
||||||
|
still-actively-maintained document at the repo root, distinct from the concept contract -
|
||||||
|
see Surprises) already had it correctly, and is pinned by three existing tests in
|
||||||
|
`test/vocabulary.test.ts`; the concept contract had NO such test.
|
||||||
|
|
||||||
|
Added the `docChangeType` signature to the concept contract's Surface block, and added a
|
||||||
|
new test, `"every 'export' shown in the concept contract's Surface block is actually
|
||||||
|
exported"`, reusing the same `publishedNames()`/`isNamespaceMember()` helpers the
|
||||||
|
existing `docs/api-contract.md` check uses. VERIFIED the new test actually catches drift:
|
||||||
|
temporarily removed `docChangeType` from `index.ts`'s export list, re-ran the suite, saw
|
||||||
|
it fail naming exactly `docChangeType`, then restored the file and confirmed green again
|
||||||
|
(diff checked against the original afterward - clean revert).
|
||||||
|
|
||||||
|
### Item 4 - stray provenance annotation on resolveScopeGraph (DONE)
|
||||||
|
|
||||||
|
VERIFIED: `resolveScopeGraph` is not re-exported by `surface/placement.ts` (which backs
|
||||||
|
the published `storeRegistry` namespace), so `storeRegistry.resolveScopeGraph` names
|
||||||
|
nothing a consumer can reach - confirmed unpublished since `1.0.0-dev.5` per
|
||||||
|
`surface/placement.ts`'s own comment. VERIFIED its two siblings, `resolveWriteGraph` and
|
||||||
|
`listMyEntityDocs` (same file, same unpublished status), carry NO `@provenance`
|
||||||
|
annotation at all - the established convention for internal/unpublished helpers. Removed
|
||||||
|
the stray `@provenance storeRegistry.resolveScopeGraph ...` line to match; left the JSDoc
|
||||||
|
comment above it untouched (still an accurate internal note). No test previously caught
|
||||||
|
this because `test/provenance.test.ts` only checks that every PUBLISHED symbol has an
|
||||||
|
annotation, never the reverse (an annotation naming something that isn't published) -
|
||||||
|
this is a real, un-pinned gap in that test file, left as a follow-up (see below).
|
||||||
|
|
||||||
|
### Gate (all measured on the final committed state)
|
||||||
|
|
||||||
|
- `bun test` -> **exit 0**, `492 pass / 0 fail` (baseline was `491 pass / 0 fail`; +1 is
|
||||||
|
the new pinning test from item 3).
|
||||||
|
- `pnpm exec tsc --noEmit -p packages/polyfill/tsconfig.json` -> **exit 0**.
|
||||||
|
- `pnpm exec tsc --noEmit -p packages/polyfill/e2e/tsconfig.json` -> **exit 0**.
|
||||||
|
- Example typecheck (`pnpm run typecheck` in `examples/notebook`) -> **exit 0**.
|
||||||
|
- `python3 ~/.claude/skills/concept/lint.py` -> **exit 0**, `0 ERROR` (5 pre-existing
|
||||||
|
WARNING categories, none new).
|
||||||
|
- e2e harness: NOT run. Nothing touched by items 1/3/4 is exercised by it (type-only
|
||||||
|
exports, doc text, a new `bun:test` unit test, one dead annotation line); item 2 made
|
||||||
|
no change at all.
|
||||||
|
|
||||||
|
### Surprises
|
||||||
|
|
||||||
|
- **VERIFIED, corrected before acting on it:** `docs/api-contract.md` genuinely exists at
|
||||||
|
the repo root and is actively maintained (last touched today by the sibling task, T01.o)
|
||||||
|
- I initially looked only under `packages/polyfill/docs/` (which holds a different file,
|
||||||
|
`polyfill-reference.md`) and briefly concluded the file referenced by `index.ts`'s header
|
||||||
|
comment and by `test/vocabulary.test.ts` was missing/stale. It is not. Two contract
|
||||||
|
documents exist side by side: `docs/api-contract.md` (detailed, symbol-by-symbol, pinned
|
||||||
|
by three tests) and the concept contract (terser, what a consumer's `usage_` leaf pulls
|
||||||
|
against, now pinned by one more test after item 3).
|
||||||
|
- **INFERRED, not verified, out of scope:** the two documents' dual maintenance is itself
|
||||||
|
a standing cost (item 3 is exactly this: one drifted, one didn't) - not something this
|
||||||
|
task was scoped to resolve.
|
||||||
|
|
||||||
|
### Follow-ups (not fixed, out of scope)
|
||||||
|
|
||||||
|
- `test/provenance.test.ts` has no test for the direction item 4 exposed: an
|
||||||
|
`@provenance` annotation naming a symbol that is not actually published. Only the
|
||||||
|
reverse (every published symbol has an annotation) is pinned.
|
||||||
|
- Several `docs/api-contract.md` / `index.ts` header comments cite line numbers (e.g.
|
||||||
|
"index.ts:48-49", "index.ts:45, :111-123") rather than symbols, which the project's own
|
||||||
|
citation discipline discourages (line numbers rot); pre-existing, not introduced here,
|
||||||
|
and not mechanically checked.
|
||||||
|
- `.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md` is
|
||||||
|
flagged by the concept linter as an oversized leaf (75 KB / 256 lines) - pre-existing,
|
||||||
|
a WARNING not an ERROR, unrelated to this task's changes beyond the ~10 lines added.
|
||||||
|
|||||||
Reference in New Issue
Block a user