@cosmicdrift/kumiko-framework 0.246.0 → 0.247.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.246.0",
+  "version": "0.247.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.246.0",
+    "@cosmicdrift/kumiko-types": "0.247.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.246.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.247.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/ownership-where-write-path.integration.test.ts

@@ -4,9 +4,10 @@
 // (userCanCreateFieldRow / userCanWriteFieldRow); there is no SQL layer on the
 // write path to run a where-rule against, and on create there is not even a
 // row yet. Boot validation rejects the shape outright
-// (boot-validator/ownership.ts), but setupTestStack wires the registry without
-// validateBoot, so this suite still reaches the runtime path the boot guard
-// protects and pins it to a fail-closed deny instead of a 500.
+// (boot-validator/ownership.ts) and setupTestStack now runs that guard too, so
+// the rule is installed after the stack is up — that is the only way left to
+// reach the runtime path behind the guard and pin it to a fail-closed deny
+// instead of a 500.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "../db/query";
@@ -17,7 +18,7 @@ import {
   defineEntityWriteHandler,
   defineFeature,
 } from "../engine";
-import type { SessionUser, WhereRule } from "../engine/types";
+import type { OwnershipRule, SessionUser, WhereRule } from "../engine/types";
 import {
   createTestUser,
   setupTestStack,
@@ -36,6 +37,10 @@ const ownerWhereRule: WhereRule = {
   }),
 };
 
+// Admin keeps a plain rule so the suite can seed rows over real HTTP; Member
+// is the shape under test and is swapped in after boot (see beforeAll).
+const memoWriteAccess: Record<string, OwnershipRule> = { Admin: "all", Member: "all" };
+
 const memoEntity = createEntity({
   table: "fw2626_memos",
   softDelete: true,
@@ -45,9 +50,7 @@ const memoEntity = createEntity({
   },
   access: {
     read: { Admin: "all", Member: "all" },
-    // Admin keeps a plain rule so the suite can seed rows over real HTTP;
-    // Member is the shape under test.
-    write: { Admin: "all", Member: ownerWhereRule },
+    write: memoWriteAccess,
   },
 });
 
@@ -81,6 +84,7 @@ let seeded: { id: string; version: number };
 beforeAll(async () => {
   stack = await setupTestStack({ features: [memosFeature] });
   await unsafeCreateEntityTable(stack.db, memoEntity, "memo");
+  memoWriteAccess["Member"] = ownerWhereRule;
 });
 
 afterAll(async () => {

package/src/engine/__tests__/boot-validator.test.ts

@@ -1266,7 +1266,7 @@ describe("boot-validator", () => {
       // Apps running only on openToAll / system handlers have no corpus
       // of known roles beyond "all"/"system" — validator must not flag
       // their OwnershipMap roles as unknown. This is the regression test
-      // for the shouldValidateRoles gate.
+      // for the canValidateRoles gate.
       const features = [
         defineFeature("orders", (r) => {
           r.entity(
@@ -3851,6 +3851,83 @@ describe("boot-validator", () => {
         /rowAction "add-note" drawer-target "ghost-form" does not resolve to a registered screen/,
       );
     });
+
+    test("projectionDetail relatedList defaultSort.field not a listed column → throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "Positions",
+                query: "shop:query:order-positions",
+                columns: [{ field: "name", sortable: true }],
+                defaultSort: { field: "price", dir: "asc" },
+              },
+            ],
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /defaultSort\.field "price" is not a listed column/,
+      );
+    });
+
+    test("projectionDetail relatedList defaultSort.field not sortable → throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "Positions",
+                query: "shop:query:order-positions",
+                columns: [{ field: "name" }],
+                defaultSort: { field: "name", dir: "asc" },
+              },
+            ],
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/defaultSort\.field "name" is not sortable/);
+    });
+
+    test("projectionDetail relatedList defaultSort.field sortable → kein Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.queryHandler("order-detail", z.object({}), async () => ({ id: "o1" }), {
+          access: { openToAll: true },
+        });
+        r.queryHandler(
+          "order-positions",
+          z.object({}),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: true } },
+        );
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "Positions",
+                query: "shop:query:order-positions",
+                columns: [{ field: "name", sortable: true }],
+                defaultSort: { field: "name", dir: "asc" },
+              },
+            ],
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
   });
 
   // --- Screen short-id collision across features ---

package/src/engine/boot-validator/__tests__/ownership.test.ts

@@ -11,7 +11,7 @@ import type { OwnershipMap, WhereRule } from "../../types/ownership";
 import { validateOwnershipRules } from "../ownership";
 
 const NO_CLAIMS: ReadonlyMap<string, ClaimKeyDefinition> = new Map();
-// Empty corpus keeps shouldValidateRoles() false, so role-existence checks
+// Empty corpus keeps canValidateRoles() false, so role-existence checks
 // stay out of the way of the where-rule assertions below.
 const NO_ROLES: ReadonlySet<string> = new Set();
 

package/src/engine/boot-validator/index.ts

@@ -1,6 +1,6 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
-import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
+import type { FeatureDefinition } from "../types";
 import { warnOnUniqueAccessRoles } from "./access-roles";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
@@ -44,7 +44,7 @@ import {
   validateNavs,
   warnOnNavAccessInversion,
 } from "./nav";
-import { validateOwnershipRules } from "./ownership";
+import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import { validateProjectionListScreens } from "./projection-list-screens";
 import { validateQueryOutputColumns } from "./query-output-columns";
@@ -119,12 +119,7 @@ export function validateBoot(
   // `from("claim:<feature>:<key>")` strings against this map. Qualified name
   // is how the resolver / readClaim / ownership system all reference claims,
   // so we key on the qualifiedName here too.
-  const allClaimKeys = new Map<string, ClaimKeyDefinition>();
-  for (const f of features) {
-    for (const def of Object.values(f.claimKeys)) {
-      allClaimKeys.set(def.qualifiedName, def);
-    }
-  }
+  const allClaimKeys = collectClaimKeys(features);
 
   // Cross-feature role set — derived from handler-access rules + framework
   // built-ins ("all", "system"). We don't have a dedicated role-registry

package/src/engine/boot-validator/ownership.ts

@@ -44,10 +44,40 @@ export type WhereRuleProbe = {
 // SQL, so it is the only path on which a where-rule is admissible.
 export type AccessPath = "read" | "write";
 
+// Qualified-name → definition map of every claim key in the mounted feature
+// set. `from("claim:<feature>:<key>")` rules resolve against exactly this.
+export function collectClaimKeys(
+  features: readonly FeatureDefinition[],
+): Map<string, ClaimKeyDefinition> {
+  const claimKeys = new Map<string, ClaimKeyDefinition>();
+  for (const f of features) {
+    for (const def of Object.values(f.claimKeys)) {
+      claimKeys.set(def.qualifiedName, def);
+    }
+  }
+  return claimKeys;
+}
+
+// Subset-safe ownership validation for callers that mount a deliberate slice
+// of the app rather than all of it (setupTestStack). Both cross-feature
+// corpora go in as undefined — a three-feature stack genuinely does not know
+// which roles and claims the whole app declares, and answering that question
+// from a slice produces false "unknown role"/"unknown claim" errors. The
+// subset-invariant checks (#2639 where-lint, #2626 where-on-write, unknown
+// column) run in full: those hold or fail per feature, whatever else is
+// mounted.
+export function validateOwnershipBoot(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    validateOwnershipRules(feature, undefined, undefined);
+  }
+}
+
+// undefined corpus = "this caller cannot answer that question", not "skip the
+// check" — see validateOwnershipBoot. validateBoot passes the real corpora.
 export function validateOwnershipRules(
   feature: FeatureDefinition,
-  allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>,
-  knownRoles: ReadonlySet<string>,
+  allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined,
+  knownRoles: ReadonlySet<string> | undefined,
 ): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     const columnNames = new Set<string>(Object.keys(entity.fields));
@@ -126,8 +156,8 @@ export function validateOwnershipRules(
 export function checkFieldAccess(args: {
   readonly access: OwnershipMap | readonly string[] | undefined;
   readonly columnNames: ReadonlySet<string>;
-  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>;
-  readonly knownRoles: ReadonlySet<string>;
+  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined;
+  readonly knownRoles: ReadonlySet<string> | undefined;
   readonly scope: string;
   readonly featureName: string;
   readonly probe?: WhereRuleProbe;
@@ -162,12 +192,12 @@ export function checkFieldAccess(args: {
 
 export function checkLegacyRoleList(
   roles: readonly string[],
-  knownRoles: ReadonlySet<string>,
+  knownRoles: ReadonlySet<string> | undefined,
   scope: string,
   featureName: string,
 ): void {
-  // skip: no handler-declared roles in this app, role-validation disabled
-  if (!shouldValidateRoles(knownRoles)) return;
+  // skip: corpus cannot answer "is this role real?" — see canValidateRoles
+  if (!canValidateRoles(knownRoles)) return;
   for (const roleName of roles) {
     if (!knownRoles.has(roleName)) {
       throw new Error(buildUnknownRoleMessage(roleName, knownRoles, scope, featureName));
@@ -175,13 +205,15 @@ export function checkLegacyRoleList(
   }
 }
 
-// Only validate role-existence when at least one handler in the system has
-// declared a non-builtin role. Apps that run entirely on openToAll +
-// system-role handlers don't benefit from role-typo detection and would
-// otherwise get false-positive errors on every OwnershipMap — their
-// knownRoles corpus is empty beyond "all"/"system", so any app-defined
-// role would flag as unknown.
-export function shouldValidateRoles(knownRoles: ReadonlySet<string>): boolean {
+// A role corpus can only answer "is this role real?" when it actually holds
+// app-defined roles. undefined means the caller could not derive one at all
+// (a test stack mounts a deliberate subset of the app), and a corpus of
+// nothing but "all"/"system" belongs to an app whose handlers never declare
+// a role — in both cases every app-defined role would flag as unknown.
+export function canValidateRoles(
+  knownRoles: ReadonlySet<string> | undefined,
+): knownRoles is ReadonlySet<string> {
+  if (!knownRoles) return false;
   for (const r of knownRoles) {
     if (r !== "all" && r !== "system") return true;
   }
@@ -191,8 +223,8 @@ export function shouldValidateRoles(knownRoles: ReadonlySet<string>): boolean {
 export function checkOwnershipMap(args: {
   readonly map: OwnershipMap;
   readonly columnNames: ReadonlySet<string>;
-  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition>;
-  readonly knownRoles: ReadonlySet<string>;
+  readonly allClaimKeys: ReadonlyMap<string, ClaimKeyDefinition> | undefined;
+  readonly knownRoles: ReadonlySet<string> | undefined;
   readonly scope: string;
   readonly featureName: string;
   readonly probe?: WhereRuleProbe;
@@ -201,9 +233,8 @@ export function checkOwnershipMap(args: {
   for (const [roleName, rawRule] of Object.entries(args.map)) {
     // Role-existence check — typos like `{"Admi": "all"}` where no handler
     // or other map mentions "Admi" would otherwise silently grant nothing.
-    // Skip when no app-defined roles exist anywhere (handler-less or
-    // system-only apps — shouldValidateRoles returns false there).
-    if (shouldValidateRoles(args.knownRoles) && !args.knownRoles.has(roleName)) {
+    // Cross-feature, so it needs a corpus that can answer the question.
+    if (canValidateRoles(args.knownRoles) && !args.knownRoles.has(roleName)) {
       throw new Error(
         buildUnknownRoleMessage(roleName, args.knownRoles, args.scope, args.featureName),
       );
@@ -216,12 +247,14 @@ export function checkOwnershipMap(args: {
       if (args.path === "write") {
         throw new Error(buildWhereOnWritePathMessage(roleName, args.scope, args.featureName));
       }
-      probeWhereRule(rule, roleName, args.probe, args.scope);
+      probeWhereRule(rule, roleName, args.probe, args.scope, args.featureName);
       continue; // escape hatch — feature author owns the SQL
     }
 
     // FromRule — validate ref + column.
-    if (rule.refKind === "claim") {
+    // Claim-existence is cross-feature: only the whole-app corpus can tell a
+    // typo from a claim declared in a feature this caller did not mount.
+    if (rule.refKind === "claim" && args.allClaimKeys) {
       // refPath is the qualified claim name ("feature:shortName").
       const claim = args.allClaimKeys.get(rule.refPath);
       if (!claim) {
@@ -258,6 +291,7 @@ export function probeWhereRule(
   roleName: string,
   probe: WhereRuleProbe | undefined,
   scope: string,
+  featureName: string,
 ): void {
   // skip: no probe means the entity's column set could not be derived above;
   // without it there is nothing to check the rule's SQL against, so the
@@ -277,7 +311,11 @@ export function probeWhereRule(
   // skip: a rule producing no SQL fragment for the probe user has nothing to
   // lint here; ruleToFragment still validates it against a real request.
   if (typeof fragment?.sqlText !== "string") return;
-  assertQualifiedWhereFragment(fragment.sqlText, probe.columns, `${scope} (role "${roleName}")`);
+  assertQualifiedWhereFragment(
+    fragment.sqlText,
+    probe.columns,
+    `${scope} (role "${roleName}", feature: "${featureName}")`,
+  );
 }
 
 export function buildWhereOnWritePathMessage(

package/src/engine/boot-validator/screens.ts

@@ -846,6 +846,23 @@ export function validateScreens(
               );
             }
           }
+          if (section.defaultSort !== undefined) {
+            const sortField = section.defaultSort.field;
+            const col = section.columns.find((c) => normalizeListColumn(c).field === sortField);
+            if (col === undefined) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) defaultSort.field "${sortField}" is not a listed column.`,
+              );
+            }
+            if (normalizeListColumn(col).sortable !== true) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) defaultSort.field "${sortField}" is not sortable. Set sortable: true on ` +
+                  `the column or pick another field.`,
+              );
+            }
+          }
           continue;
         }
         if (isWriteFormEditSection(section)) {

package/src/stack/__tests__/ownership-boot-guard.integration.test.ts

@@ -0,0 +1,108 @@
+// setupTestStack runs the ownership boot-guards (fw#2639 unqualified
+// where-fragments, fw#2626 where-rules on the write path). Before this, only
+// the prod boot ran validateBoot, so a feature with a broken access map came
+// through every test suite green and failed on the first real deploy.
+
+import { describe, expect, test } from "bun:test";
+import {
+  createEntity,
+  createTextField,
+  defineEntityQueryHandler,
+  defineFeature,
+  from,
+} from "../../engine";
+import type { WhereRule } from "../../engine/types";
+import { setupTestStack } from "../test-stack";
+
+// Bare `owner_id` inside the subquery binds to fwbootguard_shares, not to the
+// outer memo table — the predicate collapses into a tautology and grants every
+// row. This is the exact fail-open shape fw#2639 lints for.
+const unqualifiedReadRule: WhereRule = {
+  kind: "where",
+  where: (user, ctx) => ({
+    sqlText: `${ctx.tableName}.id IN (SELECT memo_id FROM fwbootguard_shares WHERE owner_id = $${ctx.paramStart})`,
+    params: [user.id],
+  }),
+};
+
+const qualifiedWriteRule: WhereRule = {
+  kind: "where",
+  where: (user, ctx) => ({
+    sqlText: `${ctx.tableName}.owner_id = $${ctx.paramStart}`,
+    params: [user.id],
+  }),
+};
+
+function memoEntity(access: Parameters<typeof createEntity>[0]["access"]) {
+  return createEntity({
+    table: "fwbootguard_memos",
+    fields: {
+      ownerId: createTextField({ required: true }),
+      title: createTextField({ required: true }),
+    },
+    ...(access ? { access } : {}),
+  });
+}
+
+function featureWith(access: Parameters<typeof createEntity>[0]["access"]) {
+  const entity = memoEntity(access);
+  return defineFeature("fwbootguard", (r) => {
+    r.entity("memo", entity);
+    r.queryHandler(
+      defineEntityQueryHandler("memo:detail", entity, { access: { roles: ["Member"] } }),
+    );
+  });
+}
+
+describe("setupTestStack — ownership boot-guards", () => {
+  test("rejects an unqualified where-fragment on access.read (fw#2639)", async () => {
+    const promise = setupTestStack({
+      features: [featureWith({ read: { Member: unqualifiedReadRule } })],
+    });
+    await expect(promise).rejects.toThrow(
+      /references column "owner_id" unqualified inside a subquery/,
+    );
+    await expect(promise).rejects.toThrow(/entity "memo"\.access\.read/);
+    await expect(promise).rejects.toThrow(/role "Member", feature: "fwbootguard"/);
+  });
+
+  test("rejects a where-rule on access.write (fw#2626)", async () => {
+    const promise = setupTestStack({
+      features: [featureWith({ read: { Member: "all" }, write: { Member: qualifiedWriteRule } })],
+    });
+    await expect(promise).rejects.toThrow(/entity "memo"\.access\.write/);
+    await expect(promise).rejects.toThrow(/feature: "fwbootguard"/);
+  });
+
+  test("a qualified read-rule still boots", async () => {
+    const stack = await setupTestStack({
+      features: [featureWith({ read: { Member: qualifiedWriteRule } })],
+    });
+    expect(stack.registry.getEntity("memo")?.table).toBe("fwbootguard_memos");
+    await stack.cleanup();
+  });
+
+  // The role and claim corpora are whole-app facts. A stack that mounts a
+  // deliberate subset cannot answer them, so those two checks stay out of the
+  // test-stack path while the subset-invariant where-lint keeps firing on the
+  // very same map. Without this test, the next "fix" to collectKnownRoles
+  // quietly reinstates the false positives it removed.
+  test("a subset stack skips the cross-feature checks but still lints where-fragments", async () => {
+    const undeclaredRefs = {
+      Auditor: "all",
+      Reviewer: from("claim:fwbootguardelsewhere:teamId", "ownerId"),
+    } as const;
+
+    const stack = await setupTestStack({
+      features: [featureWith({ read: { ...undeclaredRefs, Member: "all" } })],
+    });
+    expect(stack.registry.getEntity("memo")?.table).toBe("fwbootguard_memos");
+    await stack.cleanup();
+
+    await expect(
+      setupTestStack({
+        features: [featureWith({ read: { ...undeclaredRefs, Member: unqualifiedReadRule } })],
+      }),
+    ).rejects.toThrow(/references column "owner_id" unqualified inside a subquery/);
+  });
+});

package/src/stack/test-stack.ts

@@ -5,6 +5,7 @@ import { buildServer } from "../api/server";
 import { createSseBroker, type SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import { extractTableInfo } from "../db/query";
+import { validateOwnershipBoot } from "../engine/boot-validator/ownership";
 import { createRegistry } from "../engine/registry";
 import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
@@ -180,6 +181,14 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   const { ensureTemporalPolyfill } = await import("../time/polyfill");
   await ensureTemporalPolyfill();
 
+  // Ownership boot-guards (fw#2639 unqualified where-fragments, fw#2626
+  // where-rules on the write path) otherwise run only in the prod boot via
+  // validateBoot, leaving every test stack blind to a broken access map.
+  // Runs after the polyfill (buildEntityTable needs it to derive the probe
+  // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
+  // a database that nothing will clean up.
+  validateOwnershipBoot(options.features);
+
   // Forward db-name/persistent-flag through to createTestDb. The
   // defaults (undefined dbName, persistent:false) keep the legacy
   // test contract: fresh kumiko_test_<random> DB per setup, dropped

package/src/ui-types/index.ts

@@ -85,6 +85,7 @@ export type {
   FormWidth,
   ListColumnSpec,
   ListFacetSpec,
+  ListSortSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,