diff --git a/.tasks/doing/T01.h-refresh-the-nextgraph-packages.md b/.tasks/doing/T01.h-refresh-the-nextgraph-packages.md index 594b885..8803a1b 100644 --- a/.tasks/doing/T01.h-refresh-the-nextgraph-packages.md +++ b/.tasks/doing/T01.h-refresh-the-nextgraph-packages.md @@ -24,3 +24,72 @@ Once the surface work is done, bring `@ng-org/web`, `@ng-org/orm`, `@ng-org/shex ## Progress ## Result + +Status: done + +### The four version moves: NONE. All four were already at their latest published version. + +| package | declared before | latest published | moved | +|---|---|---|---| +| `@ng-org/web` | `0.1.2-alpha.14` | `0.1.2-alpha.14` | no | +| `@ng-org/orm` | `0.1.2-alpha.21` | `0.1.2-alpha.21` | no | +| `@ng-org/shex-orm` | `0.1.2-alpha.9` | `0.1.2-alpha.9` | no | +| `@ng-org/alien-deepsignals` | `0.1.2-alpha.13` | `0.1.2-alpha.13` | no | + +VERIFIED three ways: the `latest` dist-tag from a direct uncached `registry.npmjs.org` fetch, the full version list, and `pnpm outdated` (reports nothing for `@ng-org/*` in either workspace package). No `package.json` was touched, and nothing was pinned back - there was simply nothing newer to move to. The refresh this task was written for had already happened, earlier the same day, inside T01.d. + +**The `0.1.2` trap.** Three of the four (`web`, `shex-orm`, `alien-deepsignals`) also publish a bare `0.1.2`, which semver ranks ABOVE every `0.1.2-alpha.N`. It is a legacy release from 2025-10/2025-12; the alphas are from 2026. "Upgrading" to it would go back roughly a year. The exact pins in the `devDependencies` are what keep it out. `ng-e2e-helpers` declares the peer range `"@ng-org/web": ">=0.1.2-alpha.13"`, which DOES admit `0.1.2` - latent, since a peer is not auto-installed, but it is the one declaration in the tree that would accept the regression. + +### Breaking changes surfaced, and how each was reconciled + +The version bump surfaced none, because there was none. The install DID surface one thing, and the doctrine audit surfaced the rest. + +1. **The tree was bun-installed, not pnpm-installed.** Every `@ng-org` symlink under both workspace packages pointed into `node_modules/.bun/`, and that store still held `web@alpha.13`, `shex-orm@alpha.8` and `alien-deepsignals@alpha.11` beside the current ones. The resolved versions were correct, so the single-instance hazard was latent rather than active. Reconciled by `CI=true pnpm install --no-frozen-lockfile`, which re-pointed every symlink into `.pnpm/`. The lockfile did not move ("Lockfile is up to date"). The dead `.bun` store was left in place - it is an untracked artifact, and removing it was not asked for. + +2. **The doctrine's citation anchor is three orm releases behind the installed package.** This is the finding of the task. The pinned `nextgraph-rs` checkout `213338f6` declares orm `alpha.18` / web `alpha.13` / shex-orm `alpha.8` / alien-deepsignals `alpha.11`, while `packages/polyfill` compiles against `alpha.21/14/9/13`. Every leaf citing `sdk/js/orm/src/...` therefore describes a version this repo no longer uses. Reconciled by naming BOTH anchors wherever they disagree, rather than rewriting citations that would then be false for the commit they point at. + +### The four gates, verbatim + +- `bun test` -> `424 pass`, `0 fail`, `1162 expect() calls`, `Ran 424 tests across 39 files.` Baseline before any change was identical (`424 pass / 0 fail`), matching the figure recorded on this task. +- `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` (warnings only; the `broken [[...]] links - 1` warning present at baseline is now GONE) + +### The live measurements, against the real broker + +- `packages/polyfill/e2e/orm-live-read.ts` -> `ORM live-read summary: 5 passed, 0 failed, 5 declared - run 0.6 min`. The read is ready in 13ms and the delete reached the document. `5 declared` and not the `6` in the parent digest because the characterisation row was retired with the question it answered - the runner's own header records that, so this is not a lost row. +- `packages/polyfill/e2e/run.ts` -> `Polyfill e2e summary: 43 passed, 0 failed, 43 total - batch 3.2 min, slowest cold sync 26s`. + +### Doctrine leaves corrected, and the false fact each carried + +`app-contract/knowledge_what-the-orm-writes-and-deletes-upstream.md` +- announced `orm@alpha.19 / web@alpha.13 / alien-deepsignals@alpha.11` as installed - all three wrong +- "`core.ts` exports exactly `initNg, ngSession, OrmSubscription, DiscreteOrmSubscription, insertObject, getObjects`" - alpha.21 renames `OrmSubscription` to `RdfOrmSubscription` AND adds `removeObject`, so "exactly" was false +- `getOrCreate(shapeType, scope)` - alpha.21 takes an `RdfOrmConfig` (`Scope & {where?, orderBy?, pageSize?, maxActivePages?}`), and the instance gained `mode`, `isReady`, `addChangeListener`, `removeChangeListener`, `nextPage`, `previousPage` +- "a live ORM read still does not start against the deployment" - false, measured 5/5 today +- `[[bug_useshape-live-read-needs-a-newer-broker]]` - dangling, the leaf was deleted by the previous refresh + +`app-contract/knowledge_what-a-read-scope-is-upstream.md` +- "`Scope = { graphs?: ... }`" - `graphs` is REQUIRED in alpha.21; a caller that omitted it no longer compiles +- "`[]` or `undefined` returns no objects at all", stated of the type as a whole - true of `graphs`, FALSE of `subjects`, where `[]` means no filtering. Now a two-row table, because this is the trap the repo has already paid for once +- `OrmSubscription` / `connector/GraphOrmSubscription.ts` - both symbol and file renamed in alpha.21 + +`e2e-harness/knowledge_what-each-suite-judges.md` +- "It is EXPECTED to exit non-zero while the deployed broker and the published client packages disagree" plus a pointer to the deleted bug leaf - the runner is green now, and a red run means they have drifted apart again + +`contract_polyfill-surface.md` was checked and needed nothing: it already records `removeObject` at alpha.21 and the 2026-09-21 catch-up correctly. + +### The three out-of-scope follow-ups: none got worse + +- (a) `useShapeQuery` opens nothing named in `scope.graphs` - unchanged, scope still passed through untouched +- (b) `ensureReposOpen` dead - unchanged, still called only from its own test file +- (c) `examples/notebook/tsconfig.json` - still exactly `1 error TS2345`, the same `ShapeType` structural mismatch. Not worse + +### Surprises + +- **The task's premise did not hold: there was nothing to update.** VERIFIED. The work turned out to be the reconciliation half - the previous refresh moved the packages and left the doctrine behind. +- **The pinned source checkout is behind the installed packages.** VERIFIED (`nextgraph-rs` at `213338f6` declares orm `alpha.18`). This weakens every source citation in the concept leaves, and it is the structural version of the trap this task names: a fact read at the cited source can disagree with the package the code actually compiles against, exactly as a compile-time signature can disagree with the deployment. +- **`removeObject`'s own documentation contradicts itself.** VERIFIED from `connector/removeObject.d.ts`: it declares `DELETE WHERE { GRAPH { ?p ?o } }` - every predicate of the subject - while claiming in the same comment to have "the same effect" as a `delete()` on a subscription's object, which removes only the SHAPE's predicates. Nothing in the cited source settles which holds. Recorded in the leaf; it stays unpublished, per T01.e. +- **I nearly wrote a new false fact while fixing false facts.** I first wrote that alpha.21's `where`/`orderBy`/`pageSize` "became reachable from level 3". INFERRED from the JS surface alone, and the pinned engine refutes it: `Verifier::start_orm` still builds `OrmConfig::from_json(&json!({}))` behind a `// TODO`. Corrected before committing to say the richness is expressible at level 3 and discarded at level 1, and that measuring it is not done here. +- `playwright` is outdated in `ng-e2e-helpers` (`1.61.1` -> `1.63.0`). Out of scope - not one of the four packages. Reported, not touched. +- `pnpm-workspace.yaml` lists only `packages/*` while the root `package.json` `workspaces` also lists `examples/*`, so `examples/notebook` is outside pnpm's scope entirely. VERIFIED (`pnpm install` reports "all 3 workspace projects"). Plausibly related to follow-up (c); not investigated, not touched.