@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/engine/index.ts

@@ -6,7 +6,6 @@ export {
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";
-export { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema";
 export {
@@ -24,6 +23,7 @@ export {
   createTenantSeed,
   createUserConfig,
   createUserSeed,
+  isEncryptedAtRest,
 } from "./config-helpers";
 export type { SystemHookName } from "./constants";
 export {
@@ -42,6 +42,7 @@ export { crossTenantOverrideDenied } from "./cross-tenant";
 export { defineFeature } from "./define-feature";
 export type {
   QueryHandlerDefinition,
+  StreamHandlerDefinition,
   WriteHandlerDefinition,
   WriteHandlerInput,
 } from "./define-handler";
@@ -51,7 +52,7 @@ export { defineStep, getStep, listStepKinds } from "./define-step";
 export type { WorkflowDefinition, WorkflowInput, WorkflowTrigger } from "./define-workflow";
 export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow";
 export type { ToggleReader } from "./effective-features";
-export { computeEffectiveFeatures } from "./effective-features";
+export { computeEffectiveFeatures, isToggleableFeature } from "./effective-features";
 export {
   createEntityExecutor,
   defineEntityCreateHandler,
@@ -67,6 +68,9 @@ export {
   defineEntityUpdateHandler,
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
+  type EntityCrudRegistrar,
+  type RegisterEntityCrudOptions,
+  registerEntityCrud,
 } from "./entity-handlers";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
@@ -82,6 +86,11 @@ export {
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
+export type {
+  TenantDataDestroyHook,
+  TenantDataExtensionHooks,
+  TenantDataHookCtx,
+} from "./extensions/tenant-data";
 export type {
   TenantUserModel,
   UserDataDeleteHook,
@@ -114,7 +123,6 @@ export {
   createTextField,
   createTimestampField,
   createTzField,
-  locatedTimestamp,
 } from "./factories";
 // AST inspection + patching pipeline — used by the CLI scaffolder, the
 // Designer (C5/C6), and the AI-Builder (L2). See feature-ast/index.ts
@@ -170,15 +178,22 @@ export {
   checkWriteFieldRoles,
   filterReadFields,
 } from "./field-access";
+export { resolveName, withResponseData } from "./handler-helpers";
+// findForbiddenMembershipRole/isForbiddenMembershipRole/
+// stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
+// apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES
+// itself stays internal (637/3) — exporting the raw Set would make its
+// representation a semver promise; the predicate functions are the intended
+// surface.
 export {
-  FORBIDDEN_MEMBERSHIP_ROLES,
+  buildSessionRoles,
   findForbiddenMembershipRole,
   isForbiddenMembershipRole,
   stripForbiddenMembershipRoles,
 } from "./membership-roles";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
 export { from } from "./ownership";
-export { buildPipelineSteps, pipeline } from "./pipeline";
+export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
 export { isValidQn, parseQn, QnTypes, qn, toKebab } from "./qualified-name";
@@ -190,6 +205,7 @@ export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {
@@ -349,6 +365,8 @@ export type {
   SecretKeyHandle,
   SelectFieldDef,
   SessionUser,
+  StreamHandlerDef,
+  StreamHandlerFn,
   Subscribe,
   TargetRef,
   TenantId,
@@ -372,9 +390,7 @@ export type {
   WriteResult,
 } from "./types";
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
-export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
-export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./types/screen";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/membership-roles.ts

@@ -30,3 +30,16 @@ export function findForbiddenMembershipRole(roles: readonly string[]): string |
 export function stripForbiddenMembershipRoles(roles: readonly string[]): readonly string[] {
   return roles.filter((role) => !isForbiddenMembershipRole(role));
 }
+
+// Single mint path for session roles: merges globalRoles with the stripped
+// membership portion and dedupes. Every place that builds a session's roles
+// from a membership should go through this instead of repeating
+// `new Set([...globalRoles, ...stripForbiddenMembershipRoles(x)])` — a new
+// mint site that forgets the strip is exactly the bug class this guards
+// against.
+export function buildSessionRoles(
+  globalRoles: readonly string[],
+  membershipRoles: readonly string[],
+): readonly string[] {
+  return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
+}

package/src/engine/object-form.ts

@@ -0,0 +1,27 @@
+// Shared helper for registrar methods that accept an Object-Form call
+// (`r.entity({ name: "item", ... })`) alongside the classic positional form
+// (`r.entity("item", { ... })`). Object-Form is the shape the feature-ast
+// renderer emits for Designer/AI-generated code — a single object argument
+// with named fields is easier to generate correctly than positional args
+// whose count/order vary per method.
+export function splitNamedDefinition<T extends { readonly name: string }>(
+  definition: T,
+): [string, Omit<T, "name">] {
+  const { name, ...rest } = definition;
+  return [name, rest];
+}
+
+// Shared helper for registrar methods that accept either variadic strings
+// (hand-written call sites) or a single Object-Form object wrapping the
+// same string array under `key` (the feature-ast renderer's canonical
+// shape for Designer/AI-generated code).
+export function unwrapArrayForm<K extends string>(
+  args: readonly [Record<K, readonly string[]>] | readonly string[],
+  key: K,
+): readonly string[] {
+  const [first] = args;
+  if (typeof first === "object" && first !== null && key in first) {
+    return (first as Record<K, readonly string[]>)[key];
+  }
+  return args as readonly string[];
+}

package/src/engine/ownership.ts

@@ -17,67 +17,35 @@
 // Construction: use the `from(ref, column?)` helper. It returns a FromRule
 // ready to drop into an access map.
 
+import {
+  KUMIKO_COLUMNS_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../db/table-builder";
 import type { SessionUser } from "./types";
 
-// Parameterised SQL fragment — produced by buildOwnershipClause + by the
-// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
-// renumbering placeholders if needed (FragmentBuilder below).
-export type SqlFragment = {
-  readonly sqlText: string;
-  readonly params: readonly unknown[];
-};
-
-// Reference spec supported by `from()`:
-//   "user:id"                  → user.id
-//   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
-//   "claim:<featureName>:<key>" → user.claims["<featureName>:<key>"]
-//
-// The string form is keyed so the framework can look up the referenced
-// Registry entry at boot (Claim-QN exists? Column type compatible?). A typed
-// object form would force features to import each other's handles — the
-// whole point of H.2's unified path is string-based references, no imports.
-export type OwnershipRef = string;
-
-// Resolved during `from()` — the parser eagerly splits the prefix so the
-// runtime evaluator avoids string-parsing on every row. `kind` drives the
-// evaluator branch; the rest is the resolved metadata.
-export type FromRuleKind = "user" | "claim";
-
-export type FromRule = {
-  readonly kind: "from";
-  readonly refKind: FromRuleKind;
-  // For "user:id" → "id"; for "user:tenantId" → "tenantId".
-  // For "claim:<featureName>:<key>" → "<featureName>:<key>" (the full QN,
-  // which is exactly the key under which the JWT stores the value).
-  readonly refPath: string;
-  // Row-column to match against. For claim rules defaults to the claim's
-  // shortName (second segment of the claim QN). For user-rules the column
-  // is always explicit.
-  readonly column: string;
-};
-
-// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
-// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
-// concatenates the fragment into the larger query.
-export type WhereRuleContext<TTable = unknown> = {
-  readonly table: TTable;
-  readonly tableName: string;
-  readonly paramStart: number;
-};
-
-export type WhereRule<TTable = unknown> = {
-  readonly kind: "where";
-  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
-};
-
-// "all" collapses to a primitive so map authors can write `Admin: "all"`
-// without importing a helper.
-export type OwnershipRule = "all" | FromRule | WhereRule;
-
-// Per-role map: every key is a role name, value is the rule that role
-// satisfies to pass the access check.
-export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+// Types live in engine/types/ownership.ts (no runtime dependency); re-exported
+// here for backwards compatibility with existing importers of this file.
+export type {
+  FromRule,
+  FromRuleKind,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+  WhereRule,
+  WhereRuleContext,
+} from "./types/ownership";
+
+import type {
+  FromRule,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+} from "./types/ownership";
 
 // Parse an OwnershipRef into kind + resolved path + default column.
 // Throws on malformed input so the error surfaces at `from()`-call-site (in
@@ -254,30 +222,9 @@ export function userCanCreateFieldRow(
   return false;
 }
 
-// Result of buildOwnershipClause. The discriminant lets the caller handle
-// the three outcomes without inspecting SQL internals:
-//
-//   "pass"  → user is unrestricted. Run the query as-is.
-//   "empty" → user has a role mapped but no rule accepts any row (missing
-//             claim, empty array, role not in map). Skip the DB call entirely
-//             — returning [] is equivalent and avoids a pointless roundtrip.
-//   "sql"   → apply the parameterised fragment as an AND on the query.
-//             Caller is responsible for renumbering placeholders when
-//             concatenating with other fragments (see `shiftParams` below).
-//
-// "empty" vs. "pass" is the critical distinction for a safe default:
-// undefined/pass = allow, empty = deny-by-construction.
-export type OwnershipClause =
-  | { readonly kind: "pass" }
-  | { readonly kind: "empty" }
-  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };
-
 const PASS_CLAUSE: OwnershipClause = { kind: "pass" };
 const EMPTY_CLAUSE: OwnershipClause = { kind: "empty" };
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
 function tableNameOf(table: unknown): string {
   if (table !== null && typeof table === "object") {
     const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -46,8 +46,8 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "screen",
   "writeHandler",
   "queryHandler",
+  "streamHandler",
   "hook",
-  "entityHook",
   "job",
   "notification",
   "authClaims",
@@ -55,12 +55,10 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "projection",
   "multiStreamProjection",
   "defineEvent",
-  "eventMigration",
   "extendsRegistrar",
   "usesApi",
   "exposesApi",
   "treeActions",
-  "tree",
   "envSchema",
   "unknown",
 ];
@@ -273,20 +271,20 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         schemaSource: PLACEHOLDER_BODY_LOC,
         handlerBody: PLACEHOLDER_BODY_LOC,
       };
-    case "hook":
+    case "streamHandler":
       return {
         kind,
         source: PLACEHOLDER_LOC,
-        hookType: "postSave",
-        target: "x",
-        fnBody: PLACEHOLDER_BODY_LOC,
+        handlerName: "x",
+        schemaSource: PLACEHOLDER_BODY_LOC,
+        handlerBody: PLACEHOLDER_BODY_LOC,
       };
-    case "entityHook":
+    case "hook":
       return {
         kind,
         source: PLACEHOLDER_LOC,
         hookType: "postSave",
-        entityName: "x",
+        target: "x",
         fnBody: PLACEHOLDER_BODY_LOC,
       };
     case "job":
@@ -333,15 +331,6 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         eventName: "x",
         schemaSource: PLACEHOLDER_BODY_LOC,
       };
-    case "eventMigration":
-      return {
-        kind,
-        source: PLACEHOLDER_LOC,
-        eventName: "x",
-        fromVersion: 1,
-        toVersion: 2,
-        transformBody: PLACEHOLDER_BODY_LOC,
-      };
     case "extendsRegistrar":
       return {
         kind,
@@ -351,8 +340,6 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
       };
     case "treeActions":
       return { kind, source: PLACEHOLDER_LOC, definitions: {} };
-    case "tree":
-      return { kind, source: PLACEHOLDER_LOC, providerBody: PLACEHOLDER_BODY_LOC };
     case "envSchema":
       return { kind, source: PLACEHOLDER_LOC, schemaBody: PLACEHOLDER_BODY_LOC };
     case "unknown":