@cosmicdrift/kumiko-framework 0.159.1 → 0.161.0

package/src/engine/types/hooks.ts

@@ -1,170 +1,2 @@
-import type { StoredEvent } from "../../event-store/event-store";
-import type { HookPhases } from "../hook-helpers";
-import type { AppContext } from "./handlers";
-import type { EntityId } from "./identifiers";
-
-// --- Validation ---
-
-export type ValidationError = {
-  readonly field: string;
-  readonly error: string;
-};
-
-export type ValidationHookFn = (
-  data: Readonly<Record<string, unknown>>,
-) => readonly ValidationError[] | null;
-
-// --- Save/Delete Context (what hooks receive) ---
-
-export type SaveContext = {
-  readonly kind: "save";
-  readonly id: EntityId;
-  readonly data: Readonly<Record<string, unknown>>;
-  readonly changes: Readonly<Record<string, unknown>>;
-  readonly previous: Readonly<Record<string, unknown>>;
-  readonly isNew: boolean;
-  readonly entityName?: string | undefined;
-  // The event that produced this save. Populated by the event-store-executor;
-  // the pipeline uses it to drive projections inside the same transaction.
-  // Optional because hand-crafted SaveContexts (tests, custom executors) may
-  // not have an event — projections just skip in that case.
-  readonly event?: StoredEvent | undefined;
-};
-
-export type DeleteContext = {
-  readonly kind: "delete";
-  readonly id: EntityId;
-  readonly data: Readonly<Record<string, unknown>>;
-  readonly entityName?: string | undefined;
-  // See SaveContext.event — same semantics.
-  readonly event?: StoredEvent | undefined;
-};
-
-export type LifecycleResult = SaveContext | DeleteContext;
-
-// --- Lifecycle Hooks ---
-
-export type PreSaveHookFn = (
-  changes: Record<string, unknown>,
-  context: AppContext & {
-    readonly previous: Readonly<Record<string, unknown>>;
-    readonly isNew: boolean;
-  },
-) => Promise<Record<string, unknown>>;
-
-export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
-
-// Batch-variant: called once at the end of a dispatcher batch with every
-// successful SaveContext. The per-save PostSaveHookFn still fires for
-// side-effects that need per-entity semantics (SSE); PostSaveBatch exists
-// for adapters that can amortise work across the whole batch (e.g. search
-// index batch-writes, bulk webhook fanout).
-export type PostSaveBatchHookFn = (
-  results: readonly SaveContext[],
-  context: AppContext,
-) => Promise<void>;
-
-export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-
-export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-
-export type PostDeleteBatchHookFn = (
-  payloads: readonly DeleteContext[],
-  context: AppContext,
-) => Promise<void>;
-
-export type PreQueryHookFn = (
-  payload: Record<string, unknown>,
-  context: AppContext,
-) => Promise<Record<string, unknown>>;
-
-// postQuery — fires after query-handler-execute, before field-access-read-filter.
-// Hook receives normalized rows + entityName + can mutate rows (e.g., merge
-// custom-fields, add computed-counts, attach related-data). Mutation result
-// replaces original rows. Hook is responsible for its own field-access-logic
-// on added fields (field-access-filter only knows entity's stammfields).
-export type PostQueryHookFn = (
-  result: {
-    // undefined for standalone queries (no-colon handler names like
-    // "ns:dashboard") — those have no backing entity, but handler-keyed
-    // postQuery hooks still fire on them.
-    readonly entityName: string | undefined;
-    readonly rows: ReadonlyArray<Record<string, unknown>>;
-  },
-  context: AppContext,
-) => Promise<{ rows: ReadonlyArray<Record<string, unknown>> }>;
-
-export type LifecycleHookFn =
-  | PreSaveHookFn
-  | PostSaveHookFn
-  | PreDeleteHookFn
-  | PostDeleteHookFn
-  | PreQueryHookFn
-  | PostQueryHookFn;
-
-export type HookPhase = (typeof HookPhases)[keyof typeof HookPhases];
-
-// Owner-tag shared across every hook structure. The lifecycle pipeline uses
-// it to skip hooks whose owning feature is globally disabled:
-//   - A concrete feature name like "orders" → subject to the feature-toggle
-//     filter (skipped when "orders" is disabled).
-//   - "*" (star) → invariant plumbing, never filtered. Reserved for
-//     extension-provided hooks and framework-internal hooks that belong to
-//     the pipeline itself, not a feature.
-//   - Omitted (undefined) → treated as "*". Supports tests that hand-build
-//     HookMap objects without caring about ownership.
-export type HookOwner = { readonly featureName?: string };
-
-export type PhasedHook<TFn> = {
-  readonly fn: TFn;
-  readonly phase: HookPhase;
-} & HookOwner;
-
-// Flat (non-phased) hook — preSave, preQuery. Same owner contract, no
-// phase semantics because these hooks run exactly once per handler pass
-// before/around the DB transaction.
-export type OwnedFn<TFn> = {
-  readonly fn: TFn;
-} & HookOwner;
-
-// --- Hook Maps ---
-
-// Slots are optional: defineFeature materializes every slot, but hand-built
-// FeatureDefinitions at system boundaries (test fixtures, partial boots —
-// see registry.test.ts "slot robustness") legitimately omit them, and the
-// registry merge paths tolerate undefined. The type mirrors that contract.
-export type HookMap = {
-  readonly validation?: Readonly<Record<string, ValidationHookFn>>;
-  readonly preSave?: Readonly<Record<string, readonly OwnedFn<PreSaveHookFn>[]>>;
-  readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
-  readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
-  readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-  readonly preQuery?: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
-  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
-};
-
-export type EntityHookMap = {
-  readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
-  readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
-  readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
-};
-
-// Search-Payload-Extension (F3) — contributor function that adds flat
-// fields to an entity's search-document. Fires synchronously during
-// buildSearchDocument (in `system-hooks.ts`), receives current entity
-// state, returns extra fields to merge into the search-index payload.
-//
-// Use-cases: custom-fields-bundle (merge customFields-jsonb-keys flat
-// into index), tags-bundle (project tags-array as searchable), computed-
-// fields (denormalize related-counts).
-//
-// IMPORTANT: contributor must be deterministic per (entityName, entityId,
-// state). Async-allowed for future-proofing but discouraged — the
-// indexing path runs once per entity-write, sync extension is
-// near-zero-cost.
-export type SearchPayloadContributorFn = (args: {
-  readonly entityName: string;
-  readonly entityId: EntityId;
-  readonly state: Record<string, unknown>;
-}) => Record<string, unknown> | Promise<Record<string, unknown>>;
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/hooks";

package/src/engine/types/index.ts

@@ -1,23 +1,8 @@
-// Barrel: re-exports all types from logical modules
+// Barrel: re-exports all types from @cosmicdrift/kumiko-types, plus the
+// runtime helpers below that stay framework-side.
 // Duplicate types (OnDeleteStrategy, ConfigScope, ConcurrencyMode, LifecycleHookType)
 // are defined ONLY in constants.ts — re-exported here for backwards compatibility.
 
-// Re-export types that were duplicated in types.ts but are canonical in constants.ts
-export type {
-  ConcurrencyMode,
-  ConfigScope,
-  LifecycleHookType,
-  OnDeleteStrategy,
-} from "../constants";
-export { DEFAULT_CURRENCIES, isFileField } from "../field-helpers";
-export { resolveName, withResponseData } from "../handler-helpers";
-export { HookPhases } from "../hook-helpers";
-export {
-  isExtensionEditSection,
-  isFormatSpec,
-  normalizeEditField,
-  normalizeListColumn,
-} from "../screen-helpers";
 export type {
   ConfigAccessor,
   ConfigAccessorFactory,
@@ -62,26 +47,27 @@ export type {
   TranslationKeys,
   TranslationsDef,
   UiExtensionDef,
-} from "./config";
+} from "@cosmicdrift/kumiko-types/config";
 export type {
   QueryHandlerDefinition,
+  StreamHandlerDefinition,
   WriteHandlerDefinition,
   WriteHandlerInput,
-} from "./define-handler";
+} from "@cosmicdrift/kumiko-types/define-handler";
 export type {
   EntityCrudRegistrar,
   EntityCrudVerb,
   EntityHandlerOptions,
   EntityQueryHandlerOptions,
   RegisterEntityCrudOptions,
-} from "./entity-handlers";
+} from "@cosmicdrift/kumiko-types/entity-handlers";
 // Cross-Feature Compile-Time-Type-Map — features extend per declare-module.
 export type {
   KumikoEntityTypeMap,
   KumikoEventTypeMap,
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
-} from "./event-type-map";
+} from "@cosmicdrift/kumiko-types/event-type-map";
 export type {
   BootCheckContext,
   BootCheckFn,
@@ -99,7 +85,7 @@ export type {
   StoreTableOptions,
   UiHintOption,
   UiHints,
-} from "./feature";
+} from "@cosmicdrift/kumiko-types/feature";
 export type {
   AnyFileFieldDef,
   BigIntFieldDef,
@@ -137,7 +123,7 @@ export type {
   TimestampFieldDef,
   TransitionMap,
   TzFieldDef,
-} from "./fields";
+} from "@cosmicdrift/kumiko-types/fields";
 export type {
   AccessRule,
   AggregateStreamHandle,
@@ -176,6 +162,8 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  StreamHandlerDef,
+  StreamHandlerFn,
   TryAppendEventFn,
   TryAppendEventResult,
   UnsafeAppendEventFn,
@@ -183,7 +171,7 @@ export type {
   WriteHandlerDef,
   WriteHandlerFn,
   WriteResult,
-} from "./handlers";
+} from "@cosmicdrift/kumiko-types/handlers";
 export type {
   DeleteContext,
   EntityHookMap,
@@ -206,17 +194,21 @@ export type {
   SearchPayloadContributorFn,
   ValidationError,
   ValidationHookFn,
-} from "./hooks";
+} from "@cosmicdrift/kumiko-types/hooks";
 export type {
   HttpRouteDefinition,
   HttpRouteHandler,
   HttpRouteHandlerDeps,
   HttpRouteMethod,
-} from "./http-route";
+} from "@cosmicdrift/kumiko-types/http-route";
 // Domain-identifier type aliases — see identifiers.ts for rationale.
-export type { EntityId, TenantId } from "./identifiers";
-export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./identifiers";
-export type { NavDefinition } from "./nav";
+export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";
+export {
+  isSystemTenant,
+  parseTenantId,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-types/identifiers";
+export type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
 export type {
   FromRule,
   FromRuleKind,
@@ -227,7 +219,7 @@ export type {
   SqlFragment,
   WhereRule,
   WhereRuleContext,
-} from "./ownership";
+} from "@cosmicdrift/kumiko-types/ownership";
 export type {
   EntityProjectionExtension,
   MspErrorMode,
@@ -237,14 +229,14 @@ export type {
   ProjectionDefinition,
   ProjectionTable,
   SingleStreamApplyFn,
-} from "./projection";
+} from "@cosmicdrift/kumiko-types/projection";
 export type {
   BelongsToRelation,
   EntityRelations,
   HasManyRelation,
   ManyToManyRelation,
   RelationDefinition,
-} from "./relations";
+} from "@cosmicdrift/kumiko-types/relations";
 export type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -283,8 +275,8 @@ export type {
   ScreenFilterOp,
   ScreenSlots,
   ToolbarAction,
-} from "./screen";
-export type { TargetRef } from "./target-ref";
+} from "@cosmicdrift/kumiko-types/screen";
+export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type {
   Subscribe,
   TreeAction,
@@ -293,5 +285,21 @@ export type {
   TreeChildrenSubscribe,
   TreeNode,
   TreeNodeState,
-} from "./tree-node";
-export type { WorkspaceDefinition } from "./workspace";
+} from "@cosmicdrift/kumiko-types/tree-node";
+export type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
+// Re-export types that were duplicated in types.ts but are canonical in constants.ts
+export type {
+  ConcurrencyMode,
+  ConfigScope,
+  LifecycleHookType,
+  OnDeleteStrategy,
+} from "../constants";
+export { DEFAULT_CURRENCIES, isFileField } from "../field-helpers";
+export { resolveName, withResponseData } from "../handler-helpers";
+export { HookPhases } from "../hook-helpers";
+export {
+  isExtensionEditSection,
+  isFormatSpec,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../screen-helpers";

package/src/engine/types/nav.ts

@@ -1,67 +1,2 @@
-import type { AccessRule } from "./handlers";
-import type { TargetRef } from "./target-ref";
-import type { TreeAction } from "./tree-node";
-
-// Nav entry declaration. Every feature that wants to appear in the app's
-// navigation tree registers one or more entries via r.nav(). The engine
-// keeps the list flat — ui-core's resolveNavigation assembles the parent/
-// child tree at render time, so changes (toggles, access-gating) don't
-// require re-indexing a tree shape server-side.
-//
-// Cross-feature references are allowed: `screen` may point at any
-// registered screen QN, `parent` at any registered nav QN. The boot
-// validator checks both references exist + rejects parent cycles.
-export type NavDefinition = {
-  // Feature author writes the feature-local short id ("catalog"); the
-  // registry overwrites `id` with the qualified name ("shop:nav:catalog")
-  // in its stored copy. Callers of `registry.getNav(qn)` /
-  // `getTopLevelNavs()` / `getNavsByParent(...)` always see the qualified
-  // id — no parallel reverse index needed. `feature.navs[shortId]` on the
-  // unregistered FeatureDefinition keeps the short form.
-  readonly id: string;
-  // i18n translation key. Resolved at render time by the renderer's
-  // useTranslation hook; engine keeps it opaque.
-  readonly label: string;
-  // Icon key — whatever the icon registry of the active renderer understands.
-  // Engine doesn't validate; unknown icons surface as a missing icon on screen,
-  // not a boot failure.
-  readonly icon?: string;
-  // Qualified name of a parent nav entry ("<feature>:nav:<id>"). Omit for
-  // top-level entries. Boot-validator rejects cycles + dangling refs.
-  readonly parent?: string;
-  // Sort weight within the parent's children (lower = earlier). Ties are
-  // broken by registration order — features registered later appear lower.
-  readonly order?: number;
-  // Qualified name of the screen this entry navigates to
-  // ("<feature>:screen:<id>"). Omit for pure grouping entries (a parent-only
-  // nav node that renders a sub-tree but has no target screen itself).
-  readonly screen?: string;
-  // Polymorphes Klick-Ziel (öffnet die EditorPanel-Maske via Target-
-  // Resolver) — Alternative zu `screen`. Ein Knoten trägt screen XOR
-  // target; der Renderer dispatcht das target statt einen Route-Link zu
-  // rendern. Gespiegelt aus dem alten Visual-Tree (TreeNode.target).
-  readonly target?: TargetRef;
-  // Hover-Actions rechts in der Zeile (VS-Code-Pattern) — erst bei Hover
-  // sichtbar. Reihenfolge wie deklariert.
-  readonly actions?: readonly TreeAction[];
-  // „+"-Affordance am Knoten. Klick dispatcht createAction.target; der
-  // Provider weiß was „leer befüllen" für ihn heißt (neuer Page-Slug etc.).
-  readonly createAction?: TreeAction;
-  // Children kommen zur Laufzeit aus einem registrierten nav-provider
-  // (lazy beim Ausklappen, SSE-live via treeEntities), keyed auf diese
-  // Nav-QN. Macht den Knoten expandable auch ohne statische children.
-  readonly provider?: boolean;
-  // Role / openToAll gate. The nav resolver hides entries the user can't
-  // reach; leave unset to always show (engine stays un-opinionated about
-  // who sees what — apps that need default-deny can set { roles: [] }).
-  // If `screen` is set and `access` is left unset, the client-side nav
-  // builder (buildNavRegistrySliceForApp) fills this in from the target
-  // screen's own `access` — a nav entry never invites a role into a 403.
-  // An explicit `access` here always wins over the screen's.
-  readonly access?: AccessRule;
-  // Workspace QNs this entry self-assigns to. Merged at boot with any
-  // r.workspace({ nav: [...] }) explicit lists. Omit to leave workspace
-  // membership decided solely by the workspace's nav list (or both empty
-  // → entry belongs to no workspace).
-  readonly workspaces?: readonly string[];
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/nav";

package/src/engine/types/ownership.ts

@@ -1,83 +1,2 @@
-// --- Ownership ---
-// Pure types for the declarative Claims → Access bridge. Runtime (from(),
-// matchesRule(), buildOwnershipClause()) stays in engine/ownership.ts, which
-// re-exports these for backwards compatibility.
-
-import type { SessionUser } from "./handlers";
-
-// Parameterised SQL fragment — produced by buildOwnershipClause + by the
-// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
-// renumbering placeholders if needed (shiftParams in engine/ownership.ts).
-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>>;
-
-// 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`).
-//
-// "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[] };
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/ownership";