@lunora/cli 1.0.0-alpha.330 → 1.0.0-alpha.331

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/cli",
-  "version": "1.0.0-alpha.330",
+  "version": "1.0.0-alpha.331",
   "description": "The Lunora CLI: init, dev, deploy, codegen, migrate, seed, doctor, insights, logs, registry, and the rest of the project commands",
   "keywords": [
     "agent-skills",
@@ -52,16 +52,16 @@
   },
   "dependencies": {
     "@bomb.sh/tab": "0.0.22",
-    "@lunora/advisor": "1.0.0-alpha.175",
+    "@lunora/advisor": "1.0.0-alpha.176",
     "@lunora/bindings": "1.0.0-alpha.88",
-    "@lunora/codegen": "1.0.0-alpha.243",
-    "@lunora/config": "1.0.0-alpha.288",
+    "@lunora/codegen": "1.0.0-alpha.244",
+    "@lunora/config": "1.0.0-alpha.289",
     "@lunora/container": "1.0.0-alpha.64",
     "@lunora/d1": "1.0.0-alpha.155",
     "@lunora/errors": "1.0.0-alpha.48",
-    "@lunora/mcp": "1.0.0-alpha.201",
-    "@lunora/runtime": "1.0.0-alpha.167",
-    "@lunora/seed": "1.0.0-alpha.173",
+    "@lunora/mcp": "1.0.0-alpha.202",
+    "@lunora/runtime": "1.0.0-alpha.168",
+    "@lunora/seed": "1.0.0-alpha.174",
     "@visulima/cerebro": "3.1.1",
     "@visulima/error": "6.1.0",
     "@visulima/fs": "6.0.7",

package/skills/lunora-functions/SKILL.md

@@ -220,6 +220,7 @@ So write the call first, then run `lunora codegen` to surface the typed context:
 | `ctx.ai`                                                                                  | `@lunora/ai` (Workers AI)     |
 | `ctx.flags`                                                                               | `@lunora/flags` (OpenFeature) |
 | `ctx.queues.<name>`                                                                       | `@lunora/queue`               |
+| `ctx.topics.<name>` (pub/sub, see below)                                                  | `@lunora/queue`               |
 | `ctx.workflows` / `ctx.runStep`                                                           | `@lunora/workflow`            |
 | `ctx.containers`                                                                          | `@lunora/container`           |
 | `ctx.browser` (action-only)                                                               | `@lunora/browser`             |
@@ -242,6 +243,69 @@ non-deterministic I/O: a query is re-run on every subscription re-evaluation, so
 a non-deterministic read makes reactivity wrong, and a mutation's writes are
 transactional — a rollback cannot un-send a network call.
 
+### Topics: one event, many consumers
+
+A queue has one consumer. To fan one event out to several independent
+consumers, declare a topic and subscribe to it — in `lunora/queues.ts`, next to
+your queues. Each subscription is its own queue with its own retries and
+dead-letter queue.
+
+```ts
+// lunora/queues.ts
+import { defineSubscription, defineTopic } from "@lunora/queue";
+
+import { internal } from "./_generated/api";
+
+export const signups = defineTopic<{ userId: string }>();
+
+export const welcomeEmail = defineSubscription(signups, {
+    handler: async (_ctx, batch) => {
+        for (const message of batch.messages) {
+            await message.run(internal.email.welcome, { userId: message.body.userId });
+            message.ack();
+        }
+    },
+    maxRetries: 5,
+    deadLetterQueue: "welcome-email-dlq",
+});
+
+// in a mutation or action
+await ctx.topics.signups.publish({ userId });
+```
+
+- Delivery is **at-least-once per subscription** and unordered — make handlers
+  idempotent. A failed send rejects `publish`, and a retry re-delivers to the
+  subscriptions that already got it.
+- A subscription is published to only through its topic, never `ctx.queues`.
+  The topic passed to `defineSubscription` must be a `defineTopic` export of the
+  same file.
+- Rate-limit public procedures that publish: one publish is one send per
+  subscription (`privileged_fanout_from_public_procedure` flags it).
+
+## Modules: grouping `lunora/` folders
+
+A folder whose `module.ts` default-exports `defineModule(...)` is a module.
+Modules are metadata — no `api.*` path or runtime change, still one Worker —
+that drive the Studio **Architecture** view, OpenAPI tags, and table ownership:
+
+```ts
+// lunora/billing/module.ts
+import { defineModule } from "@lunora/server";
+
+export default defineModule({ description: "Invoices and payments", tables: ["invoices"] });
+```
+
+- Write `description` and `tables` inline; codegen reads them without running
+  the file. Modules do not nest.
+- `cross_module_table_write` warns when a function outside the owning module
+  writes an owned table (insert, `patch`/`replace`/`delete`, batch or facade).
+  Route the write through a function in the owning module instead.
+- Installed components (`.extend(...)` schema extensions) count as modules that
+  own their prefixed tables: write them through the component's functions, not
+  `ctx.db` directly.
+- Keep ids typed `Id<"table">` — a write through an untyped `string` id cannot
+  be attributed to a table.
+
 ## HTTP endpoints
 
 For webhooks or non-RPC HTTP, use `httpRouter` / `httpRoute` + `httpAction`:
@@ -284,4 +348,6 @@ export default app;
 - [ ] `ctx.db` writes only inside mutations; ids typed with `Id<"table">`.
 - [ ] Any `ctx.db.related` walk is narrowed with `edges` / `direction`, and its
       foreign keys are indexed.
+- [ ] Writes to a module- or component-owned table go through the owner's
+      functions (`cross_module_table_write` is clean).
 - [ ] Ran `lunora codegen`; typecheck is clean.