@byollm/server 0.1.0-alpha.52 → 0.1.0-alpha.53

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.52`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.53`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/server@alpha`.
 >
@@ -105,7 +105,7 @@
 > packages published and `@byollm/server` did not: a Sigstore
 > transparency-log 409 on its provenance attestation. The workflow's
 > "already published" guard correctly refuses to resume a partial publish,
-> so `0.1.0-alpha.52` is that release, whole.
+> so `0.1.0-alpha.53` is that release, whole.
 >
 > If you run the Supabase adapter, `alpha.21` needs
 > `20260819010000_completed_by_lease_id.sql`: alpha.19 shipped §3.6's
@@ -222,7 +222,7 @@ whichever one it did not pair with.
 const job = await getApp().enqueue({
   kind: "llm.generate",
   audience: "private", // this user's own device only — the default
-  owner: userId,
+  owner: ownerId, // who this is depends on your mode — see below
   payload: { prompt: `Summarize this transcript:\n\n${transcript}` },
 });
 
@@ -241,6 +241,56 @@ const { outcome, fallback } = await job.result({
 `noRunnerAvailable` path — never a bare promise that hangs forever. If nobody
 is online to run the job, you find out and can fall back.
 
+## Who `owner` is — this differs by mode
+
+`owner` names the person whose devices should do the work, and the two
+connection modes do not use the same names for people. Getting this wrong is
+the one integration mistake that produces no error: the job enqueues, returns
+an id, and never routes.
+
+**Direct** — daemons reach your own handlers, and you are the only party who
+knows who anybody is. `owner` is your own user id, from your session, never
+from the client. That is what the example above shows.
+
+**Cloud** — daemons reach `hub.byollm.cloud`, which has its own identity
+space: rosters, consents and budgets all speak **BYOLLM ids**. Your user id
+means nothing there. `owner` must be the person's BYOLLM id.
+
+Ask them for it. Every signed-in person can read it on their byollm.cloud
+account page under **Your BYOLLM id**, with a copy button. Add a settings
+field, have them paste it, store it against your own user record.
+
+The id names them and authorises nothing — someone holding it can address work
+to a person and cannot deliver it, because the consent row is what opens the
+route. So a pasted id is not a credential you are being trusted with, and a
+wrong one is harmless. Two things still matter: it must come from the person's
+own account rather than being inferred by your app, and they must connect your
+site on byollm.cloud before anything routes.
+
+**A wrong id is silence, not an error.** The relay routes on a consented
+`(site, owner)` pair, so a mistyped id — or one belonging to somebody who has
+not connected your site — matches no route. The job waits, then expires. So
+check ids when you receive them rather than when you enqueue:
+
+```ts
+const { available } = await getApp().runnerAvailability({
+  kind: "llm.generate",
+  owner: pastedByollmId,
+});
+
+if (!available) {
+  // Existence-neutral, deliberately.
+  return "That id has no devices for you. Check it, or connect this site on byollm.cloud.";
+}
+```
+
+Keep that message vague on purpose. A typo'd id and an id belonging to somebody
+who has not connected you give the same answer, and that is the system working
+rather than a limitation to route around — telling them apart would make this
+call an account-existence oracle: probe a guess, sort the answers, enumerate.
+Never write "no such account". If you ever get an answer that *does*
+distinguish them, that is a bug worth reporting.
+
 ## The approval page
 
 Pairing is a device-code exchange, so you need one page where a signed-in user

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byollm/server",
-  "version": "0.1.0-alpha.52",
+  "version": "0.1.0-alpha.53",
   "description": "Framework-agnostic BYOLLM protocol handlers, a reference in-memory store, a Next.js mount, and a Supabase adapter.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "node": ">=22.14"
   },
   "dependencies": {
-    "@byollm/protocol": "0.1.0-alpha.52"
+    "@byollm/protocol": "0.1.0-alpha.53"
   },
   "peerDependencies": {
     "@supabase/supabase-js": "^2.58.0"