ng-eventually/.tasks/todo/T01-align-the-published-surface.md

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

id	title	parent	depends_on	created	claimed_by	claimed_at	blocked
T01	Align the published surface on the NextGraph SDK	null		2026-09-16	null	null	false

Description

The polyfill's published surface has drifted from the SDK's: invented names, invented parameters, and symbols with no upstream counterpart. This task brings it back and installs what stops it recurring.

The principle to apply — .project/rules/nextgraph/surface-mirrors-the-sdk.md, and its semantic sibling no-divergence-from-nextgraph.md. Publish the SDK's names, parameters and return values; a difference must be duly justified beside the code, and the best justification is that it is NextGraph's own direction as announced by its developers.

The facts this rests on — .project/concepts/app-contract/knowledge_what-a-read-scope-is-upstream.md. In particular: a graphs entry is one document's graph; a store's graph holds only its containment triples, so "search my private store" returns empty silently; did:ng:i means the whole local dataset with no permission narrowing; scoping a read by store is not expressible at all.

Four pieces of work:

1. watchShape becomes useShapeQuery, takes the SDK's Scope ({ graphs?, subjects? }) instead of the three literals "public" | "protected" | "private", and reads through the SDK's shape query instead of enumerating documents. The ShapeQuery return shape (TanStack-like) and the capability filter both stay — that difference is the justified kind.
2. Wrap the ORM family the polyfill does not expose: getObjects and insertObject at identical signatures with the rights filter; arbitrate OrmSubscription, DiscreteOrmSubscription, ngSession; establish upstream's shape for deletion before specifying it. Today an application must import them straight from @ng-org/orm, and then receives every identity's data from the shared wallet with nothing signalling it — a rights hole, not a missing convenience.
3. Remove readUnion entirely once nothing internal calls it. Three single-document reads become an anchored SPARQL query. ng-helpers' contract cites it and must be revised.
4. The annotation mechanism: a mandatory reference on every function, which must resolve; plus a form for "target announced by the developers, not yet written", which the current format cannot express — so an author holding the strongest justification is pushed to miscite or to understate.

Boundary that must not be lost: the store axis survives for creation (docCreate takes a destination upstream) and dies for reading.

Success criteria: every published symbol either mirrors an SDK symbol in name, parameters and return, or carries a justified annotation; no symbol without an upstream counterpart survives unjustified; gates green (bun test, both typechecks, lint.py 0 ERROR, e2e); and an adversarial review over the whole published surface finds nothing unaddressed.

Progress

Result

Subtasks

• T01.a A provenance annotation for a target announced but not yet written
• T01.b What the ORM offers for writing and deleting, and what the three remaining symbols are (reconnaissance)
• T01.c watchShape becomes useShapeQuery and takes the SDK's Scope (deps: T01.a)
• T01.d useShapeQuery reads through the SDK's shape query (deps: T01.c)
• T01.e Publish the ORM family with the rights filter (deps: T01.b, T01.d)
• T01.f Remove readUnion, and the documents that cite it (deps: T01.e)
• T01.g Adversarial review of the whole published surface (deps: all)

Learnings digest