@vibes.diy/prompts 8.2.0 → 8.2.1

package/llms/access.md

@@ -47,8 +47,16 @@ export function chat(doc, oldDoc, user, ctx) {
 
 **A follow-up edit that adds a NEW doc type updates `access.js` FIRST.** The app runs live while your edits stream in, and writes are enforced against the access.js that was in force before this turn until the whole turn completes — so a `db.put` of a doc type the old function rejects fails immediately (`unknown document type`), even though your access.js update lands later in the same reply. Emit the access.js edit adding the new type's branch before the App.jsx edits that write it. And never fire-and-forget background writes of a newly added type: gate seed/auto-write effects on `useVibe(dbName)` — `if (!ready || !can.create(sampleDoc).ok) return;` with `ready`/`can` in the effect deps, checking a representative sample of **each** doc type the effect writes — so a not-yet-allowed write is skipped quietly instead of surfacing rejection errors the user didn't cause.
 
+### Ending the function: terminal denial (the default) vs. the discard channel
+
+Every access function ends by handling the doc types it knows and **denying everything else**. The **default** ending — closing every worked example below — is the terminal `throw { forbidden: "unknown document type" }`: fail-closed, and loud. If the app later writes a type nobody added a branch for, the write is rejected with a visible error, so type-enumeration drift surfaces instead of silently corrupting the data model. **Reach for the throw unless you have a specific, named reason not to.**
+
+The one documented alternative is the **discard channel** — `return { channels: ["discard"], grant: {} }`: accept the unknown-type write into a channel that has **no** grant, so it persists but nothing can ever read it back. This is **deny-by-unreadability**, not deny-by-error — the write silently succeeds and then vanishes, so the user sees neither a failure nor the data. That trade-off makes it the wrong default: a silent swallow hides real bugs the throw would have caught. Use it **only** where a visible failure is worse than a silent one. The canonical case is the **anonymous-local sign-in migration**: when an anonymous visitor signs in, their device-local docs migrate into the cloud db in bulk, and a single stray legacy doc type hitting a terminal throw would fail the *whole* migration and surface error toasts on first sign-in. Routing the unknown remainder to `discard` lets the known docs migrate while the legacy straggler is swallowed instead of breaking the flow. Outside that kind of bulk/legacy-migration path, keep the throw. (Note the shape difference the runtime cares about: `grant: {}` grants no reader, so the write is unreadable — deny. A permissive fallthrough that returns a *readable* channel for unknown types, e.g. `grant: { public: [...] }`, is fail-open and is the exact bug both endings exist to prevent.)
+
 ## Worked examples — permission design
 
+_Each example below closes its type dispatch with the default terminal `throw { forbidden: "unknown document type" }`; substitute the `discard`-channel fallthrough above only for an app on the bulk/legacy-migration path that documents why._
+
 ### Worked example — open channel wall (author-owned writes)
 
 access.js

package/llms/backend.md

@@ -32,6 +32,10 @@ An app can need more than one — a payments app wants `fetch` (webhook receipt)
 **and** `onChange` (email on the new order). If none of these signal words fit
 the request, the app needs no `backend.js` — don't emit one.
 
+**Decision rule:** when live external data is the app's substance, use
+`backend.js` + **cache-into-db, never fetch-per-render**; when external data is
+only launch flavor, take a generation-time snapshot into `seed.json` instead.
+
 ## Output format
 
 `backend.js` is a separate file, exactly like `access.js`: one prose line, the
@@ -143,6 +147,149 @@ const res = await ctx.fetch("https://api.example.com/x", { headers }); // outbou
   when the result must be server-authoritative (moderation, digests,
   summaries users shouldn't be able to forge).
 
+## Worked external-data pattern — cache into the live database
+
+A URL that worked during generation may still be denied by runtime egress.
+Never fetch an external feed from render or a React effect. Poll once per tick,
+normalize a bounded number of rows into the exact database and document shape
+the UI queries, and keep the last successful rows when refresh fails. Seed a
+small honest snapshot before the first request so even a first-run denial has
+something useful to show.
+
+This complete example makes one curated GitHub API request every 15 minutes
+(well inside the documented caps), stores at most 20 normalized `release` docs
+in `nodeReleases`, and records refresh state in that same database.
+
+backend.js
+
+```js
+export const config = { scheduled: { interval: "15m" } };
+
+const SNAPSHOT = [
+  {
+    _id: "release:snapshot-v22",
+    type: "release",
+    title: "Node.js 22 (saved snapshot)",
+    url: "https://nodejs.org/en/blog/release/v22.0.0",
+    publishedAt: "2024-04-24T00:00:00.000Z",
+    source: "saved-snapshot",
+  },
+];
+
+async function ensureSnapshot(ctx) {
+  const docs = await ctx.db.query({ db: "nodeReleases" });
+  if (docs.some((doc) => doc.type === "release")) return;
+  for (const doc of SNAPSHOT) await ctx.db.put(doc, { db: "nodeReleases" });
+}
+
+export async function scheduled(event, ctx) {
+  await ensureSnapshot(ctx);
+
+  // 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" },
+  });
+
+  if (response.status === 403) {
+    const denied = await response.clone().json().catch(() => null);
+    if (denied?.vibesEgressDenied === true) {
+      await ctx.db.put(
+        {
+          _id: "refresh:status",
+          type: "refreshStatus",
+          state: "egress-denied",
+          message: "showing saved data — live refresh unavailable",
+          checkedAt: event.scheduledTime,
+        },
+        { db: "nodeReleases" }
+      );
+      return; // preserve the seeded/last-good release docs
+    }
+  }
+
+  if (!response.ok) {
+    await ctx.db.put(
+      {
+        _id: "refresh:status",
+        type: "refreshStatus",
+        state: "failed",
+        message: "showing saved data — refresh failed",
+        checkedAt: event.scheduledTime,
+      },
+      { db: "nodeReleases" }
+    );
+    return;
+  }
+
+  const rows = await response.json();
+  for (const row of rows.slice(0, 20)) {
+    if (!row?.id || !row?.html_url || !row?.published_at) continue;
+    await ctx.db.put(
+      {
+        _id: `release:github-${row.id}`,
+        type: "release",
+        title: String(row.name || row.tag_name || "Node.js release"),
+        url: String(row.html_url),
+        publishedAt: String(row.published_at),
+        source: "github-live",
+      },
+      { db: "nodeReleases" }
+    );
+  }
+  await ctx.db.put(
+    {
+      _id: "refresh:status",
+      type: "refreshStatus",
+      state: "fresh",
+      message: "Live feed refreshed",
+      checkedAt: event.scheduledTime,
+    },
+    { db: "nodeReleases" }
+  );
+}
+```
+
+App.jsx
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+
+export default function App() {
+  const { useLiveQuery } = useFireproof("nodeReleases");
+  const { docs: releaseDocs } = useLiveQuery("type", { key: "release" });
+  const { docs: statusDocs } = useLiveQuery("type", { key: "refreshStatus" });
+  const releases = [...releaseDocs].sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+  const status = statusDocs.find((doc) => doc._id === "refresh:status");
+
+  return (
+    <main className="mx-auto max-w-2xl p-6">
+      <h1 className="text-3xl font-bold">Node.js releases</h1>
+      {status?.state === "egress-denied" && (
+        <p role="status" className="my-4 rounded bg-amber-100 p-3 text-amber-950">
+          showing saved data — live refresh unavailable
+        </p>
+      )}
+      <ul className="mt-6 space-y-3">
+        {releases.map((release) => (
+          <li key={release._id} className="rounded border p-4">
+            <a className="font-semibold underline" href={release.url} target="_blank" rel="noreferrer">
+              {release.title}
+            </a>
+            <time className="ml-3 text-sm text-slate-500">{release.publishedAt.slice(0, 10)}</time>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+```
+
+The `vibesEgressDenied` body is a policy result, not proof that the upstream is
+down. Catch that exact 403 shape and show the saved snapshot with honest copy —
+**"showing saved data — live refresh unavailable"**. Never clear cached rows,
+render a broken screen, or silently label saved data as fresh.
+
 ## 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": "8.2.0",
+  "version": "8.2.1",
   "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": "^8.2.0",
-    "@vibes.diy/identity": "^8.2.0",
-    "@vibes.diy/use-vibes-types": "^8.2.0",
+    "@vibes.diy/call-ai-v2": "^8.2.1",
+    "@vibes.diy/identity": "^8.2.1",
+    "@vibes.diy/use-vibes-types": "^8.2.1",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.2"
   },

package/system-prompt-initial-oneshot.md

@@ -239,6 +239,7 @@ Rules for the items:
 - Every item carries a short immutable **`key`** slug (`"alert"`, `"setname"`), **unique within its database's array**. The key is the item's identity across codegen turns — the platform derives the document id and idempotency from it, so **do NOT invent `_id`s or write any dedupe logic**. Re-emitting an unchanged `seed.json` on a later turn is a no-op; changing an item's content updates that one document.
 - Set `_id` explicitly **only** for a well-known singleton (a `config:setname` settings doc); the `key` is still required.
 - Multi-db apps get one array per db; use the exact db names from `App.jsx`.
+- **Seed every app-written document type.** For every string-literal `type` that `App.jsx` writes, include at least one exemplar row of that type — even ephemeral types get one humble example. Types originated by the platform at runtime (for example ImgGen's `"image"`) cannot be seeded; handle those with `access.js` branches instead.
 - **JSON only — no images or binary.** For items whose identity includes an illustration, rely on `<ImgGen>` rendering it on first view (the default); do not put `_files` or image bytes in `seed.json`.
 - **If the app has an `access.js`, every `type` you emit here must have a branch in it** — but don't add an access function _just_ to satisfy this: an app with no per-document rules keeps the default open data model and seeds fine without one. When there **is** an `access.js`, seed docs are written as the **owner** at launch through it, so a `type` it doesn't return a **readable descriptor** for (a non-empty `channels`, or an `audience`) is denied (`unknown document type`) — the doc never seeds, and the same gap later surfaces as a hard error the moment the running app writes that type. Before finishing, if you emitted an `access.js`, confirm it returns a readable descriptor for every distinct `type` present in `seed.json`. (Deletes go through the same gate: a `db.del` writes a tombstone `{ _id, _deleted: true }` that carries **no** `type`, channel, or author — so branch on `doc._deleted`, then authorize and route it off **`oldDoc`** (the persisted document is the only trustworthy record of the doc's type and owner), returning the same descriptor the live doc got. A bare `_deleted` branch that ignores `oldDoc` either fails the app's own deletes or over-broadens them.)
 

package/system-prompt-initial.md

@@ -243,6 +243,7 @@ Rules for the items:
 - Every item carries a short immutable **`key`** slug (`"alert"`, `"setname"`), **unique within its database's array**. The key is the item's identity across codegen turns — the platform derives the document id and idempotency from it, so **do NOT invent `_id`s or write any dedupe logic**. Re-emitting an unchanged `seed.json` on a later turn is a no-op; changing an item's content updates that one document.
 - Set `_id` explicitly **only** for a well-known singleton (a `config:setname` settings doc); the `key` is still required.
 - Multi-db apps get one array per db; use the exact db names from `App.jsx`.
+- **Seed every app-written document type.** For every string-literal `type` that `App.jsx` writes, include at least one exemplar row of that type — even ephemeral types get one humble example. Types originated by the platform at runtime (for example ImgGen's `"image"`) cannot be seeded; handle those with `access.js` branches instead.
 - **JSON only — no images or binary.** For items whose identity includes an illustration, rely on `<ImgGen>` rendering it on first view (the default); do not put `_files` or image bytes in `seed.json`.
 - **If the app has an `access.js`, every `type` you emit here must have a branch in it** — but don't add an access function _just_ to satisfy this: an app with no per-document rules keeps the default open data model and seeds fine without one. When there **is** an `access.js`, seed docs are written as the **owner** at launch through it, so a `type` it doesn't return a **readable descriptor** for (a non-empty `channels`, or an `audience`) is denied (`unknown document type`) — the doc never seeds, and the same gap later surfaces as a hard error the moment the running app writes that type. Before finishing, if you emitted an `access.js`, confirm it returns a readable descriptor for every distinct `type` present in `seed.json`. (Deletes go through the same gate: a `db.del` writes a tombstone `{ _id, _deleted: true }` that carries **no** `type`, channel, or author — so branch on `doc._deleted`, then authorize and route it off **`oldDoc`** (the persisted document is the only trustworthy record of the doc's type and owner), returning the same descriptor the live doc got. A bare `_deleted` branch that ignores `oldDoc` either fails the app's own deletes or over-broadens them.)
 

package/system-prompt.md

@@ -633,6 +633,7 @@ Rules for the items:
 - Every item carries a short immutable **`key`** slug (`"alert"`, `"setname"`), **unique within its database's array**. The key is the item's identity across codegen turns — the platform derives the document id and idempotency from it, so **do NOT invent `_id`s or write any dedupe logic**. Re-emitting an unchanged `seed.json` on a later turn is a no-op; changing an item's content updates that one document.
 - Set `_id` explicitly **only** for a well-known singleton (a `config:setname` settings doc); the `key` is still required.
 - Multi-db apps get one array per db; use the exact db names from `App.jsx`.
+- **Seed every app-written document type.** For every string-literal `type` that `App.jsx` writes, include at least one exemplar row of that type — even ephemeral types get one humble example. Types originated by the platform at runtime (for example ImgGen's `"image"`) cannot be seeded; handle those with `access.js` branches instead.
 - **JSON only — no images or binary.** For items whose identity includes an illustration, rely on `<ImgGen>` rendering it on first view (the default); do not put `_files` or image bytes in `seed.json`.
 - **If the app has an `access.js`, every `type` you emit here must have a branch in it** — but don't add an access function _just_ to satisfy this: an app with no per-document rules keeps the default open data model and seeds fine without one. When there **is** an `access.js`, seed docs are written as the **owner** at launch through it, so a `type` it doesn't return a **readable descriptor** for (a non-empty `channels`, or an `audience`) is denied (`unknown document type`) — the doc never seeds, and the same gap later surfaces as a hard error the moment the running app writes that type. Before finishing, if you emitted an `access.js`, confirm it returns a readable descriptor for every distinct `type` present in `seed.json`. (Deletes go through the same gate: a `db.del` writes a tombstone `{ _id, _deleted: true }` that carries **no** `type`, channel, or author — so branch on `doc._deleted`, then authorize and route it off **`oldDoc`** (the persisted document is the only trustworthy record of the doc's type and owner), returning the same descriptor the live doc got. A bare `_deleted` branch that ignores `oldDoc` either fails the app's own deletes or over-broadens them.)