Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs+refactor(client): fidelity pass — id identity, drop connections, no faux-login, accurate NextGraph framing

Browse Source 
Align the polyfill's surface and docs with the verified NextGraph reality and
remove application-level concepts:

- Identity is an ID, not a username: AccountRecord.id, shim predicate shim:id,
  normalizeId; accounts core becomes IdentityStore (set/clear/get) — the faux
  login/logout framing is gone (identity is set at wallet-import time).
- Relationship/connection is an application concept, not a platform primitive
  (NextGraph has no bilateral-connection primitive: grantee is unpersisted
  scaffolding, cap-send is unimplemented). Remove connections.ts; caps exposes
  only a directed grantRead(doc, granteeId) + a read-only protectedDocsOf(owner).
  Delete the now-dead isolation.ts social-visibility axis.
- Inbox docs: NextGraph has no separate curator — the recipient's own verifier
  unseals and applies each queued sealed message inline (process_inbox);
  inbox_post_link is a proposed/future API. Stop attributing the emulated
  curator to the platform.
- Read isolation reframed around the outcome: no cap -> empty union read;
  targeted read of an unheld repo -> RepoNotFound; cap introspection
  (canRead/governsRead) is emulation-only with no NextGraph API behind it.
- read-model.md corrected: the listing path is per-doc ANCHORED default-graph
  queries, never the anchorless GRAPH ?g union (that is O(wallet)); the probe
  section no longer claims the opposite.
- README recap table restructured (target | current NextGraph status | current
  emulation); INDEX_ACCOUNT documented as reservedAccount("index") in the
  sentinel namespace; de-domained generic-layer comments; softened tone.

Consumer application (Festipod) rewired separately to own the relationship
concept and feed the lib an id. Lib gates: bun test 83 pass / 0 fail, tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sylvain Duchesne
2026-07-06 14:02:16 +02:00
parent d39b12885a
commit 63ecfeeff8
31 changed files with 1059 additions and 1396 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/client/src/inbox.ts
+38 -35
View File
@@ -1,25 +1,27 @@
/**
* Inbox — the ONE deposit + materialization mechanism, reused for BOTH meeting-
* point registration AND submission to the discovery index (see the discovery-
* model decision: same `inbox.post` API, same watcher). GENERIC by construction:
* this module knows no application domain (no meeting-point, no notification).
* The consumer supplies the inbox document NURI and interprets the `payload`.
* Inbox — a generic deposit + read/materialize mechanism the consumer reuses for
* its own purposes (same `inbox.post` API, same watcher — see the discovery-model
* decision). The mechanism itself knows no application domain: the consumer
* supplies the inbox document NURI and interprets the `payload`. (An example
* consumer mapping, purely illustrative: a consumer might use one inbox for a
* registration deposit and another for submitting a reference to an index.)
*
* ── TARGET vs POLYFILL ────────────────────────────────────────────────────
* Target: `post` seals a reference into the inbox owner's native inbox
* (`ng.inbox_post_link(...)`), and a SEPARATE curator process (the deferred
* `@ng-eventually/service` package) MATERIALIZES the deposits into the owned
* document. Here, in the shared-wallet polyfill (everything is readable),
* both sides are emulated in-lib:
* ── Real target vs this emulation ─────────────────────────────────────────
* In real NextGraph, a message is sealed to the recipient's key and queued into
* their inbox; the recipient's own verifier unseals each queued message and
* applies it inline as it processes the inbox — there is no separate curator
* process. A future `inbox_post_link` is the intended way to seal a link into an
* inbox from the sender side; it is not exposed yet.
*
* Here, on one shared wallet where everything is readable, both sides run in-lib:
* - `post` appends a deposit `{ from, payload, ts }` as RDF into the inbox
* DOCUMENT (in the shared wallet) via the `docs.sparqlUpdate` primitive;
* - `read` / `watch` play the CURATOR: they read the deposits back via
* `docs.sparqlQuery` and expose them. This in-client emulation is enough
* for the polyfill — at migration the real materialization moves to the
* separate curator and this read side goes away.
* document (in the shared wallet) via the `docs.sparqlUpdate` primitive;
* - `read` / `watch` read the deposits back via `docs.sparqlQuery` and expose
* them. This in-lib read stands in for the recipient's own inbox processing
* until the sealed-inbox path (`inbox_post_link`) is available.
*
* All NextGraph I/O routes through the T01.a `docs` primitives (the REAL
* injected `ng`, never `makeNg`), so this module imports NO `@ng-org` package.
* All NextGraph I/O routes through the `docs` primitives (the real injected `ng`,
* never `makeNg`), so this module imports no `@ng-org` package.
*/
import { sparqlUpdate, sparqlQuery } from "./docs";
@@ -92,13 +94,13 @@ function readBindings(result: unknown): Array<Record<string, { value: string }>>
* (the real injected `ng`). Each deposit is a fresh RDF subject in the inbox
* graph, so concurrent deposits don't collide.
*
* `from` is BOUND TO THE CURRENT IDENTITY — it is authenticated, not
* caller-supplied. Omit it to stamp the current user; pass `null` to deposit
* ANONYMOUSLY (a legitimate choice — "identified if known, anonymous otherwise").
* A `from` naming ANOTHER principal is a SPOOF and is REJECTED: in the target the
* `from` is bound to the current identity — it is authenticated, not
* caller-supplied. Omit it to stamp the current identity; pass `null` to deposit
* anonymously (a legitimate choice — identified if known, anonymous otherwise).
* A `from` naming another identity is rejected as a spoof: in the target the
* broker seals the sender from the wallet's own key, so a client cannot forge
* another's identity. (At migration this check is redundant — the seal enforces
* it — but until then it closes the spoof the shared wallet would otherwise allow.)
* another's identity. This check is redundant once the seal enforces it, but
* until then it closes the spoof the shared wallet would otherwise allow.
*/
export async function post(targetInbox: Nuri, opts: PostOptions): Promise<void> {
const current = getCurrentUser();
@@ -140,13 +142,14 @@ export async function post(targetInbox: Nuri, opts: PostOptions): Promise<void>
await sparqlUpdate(sid, update, targetInbox);
}
// --- read / materialize (emulated curator) --------------------------------
// --- read --------------------------------------------------------------
/**
* Read (materialize) every deposit currently in `targetInbox`, sorted by `ts`
* ascending. This is the EMULATED CURATOR: at migration a separate curator
* process materializes deposits and this in-client read goes away. The consumer
* interprets each deposit's `payload`.
* Read every deposit currently in `targetInbox`, sorted by `ts` ascending. In
* real NextGraph the recipient's own verifier applies queued messages inline as
* it processes the inbox; here this read stands in for that until the
* sealed-inbox path is available. The consumer interprets each deposit's
* `payload`.
*/
export async function read(targetInbox: Nuri): Promise<Deposit[]> {
const sid = await sessionId();
@@ -179,15 +182,15 @@ export async function read(targetInbox: Nuri): Promise<Deposit[]> {
return deposits;
}
/** Alias for {@link read} — the name that reads as "run the curator now". */
/** Alias for {@link read} — the name that reads as "process the inbox now". */
export const materialize = read;
/**
* Subscription over an inbox — the emulated watcher. Polls {@link read} on an
* interval and invokes `onDeposits` with the full current deposit list whenever
* it changes (grows). Returns an unsubscribe function. The polyfill has no
* native reactive inbox subscription, so this emulates one; at migration it is
* replaced by the real curator's watch. `onDeposits` fires once immediately.
* Subscription over an inbox. Polls {@link read} on an interval and invokes
* `onDeposits` with the full current deposit list whenever it changes (grows).
* Returns an unsubscribe function. The polyfill has no reactive inbox
* subscription, so this polls; against real NextGraph it follows the recipient's
* own inbox processing. `onDeposits` fires once immediately.
*/
export function watch(
targetInbox: Nuri,