Settle what interchangeability means, and ask for what is missing

Opens the brief that holds this binding to `@activitypods/refine-providers`,
with which it must be interchangeable, and settles its six questions. The
decisive finding of the comparison: the reference asks its server for almost
none of what a Refine resource needs — filters, sorting, pagination and
totals are computed in memory there too — so most of the gap is this
package's own work rather than the polyfill's.

What the engagement is now asked for, in order: a shape-typed write and
removal that can be awaited outside React, a call that closes a session, a
display name, and a write-ownership predicate that would let an interface
hide a control instead of letting it fail.

Two corrections worth their own mention, both found by review rather than
by reading further:

- a non-guarantee about how strongly the upstream authenticates was being
  allowed to dictate the SHAPE of this binding, which had `login` and
  `logout` published as having no surface. Opening a wallet is the act the
  target will have, so the auth provider is wired to it and the missing
  closing call is a request, not an absence of analogue;
- what is internal to the emulation must not be known in this repository at
  all. Restating it here would duplicate a claim this package cannot verify
  and would teach an application a distinction that disappears at migration.

.project/concepts/refine-binding/_overview.md

@@ -2,7 +2,7 @@
 type: overview
 summary: How a Refine application's resources are bound to NextGraph documents through the eventual SDK — and what that binding may rely on
 triggers:
-  keywords: [refine, provider, dataProvider, authProvider, liveProvider, resource, getList, getOne, shapeTypes, shape, scope, store, polyfill, eventually]
+  keywords: [refine, provider, dataProvider, authProvider, liveProvider, accessControlProvider, resource, getList, getOne, shapeTypes, shape, scope, store, polyfill, eventually, activitypods, interchangeable, equivalence]
   paths:
     - "src/**"
     - "package.json"
@@ -25,3 +25,4 @@ The distinguishing rule: **nothing here compensates for the current state of Nex
 
 - `polyfill-surface/contract_polyfill-surface` — the engagement this package consumes (pulled, version-pinned).
 - `polyfill-surface/usage_refine-providers-eventually` — what this package actually relies on, and what it still needs.
+- `brief_2026-10-01_interchangeability-with-activitypods` — the bar this binding is held to, and the questions still open on it.

.project/concepts/refine-binding/brief_2026-10-01_interchangeability-with-activitypods.md

@@ -0,0 +1,73 @@
+---
+type: brief
+summary: What "interchangeable with @activitypods/refine-providers" has to mean for this binding — what the adapter owes, what waits on the polyfill, and what has no analogue at all
+---
+
+# Interchangeability with `@activitypods/refine-providers`
+
+## The bar
+
+This package is held to being **at least as capable as `@activitypods/refine-providers`**, because the two sets of providers must be interchangeable: an application should move from one to the other without rewriting its pages. That reference (v0.1.5, same author, a structural twin of `@ng-org/refine-providers`) is therefore the specification of what must work — not the `DataProvider` interface in the abstract, and not the NextGraph sibling, which is thinner than both.
+
+Interchangeability is claimed on **what an application can call and render**. Each binding gets its authentication from what it sits on — the reference from a Pod provider, this one from the engagement it consumes — and how far either goes is that provider's business, not this package's. Nothing about either mechanism belongs in this repository: a binding that reasoned about its upstream's internals would hold knowledge it cannot verify, that drifts when the upstream moves, and that its own consumers would have to unlearn.
+
+## What the adapter owes, and can deliver alone
+
+The decisive finding of the comparison: the reference asks its server for almost none of this. Containers support no server-side filtering, sorting or pagination, so it fetches the whole container and computes in memory. That is the same posture available here, which moves most of the gap off the polyfill and onto this package.
+
+| | the reference | here |
+|---|---|---|
+| Filters | every Refine operator, plus nested `and`/`or`, in memory, case-insensitive by default with sensitive variants | the same, over the read result — the NextGraph sibling honours `eq` only and warns on the rest |
+| Sorting, pagination, `total` | in memory, over the whole container | the same, over the whole shape read |
+| `getMany` | one read per id, `allSettled`, keeps what answered | one read per document — which also sidesteps the all-or-nothing of naming several documents at once |
+| Live | one subscription per record (`Update`/`Delete`), one on the container (`Add`/`Remove`); **list views never see a member's own fields change**, a limit it documents | one subscription per document, over the documents a read hands back — `subscribeDoc` is the guaranteed channel. A diff of shape-query snapshots would be the elegant route and must NOT be assumed: the engagement promises a re-publication when a **capability arrives**, and nowhere when a held document's **content** changes |
+
+## What waits on the polyfill
+
+`update` and `deleteOne`. The reference serves both as ordinary awaited calls — a read-then-merge `PUT`, and a `DELETE`. Here no published call is both shape-typed and awaitable: removal goes through the live set a shape query hands back, reachable only from a React hook, and a mutation of that set is batched into a call nothing awaits. Refine requires a promise that resolves with the record or rejects.
+
+This is the one gap with no caller-side answer, and it is declared in `polyfill-surface/usage_refine-providers-eventually.md`, with the ownership predicate an edit control would need to know whether to show itself.
+
+**And deletion is deeper than a missing call.** The engagement publishes no removal of any kind, and describes what a removal through the live set does take away: the predicates the shape declares, while the subject, the document and every key already handed out survive. So on this surface `deleteOne` cannot make a record absent the way the reference's `DELETE` does — a bookmarked show page renders an empty record instead of a missing one. Calling this "a missing call" understates it; what it needs is a published meaning for deletion, which is question 5 below.
+
+## What has no analogue
+
+The reference's auth provider is not only authentication. It carries **delegated access consent**: an application registers itself against the person's Pod, declares the access it needs, and is sent to an authorization agent for approval — `registerApp()`, `getAppStatus()`, `upgradeNeeded`, a periodic re-check, and two antd components (`AntdAuthPage`, `AntdBackgroundChecks`).
+
+The engagement publishes nothing of the kind, and places user management outside its `## Scope` — so there is no surface here to bind such a flow to, and none to be asked for: what the eventual SDK will do about application consent is not something this leaf can know, and guessing it is how a binding ends up teaching a model that never arrives. The question is therefore what THIS package answers when an application calls those two methods, not what the platform ought to provide.
+
+**`logout` DOES have an analogue — what is missing is the call.** This is worth stating carefully, because getting it wrong is how a binding teaches a model that will not exist. In the target each person opens their own wallet, so an open wallet IS the authenticated state, and closing it is the sign-out; `ensureIdentity()` is the emulation of the first act, and this binding must be wired to it as such — `check()` asks whether an identity is settled, `getIdentity()` asks who, `logout()` closes. That shape survives migration unchanged.
+
+What does not exist yet is any published way to perform the closing: the engagement names "changing identity or clearing it" as an event that occurs, and offers no call that causes it. So an application that switches bindings keeps its Logout button and it stops protecting anything — the barrier comes back prefilled, one click re-enters the identity that just left, and `ensureIdentity()` shows no barrier at all. That is a NEED (declared), not an absence of analogue, and until it is served this binding's `logout` can only clear what it holds itself and say so.
+
+## Open questions
+
+~~1. What does "interchangeable" cover?~~ **SETTLED (2026-10-01): the pages and the providers' surface — not the antd components.**
+
+The three providers expose the same methods as the reference, `registerApp`, `getAppStatus` and `handleCallback` included, in a degenerate behaviour: there is nothing to register, so registering resolves at once and the status reads installed and up to date. Each binding keeps its own bootstrap — this one needs `configure` and an awaited `ensureIdentity()` before the interface renders — and no antd component is published here: the polyfill's own barrier leaves a login page almost nothing to do, and a gate component nothing to gate.
+
+**What decided it was the reverse direction.** "Interchangeable" is symmetric, and an application written here and later moved to ActivityPods must have registered itself to read anything there. Without the method it never called it, and the failure lands in the other binding, silently, caused by a surface missing from this one. Exposing it means an application calls it by construction.
+
+**How the degenerate answer must be worded.** "Nothing to register" describes THIS package: the engagement publishes no application registration, so there is nothing here to register. It says nothing about the platform, and nothing about what the eventual SDK will do with application consent. The engagement this package publishes will present these three as **compatibility, never capability** — a published member that describes no mechanism is honest only if it says so.
+~~2. Where does a display name come from?~~ **SETTLED (2026-10-01): raised upstream; the identifier stands in meanwhile.**
+
+The sibling binding offered no lead — its `getIdentity` returns a hard-coded name and a stock photo, so the question was never faced there. Inventing a profile shape here would be a convention of this package's own, which an application would have to unlearn the day the SDK publishes one, so it is declared as a need instead (an ask to widen a scope that excludes display names, justified by a caller having no conforming option: the identifier may not be rendered as a name, and no name is offered). Until it is answered, `getIdentity` returns the identifier in the `name` field — the same stand-in the reference falls back to when a profile cannot be read.
+~~3. How is the authentication difference stated?~~ **SETTLED (2026-10-01): nowhere — the question was wrongly posed.**
+
+It assumed this package has something to say about how strongly its upstream authenticates. It does not: it receives an authentication and wires Refine to it. How that authentication is established, and what it is worth today, belongs to the engagement and to its own `## Non-guarantees`, where a consumer of this package reads it directly. Restating it here would duplicate a claim this package cannot verify, would drift the moment the upstream moves, and would teach an application a distinction that disappears at migration. The point stands for the whole repository, not just this leaf: **what is internal to the emulation must not be known here.**
+~~4. Does `check()` honour `allowAnonymous`?~~ **SETTLED (2026-10-01): the option is not published; `check()` fails closed.**
+
+It follows from question 1 rather than needing its own arbitration: `allowAnonymous` is a field of the reference's `AuthProviderConfig`, and the bootstrap is the part each binding keeps for itself — `clientId`, `redirectUri` and `appStatusCheckInterval` have no object here either. What belongs to the interchangeable surface is the behaviour of `check()`, and there is no anonymous state for it to allow: an identity is settled before the interface renders, or the call that settles it rejected. So `check()` answers unauthenticated and redirects to the login route when no identity is settled — the reference's own default when the option is absent.
+
+~~5. What should a listing contain?~~ **SETTLED (2026-10-01): everything accessible of that shape, and this package filters nothing.**
+
+A listing is `getObjects(shapeType, { graphs: "" })` and that is the whole of it. The surface already returns only what the identity holds the key for, so the filtering a Refine resource needs is the one already performed on the way out — there is nothing for this package to add, decide or restrict, and it must not invent a narrower notion of "mine" on top of a surface that already answers the question.
+
+Two consequences follow, both accepted rather than worked around:
+
+- **A listing mixes records that can be written with records that can only be read.** The default path is therefore to let the person act and surface the refusal, exactly as any failed mutation surfaces — which needs the awaitable write, not a predicate. The ownership predicate stays requested, demoted from "required" to a comfort: it lets an interface hide a control instead of letting it fail, and it blocks nothing.
+- ~~6. Does browsing grow a resource?~~ **Yes, and that is the intended behaviour.** Opening a public document by its `reference` puts its key in what the identity holds, so it joins later listings of that shape. A listing reflects what is accessible; it is not an inventory this package curates.
+
+## To graduate
+
+**Every question is settled.** This brief is ready to graduate: the inventory becomes the engagement's `## Scope` and `## Non-guarantees`, the six settled answers become entries there (question 1's three compatibility members, question 5's definition of a listing, question 4's `check()`), and the brief is deleted once they are written. The engagement itself still waits on what the declaration asks of the polyfill — an engagement promises only what it can hold. Then this brief splits — the inventory above becomes the engagement's `## Scope` and `## Non-guarantees`, the settled question 1 and the answer to 3 become entries there, and what remains of 2 and 4 becomes either a `decision_` or an engagement entry.

.project/concepts/refine-binding/polyfill-surface/usage_refine-providers-eventually.md

@@ -1,7 +1,7 @@
 ---
 type: usage
 summary: Binds a Refine application's resources to NextGraph documents — one shape per resource, one document per entity — through this engagement's shape reads, its shape-typed insert and its inbox
-against: 4c1801f6ee1dba0ce193e693960a6788686d602e
+against: '@ng-eventually/polyfill@1.0.0-dev.15 (tag polyfill/v1.0.0-dev.15, commit ec3900077bfd090f5388e52b47a8132b2fc68d16)'
 ---
 
 # usage_refine-providers-eventually — `@ng-eventually/refine-providers`
@@ -10,7 +10,7 @@ This package is a set of [Refine](https://refine.dev/core/) providers — `dataP
 
 It carries no compensation for the current state of NextGraph. Capability isolation, identity, inboxes, sharing, broker state: all of that is this engagement's. What this package does is translate — a Refine resource is one SHEX shape, a Refine `id` is the NURI of one document, and one document holds one business entity.
 
-The pinned version is the engagement's own `1.0.0-dev.14`, reached through the branch it is authored on rather than a tag — see `## Frictions`.
+The pinned version is `1.0.0-dev.15`, through the tag `polyfill/v1.0.0-dev.15` that carries it.
 
 ## Consumed surface
 
@@ -21,7 +21,9 @@ The pinned version is the engagement's own `1.0.0-dev.14`, reached through the b
 - `graphs: ""` for a resource listing. There is no call that lists the documents of a store, so the per-document capability filter IS the listing: what comes back is what this identity holds of that shape, which is exactly what a listing should contain — the documents it created and the documents whose key it was given, with no gesture of its own to tell them apart.
 - `graphs: [<nuri>]` for one record, or several.
 
-`where` and `orderBy` carry Refine's filters and sorters. `docs.sparqlQuery`, anchored, is called before a named read when the document may be a public one this identity has never read — see `## Frictions`.
+Refine's filters and sorters are applied **in memory**, over what the read returns — the engagement gives `where` and `orderBy` no published semantics, and the one guarantee it attaches to them is that an `orderBy` makes the result an array rather than a `Set`. Passing them through and claiming they carry a filter would be relying on something nothing promises.
+
+`docs.sparqlQuery`, anchored, is called before a named read when the document may be a public one this identity has never read — see `## Frictions`.
 
 **Writing.** `storeRegistry.createEntityDoc(store?)` with `privateStore()` / `protectedStore()` / `publicStore()` to place it, then `insertObject(shapeType, object)` with the object carrying its `@graph` and an empty `@id`. `docs.sparqlUpdate` for modification and removal, for want of anything else — see `## Needs`.
 
@@ -45,15 +47,23 @@ The pinned version is the engagement's own `1.0.0-dev.14`, reached through the b
 
 **One document per entity must remain the recommended placement**, and access must stay per document. A Refine `id` is a document's NURI; if access were granted at any other granularity, `id` would stop being the unit that can be read, shared and listed.
 
+**The application must inject `ormSubscription`, `getObjects`, `insertObject` and `initNg` into `configure`.** All four are optional fields of `EventuallyConfig`, and this package reaches none of the ORM on its own — it is a library, and `## Non-guarantees` states that one wiring no `@ng-org/*` of its own cannot reach the injected write. An application that omits them gets a binding whose reads and writes have no engine. `useShape` must also carry a value, being required, though this package never calls it: a function that throws says the most.
+
+**And it must call THIS package's `initNg`, never the SDK's.** `## Scope` is explicit about the consequence — *« Calling `@ng-org/orm`'s `initNg` directly leaves ORM writes ungoverned »*, and `## Change policy` repeats that such an application *« still works and is still unguarded »*. That call decides which `ng` the ORM reaches the engine through, and the write guard rides on the substituted one. This is the single most consequential line of the bootstrap and the easiest to get wrong, because the wrong version works: the sibling binding calls the SDK's `initNg` today (`src/auth-provider.ts`), and a binding ported from it inherits an unguarded write path where every other guarantee still appears to hold.
+
+**The application must hand this package the session.** `docs.docCreate`, `sparqlQuery` and `sparqlUpdate` all take a `sessionId` first, and the engagement gives a library no way to obtain one: a session is never built, no call takes one, `getSession` was removed, and the session arrives only in the callback passed to this package's `init`. So the application catches it there and hands it over — the same shape the sibling already has, where `authProvider.getSession()` is what the data provider calls. A library that assumed it could ask for one would have no first argument to pass.
+
 Relayed to the application, which owns its URL: `?ng-id=` must survive its router. Refine's `syncWithLocation` rewrites the query string, and a dropped parameter is a silent mis-identification rather than an error.
 
 ## Frictions
 
-**The version this engagement tells us to anchor on is not referenceable.** `## Change policy` names the regime — `polyfill/vX.Y.Z`, package-prefixed — and names `1.0.0-dev.14` as what exists today, to be pinned exactly and anchored here as `against: @ng-eventually/polyfill@1.0.0-dev.14`. The only tags that exist are `polyfill/v1.0.0-dev.2` and `polyfill/v1.0.0-dev.3`, so that string names nothing: the pin is the branch the engagement is authored on and `against:` is the commit it resolved to. Nothing about the resolution is irregular — a canonical identity mapped onto a local checkout is what a shared machine is for, and the stamp records the canonical value either way. What is missing is only the tag, and until one carries this version the policy's own instruction cannot be followed, nor can "between two pre-releases nothing is promised" be acted on: there is no pre-release to compare against.
-
 **Modifying and removing a record have no published path that is both shape-typed and awaitable.** `## Non-guarantees` routes removal through the LIVE set a shape query handed back, and that set is reachable only through `useShape` — a React hook, which a `DataProvider` cannot call. Worse for this shape of caller: a mutation of a live set is batched into a call NextGraph does not await, so a refusal surfaces as an unhandled rejection in the console rather than at the line that made the change. Refine's `update` and `deleteOne` must resolve with the record or reject; neither is possible on that channel. What is left is projecting the shape into SPARQL and calling `docs.sparqlUpdate` — re-implementing in this package what NextGraph's ORM already does, which is exactly the kind of compensation this package exists not to carry.
 
-**A named read needs a priming call that has no other purpose.** `getObjects` spends no round-trip asking a public store for its key, so a reference received from elsewhere reads empty until the document has been read by name through `docs.sparqlQuery`. Reading one record is therefore two calls, the first of which exists only to make the second work. `useShapeQuery` has not had this since `1.0.0-dev.9` — it asks once per document named in `graphs` — so the asymmetry between the two reads is what costs the call.
+**Reading one named record costs either two calls or a short-lived observable.** `getObjects` spends no round-trip asking a public store for its key, so a `reference` received from elsewhere reads empty through it. `## Guarantees` names the two calls that do ask — an anchored `docs.sparqlQuery`, always, and `useShapeQuery` for a document named in `scope.graphs` since `1.0.0-dev.9`, typed and reactive — so a `getOne` is either a priming query followed by `getObjects`, or a `useShapeQuery` subscribed and torn down for one read. Neither is wrong; both pay for the asymmetry between the one-shot read and the reactive one.
+
+**Reading one record changes what the next listing contains.** `## Guarantees` says of a document read by name that *« the key lands in what you hold, which all three re-read on »*. A listing under `graphs: ""` is defined as what this identity holds, so opening one public document by its `reference` — a link followed into a show page — puts it in every subsequent listing of that shape, with no gesture from the application and no way to take it back. The acquisition is the engagement's intended behaviour; what is unsettled is that it makes a Refine resource grow by being browsed.
+
+**A named read can stay pending for the life of the session.** `## Guarantees` keeps a named document that never synced in `isPending` deliberately — *« a barrier that was never crossed is not authority to call anything empty »* — and `## Non-guarantees` adds the shape query the engine refuses, which never finishes loading either. A `DataProvider` method must return a promise that settles; built on an observable that may never answer, `getOne` hangs and the interface shows a spinner with no end. The reference binding cannot do this: its reads are HTTP and always settle, success or failure.
 
 **Naming several documents fails as a whole.** One unreachable document in `graphs` means nothing is answered, so a `getMany` over a heterogeneous list — some created here, some received, some public — cannot return the records that ARE readable. A Refine table that resolves relations in one call cannot use it.
 
@@ -63,12 +73,16 @@ Relayed to the application, which owns its URL: `?ng-id=` must survive its route
 
 ## Needs
 
-**A shape-typed write and a shape-typed removal, awaitable, callable outside React.** The analogue of `insertObject` for modifying and removing — same posture: the object carries its `@graph`, the call rejects when refused, and the caller awaits it. This is the one need that decides the shape of this package's `dataProvider`; everything else here is a cost, this is a wall.
+**A shape-typed write and a shape-typed removal, awaitable, callable outside React.** The analogue of `insertObject` for modifying and removing — same posture: the object carries its `@graph`, the call rejects when refused, and the caller awaits it.
 
-**A count, or a reachable page, on the one-shot read** — so a listing does not have to rapatriate everything an identity holds to know how many there are.
+**First, a silence to break rather than a call to add.** `## Surface` says `insertObject` fills in an `@id` *« where one was left empty »*, and says nothing about an object that arrives carrying one that already exists in its document — merge, duplicate subject, or refusal. If it merges, the modification path already exists and this need is half answered; if it duplicates, an application that tries it corrupts a document and learns so later. Either way the answer belongs in the engagement, and it is cheaper to state than to implement.
 
-**A key asked for the documents named in `getObjects`'s `graphs`**, as `useShapeQuery` has done since `1.0.0-dev.9`. That would retire the priming `docs.sparqlQuery` and make one record cost one call.
+That aside, this is the need that decides the shape of this package's `dataProvider`, and the bar is set outside this pair: the binding is held to being interchangeable with `@activitypods/refine-providers`, which serves `update` and `deleteOne` as ordinary awaited calls. Every other gap this leaf records has a caller-side answer — filters, sorting, pagination and totals are computed in memory there too, a `getMany` reads one record at a time and keeps what answered, and a reference received from elsewhere is reached through `useShapeQuery`. These two have none: Refine's `update` and `deleteOne` must resolve with the record or reject, and no published call can do either.
 
-**Per-document outcomes when several are named**, rather than an all-or-nothing answer — so a listing of mixed provenance can show what is readable.
+**A meaning for "delete" that a Refine interface can present.** `## Non-guarantees` is categorical: there is no object removal call and no document deletion *« at any level of NextGraph »*; what a removal takes away is the predicates the shape declares on that subject, while the subject, the document and every other triple survive. So even once the write above exists, `deleteOne` cannot make a record go away: the document stays readable, answers `isSuccess` with nothing of the shape in it, and the key already handed to someone else keeps resolving. A bookmarked show page renders an empty record rather than a missing one, where the reference binding's `DELETE` makes the next read a 404. What is needed is not only the call but a published answer to what deletion means here — whether an emptied document is meant to read as absent, and through which observation.
 
-**A tag for the version `## Change policy` says to pin.**
+**A call that closes the session.** In the target, an open wallet is the authenticated state and closing it is the sign-out, so a binding wires Refine's `logout` to that act — the shape survives migration. No published call performs it: `## Guarantees` names "changing identity or clearing it" as an event that happens, `setCurrentUser` was removed on purpose, and awaiting `ensureIdentity()` again shows no barrier. The consequence is concrete and it is a loss of protection rather than an inconvenience: a Logout button can be rendered, it cannot sign anybody out, and the next visitor re-enters the previous identity in one click from a prefilled barrier. The reference binding clears its token and `check()` then fails.
+
+**A display name, or something able to carry one.** This is an ASK TO WIDEN the scope, not a gap: `## Scope` excludes display names explicitly. The reason to ask anyway is that the two halves of the current answer leave a caller with no conforming option — `## Non-guarantees` forbids rendering the identifier as a readable name, and nothing published offers a name to render instead. Refine puts `getIdentity().name` in its own layout by default, and the reference binding reads a name and an avatar off the person's profile, so an interface that showed a name on one binding can show nothing lawful on this one. Anything observable would settle it: a name alongside the identifier, or a published place to keep one. Until then this package returns the identifier in that field, deliberately and against the letter of the non-guarantee, because the alternative is an empty layout.
+
+**A predicate for write ownership — a comfort, not a blocker.** `## Guarantees` says only a document's owner writes to it, and `insertObject` refuses a document this identity does not own, but no published call answers whether it owns one. A listing here is everything accessible of a shape, so it legitimately mixes the two, and the default path is to let the person act and surface the refusal — which needs the awaitable write above and nothing else. What the predicate would buy is an interface that hides a control rather than letting it fail; it is worth asking for and it blocks nothing. It is not the read-side question this surface declines to answer: on the read side the answer already arrives as the absence of the record from what a read returns. It is the write side, where `## Guarantees` already expects a caller to know what it owns — *« write into documents you own, and treat a document you merely hold the key for as read-only »* — while publishing no call that says which is which.