@vibes.diy/prompts 12.1.0 → 12.1.2

package/llms/backend.md

@@ -81,6 +81,44 @@ than `forbidden` — keep scheduled writes small and well-guarded. `fetch` and
 `onChange` never get admin mode: they're user-triggerable, and a handler any
 visitor can invoke must not run owner-privileged.
 
+### Taking on the authorization job: `config.fetch.unfilteredReads`
+
+Because the `fetch` lane runs as the calling user, a `fetch` handler by default
+reads nothing for a caller with no session, and cannot read an access-fn-bound
+database without an opt-in. Some routes legitimately need to: a calendar feed at
+`GET /_api/faves.ics?t=<token>` is fetched by a calendar app that carries no
+login, and the docs it serves are private to one user. For those, `backend.js`
+can opt in — per database, `fetch` lane only:
+
+```js
+export const config = {
+  fetch: {
+    unfilteredReads: {
+      dbs: ["faves"],
+      why: "serves per-user .ics calendar feeds authorized by an unguessable token",
+    },
+  },
+};
+```
+
+This is an **obligation, not a convenience**. Inside that handler, for those
+databases, you are taking on the authorization job the platform normally does:
+both the anonymous refusal and the access-function scoping come off, so
+`ctx.db.query`/`ctx.db.get` return **every** document in the named databases —
+all users, all channels — to whoever called the route. The legitimate pattern is
+a **capability**: an unguessable, per-user, revocable token in the URL or a
+header, checked before you read, with the response scoped to exactly that
+token's owner. "The URL is hard to guess" only holds if you mint the token
+yourself with real entropy and never print it anywhere else.
+
+Two things to design around. The opt-in is scoped to the **lane, not the
+route**: `backend.js` exports one `fetch` handler that routes internally, so
+every path inside it can read those databases — keep the check at the top and
+name as few databases as the feature needs. And it is a **static declaration**:
+`dbs` must be plain string literals and `why` a non-empty string literal saying
+who is authorized and how, or the push is rejected. There is no call-site flag,
+and no other lane can opt in.
+
 ## ctx — what a handler gets
 
 ```js
@@ -89,7 +127,8 @@ ctx.userInfo; // { userHandle } or null — who the handler is acting as
 ctx.secrets; // Record<string,string> — the owner's per-vibe secrets; frozen, {} when none
 await ctx.db.put(doc, { db: "notes", id: "optional-id" }); // resolves to the doc id AFTER commit
 await ctx.db.delete(docId, { db: "notes" });
-const docs = await ctx.db.query({ db: "notes" }); // latest non-deleted docs (each with _id)
+const docs = await ctx.db.query({ db: "notes", field: "type", key: "note", limit: 100 }); // a filtered page
+const doc = await ctx.db.get("state:cursor", { db: "notes" }); // one doc by _id, or null
 const text = await ctx.callAI("prompt", { model: "openrouter/auto", max_tokens: 500 }); // server-side AI call
 const res = await ctx.fetch("https://api.example.com/x", { headers }); // outbound HTTP — use this, not bare fetch()
 ```
@@ -99,13 +138,57 @@ const res = await ctx.fetch("https://api.example.com/x", { headers }); // outbou
   database that triggered the event is the default.
 - Always `await` db calls; they resolve only after the write commits (or throw
   when the access function denies it).
-- `ctx.db.query({ db })` returns the whole database's latest docs (capped at
-  2000) — filter and sort in the handler. It is read-ACL-gated as the acting
-  identity and anonymous `fetch` callers are denied. In `scheduled` (admin
-  mode) the read is **unfiltered** — access-fn-bound databases return every
-  doc, across all users and channels. In `fetch`/`onChange`, databases bound
-  to an access function cannot be queried (keep those lanes' read databases on
-  plain ACLs). Made for `scheduled` sweeps: read, decide, then `put`/`delete`.
+- `ctx.db.get(id, { db })` resolves the single document with that `_id`, or
+  `null` when it is missing or deleted. It is the right read whenever you can
+  name the document — a tick's state doc, a token lookup, a singleton. Never
+  scan a database looking for a doc whose id you already know.
+- `ctx.db.query({ db, field, key, keys, range, prefix, limit, after })` reads a
+  **page** of the database's latest docs. Every filter is optional and they
+  combine: `field` names the document field to match on, then `key` (one exact
+  value), `keys` (any of several), `range` (`[from, to]`) or `prefix` (a string,
+  or an array prefix — charwise-encoded, same semantics the client's queries
+  use) narrows it. Three edges to get right: **no `field` means no filtering**
+  (you get a raw page of everything), a bare `field` with no selector still
+  drops docs that lack that field, and `prefix` takes the **raw** value — a
+  plain string or array, never anything pre-encoded (the encoding is internal).
+  `limit` only clamps the page **down**; the 2000-doc cap stays. Ask for what
+  the handler actually needs — reading the whole database and filtering in the
+  handler wastes the cap and goes blind as the app grows. Sorting still happens
+  in the handler.
+- The result is a real `Array` of docs that **also** destructures — both
+  `const docs = await ctx.db.query(...)` and
+  `const { docs, next } = await ctx.db.query(...)` work.
+- **Paginate on `next`, never on emptiness.** `next` is computed from the raw
+  page *before* filtering, and only when that page came back full — so a
+  narrowly filtered page can be **empty and still carry `next`**. Stopping at
+  the first empty page silently truncates the read:
+
+  ```js
+  let after;
+  do {
+    const page = await ctx.db.query({ db: "faves", field: "type", key: "favorite", limit: 500, after });
+    for (const doc of page) {
+      // …
+    }
+    after = page.next;
+  } while (after);
+  ```
+
+  `next` rides on the array itself, so read it **before** transforming: any
+  array operation (`.filter()`, `.map()`, spread) returns a plain array with no
+  `next`. On the last page the property is absent, not undefined — `"next" in
+  page` is `false`.
+- Both reads are read-ACL-gated as the acting identity, through the same gate:
+  anonymous `fetch` callers are denied, and in `fetch`/`onChange` a database
+  bound to an access function cannot be read at all (keep those lanes' read
+  databases on plain ACLs). In `scheduled` (admin mode) reads are
+  **unfiltered** — access-fn-bound databases return every doc, across all users
+  and channels. Made for `scheduled` sweeps: read, decide, then `put`/`delete`.
+- The one exception to that last sentence is the declared opt-in above,
+  `config.fetch.unfilteredReads` — a `fetch` handler that names a database there
+  reads it unfiltered, anonymous callers included, and owes the authorization
+  check itself. Nothing changes for writes, or for any lane or database you
+  didn't name.
 - `ctx.secrets` carries the owner's per-vibe secrets, set in the vibe's settings
   page or with `vibes-diy secrets set KEY`. Use it to verify inbound credentials —
   a webhook's shared secret or token — or to authenticate outbound calls
@@ -177,8 +260,8 @@ const SNAPSHOT = [
 ];
 
 async function ensureSnapshot(ctx) {
-  const docs = await ctx.db.query({ db: "nodeReleases" });
-  if (docs.some((doc) => doc.type === "release")) return;
+  // Point-read by id — the snapshot has a known `_id`, so there's nothing to scan for.
+  if (await ctx.db.get(SNAPSHOT[0]._id, { db: "nodeReleases" })) return;
   for (const doc of SNAPSHOT) await ctx.db.put(doc, { db: "nodeReleases" });
 }
 
@@ -190,18 +273,19 @@ function unchanged(existing, next) {
   return Object.keys(next).every((k) => existing[k] === next[k]);
 }
 
-async function putIfChanged(ctx, byId, next) {
-  if (unchanged(byId.get(next._id), next)) return;
+// The diff source is a POINT-READ per incoming id, not a query over the stored
+// set: the work is bounded by what the feed sent (≤20 docs), never by how big
+// the database has grown — so a db that outgrows a query page can never
+// silently eject rows from the diff and turn this tick into a rewrite loop.
+async function putIfChanged(ctx, next) {
+  const existing = await ctx.db.get(next._id, { db: "nodeReleases" });
+  if (unchanged(existing, next)) return;
   await ctx.db.put(next, { db: "nodeReleases" });
 }
 
 export async function scheduled(event, ctx) {
   await ensureSnapshot(ctx);
 
-  // Read current docs once so each write can diff against what's already stored.
-  const current = await ctx.db.query({ db: "nodeReleases" });
-  const byId = new Map(current.map((doc) => [doc._id, doc]));
-
   // One request, no retry storm; ctx.fetch enforces 15s/10MB and egress caps.
   const response = await ctx.fetch("https://api.github.com/repos/nodejs/node/releases?per_page=20", {
     headers: { accept: "application/vnd.github+json" },
@@ -215,7 +299,7 @@ export async function scheduled(event, ctx) {
     if (denied?.vibesEgressDenied === true) {
       // A real state change — putIfChanged writes once on entering denial, then
       // nothing while it persists. No per-tick timestamp, so no churn.
-      await putIfChanged(ctx, byId, {
+      await putIfChanged(ctx, {
         _id: "refresh:status",
         type: "refreshStatus",
         state: "egress-denied",
@@ -233,7 +317,7 @@ export async function scheduled(event, ctx) {
   for (const row of rows.slice(0, 20)) {
     if (!row?.id || !row?.html_url || !row?.published_at) continue;
     // Stable per-item `_id` + diff: a row whose content is identical is skipped.
-    await putIfChanged(ctx, byId, {
+    await putIfChanged(ctx, {
       _id: `release:github-${row.id}`,
       type: "release",
       title: String(row.name || row.tag_name || "Node.js release"),
@@ -243,7 +327,7 @@ export async function scheduled(event, ctx) {
     });
   }
 
-  await putIfChanged(ctx, byId, {
+  await putIfChanged(ctx, {
     _id: "refresh:status",
     type: "refreshStatus",
     state: "fresh",
@@ -294,15 +378,29 @@ down. Catch that exact 403 shape and show the saved snapshot with honest copy
 render a broken screen, or silently label saved data as fresh.
 
 **Zero-churn discipline for scheduled ticks.** A cron runs forever, so it must
-not write forever. Read the current docs first (`ctx.db.query`), give every item
-a stable `_id`, and `put` **only** the rows whose content actually changed — the
-`putIfChanged` diff above. Never stamp a per-tick `checkedAt`/`updatedAt`/run
+not write forever. Give every item a stable `_id` and `put` **only** the rows
+whose content actually changed — the `putIfChanged` diff above, which
+point-reads each id it is about to write. Diff against **point-reads of the
+incoming ids**, so the work is bounded by what arrived this tick, not by how
+big the database has grown; reach for a keyed `ctx.db.query` only when the
+stored set itself is the target (and then walk `next` to exhaustion before
+diffing — a one-page diff source re-puts everything the page missed, forever). Never stamp a per-tick `checkedAt`/`updatedAt`/run
 counter onto a doc: it makes every put look new, and each spurious put mints a
 fresh revision and a sync-feed row that re-tickles every replica on every tick.
 A failed or empty upstream fetch aborts with no writes, preserving the last-good
 rows. Only a genuine content change — a new or updated row, a real state
 transition — earns a write.
 
+**A tick's own memory is a document it reads by id.** Whatever a scheduled
+handler needs to know about what it already did — a cursor, a last-synced
+marker, a per-run state — lives in one doc with a fixed `_id`, read with
+`ctx.db.get(id, { db })`. Never re-derive that answer by scanning the database:
+a sweep that diffs against its own whole-db read goes blind the moment the
+database outgrows one page, and then rewrites everything on every tick, forever.
+Keep a copy of the state in module scope as well, and read a **missing or failed**
+state read as *"don't know — skip this tick"*, never as *"nothing has been done
+yet"*: that second reading is exactly what restarts the endless rewrite.
+
 ## fetch — the app's HTTP endpoint
 
 Runs for requests to the app's `/_api` route. The request path is rooted after

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "12.1.0",
+  "version": "12.1.2",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -24,9 +24,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "^12.1.0",
-    "@vibes.diy/identity": "^12.1.0",
-    "@vibes.diy/use-vibes-types": "^12.1.0",
+    "@vibes.diy/call-ai-v2": "^12.1.2",
+    "@vibes.diy/identity": "^12.1.2",
+    "@vibes.diy/use-vibes-types": "^12.1.2",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.2"
   },