@cosmicdrift/kumiko-framework 0.176.2 → 0.178.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.176.2",
+  "version": "0.178.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.176.2",
+    "@cosmicdrift/kumiko-types": "0.178.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.176.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.178.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.177.0",
+    "type": "breaking",
+    "title": "createMoneyField's amount now converts to/from minor-unit BIGINT storage (fw#1767).",
+    "detail": "flattenMoney/rehydrateMoney used to pass the API amount straight into the BIGINT column without the minor-unit (cents) conversion the column's own doc comment always claimed. A decimal amount (e.g. 56799.16) crashed the insert (float into bigint); a plain integer major-unit amount (e.g. 45000 meaning €450.00) was silently stored as 45000 minor units — 100× too small on read-back.",
+    "migration": "amount is now always major units (ordinary decimal, e.g. 56799.16) on both write and read — DB storage stays exact-integer cents automatically, no caller change needed for that direction. If you already wrote createMoneyField data under the old (unconverted) semantics, multiply stored amounts by 100 before upgrading, or reconcile after — no known production deployment currently persists money-typed data (verified solon and phronexsis are both pre-launch before this merged)."
+  },
   {
     "version": "0.167.0",
     "type": "breaking",

package/src/db/__tests__/compound-types.test.ts

@@ -49,7 +49,8 @@ describe("flattenCompoundTypes — Pipeline", () => {
     expect(flat["label"]).toBe("ACME");
     expect((flat["pickupUtc"] as Temporal.Instant).toString()).toBe("2026-04-15T09:00:00Z");
     expect(flat["pickupTz"]).toBe("Europe/Lisbon");
-    expect(flat["buyingPrice"]).toBe(45_000);
+    // flattenMoney converts major units (API) → minor units (DB, ×100).
+    expect(flat["buyingPrice"]).toBe(4_500_000);
     expect(flat["buyingPriceCurrency"]).toBe("EUR");
   });
 
@@ -75,7 +76,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
         label: "ACME",
         pickupUtc: "2026-04-15T09:00:00Z",
         pickupTz: "Europe/Lisbon",
-        buyingPrice: 45_000,
+        buyingPrice: 4_500_000,
         buyingPriceCurrency: "EUR",
       },
       mixedEntity,
@@ -83,6 +84,7 @@ describe("rehydrateCompoundTypes — Pipeline", () => {
     expect(out).toEqual({
       label: "ACME",
       pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" },
+      // rehydrateMoney converts minor units (DB) → major units (API, ÷100).
       buyingPrice: { amount: 45_000, currency: "EUR" },
     });
   });

package/src/db/__tests__/money.test.ts

@@ -1,4 +1,8 @@
 // Pure Unit-Tests für money flatten/rehydrate Helpers.
+//
+// Contract: API-form amount is MAJOR units (56799.16 EUR), DB-form is
+// MINOR units (5679916 cents) — flattenMoney/rehydrateMoney convert at the
+// boundary (×100 / ÷100). See money.ts's file header for why this exists.
 
 import { describe, expect, test } from "bun:test";
 import { createEntity, createMoneyField, createTextField } from "../../engine";
@@ -21,24 +25,29 @@ const usdEntity: EntityDefinition = createEntity({
   },
 });
 
-describe("flattenMoney — Insert/Update Convert", () => {
-  test("{ amount, currency } → { <name>: amount, <name>Currency: currency }", () => {
-    const flat = flattenMoney({ buyingPrice: { amount: 45000, currency: "EUR" } }, orderEntity);
+describe("flattenMoney — Insert/Update Convert (major units → minor units)", () => {
+  test("{ amount, currency } → { <name>: amount*100, <name>Currency: currency }", () => {
+    const flat = flattenMoney({ buyingPrice: { amount: 450, currency: "EUR" } }, orderEntity);
     expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
   });
 
+  test("decimal amount rounds to the nearest cent", () => {
+    const flat = flattenMoney({ buyingPrice: { amount: 56799.16, currency: "EUR" } }, orderEntity);
+    expect(flat).toEqual({ buyingPrice: 5679916, buyingPriceCurrency: "EUR" });
+  });
+
   test("primitive number (legacy) wird akzeptiert + entity.defaultCurrency angehängt", () => {
-    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+    const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     expect(flat).toEqual({ buyingPrice: 45000, buyingPriceCurrency: "EUR" });
   });
 
   test("primitive number nutzt USD wenn entity.defaultCurrency = USD", () => {
-    const flat = flattenMoney({ fee: 199 }, usdEntity);
+    const flat = flattenMoney({ fee: 1.99 }, usdEntity);
     expect(flat).toEqual({ fee: 199, feeCurrency: "USD" });
   });
 
   test("expliziter <name>Currency im Payload überschreibt nicht", () => {
-    const flat = flattenMoney({ buyingPrice: 45000, buyingPriceCurrency: "USD" }, orderEntity);
+    const flat = flattenMoney({ buyingPrice: 450, buyingPriceCurrency: "USD" }, orderEntity);
     // Wenn bereits gesetzt, nicht überschreiben — caller-explicit gewinnt
     expect(flat["buyingPriceCurrency"]).toBe("USD");
   });
@@ -46,8 +55,8 @@ describe("flattenMoney — Insert/Update Convert", () => {
   test("mehrere money-Felder am gleichen Object", () => {
     const flat = flattenMoney(
       {
-        buyingPrice: { amount: 45000, currency: "EUR" },
-        sellingPrice: { amount: 60000, currency: "USD" },
+        buyingPrice: { amount: 450, currency: "EUR" },
+        sellingPrice: { amount: 600, currency: "USD" },
       },
       orderEntity,
     );
@@ -61,7 +70,7 @@ describe("flattenMoney — Insert/Update Convert", () => {
 
   test("andere Felder bleiben unverändert", () => {
     const flat = flattenMoney(
-      { label: "Premium", buyingPrice: { amount: 100, currency: "EUR" } },
+      { label: "Premium", buyingPrice: { amount: 1, currency: "EUR" } },
       orderEntity,
     );
     expect(flat["label"]).toBe("Premium");
@@ -77,33 +86,33 @@ describe("flattenMoney — Insert/Update Convert", () => {
     const noCurrencyEntity: EntityDefinition = createEntity({
       fields: { fee: createMoneyField() },
     });
-    const flat = flattenMoney({ fee: 50 }, noCurrencyEntity);
+    const flat = flattenMoney({ fee: 0.5 }, noCurrencyEntity);
     expect(flat["feeCurrency"]).toBe("EUR");
   });
 
   test("ist pure — input wird nicht mutiert", () => {
-    const input = { buyingPrice: { amount: 45000, currency: "EUR" } };
+    const input = { buyingPrice: { amount: 450, currency: "EUR" } };
     const before = JSON.stringify(input);
     flattenMoney(input, orderEntity);
     expect(JSON.stringify(input)).toBe(before);
   });
 });
 
-describe("rehydrateMoney — Read Convert", () => {
-  test("{ <name>: number, <name>Currency: string } → { <name>: { amount, currency } }", () => {
+describe("rehydrateMoney — Read Convert (minor units → major units)", () => {
+  test("{ <name>: minorUnits, <name>Currency: string } → { <name>: { amount: majorUnits, currency } }", () => {
     const out = rehydrateMoney({ buyingPrice: 45000, buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 45000, currency: "EUR" } });
+    expect(out).toEqual({ buyingPrice: { amount: 450, currency: "EUR" } });
   });
 
   test("PG-BIGINT als String wird zu number gecastet", () => {
     // Postgres-driver liefert BIGINT manchmal als String (>2^53 sicher).
     const out = rehydrateMoney({ buyingPrice: "45000", buyingPriceCurrency: "EUR" }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("fehlende Currency-Spalte fällt auf entity.defaultCurrency", () => {
     const out = rehydrateMoney({ buyingPrice: 45000 }, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("null/undefined amount → Field wird aus Output entfernt", () => {
@@ -122,25 +131,25 @@ describe("rehydrateMoney — Read Convert", () => {
       orderEntity,
     );
     expect(out).toEqual({
-      buyingPrice: { amount: 45000, currency: "EUR" },
-      sellingPrice: { amount: 60000, currency: "USD" },
+      buyingPrice: { amount: 450, currency: "EUR" },
+      sellingPrice: { amount: 600, currency: "USD" },
     });
   });
 
-  test("Round-Trip: flatten dann rehydrate ergibt dasselbe", () => {
+  test("Round-Trip: flatten dann rehydrate ergibt dasselbe, inkl. Cents", () => {
     const original = {
-      buyingPrice: { amount: 45000, currency: "EUR" },
-      sellingPrice: { amount: 60000, currency: "USD" },
+      buyingPrice: { amount: 450.5, currency: "EUR" },
+      sellingPrice: { amount: 56799.16, currency: "USD" },
     };
     const flat = flattenMoney(original, orderEntity);
     const rehydrated = rehydrateMoney(flat, orderEntity);
     expect(rehydrated).toEqual(original);
   });
 
-  test("Round-Trip primitive-Insert: flatten(45000) → rehydrate → { amount:45000, currency:EUR }", () => {
-    const flat = flattenMoney({ buyingPrice: 45000 }, orderEntity);
+  test("Round-Trip primitive-Insert: flatten(450) → rehydrate → { amount:450, currency:EUR }", () => {
+    const flat = flattenMoney({ buyingPrice: 450 }, orderEntity);
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out["buyingPrice"]).toEqual({ amount: 45000, currency: "EUR" });
+    expect(out["buyingPrice"]).toEqual({ amount: 450, currency: "EUR" });
   });
 
   test("ist pure — input wird nicht mutiert", () => {
@@ -166,13 +175,13 @@ describe("rehydrateMoney — Read Convert", () => {
 describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () => {
   test("Update-Changes-Payload mit money geht durch flatten + zurück durch rehydrate", () => {
     // Simuliert was der Executor macht: changes → flatten → DB → rehydrate
-    const changes = { buyingPrice: { amount: 99_000, currency: "USD" } };
+    const changes = { buyingPrice: { amount: 990, currency: "USD" } };
     const flat = flattenMoney(changes, orderEntity);
     expect(flat).toEqual({ buyingPrice: 99_000, buyingPriceCurrency: "USD" });
 
     // DB liefert dieselben Spalten zurück
     const out = rehydrateMoney(flat, orderEntity);
-    expect(out).toEqual({ buyingPrice: { amount: 99_000, currency: "USD" } });
+    expect(out).toEqual({ buyingPrice: { amount: 990, currency: "USD" } });
   });
 
   test("List-Pfad: mehrere Rows hintereinander rehydraten", () => {
@@ -183,9 +192,9 @@ describe("Round-Trip im Update-Pfad (Helper-Verkettung wie im Executor)", () =>
     ];
     const apiRows = dbRows.map((r) => rehydrateMoney(r, orderEntity));
     expect(apiRows).toEqual([
-      { buyingPrice: { amount: 100, currency: "EUR" } },
-      { buyingPrice: { amount: 200, currency: "USD" } },
-      { buyingPrice: { amount: 300, currency: "GBP" } },
+      { buyingPrice: { amount: 1, currency: "EUR" } },
+      { buyingPrice: { amount: 2, currency: "USD" } },
+      { buyingPrice: { amount: 3, currency: "GBP" } },
     ]);
   });
 });

package/src/db/money.ts

@@ -1,9 +1,19 @@
 // Auto-Convert für money-Felder im DB-Layer.
 //
 // Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { amount, currency } | number (permissiv für Legacy)
-//   DB-Form:     <name> BIGINT + <name>Currency TEXT
-//   Read-Form:   { amount, currency }
+//   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
+//   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
+//   Read-Form:   { amount, currency } — amount in MAJOR units again
+//
+// table-builder.ts's moneyAmount column has always documented BIGINT as
+// "the integer minor unit" — this file used to just pass the API amount
+// through unconverted, silently violating that contract: a caller doing
+// the ergonomic thing (passing 56799.16) got a float into a bigint column
+// (driver error) or, worse, an integer major-unit amount (56799) got
+// stored as if it were already minor units — 100× too small on read back.
+// MINOR_UNIT_SCALE fixes that at the boundary so every caller can just
+// pass/receive ordinary decimal amounts; DB storage stays exact-integer
+// cents (no float drift in SUM()/aggregate queries).
 //
 // Permissiv-Insert: primitive number wird als amount akzeptiert (Legacy aus
 // pre-Stufe-3-Samples). Currency fällt dann auf entity.defaultCurrency
@@ -18,6 +28,19 @@ import { DEFAULT_CURRENCIES } from "../engine/types";
 
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
 
+// 2 decimal places (cents) — covers every currently-supported currency
+// (EUR/USD/GBP/...). No ISO-4217 minor-unit table yet (JPY=0, BHD=3) —
+// upgrade path once a currency needing a different scale actually lands.
+const MINOR_UNIT_SCALE = 100;
+
+function toMinorUnits(amount: number): number {
+  return Math.round(amount * MINOR_UNIT_SCALE);
+}
+
+function toMajorUnits(amountMinor: number): number {
+  return amountMinor / MINOR_UNIT_SCALE;
+}
+
 /**
  * API → DB: money-Felder zu zwei flachen Spalten flatten.
  *
@@ -68,7 +91,7 @@ export function flattenMoney(
     }
 
     delete result[name];
-    result[name] = amount;
+    result[name] = toMinorUnits(amount);
     result[`${name}Currency`] = currency;
   }
 
@@ -103,18 +126,18 @@ export function rehydrateMoney(
       continue;
     }
 
-    let amount: number;
+    let amountMinor: number;
     if (typeof amountRaw === "number") {
-      amount = amountRaw;
+      amountMinor = amountRaw;
     } else if (typeof amountRaw === "bigint") {
-      amount = Number(amountRaw);
-      if (Number.isNaN(amount)) {
+      amountMinor = Number(amountRaw);
+      if (Number.isNaN(amountMinor)) {
         throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a number`);
       }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
-      amount = Number(amountRaw);
-      if (Number.isNaN(amount)) {
+      amountMinor = Number(amountRaw);
+      if (Number.isNaN(amountMinor)) {
         throw new Error(
           `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a number — DB corruption?`,
         );
@@ -128,7 +151,7 @@ export function rehydrateMoney(
     const currency =
       typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
 
-    result[name] = { amount, currency };
+    result[name] = { amount: toMajorUnits(amountMinor), currency };
   }
 
   return result;

package/src/engine/__tests__/content-collection.test.ts

@@ -0,0 +1,212 @@
+// r.contentCollection() — sugar over r.nav() that also records which
+// template-resource kind the node lists, so the client can derive the tree
+// provider instead of the app repeating navId + kind.
+
+import { describe, expect, test } from "bun:test";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { buildAppSchema } from "../build-app-schema";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+describe("r.contentCollection() — registration", () => {
+  test("registers a nav entry with provider:true and returns its qualified name", () => {
+    let qn = "";
+    const feature = defineFeature("mail", (r) => {
+      qn = r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: { label: "mail:nav.templates", icon: "file" },
+      });
+    });
+
+    expect(qn).toBe("mail:nav:templates");
+    // The children arrive from a runtime provider — without provider:true the
+    // node would render as an empty leaf.
+    expect(feature.navs["templates"]?.provider).toBe(true);
+    expect(feature.navs["templates"]?.label).toBe("mail:nav.templates");
+    expect(feature.navs["templates"]?.icon).toBe("file");
+    expect(feature.contentCollections?.["templates"]?.kind).toBe("mail-html");
+  });
+
+  test("passes nav placement through: parent, order, access, workspaces", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.nav({ id: "root", label: "mail:nav.root" });
+      r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: {
+          label: "mail:nav.templates",
+          parent: "mail:nav:root",
+          order: 20,
+          access: { roles: ["TenantAdmin"] },
+          workspaces: ["mail:workspace:ops"],
+        },
+      });
+    });
+
+    const nav = feature.navs["templates"];
+    expect(nav?.parent).toBe("mail:nav:root");
+    expect(nav?.order).toBe(20);
+    expect(nav?.access).toEqual({ roles: ["TenantAdmin"] });
+    expect(nav?.workspaces).toEqual(["mail:workspace:ops"]);
+  });
+
+  test("passes createAction and hover actions through to the nav entry", () => {
+    const target = { featureId: "template-resolver", action: "create", args: { folder: "" } };
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "templates",
+        kind: "mail-html",
+        nav: {
+          label: "mail:nav.templates",
+          createAction: { label: "mail:action.new", icon: "plus", target },
+          actions: [{ label: "mail:action.list", icon: "list", target }],
+        },
+      });
+    });
+
+    // Without these a collection can only list what already exists — the "+"
+    // affordance is the whole authoring entry point.
+    expect(feature.navs["templates"]?.createAction?.label).toBe("mail:action.new");
+    expect(feature.navs["templates"]?.actions).toHaveLength(1);
+  });
+
+  test("the nav node inherits the collection's access — no node the handler would refuse", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        access: { roles: ["PromptEngineer"] },
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.navs["prompts"]?.access).toEqual({ roles: ["PromptEngineer"] });
+  });
+
+  test("an explicit nav.access still wins over the collection's", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        access: { roles: ["PromptEngineer"] },
+        nav: { label: "mail:nav.prompts", access: { roles: ["TenantAdmin"] } },
+      });
+    });
+
+    expect(feature.navs["prompts"]?.access).toEqual({ roles: ["TenantAdmin"] });
+  });
+
+  test("records ownership so the handlers can scope reads", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "signatures",
+        kind: "mail-html",
+        ownership: "user",
+        nav: { label: "mail:nav.signatures" },
+      });
+    });
+
+    expect(feature.contentCollections?.["signatures"]?.ownership).toBe("user");
+  });
+
+  test("rejects a second collection with the same id", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+        r.contentCollection({ id: "templates", kind: "ai-prompt", nav: { label: "b" } });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects an id already taken by a plain r.nav()", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.nav({ id: "templates", label: "mail:nav.templates" });
+        r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "b" } });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects a non-kebab id", () => {
+    expect(() =>
+      defineFeature("mail", (r) => {
+        r.contentCollection({ id: "MailTemplates", kind: "mail-html", nav: { label: "a" } });
+      }),
+    ).toThrow(/kebab-case/);
+  });
+});
+
+describe("r.contentCollection() — boot validation", () => {
+  test("a collection mounted under another feature's nav passes", () => {
+    const mail = defineFeature("mail", (r) => {
+      r.nav({ id: "root", label: "mail:nav.root" });
+    });
+    const templates = defineFeature("templates", (r) => {
+      r.contentCollection({
+        id: "mail-templates",
+        kind: "mail-html",
+        nav: { label: "templates:nav.mail", parent: "mail:nav:root" },
+      });
+    });
+
+    expect(() => validateBoot([mail, templates])).not.toThrow();
+  });
+
+  test("a dangling parent fails boot instead of silently vanishing from the sidebar", () => {
+    const templates = defineFeature("templates", (r) => {
+      r.contentCollection({
+        id: "mail-templates",
+        kind: "mail-html",
+        nav: { label: "templates:nav.mail", parent: "mail:nav:root" },
+      });
+    });
+
+    expect(() => validateBoot([templates])).toThrow(/mail:nav:root/);
+  });
+});
+
+describe("buildAppSchema — content collections", () => {
+  test("projects collections with the nav QN qualified", () => {
+    const registry = createRegistry([
+      defineFeature("mail", (r) => {
+        r.nav({ id: "root", label: "mail:nav.root" });
+        r.contentCollection({
+          id: "templates",
+          kind: "mail-html",
+          nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
+        });
+      }),
+    ]);
+
+    const schema = buildAppSchema(registry);
+    const mail = schema.features.find((f) => f.featureName === "mail");
+    expect(mail?.contentCollections).toEqual([
+      {
+        id: "templates",
+        kind: "mail-html",
+        nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
+        navQn: "mail:nav:templates",
+      },
+    ]);
+    // The nav entry itself still travels the normal route — the collection
+    // list only carries what a NavDefinition cannot express.
+    expect(mail?.navs?.map((n) => n.id)).toContain("templates");
+  });
+
+  test("omits the slot for features without collections", () => {
+    const registry = createRegistry([
+      defineFeature("shop", (r) => {
+        r.nav({ id: "catalog", label: "shop:nav.catalog" });
+      }),
+    ]);
+
+    const shop = buildAppSchema(registry).features.find((f) => f.featureName === "shop");
+    expect(shop?.contentCollections).toBeUndefined();
+  });
+});

package/src/engine/build-app-schema.ts

@@ -46,11 +46,21 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
   const features: FeatureSchema[] = [];
   for (const [featureName, feature] of registry.features) {
     const navs = Object.values(feature.navs);
+    // The nav entry alone doesn't say which kind a collection lists, so the
+    // client can't derive its tree provider from `navs` — project the
+    // collections separately, with the nav QN already qualified.
+    const contentCollections = Object.values(feature.contentCollections ?? {}).map(
+      (collection) => ({
+        ...collection,
+        navQn: `${featureName}:nav:${collection.id}`,
+      }),
+    );
     const featureSchema: FeatureSchema = {
       featureName,
       entities: projectEntities(feature.entities ?? {}),
       screens: Object.values(feature.screens),
       ...(navs.length > 0 && { navs }),
+      ...(contentCollections.length > 0 && { contentCollections }),
       // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
       // doc for why this must NOT go through registry.getAllTranslations()
       // (double-prefixes features that already qualify their own keys).

package/src/engine/define-feature.ts

@@ -152,6 +152,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     claimKeys: state.claimKeys,
     screens: state.screens,
     navs: state.navs,
+    contentCollections: state.contentCollections,
     workspaces: state.workspaces,
     httpRoutes: state.httpRoutes,
     storeTables: state.storeTables,

package/src/engine/feature-builder-state.ts

@@ -38,7 +38,7 @@ import type {
   WriteHandlerDef,
 } from "./types";
 import type { HttpRouteDefinition } from "./types/http-route";
-import type { NavDefinition } from "./types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
 import type { WorkspaceDefinition } from "./types/workspace";
 
@@ -95,6 +95,7 @@ export type FeatureBuilderState = {
   claimKeys: Record<string, ClaimKeyDefinition>;
   screens: Record<string, ScreenDefinition>;
   navs: Record<string, NavDefinition>;
+  contentCollections: Record<string, ContentCollectionDefinition>;
   workspaces: Record<string, WorkspaceDefinition>;
   httpRoutes: Record<string, HttpRouteDefinition>;
   translations: TranslationKeys;
@@ -155,6 +156,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     claimKeys: {},
     screens: {},
     navs: {},
+    contentCollections: {},
     workspaces: {},
     httpRoutes: {},
     translations: {},

package/src/engine/feature-ui-extensions.ts

@@ -25,7 +25,7 @@ import type {
 } from "./types";
 import { HookPhases } from "./types";
 import type { HttpRouteDefinition } from "./types/http-route";
-import type { NavDefinition } from "./types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
 import type { WorkspaceDefinition } from "./types/workspace";
 
@@ -373,6 +373,41 @@ export function buildUiExtensionsMethods<TName extends string>(
     nav(definition: NavDefinition): void {
       registerNav(definition);
     },
+    contentCollection(definition: ContentCollectionDefinition): string {
+      if (state.contentCollections[definition.id]) {
+        throw new Error(
+          `[Feature ${name}] Content collection "${definition.id}" already registered. ` +
+            `Collection ids must be unique per feature.`,
+        );
+      }
+      // registerNav owns the kebab + collision checks, including collisions
+      // with a plain r.nav() of the same id. Optional fields stay absent
+      // rather than explicitly undefined — buildAppSchema's JSON-safety check
+      // flags undefined values.
+      registerNav({
+        id: definition.id,
+        label: definition.nav.label,
+        ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+        ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+        ...(definition.nav.order !== undefined && { order: definition.nav.order }),
+        // Nav visibility follows the collection's access unless the caller
+        // overrode it — a node the handler would refuse has no business in
+        // the sidebar.
+        ...((definition.nav.access ?? definition.access) !== undefined && {
+          access: definition.nav.access ?? definition.access,
+        }),
+        ...(definition.nav.workspaces !== undefined && { workspaces: definition.nav.workspaces }),
+        ...(definition.nav.createAction !== undefined && {
+          createAction: definition.nav.createAction,
+        }),
+        ...(definition.nav.actions !== undefined && { actions: definition.nav.actions }),
+        // The tree children come from a runtime provider keyed on this QN —
+        // a collection without it would render as an empty leaf.
+        provider: true,
+      });
+      state.contentCollections[definition.id] = definition;
+      return `${name}:nav:${definition.id}`;
+    },
     workspace(definition: WorkspaceDefinition): void {
       // Same kebab guard as r.screen / r.nav so authoring-time mistakes
       // surface at the feature file, not deep in registry boot.

package/src/engine/index.ts

@@ -292,6 +292,7 @@ export type {
   ConfigValue,
   ConfigValueSource,
   ConfigValueWithSource,
+  ContentCollectionDefinition,
   CreateSeedOptions,
   CreateTenantSeedOptions,
   CreateUserSeedOptions,

package/src/engine/types/index.ts

@@ -206,7 +206,7 @@ export {
   parseTenantId,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-types/identifiers";
-export type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
+export type { ContentCollectionDefinition, NavDefinition } from "@cosmicdrift/kumiko-types/nav";
 export type {
   FromRule,
   FromRuleKind,

package/src/ui-types/app-schema.ts

@@ -9,7 +9,7 @@
 
 import type { TranslationKeys } from "../engine/types/config";
 import type { EntityDefinition } from "../engine/types/fields";
-import type { NavDefinition } from "../engine/types/nav";
+import type { ContentCollectionDefinition, NavDefinition } from "../engine/types/nav";
 import type { ScreenDefinition } from "../engine/types/screen";
 import type { WorkspaceDefinition } from "../engine/types/workspace";
 
@@ -20,6 +20,12 @@ export type FeatureSchema = {
   // Flat list; resolveNavigation builds the tree at render-time from
   // the registry's indexes. Omitted when the app has no top-level nav.
   readonly navs?: readonly NavDefinition[];
+  // Content collections declared via r.contentCollection(), each with its nav
+  // QN already qualified. The matching nav entries are in `navs` like any
+  // other; this list only carries what a NavDefinition can't express — which
+  // template-resource `kind` the node lists — so the client can build one
+  // tree provider per collection. Omitted when a feature declares none.
+  readonly contentCollections?: readonly QualifiedContentCollection[];
   // Server-authored `r.translations({ keys })`, projected verbatim — byte-
   // identical keys, NOT re-prefixed with featureName (unlike the registry's
   // internal mergedTranslations, which double-prefixes features that
@@ -39,6 +45,12 @@ export type FeatureSchema = {
   readonly workspaces?: readonly WorkspaceSchema[];
 };
 
+// A content collection as it reaches the client: the declaration plus the
+// already-qualified nav QN, so consumers don't rebuild "<feature>:nav:<id>".
+export type QualifiedContentCollection = ContentCollectionDefinition & {
+  readonly navQn: string;
+};
+
 // Per-workspace projection of the engine's WorkspaceDefinition + the
 // pre-resolved member nav QNs. The shell renders the switcher from
 // `definition` and filters the nav tree using `navMembers`.

package/src/ui-types/index.ts

@@ -91,4 +91,9 @@ export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
 export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
-export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";
+export type {
+  AppSchema,
+  FeatureSchema,
+  QualifiedContentCollection,
+  WorkspaceSchema,
+} from "./app-schema";