@gemmein/sdk 0.4.4 → 0.4.6

package/REFERENCE.md

@@ -21,8 +21,10 @@ The browser client. `appKey` is your public `pk_...` key. `options` (optional):
 
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
-browser.** Exposes read/update on collections without a signed-in user, plus
-`testSession()` for CI self-tests (dev environments only — see **Reaffirm**).
+browser.** Exposes read/update on collections without a signed-in user,
+`notify()` to email one of your app's own verified people (see **Notify**),
+plus `testSession()` for CI self-tests (dev environments only — see
+**Reaffirm**).
 
 The client has two layers. **Your app's collections** — `g.collection(name)`
 (the canonical spelling; `g.storage.collection(name)` is the same client). And
@@ -88,10 +90,11 @@ certain the collection exists yet.
 |--------|-----------|---------|
 | `create` | `(data: T, options?: { key?: string; for?: string; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
 | `list` | `(options?: ListOptions)` | `Promise<ListResult<T>>` |
+| `watch` | `(onChange: (delta: { records; deleted; initial }) => void, options?: { every?: number; where?; search?; limit? })` | `{ stop(): void }` — see **Live data** |
 | `get` | `(id: string, options?: { expand?: string[] })` | `Promise<GemmeinRecord<T>>` |
 | `update` | `(id: string, data: Partial<T> \| { field: { increment\|decrement, floor?, ceiling? } }, options?: { ifVersion?: number; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
 | `delete` | `(id: string)` | `Promise<void>` |
-| `upload` | `(file: Blob \| File, options?: { name?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
+| `upload` | `(file: Blob \| File, options?: { name?: string; contentType?: string; for?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
 
 ### Files
 
@@ -126,6 +129,29 @@ immediately; a link already issued works until it expires, and a download that
 started before expiry may finish after it. Controlled delivery, not DRM —
 nothing takes back a file someone already downloaded.
 
+**What uploads take.** Images — JPEG, PNG, WebP, GIF, HEIC — and documents —
+PDF, ZIP, EPUB — at **25 MB per file**; nothing else (no video, audio, SVG,
+HTML or office files — zip an office file). The server checks the actual
+bytes, not the filename. A document always **downloads** (served as an
+attachment; it never opens inside the page) — link it with
+`{ intent: "download" }` — and pass `contentType` to `upload()` when a Blob
+doesn't carry its own type.
+
+**Handing a file to one person.** On `addressed`/`direct` collections,
+`upload(file, { for: userId })` stamps that person as the file's audience at
+birth — immutable, and only they (and you, the owner) can ever `link()` it.
+That's how a direct message carries an attachment. A field holding file
+references is learned as a **file field** — image or document, from the real
+uploads. The file law is UNIVERSAL: on every rule, locked or not, any
+top-level field value matching the ref grammar must name a real file you
+could read — a made-up ref is refused (`unknown_file`). Once the shape is
+sealed, the field's class is law too: the wrong kind teaches on the wire
+(`invalid_shape`, the message names which kind the field takes); before the
+seal, learning owns class (seen-both widens to "any"). A stored ref whose
+file was later deleted refuses the same way on re-write — clear the field
+(`null`) or upload a fresh file. Refs inside `list`/`json` values aren't
+judged at write; they still grant nothing at read.
+
 ```ts
 type GemmeinRecord<T> = {
   id: string;
@@ -144,7 +170,11 @@ type GemmeinRecord<T> = {
   existing?: true;             // present only when a keyed create returned YOUR existing record
 };
 
-type ListResult<T> = { records: GemmeinRecord<T>[]; cursor?: string; hasMore: boolean };
+type ListResult<T> = {
+  records: GemmeinRecord<T>[]; cursor?: string; hasMore: boolean;
+  deleted?: string[];   // on a `since` read: ids deleted after that instant — your rule scope only
+  watermark?: string;   // pass as the next `since`; paging a plain list in full, adopt the FIRST page's
+};
 
 type ListOptions = {
   limit?: number;
@@ -153,6 +183,8 @@ type ListOptions = {
   cursor?: string;                   // from a previous ListResult
   search?: string;                   // free-text across data
   expand?: string[];                 // link fields to embed (≤3), only on community/shared/direct
+  since?: string;                    // everything changed OR deleted after this instant, oldest first
+                                     // — the previous answer's watermark; incompatible with sort
 };
 ```
 
@@ -162,6 +194,19 @@ recipient id on `addressed`/`direct`. `published: false` = draft on a public
 rule. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
 position: `update(id, { stock: { decrement: 1, floor: 0 } })`. `expand` throws
 on `private`/`public_read`/`admin_write` (no link shape) — join in memory there.
+`since` fixes the order (oldest change first) — pairing it with `sort` is a 400
+`invalid_since`. Deltas are at-least-once: apply by id.
+
+### Live data — `watch()`
+
+`watch(onChange, { every? })` keeps a list fresh by polling `list({ since })`
+— every 10 s by default, clamped to 5 s–300 s. `onChange` receives
+`{ records, deleted, initial }`: the first call is the full list
+(`initial: true`); every later call only what changed or was deleted. It
+sleeps while the tab is hidden and resyncs in full on return, backs off on
+rate limits (honouring `resetAt`), never overlaps its own requests, and stops
+itself on 401/403. Returns `{ stop() }` — call it when the view unmounts.
+Never hand-roll a polling loop; this is the sanctioned one.
 
 ---
 
@@ -172,6 +217,7 @@ on `private`/`public_read`/`admin_write` (no link shape) — join in memory ther
 | `subscriptions.mine` | `()` | `Promise<{ plan: string; status: "active" \| "cancelled" } \| null>` |
 | `subscriptions.checkout` | `(plan?: string)` | `Promise<{ url: string; plan: string }>` — **navigates the browser to Stripe** and resolves the url |
 | `payments.buy` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
+| `purchases.mine` | `()` | `Promise<Purchase[]>` — the array itself (not wrapped): `{ item, kind, amountMinor, currency, refundedMinor, status, grants, paidAt, delivery? }` — gate one-off fulfilment on this, never the redirect |
 
 Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 `buy` self-navigate via `window.location` — just `await` them on the click;
@@ -181,83 +227,82 @@ gate one-off fulfilment on the receipt record, never the redirect.
 
 ---
 
-## Reaffirm — prove your app's boundaries in CI
-
-Gemmein enforces the rules **server-side**, so your frontend is never the source
-of truth. That's exactly why you can move fast: a `reaffirm` script *exercises*
-your boundaries with live calls and fails the build on drift — so if a rule ever
-stopped matching what your UI assumes, you catch it on deploy, not in front of a
-user. You reaffirm **because** Gemmein enforces — never because these checks are
-the enforcement.
+## Notify — `gemmeinServer(sk).notify(personId, input)`
+
+Your app's **server** emails one of its **own verified people** — by person
+id, never an address. A missing, cross-environment, or suspended id is one
+`404 not_a_customer` on purpose: existence is never leaked.
+
+`input`: `{ subject: string; text: string; kind?: "event" | "account"; key?: string }`
+→ `Promise<{ sent: boolean; deduped?: boolean; recorded?: boolean; id: string | null; threadId: string | null; replyRail?: boolean }>`
+(`recorded: false` means the email went but Inbox recording failed — reported
+honestly, not hidden.)
+
+- `kind: "event"` (the default) — order shipped, booking confirmed. Capped at
+  **5 per person per day** so a bug can never flood an inbox, and 200 per app
+  per hour (`resetAt` rides the 429). `kind: "account"` — sign-in, access,
+  billing trouble — is exempt from the per-person cap (a security notice never
+  loses to order emails), same hourly app cap.
+- `key` makes the send at-most-once through retries: a delivered send answers
+  idempotently (`deduped: true`); a concurrent twin gets `409 in_flight` —
+  retry in a moment.
+- Plain text only — this is a notification, not a campaign. Every email
+  carries a footer naming why it arrived; replies land in the owner's Inbox
+  as a thread (`threadId`), and `replyRail` states honestly whether
+  reply-by-email is on. Every send is on the record.
 
-Two tiers:
+---
 
-**Tier A — anonymous + shape (zero setup, runs against any environment incl. live).**
-No session needed. Catches the loudest drift: a private collection an anon can
-read, a renamed/mis-cased collection (`collection("savedGames")` throws
-*synchronously*), the error-code contract, and the deliberate reminder that a
-`community`/`public_read` collection is readable by anyone.
+## Reaffirm — prove your app's boundaries in CI
 
-**Tier B — cross-user isolation (dev environments only).**
-Proving "user B genuinely can't read user A's private record" needs two real
-sessions. Mint them without an OTP round-trip:
+Gemmein enforces the rules **server-side**, so your frontend is never the source
+of truth. Because enforcement is server-side, a script of live calls can verify
+it: `reaffirm.mjs` ships inside this npm package — copy it next to your app,
+fill the CONFIG block at its top, run it on every deploy. You reaffirm
+**because** Gemmein enforces — never because these checks are the enforcement.
+
+Exit codes: `0` all proven · `1` boundary drift · `2` could not complete (a
+config or connectivity failure, named as such — never a boundary verdict).
+
+The CONFIG block: `PRIVATE_COLLECTION` (required) · `PUBLIC_COLLECTION`,
+`DIRECT_COLLECTION`, `COMMUNITY_COLLECTION`, `GATED_COLLECTION` (each `""` to
+skip — every skip prints its reason, so the CI log always says what was proven
+and what was not) · `PROBE_FIELD`/`TEXT_FIELD` (your shapes' own field names —
+dev shapes learn from writes, so the probes speak your app's shape) ·
+`TEST_USERS` (three dev test emails).
+
+**Tier A — anonymous, read/refusal only, safe against any environment
+including live:** an anonymous caller is refused reading and writing the
+private collection, and the public collection's exposure is stated with a
+record count. A format-invalid collection name throws at the `collection()`
+line; a wrong-but-well-formed name surfaces as `unknown_collection` and exits
+`2` with "fix the CONFIG block" — a typo is never reported as drift.
+
+**Tier B — dev environments only**, sessions minted without a sign-in code:
 
 ### `gemmeinServer(sk).testSession(email) → { token, expiresAt, user }`
-Mints a **member** session for a test email. **Dev only** — throws
-`test_session_forbidden_live` on an `sk_live` key, and the server refuses it on a
-live environment too (the invariant that keeps it off real user data). Pass the
-returned `token` to `gemmein(pk, { tokenStore })` to act as that user. Dev and
-live enforce the *same* rules, so isolation proven in dev holds in live.
-
-This exact harness ships as **`reaffirm.mjs` inside the npm package** — copy it
-out, edit the CONFIG block, run in CI.
-
-```js
-// reaffirm.mjs — run in CI: `node reaffirm.mjs` (exits non-zero on any drift).
-import { gemmein, gemmeinServer } from "@gemmein/sdk";
-
-const API = process.env.GEMMEIN_API_URL;                 // your dev API url
-const g   = gemmein(process.env.PUBLIC_KEY, { apiUrl: API });
-const srv = gemmeinServer(process.env.SECRET_KEY, { apiUrl: API }); // sk_dev only
-let fail = 0;
-const refuse = async (label, code, fn) => {              // must throw `code`
-  try { await fn(); console.error("✗", label, "— expected", code, "got success"); fail++; }
-  catch (e) { e.code === code ? console.log("✓", label)
-            : (console.error("✗", label, "— got", e.code), fail++); }
-};
-const asUser = (token) => gemmein(process.env.PUBLIC_KEY, {
-  apiUrl: API,
-  tokenStore: { get: async () => token, set: async () => {}, clear: async () => {} },
-});
-
-// ── TIER A: functional + anonymous (no login) ──
-g.collection("private_notes");                   // misnamed → throws HERE, loudly, in CI
-await refuse("anon can't read private",    "denied", () => g.collection("private_notes").list());
-await refuse("anon can't write community", "denied", () => g.collection("board").create({ text: "x" }));
-
-// ── TIER B: cross-user isolation (dev only) ──
-const alice = await srv.testSession("alice@test.dev");
-const bob   = await srv.testSession("bob@test.dev");
-const A = asUser(alice.token), B = asUser(bob.token);
-
-const note = await A.collection("private_notes").create({ text: "alice-secret" });
-await refuse("B can't read A's private note", "not_found", () =>
-  B.collection("private_notes").get(note.id));
-const bobSees = await B.collection("private_notes").list();
-if (bobSees.records.length !== 0) { console.error("✗ B sees A's private records"); fail++; }
-else console.log("✓ B's private list is isolated");
-
-// shape the UI reads (userId, NOT id):
-const who = await A.auth.currentUser();
-if (!who.userId) { console.error("✗ currentUser().userId missing"); fail++; }
-else console.log("✓ currentUser().userId present");
-
-process.exit(fail ? 1 : 0);
-```
-
-Add a probe every time you add a feature. Point the harness at your **dev**
-environment (Tier B needs it); the Tier-A block alone can additionally smoke-test
-live, since it never mints a session.
+**Dev only** — throws `test_session_forbidden_live` on an `sk_live` key, and
+the server refuses it on a live environment too. Pass the `token` to
+`gemmein(pk, { tokenStore })` to act as that user. Dev and live enforce the
+*same* rules, so what is proven in dev holds in live.
+
+What Tier B proves, per probe: B can't read A's private record and B's list
+excludes it · `currentUser().userId` and `.data` shapes · the `since` contract
+(a plain list carries the watermark to bootstrap from; malformed `since` →
+`invalid_since`; a delta answers the next watermark) · a made-up file ref is
+refused on write (`unknown_file`) · the uploader can `link()` their own file
+and B is refused A's (`not_found`) · on a `direct` collection the recipient
+sees the record, a third user is refused, and a file uploaded `{for}` one
+person opens for that person only · HTML into a `community` field →
+`html_not_allowed`, and an unpublished draft is invisible to the public · on a
+gated collection, a user with no plan → `entitlement_required` carrying
+`err.requires`.
+
+Probe writes are deleted afterwards; probe uploads remain in dev storage
+(files have no delete API yet) — two tiny PNGs per configured run. Against an
+older **local** engine (< 0.4.8) the since/ghost-ref/handed-file probes fail
+with a message naming the engine as the likely cause; the hosted API is always
+current. Add a probe whenever you add a feature.
 
 ---
 
@@ -288,17 +333,21 @@ Branch on `err.code`. The stable codes:
 | `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
 | `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
 | `invalid_publish` | `{ published }` on a non-public rule | drop it |
-| `invalid_shape` | field not in a locked (live) collection's shape | ask the owner to add it |
+| `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | ask the owner to add it / send the kind the field takes |
+| `unknown_file` | a ref-shaped value points at a file that doesn't exist or isn't yours to hand — every rule, every write | fix the ref — never invent one |
+| `invalid_since` | `since` isn't a strict ISO 8601 timestamp, or came with `sort` | pass the previous answer's watermark; drop `sort` |
+| `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |
+| `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
 | `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
 | `unknown_record` | a link field points at a missing record (live only) | fix the id |
 | `payload_too_large` / `file_too_large` | over the size cap (message states it) | shrink it |
-| `invalid_file_content` | uploaded bytes aren't the claimed image type | send the real image |
+| `invalid_file_content` | uploaded bytes aren't the claimed type (usually a renamed file) | send the real file |
 | `test_session_forbidden_live` | `testSession()` called on a live env / `sk_live` key | reaffirm's Tier B is dev-only — point it at your dev environment |
 | `unknown_plan` | no plan by that name | use a name from the list in the message |
 | `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
 | `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
-| `unsupported_file_type` (415) | upload isn't one of the allowed image types | send JPEG/PNG/WebP/GIF/HEIC |
+| `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |

package/llms.txt

@@ -330,11 +330,16 @@ go-live. Everything else is yours.
   live it locks. Field kinds the shape learns: text, number, yes/no, list,
   link (a stored record id), json, and FILE — a field that held an
   upload()'s ref learns as a file field — and WHICH class (an image field
-  vs a document field, from what you actually uploaded). Once locked, the
-  field accepts only a reference to a real, confirmed file of this app
-  that the writer may read, of the right class — a ZIP into a profile
-  photo field is refused with the teach, as is a made-up or foreign ref
-  ("file not found"). A 400 invalid_shape means the field isn't in the locked
+  vs a document field, from what you actually uploaded). The file law is
+  UNIVERSAL: on every rule, locked or not, any top-level field value
+  matching the ref grammar must name a real, confirmed file of this app
+  that the writer may read — a made-up or foreign ref is refused ("file
+  not found", 400 unknown_file). Never invent a ref. (Refs inside list or
+  json values aren't judged at write — they still grant nothing at read.)
+  If a stored ref's file was later deleted, re-sending it refuses the same
+  way: clear the field (null) or upload a fresh file. Once sealed, class
+  is law too: a ZIP into a profile photo field is refused with the teach;
+  before the seal, what you upload is what the field learns. A 400 invalid_shape means the field isn't in the locked
   shape or the value doesn't fit its kind. A live shape is sealed and
   cannot take new fields — stop, tell your human which field you needed,
   and send only the fields the shape already has. Never rename fields to
@@ -517,29 +522,34 @@ rule. The specifics:
   `{ url, ... }`. Just `await` them on the click — don't also redirect to the
   returned `url` (you'll double-navigate), and don't build the URL yourself.
 
-## Reaffirm your app (don't trust your frontend — prove it)
+## Reaffirm your app (the server enforces — prove it in CI)
 
 Gemmein enforces the rules on the server, so your UI is never the source of
-truth. That's what lets you move fast: ship a small `reaffirm` script that
-*exercises* your boundaries with live calls and run it in CI. When a rule ever
-stops matching what your screens assume, this catches it on deploy — not in
-front of a user.
+truth. Because enforcement is server-side, a script of live calls can verify
+it: a ready-to-edit `reaffirm.mjs` ships inside the `@gemmein/sdk` npm package
+(next to this file and REFERENCE.md). Copy it next to the app, fill the CONFIG
+block at its top (the private collection is required; direct/community/gated
+collections each unlock more probes, `""` skips with the reason printed; set
+PROBE_FIELD/TEXT_FIELD to the app's own field names), and run it on every
+deploy. Exit 0 = all proven, 1 = boundary drift, 2 = could not complete
+(config/connectivity — named as such, never reported as drift).
 
-- **Anywhere, no login:** anonymous reads/writes that must be refused (an anon
-  reading a `private` collection → `denied`; an anon writing `community` →
-  `denied`), plus the shapes your UI reads (`currentUser().userId`,
-  `record.data.*`) and that your collection names don't throw.
-- **Isolation (dev environment):** to prove one user can't see another's
-  private records, sign in two test users without an OTP round-trip —
-  `gemmeinServer(sk_dev).testSession(email)` returns a session `token` you pass
-  to `gemmein(pk, { tokenStore })`. It works in a **dev environment only**
-  (`sk_live` throws `test_session_forbidden_live`), and dev and live enforce the
-  same rules, so isolation proven in dev holds in live.
+- **Anywhere, no login (Tier A):** anonymous reads and writes of the private
+  collection must be refused (`denied`); the public collection's exposure is
+  stated out loud. Read-and-refusal only — safe against live.
+- **Isolation (Tier B, dev environment only):** sessions are minted without a
+  sign-in code via `gemmeinServer(sk_dev).testSession(email)` (`sk_live`
+  throws `test_session_forbidden_live`). It then proves: cross-user private
+  isolation; the `since` contract (bootstrap from a plain list's watermark;
+  junk → `invalid_since`); a made-up file ref is refused (`unknown_file`);
+  sealed file delivery (own file links, another user's is `not_found`);
+  `direct` recipient scoping and handed files (`upload(blob, {for})` opens for
+  the named person only); `community` plain text (`html_not_allowed`) and
+  invisible drafts; entitlements (`entitlement_required` + `err.requires`).
 
-Add a probe whenever you add a feature. You reaffirm **because** Gemmein
-enforces — never because these checks are the enforcement. A ready-to-edit
-`reaffirm.mjs` ships inside the `@gemmein/sdk` npm package (next to this file and
-REFERENCE.md) — copy it out, name your collections, run it in CI.
+Dev and live enforce the same rules, so what is proven in dev holds in live.
+Add a probe whenever you add a feature. You reaffirm BECAUSE Gemmein
+enforces — never because these checks are the enforcement.
 
 ## Pricing (current, v4 — one banded plan)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Gemmein SDK \u2014 passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",
@@ -53,4 +53,4 @@
   "bugs": {
     "email": "hello@gemmein.com"
   }
-}
+}

package/reaffirm.mjs

@@ -5,19 +5,39 @@
 //
 //   PUBLIC_KEY=pk_test_... SECRET_KEY=sk_dev_... node reaffirm.mjs
 //
-// Exits non-zero on any drift. Gemmein enforces the rules server-side — you
-// reaffirm BECAUSE the server enforces, never because these checks are the
-// enforcement. Tier A (anonymous) runs against any environment, live included.
-// Tier B (cross-user isolation) mints sessions via testSession, which works
-// ONLY in a development environment (sk_live is refused, by design) — dev and
-// live enforce the same rules, so isolation proven in dev holds in live.
+// Exits 0 all-proven · 1 boundary drift · 2 could-not-complete (config or
+// connectivity — NOT a boundary verdict). Gemmein enforces the rules
+// server-side — you reaffirm BECAUSE the server enforces, never because
+// these checks are the enforcement. Tier A (anonymous) runs against any
+// environment, live included. Tier B (cross-user isolation) mints sessions
+// via testSession, which works ONLY in a development environment (sk_live
+// is refused, by design) — dev and live enforce the same rules, so what is
+// proven in dev holds in live.
+//
+// Every probe past the first is optional: name a collection to prove its
+// surface, leave it "" and the probe is skipped WITH ITS REASON PRINTED —
+// your CI log always says what was proven and what was not.
+//
+// Probes write only to the collections you name, using YOUR field names
+// (dev shapes learn from writes — the probes must speak your app's shape).
+// Probe uploads stay in dev storage (files have no delete API yet): two
+// tiny PNGs per configured run, a known cost.
+//
+// The since/ghost-ref/handed-file probes need engine ≥ 0.4.8 when pointed
+// at a LOCAL runtime (GEMMEIN_API_URL) — an older engine fails them even
+// though your hosted app is fine. `npx -y gemmein@latest dev` updates.
 
 import { gemmein, gemmeinServer } from "@gemmein/sdk";
 
 // ── CONFIG — edit for your app ──────────────────────────────────────────────
-const PRIVATE_COLLECTION = "notes";   // a collection with the `private` rule
-const PUBLIC_COLLECTION  = "board";   // a `community` or `public_read` collection (or "" to skip)
-const TEST_USERS = ["reaffirm-a@test.dev", "reaffirm-b@test.dev"];
+const PRIVATE_COLLECTION   = "notes";  // a collection with the `private` rule (required)
+const PUBLIC_COLLECTION    = "";       // a `community`/`public_read` collection, e.g. "board" ("" to skip)
+const DIRECT_COLLECTION    = "";       // a `direct` collection — proves recipient scoping + handed files
+const COMMUNITY_COLLECTION = "";       // a `community` collection — proves plain-text + drafts
+const GATED_COLLECTION     = "";       // a collection unlocked by a paid plan — proves entitlements
+const PROBE_FIELD = "probe";           // a field YOUR private collection's shape allows
+const TEXT_FIELD  = "text";            // the text field YOUR direct/community shapes use
+const TEST_USERS = ["reaffirm-a@test.dev", "reaffirm-b@test.dev", "reaffirm-c@test.dev"];
 // ────────────────────────────────────────────────────────────────────────────
 
 const API = process.env.GEMMEIN_API_URL;               // omit for production api
@@ -30,46 +50,142 @@ const g = gemmein(PK, opts);
 let fail = 0;
 
 const refuse = async (label, code, fn) => {            // the call MUST throw `code`
-  try { await fn(); console.error("✗", label, "— expected", code, "but it succeeded"); fail++; }
-  catch (e) { e.code === code ? console.log("✓", label)
-            : (console.error("✗", label, "— expected", code, "got", e.code ?? e.message), fail++); }
+  try { await fn(); console.error("✗", label, "— expected", code, "but it succeeded"); fail++; return null; }
+  catch (e) {
+    if (e.code === code) { console.log("✓", label); return e; }
+    console.error("✗", label, "— expected", code, "got", e.code ?? "(no code)", "—", e.message); fail++; return e;
+  }
 };
-const check = (label, cond) => cond ? console.log("✓", label) : (console.error("✗", label), fail++);
+const check = (label, cond, got) => cond ? console.log("✓", label)
+  : (console.error("✗", label, got !== undefined ? `— got ${JSON.stringify(got)}` : ""), fail++);
+const skip = (what, why) => console.log(`· ${what} skipped — ${why}`);
 const asUser = (token) => gemmein(PK, { ...opts, tokenStore: {
   get: async () => token, set: async () => {}, clear: async () => {} } });
+// A tiny real PNG head: enough for the server's content check, no meaning.
+const PNG = new Blob([Uint8Array.from([0x89,0x50,0x4e,0x47,0x0d,0x0a,0x1a,0x0a,
+  0,0,0,0x0d,0x49,0x48,0x44,0x52, ...new Array(64).fill(0)])], { type: "image/png" });
+// A well-formed reference no upload ever returned — the write must refuse it.
+const GHOST_REF = "file:99999999-9999-4999-8999-999999999999";
 
-// ── TIER A — functional + anonymous. No login; safe against live. ───────────
-g.collection(PRIVATE_COLLECTION);              // a misnamed collection throws HERE, loudly
-await refuse("anon can't read the private collection", "denied",
-  () => g.collection(PRIVATE_COLLECTION).list());
-await refuse("anon can't write the private collection", "denied",
-  () => g.collection(PRIVATE_COLLECTION).create({ probe: "x" }));
-if (PUBLIC_COLLECTION) {
-  const open = await g.collection(PUBLIC_COLLECTION).list();
-  console.log(`ℹ "${PUBLIC_COLLECTION}" is public by rule — ${open.records.length} records visible to ANYONE. Never put secrets in it.`);
-}
+try {
+  // ── TIER A — functional + anonymous. No login; read/refusal only. ─────────
+  // A format-invalid name (uppercase, spaces) throws right here. A
+  // wrong-but-well-formed name surfaces below as `unknown_collection` —
+  // that is a CONFIG fix, not a boundary failure.
+  g.collection(PRIVATE_COLLECTION);
+  await refuse("anon can't read the private collection", "denied",
+    () => g.collection(PRIVATE_COLLECTION).list());
+  await refuse("anon can't write the private collection", "denied",
+    () => g.collection(PRIVATE_COLLECTION).create({ [PROBE_FIELD]: "x" }));
+  if (PUBLIC_COLLECTION) {
+    const open = await g.collection(PUBLIC_COLLECTION).list({ limit: 100 });
+    const shown = open.hasMore ? `${open.records.length}+` : `${open.records.length}`;
+    console.log(`ℹ "${PUBLIC_COLLECTION}" is public by rule — ${shown} records visible to ANYONE. Never put secrets in it.`);
+  } else skip("public-collection reminder", "set PUBLIC_COLLECTION");
+
+  // ── TIER B — cross-user isolation. Dev environments only. ─────────────────
+  if (SK && !SK.startsWith("sk_live")) {
+    const srv = gemmeinServer(SK, opts);
+    const [a, b] = await Promise.all(TEST_USERS.slice(0, 2).map((e) => srv.testSession(e)));
+    const A = asUser(a.token), B = asUser(b.token);
+
+    // The original core: private means private.
+    const note = await A.collection(PRIVATE_COLLECTION).create({ [PROBE_FIELD]: "a-secret" });
+    await refuse("B can't read A's private record", "not_found",
+      () => B.collection(PRIVATE_COLLECTION).get(note.id));
+    const bSees = await B.collection(PRIVATE_COLLECTION).list();
+    check("B's private list contains none of A's records",
+      !bSees.records.some((r) => r.id === note.id));
+
+    const who = await A.auth.currentUser();            // the shape your UI reads
+    check("currentUser() exposes userId (not id)", !!who.userId, who);
+    check("record fields live under .data", note.data?.[PROBE_FIELD] === "a-secret", note.data);
+
+    // Live data: bootstrap `since` from a plain list's watermark (that is
+    // the real pattern — never an ancient timestamp, which pages through
+    // history) and prove junk is refused.
+    const seed = await A.collection(PRIVATE_COLLECTION).list({ limit: 1 });
+    check("a plain list carries the watermark to start from", typeof seed.watermark === "string", seed.watermark);
+    await refuse("a malformed `since` is refused", "invalid_since",
+      () => A.collection(PRIVATE_COLLECTION).list({ since: "not-a-timestamp" }));
+    const delta = await A.collection(PRIVATE_COLLECTION).list({ since: seed.watermark });
+    check("a delta read returns the next watermark", typeof delta.watermark === "string", delta.watermark);
+
+    // The file law: a made-up reference never lands in a record. (If this
+    // SUCCEEDS against a local runtime, your engine predates 0.4.8 —
+    // update it; the hosted API always enforces this.)
+    try {
+      const polluted = await A.collection(PRIVATE_COLLECTION).create({ [PROBE_FIELD]: GHOST_REF });
+      console.error("✗ a made-up file ref is refused on write — it SUCCEEDED (old local engine? run `npx -y gemmein@latest dev`)"); fail++;
+      await A.collection(PRIVATE_COLLECTION).delete(polluted.id);       // never leave the ghost behind
+    } catch (e) {
+      e.code === "unknown_file" ? console.log("✓ a made-up file ref is refused on write")
+        : (console.error("✗ a made-up file ref is refused on write — expected unknown_file got", e.code ?? "(no code)", "—", e.message), fail++);
+    }
+
+    // Sealed delivery: your file is not their file.
+    try {
+      const up = await A.collection(PRIVATE_COLLECTION).upload(PNG, { name: "probe.png" });
+      const mine = await A.files.link(up.ref);
+      check("the uploader can link their own file", typeof mine.url === "string");
+      await refuse("B can't link A's file", "not_found", () => B.files.link(up.ref));
+    } catch (e) {
+      if (e.code === "unsupported_file_type") skip("file-delivery probes", `"${PRIVATE_COLLECTION}" doesn't accept PNG uploads — point the probes at a collection that takes images`);
+      else throw e;
+    }
+
+    await A.collection(PRIVATE_COLLECTION).delete(note.id);             // leave dev tidy
+
+    // direct: the recipient reads it; nobody else does. And a file handed
+    // to one person opens for that person only.
+    if (DIRECT_COLLECTION) {
+      const [cSess] = await Promise.all([srv.testSession(TEST_USERS[2])]);
+      const C = asUser(cSess.token);
+      const msg = await A.collection(DIRECT_COLLECTION).create({ [TEXT_FIELD]: "for b" }, { for: b.user.id });
+      const bBox = await B.collection(DIRECT_COLLECTION).list({ limit: 100 });
+      check("the recipient sees the direct record", bBox.records.some((r) => r.id === msg.id));
+      await refuse("a third user can't read it", "not_found",
+        () => C.collection(DIRECT_COLLECTION).get(msg.id));
+      try {
+        const handed = await A.collection(DIRECT_COLLECTION).upload(PNG, { name: "handed.png", for: b.user.id });
+        const bGets = await B.files.link(handed.ref);
+        check("the person a file was handed to can open it", typeof bGets.url === "string");
+        await refuse("anyone else is refused the handed file", "not_found",
+          () => C.files.link(handed.ref));
+      } catch (e) {
+        if (e.code === "unsupported_file_type") skip("handed-file probes", `"${DIRECT_COLLECTION}" doesn't accept PNG uploads`);
+        else throw e;
+      }
+      await A.collection(DIRECT_COLLECTION).delete(msg.id);
+    } else skip("direct-rule probes (recipient scoping, handed files)", "set DIRECT_COLLECTION");
+
+    // community: other people's screens get text, never markup — and
+    // drafts stay invisible until published.
+    if (COMMUNITY_COLLECTION) {
+      await refuse("HTML into a community field is refused", "html_not_allowed",
+        () => A.collection(COMMUNITY_COLLECTION).create({ [TEXT_FIELD]: "<b>hi</b>" }));
+      const draft = await A.collection(COMMUNITY_COLLECTION).create({ [TEXT_FIELD]: "draft probe" }, { published: false });
+      const anon = await g.collection(COMMUNITY_COLLECTION).list({ limit: 100 });
+      check("an unpublished draft is invisible to the public", !anon.records.some((r) => r.id === draft.id));
+      await A.collection(COMMUNITY_COLLECTION).delete(draft.id);
+    } else skip("community probes (plain text, drafts)", "set COMMUNITY_COLLECTION");
 
-// ── TIER B — cross-user isolation. Dev environments only. ───────────────────
-if (SK && !SK.startsWith("sk_live")) {
-  const srv = gemmeinServer(SK, opts);
-  const [a, b] = await Promise.all(TEST_USERS.map((e) => srv.testSession(e)));
-  const A = asUser(a.token), B = asUser(b.token);
-
-  const note = await A.collection(PRIVATE_COLLECTION).create({ probe: "a-secret" });
-  await refuse("B can't read A's private record", "not_found",
-    () => B.collection(PRIVATE_COLLECTION).get(note.id));
-  const bSees = await B.collection(PRIVATE_COLLECTION).list();
-  check("B's private list contains none of A's records",
-    !bSees.records.some((r) => r.id === note.id));
-
-  const who = await A.auth.currentUser();              // the shape your UI reads
-  check("currentUser() exposes userId (not id)", !!who.userId);
-  check("record fields live under .data", note.data?.probe === "a-secret");
-
-  await A.collection(PRIVATE_COLLECTION).delete(note.id);   // leave dev tidy
-} else {
-  console.log(SK ? "· Tier B skipped — sk_live can never mint test sessions (by design)"
-                 : "· Tier B skipped — set SECRET_KEY (sk_dev) to prove cross-user isolation");
+    // entitlements: no plan, no access — and the error names the plan.
+    if (GATED_COLLECTION) {
+      const e = await refuse("no plan → entitlement_required", "entitlement_required",
+        () => B.collection(GATED_COLLECTION).list());
+      if (e?.code === "entitlement_required")
+        check("the refusal names the plan key (err.requires)", typeof e.requires === "string" && e.requires.length > 0, e.requires);
+    } else skip("entitlement probe (paid access)", "set GATED_COLLECTION");
+  } else {
+    console.log(SK ? "· Tier B skipped — sk_live can never mint test sessions (by design)"
+                   : "· Tier B skipped — set SECRET_KEY (sk_dev) to prove cross-user isolation");
+  }
+} catch (e) {
+  console.error(`\nreaffirm could not complete — this is a config or connectivity failure, NOT a boundary verdict:`);
+  console.error(`  ${e.code ?? "(no code)"} — ${e.message}`);
+  if (e.code === "unknown_collection") console.error("  → a CONFIG name doesn't exist in this app. Fix the CONFIG block at the top of this file.");
+  process.exit(2);
 }
 
 console.log(fail ? `\n${fail} boundary check(s) FAILED` : "\nall boundaries reaffirmed");