ng-eventually/.tasks/todo/T01.p-four-minor-surface-faults.md

id, title, parent, depends_on, created, claimed_by, claimed_at, blocked

id	title	parent	depends_on	created	claimed_by	claimed_at	blocked
T01.p	Four minor faults on the published surface	T01	T01.o	2026-09-24	T01p-agent	2026-09-24T18:50:06Z	true

Description

The four minor findings of T01.g, all CONFIRMED there. None is a rights or correctness defect; each is a published-surface or annotation inaccuracy. Verify each still stands before changing it - T01.o may have moved some.

1. Schema and DeepSignalSet are published with no published signature using them, against the rule stated at packages/polyfill/src/index.ts:78 (the same ReadCap/InboxScope rule, so this is a recurrence). Either a published signature uses them or they are unpublished.
2. Seven symbols annotated kind=invention level=none ref=none sit ABOVE the polyfill-era divider, under the heading that promises a target counterpart for every symbol (index.ts:45, :111-123). Either the annotation is wrong or they are on the wrong side of the divider.
3. docChangeType is published but absent from the concept contract's ## Surface, and nothing pins that block against the actual exports. Add it, and consider whether the block should be pinned by a test the way the deletion list already is.
4. account-registry.ts:971 annotates storeRegistry.resolveScopeGraph, unpublished since 1.0.0-dev.5. A provenance annotation on an unpublished symbol claims a surface that does not exist.

Hard gate: bun test -> 0 fail; both typechecks exit 0; python3 ~/.claude/skills/concept/lint.py -> 0 ERROR. Anti-cheat as usual. Any symbol you unpublish is a MAJOR by the contract's own change policy - follow it rather than deciding the level yourself.

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

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.