@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/engine/define-handler.d.ts

@@ -0,0 +1,21 @@
+import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
+import type { ZodType } from "zod";
+import type { ContainsSecret } from "../secrets/types.js";
+import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.js";
+import type { KumikoEventTypeMap } from "./types/index.js";
+export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.js";
+export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap>(def: WriteHandlerInput<TName, TSchema, TData, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
+    secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
+] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap>;
+export declare function defineQueryHandler<const TName extends string, TSchema extends ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TResult> ? [
+    secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
+] : []): QueryHandlerDefinition<TName, TSchema, TResult, TMap>;
+export declare const PAGED_QUERY_HANDLER_BRAND = "__kumikoPagedQueryHandler";
+export declare function isPagedQueryHandler(def: object): boolean;
+export declare function isEntityConventionQueryHandler(def: object): boolean;
+export type PagedQueryHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap> = QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap> & {
+    readonly [PAGED_QUERY_HANDLER_BRAND]: true;
+};
+export declare function definePagedQueryHandler<const TName extends string, TSchema extends ZodType, TRow = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, CursorResult<TRow>, TMap>, ..._noSecretInResponse: true extends ContainsSecret<CursorResult<TRow>> ? [
+    secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
+] : []): PagedQueryHandlerDefinition<TName, TSchema, TRow, TMap>;

package/dist/engine/define-handler.js

@@ -0,0 +1,117 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { runPipeline } from "./run-pipeline.js";
+export function defineWriteHandler(def, 
+// R6: a phantom rest-param. When the inferred response `TData` carries a
+// Secret<> anywhere, ContainsSecret<TData> is `true` and this resolves to a
+// 1-tuple the caller can't supply → compile error at the leak site. Clean
+// responses get `[]`, so existing call-sites are unaffected. Checking it in a
+// parameter post-inference (not as a `TData extends …` constraint, which TS
+// rejects as circular, TS2313) is what makes inference survive.
+//
+// Membership form `true extends ContainsSecret<TData>` (556/1), not
+// `ContainsSecret<TData> extends true`: when TData is a union like
+// `{ok:true} | {s:Secret<string>}`, the naked-type-parameter conditional in
+// ContainsSecret DISTRIBUTES over the union, so the result is
+// `false | true` = `boolean`, not the literal `true` — `ContainsSecret<
+// TData> extends true` is then false (boolean isn't assignable to the
+// literal true) and the old check silently fell through to `[]` even with
+// a real leak in one branch. Putting the naked `true` on the LEFT instead
+// keeps the check fail-closed for the union case (`true extends boolean`
+// is true) without eagerly normalizing ContainsSecret<TData> against a
+// literal — which is what blew up TS's instantiation depth on generic
+// call-sites (createTokenRequestHandler's still-unresolved TSuccessKind).
+..._noSecretInResponse) {
+    // Runtime-guard against accidentally setting BOTH handler+perform.
+    // The discriminated-union type-error
+    //   "Type 'PipelineDef<...>' is not assignable to type 'undefined'."
+    // is functional but cryptic for less TS-experienced users; this throws
+    // a name-and-explanation error message instead. Followup #3.
+    // The cast is necessary because the discriminated union narrows
+    // `handler` away once `perform` is present (and vice-versa) — at this
+    // boundary we want to read both regardless of the narrowing.
+    const probe = def;
+    if (probe.handler !== undefined && probe.perform !== undefined) {
+        throw new Error(`defineWriteHandler("${def.name}"): both \`handler\` and \`perform\` are set. ` +
+            `Pick one — \`handler\` for the free-form async function, ` +
+            `\`perform: stepsPipeline(...)\` for the step-pipeline form. ` +
+            `(See step-vocabulary.md for which form fits.)`);
+    }
+    // Conditional spreads (`...(def.access && { access: def.access })`)
+    // mirror the existing convention in entity-handlers.ts /
+    // define-feature.ts — optional fields stay absent rather than being
+    // serialised as `key: undefined`.
+    const base = {
+        name: def.name,
+        schema: def.schema,
+        ...(def.access && { access: def.access }),
+        ...(def.description !== undefined && { description: def.description }),
+        ...(def.agent && { agent: def.agent }),
+        ...(def.unsafeSkipTransitionGuard && {
+            unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
+        }),
+        ...(def.rateLimit && { rateLimit: def.rateLimit }),
+        ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+    };
+    if ("perform" in def && def.perform !== undefined) {
+        const performDef = def.perform;
+        // @wrapper-known semantic-alias
+        const compiledHandler = async (event, ctx) => {
+            return runPipeline(performDef, event, ctx);
+        };
+        return { ...base, handler: compiledHandler, perform: performDef };
+    }
+    return { ...base, handler: def.handler };
+}
+export function defineQueryHandler(def, 
+// R6: phantom rest-param — see defineWriteHandler. Forbids a Secret<> in the
+// inferred query response `TResult` at compile time; `[]` for clean responses.
+// Membership form (556/1) — see defineWriteHandler's comment for why.
+..._noSecretInResponse) {
+    return def;
+}
+// Runtime marker set only by definePagedQueryHandler. A plain
+// defineQueryHandler-built object never carries it. Kept as a type-level
+// signal (fw#2216) even though no validator gates on it — QueryHandlerDef
+// has no output schema, so a boot check can't distinguish "returns
+// PagedRows" from "doesn't" without running the handler; the actual
+// enforcement is a runtime shape guard in the renderer (kumiko-screen.tsx).
+//
+// A string key, not a Symbol: bundled-features imports this module through
+// the package's "@cosmicdrift/kumiko-framework/engine" subpath (symlinked
+// node_modules entry) via a different resolution route than a same-package
+// relative import — two routes to the same file that can end up as two
+// separate module instances under bundler symlink handling. A Symbol()
+// evaluated twice would produce two unequal brands; a string literal doesn't
+// have that failure mode.
+// Exported (not just the predicate) so feature-entity-handlers.ts's
+// queryHandler() registrar — which rebuilds a fresh QueryHandlerDef from an
+// explicit field whitelist rather than spreading `def` — can carry the
+// brand through into the stored registry entry.
+export const PAGED_QUERY_HANDLER_BRAND = "__kumikoPagedQueryHandler";
+export function isPagedQueryHandler(def) {
+    // @cast-boundary brand-probe — reading an internal marker key off an
+    // otherwise-typed handler definition; the property may legitimately be
+    // absent, which is exactly the case this function distinguishes.
+    return def[PAGED_QUERY_HANDLER_BRAND] === true;
+}
+export function isEntityConventionQueryHandler(def) {
+    // @cast-boundary brand-probe — same shape as isPagedQueryHandler above.
+    return def[ENTITY_CONVENTION_QUERY_BRAND] === true;
+}
+// A projectionList screen's query must resolve to { rows, nextCursor, total? }
+// (CursorResult<T>) — the renderer used to read rowsQuery.data?.rows and
+// silently show an empty list otherwise (fw#2216: session-list); the
+// renderer now guards against a malformed shape at runtime instead. Use this
+// instead of defineQueryHandler for any query wired to a projectionList
+// screen's `query` so the contract is documented at the definition site.
+//
+// Deliberately does NOT merge cursor/limit/sort/search into the input
+// schema — that would change sortable/paginated derivation for existing
+// screens (a behavior change, not a wrapper change). Callers that want
+// those params add them to `schema` themselves.
+export function definePagedQueryHandler(def, 
+// R6: phantom rest-param — see defineWriteHandler. CursorResult<TRow> wraps
+// TRow in `rows`, so ContainsSecret recurses through the array element.
+..._noSecretInResponse) {
+    return { ...def, [PAGED_QUERY_HANDLER_BRAND]: true };
+}

package/dist/engine/define-roles.d.ts

@@ -0,0 +1,5 @@
+type RoleMap<T extends readonly string[]> = {
+    readonly [K in T[number]]: K;
+};
+export declare function defineRoles<const T extends readonly string[]>(roles: T): RoleMap<T>;
+export {};

package/dist/engine/define-roles.js

@@ -0,0 +1,14 @@
+// Identity function for type-safe role definitions.
+// App defines roles once, all features reference them via the typed object.
+//
+// Usage:
+//   const roles = defineRoles(["Admin", "SystemAdmin", "Driver"] as const);
+//   roles.Admin     // "Admin" — autocomplete + type-checked
+//   roles.Admni     // TS error
+export function defineRoles(roles) {
+    const map = {}; // @cast-boundary schema-walk
+    for (const role of roles) {
+        map[role] = role;
+    }
+    return map; // @cast-boundary schema-walk
+}

package/dist/engine/define-step.d.ts

@@ -0,0 +1,4 @@
+import type { StepDef, StepKind } from "./types/step.js";
+export declare function defineStep<TArgs, TResult>(def: StepDef<TArgs, TResult>): StepDef<TArgs, TResult>;
+export declare function getStep(kind: StepKind): StepDef | undefined;
+export declare function listStepKinds(): readonly StepKind[];

package/dist/engine/define-step.js

@@ -0,0 +1,22 @@
+// Step-Registry + defineStep factory.
+//
+// Steps are registered at module-load time via defineStep(). The runtime
+// (run-pipeline.ts) looks them up by `kind` to dispatch run-calls.
+//
+// The registry is process-global; Tier-2 step opt-in via
+// `r.requires.step("…")` (Q9 in step-vocabulary.md) is a future pass.
+const stepRegistry = new Map();
+export function defineStep(def) {
+    const existing = stepRegistry.get(def.kind);
+    if (existing && existing !== def) {
+        throw new Error(`Step kind "${def.kind}" is already registered with a different definition`);
+    }
+    stepRegistry.set(def.kind, def);
+    return def;
+}
+export function getStep(kind) {
+    return stepRegistry.get(kind);
+}
+export function listStepKinds() {
+    return Array.from(stepRegistry.keys());
+}

package/dist/engine/define-workflow.d.ts

@@ -0,0 +1,89 @@
+import type { WriteEvent } from "./types/handlers.js";
+import type { AwaitedEventType, PipelineDef } from "./types/step.js";
+/**
+ * Trigger configuration for a workflow. Determines what starts a run.
+ */
+export type WorkflowTrigger = {
+    readonly kind: "event";
+    readonly eventType: string;
+    readonly filter?: (event: WriteEvent) => boolean;
+} | {
+    readonly kind: "cron";
+    readonly schedule: string;
+} | {
+    readonly kind: "webhook";
+    readonly path: string;
+};
+/**
+ * Workflow definition — the result of defineWorkflow().
+ */
+export type WorkflowDefinition<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = {
+    readonly __kind: "workflow";
+    readonly name: string;
+    readonly trigger: WorkflowTrigger;
+    /**
+     * Declared expected events (D4, workflow-resume-loop.md) — the sole route
+     * a waitForEvent step can reach an event type. Read at registration time
+     * to build the static apply-map (Phase 3b); values are plain event-type
+     * strings, not the branded AwaitedEventType the pipeline closure sees.
+     */
+    readonly awaits?: TAwaits;
+    /** The pipeline definition containing the step list closure. */
+    readonly pipelineDef: PipelineDef<TPayload, TData, {
+        readonly [K in keyof TAwaits]: AwaitedEventType;
+    }>;
+    /** Idempotency key for deduplication — prevents duplicate runs. */
+    readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
+};
+/**
+ * Input shape for defineWorkflow() — the user-facing API.
+ */
+export type WorkflowInput<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = {
+    readonly name: string;
+    readonly trigger: WorkflowTrigger;
+    readonly awaits?: TAwaits;
+    readonly steps: PipelineDef<TPayload, TData, {
+        readonly [K in keyof TAwaits]: AwaitedEventType;
+    }>;
+    readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
+    readonly onError?: PipelineDef<unknown>;
+};
+/**
+ * Define a suspendable workflow.
+ *
+ * Example:
+ * ```ts
+ * defineWorkflow({
+ *   name: "user-onboarding",
+ *   trigger: { kind: "event", eventType: "user.signed-up" },
+ *   steps: stepsPipeline(({ event, r }) => [
+ *     r.step.mail.send({ to: () => event.payload.email, subject: "Welcome!", body: "..." }),
+ *     r.step.wait({ for: "P1D" }),
+ *     r.step.read.findOne("user", { table: userTable, where: ... }),
+ *     r.step.branch({ if: ({ steps }) => ..., onTrue: [...], onFalse: [...] }),
+ *     r.step.retry({ times: 3, backoff: "exponential", do: [
+ *       r.step.webhook.send({ url: "...", mode: "deferred" }),
+ *     ]}),
+ *   ]),
+ * });
+ * ```
+ */
+export declare function defineWorkflow<TPayload = unknown, TData = unknown, const TAwaits extends Record<string, string> = Record<string, string>>(input: WorkflowInput<TPayload, TData, TAwaits>): WorkflowDefinition<TPayload, TData, TAwaits>;
+/**
+ * Q7 Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
+ * identity (name + trigger + serialized pipeline-closure source). Persisted
+ * in `workflow.run.started` and re-checked at every resume so a library-
+ * upgrade that changes the closure source surfaces as a loud
+ * `workflow-definition-changed` failure on in-flight runs instead of a
+ * silent semantic drift.
+ *
+ * Limitations (will be tightened in M.5 with the Designer/AST layer):
+ *   - `build.toString()` captures the closure source but not bindings —
+ *     two definitions that import different external helpers with the
+ *     same source bytes would collide. Acceptable for M.4 because the
+ *     fingerprint is a *change-detector*, not a deep semantic identity.
+ *   - Minifiers / source-maps will produce different fingerprints across
+ *     environments. Run-the-fingerprint-in-the-same-environment is the
+ *     contract; cross-env replay is out of scope.
+ */
+export declare function computeDefinitionFingerprint<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>>(workflow: Pick<WorkflowDefinition<TPayload, TData, TAwaits>, "name" | "trigger" | "pipelineDef">): string;

package/dist/engine/define-workflow.js

@@ -0,0 +1,70 @@
+// defineWorkflow — define a persistent, suspendable workflow.
+// Tier-3 / Workflow-only mount-point. See step-vocabulary.md Sample 2 for
+// the full lifecycle (run.started → wait → resume → run.completed) and
+// Q7 (Snapshot-at-Start) for the in-flight upgrade story.
+import { createHash } from "node:crypto";
+/**
+ * Define a suspendable workflow.
+ *
+ * Example:
+ * ```ts
+ * defineWorkflow({
+ *   name: "user-onboarding",
+ *   trigger: { kind: "event", eventType: "user.signed-up" },
+ *   steps: stepsPipeline(({ event, r }) => [
+ *     r.step.mail.send({ to: () => event.payload.email, subject: "Welcome!", body: "..." }),
+ *     r.step.wait({ for: "P1D" }),
+ *     r.step.read.findOne("user", { table: userTable, where: ... }),
+ *     r.step.branch({ if: ({ steps }) => ..., onTrue: [...], onFalse: [...] }),
+ *     r.step.retry({ times: 3, backoff: "exponential", do: [
+ *       r.step.webhook.send({ url: "...", mode: "deferred" }),
+ *     ]}),
+ *   ]),
+ * });
+ * ```
+ */
+export function defineWorkflow(input) {
+    // pipelineDef.awaits carries the same raw strings as the declaration
+    // below — buildPipelineSteps (pipeline.ts) is where they're branded into
+    // AwaitedEventType for the step closure, not here (see PipelineDef.awaits
+    // doc comment in types/step.ts for why the brand can't happen at this
+    // layer without breaking inference for an inline `stepsPipeline(...)`).
+    return {
+        __kind: "workflow",
+        name: input.name,
+        trigger: input.trigger,
+        awaits: input.awaits,
+        pipelineDef: { ...input.steps, awaits: input.awaits },
+        idempotencyKey: input.idempotencyKey,
+    };
+}
+/**
+ * Q7 Snapshot-at-Start fingerprint. SHA-256 over the workflow's stable
+ * identity (name + trigger + serialized pipeline-closure source). Persisted
+ * in `workflow.run.started` and re-checked at every resume so a library-
+ * upgrade that changes the closure source surfaces as a loud
+ * `workflow-definition-changed` failure on in-flight runs instead of a
+ * silent semantic drift.
+ *
+ * Limitations (will be tightened in M.5 with the Designer/AST layer):
+ *   - `build.toString()` captures the closure source but not bindings —
+ *     two definitions that import different external helpers with the
+ *     same source bytes would collide. Acceptable for M.4 because the
+ *     fingerprint is a *change-detector*, not a deep semantic identity.
+ *   - Minifiers / source-maps will produce different fingerprints across
+ *     environments. Run-the-fingerprint-in-the-same-environment is the
+ *     contract; cross-env replay is out of scope.
+ */
+export function computeDefinitionFingerprint(workflow) {
+    // `awaits` is part of the routing contract (D4, workflow-resume-loop.md):
+    // changing which events a run waits on changes the run's behavior just
+    // like changing the step source does, so a changed declaration must flip
+    // the fingerprint and trip the Q7 stale-definition check on resume.
+    const material = JSON.stringify({
+        name: workflow.name,
+        trigger: workflow.trigger,
+        awaits: workflow.pipelineDef.awaits,
+        source: workflow.pipelineDef.build.toString(),
+    });
+    return createHash("sha256").update(material).digest("hex");
+}

package/dist/engine/effective-features.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureDefinition, Registry } from "./types/index.js";
+export type ToggleReader = (featureName: string) => boolean | undefined;
+export declare function isToggleableFeature(feature: FeatureDefinition): feature is FeatureDefinition & {
+    toggleableDefault: boolean;
+};
+export declare function computeEffectiveFeatures(registry: Registry, readToggle: ToggleReader): ReadonlySet<string>;

package/dist/engine/effective-features.js

@@ -0,0 +1,73 @@
+// A feature is toggleable iff it declared r.toggleable() at define-time
+// (toggleableDefault set). Non-toggleable features are always-on and ignore
+// overrides entirely — used here, by compose-tier-resolver, and by
+// tier-engine's always-on set to agree on the same rule.
+export function isToggleableFeature(feature) {
+    return feature.toggleableDefault !== undefined;
+}
+// Compute the set of effectively-enabled features for the current call.
+//
+// Rules (AND-combined, any false wins):
+//   1. Always-on: feature without r.toggleable() → enabled, ignores overrides.
+//   2. Toggleable: enabled = (globalOverride ?? toggleableDefault).
+//   3. Cascade: a feature is only effectively enabled if ALL its r.requires()
+//      targets are effectively enabled. Applied transitively.
+//
+// Cascade semantics note: a NON-toggleable feature A that requires a
+// toggleable feature B becomes effectively disabled when B is off. This is
+// intentional — running A's handlers/hooks without its declared dependency
+// would be a worse failure mode than gating A. Ops documentation must call
+// this out so disabling "leaf" features doesn't surprise anyone.
+//
+// The result is a plain Set for O(1) `has(name)` checks in the dispatcher
+// gate, hook filter, and MSP runner. Cycle-safety is delegated to the
+// registry's existing boot-validation (cycles are rejected there).
+export function computeEffectiveFeatures(registry, readToggle) {
+    // Raw enablement, before cascade.
+    const raw = new Map();
+    for (const feature of registry.features.values()) {
+        if (!isToggleableFeature(feature)) {
+            raw.set(feature.name, true);
+            continue;
+        }
+        const override = readToggle(feature.name);
+        raw.set(feature.name, override ?? feature.toggleableDefault);
+    }
+    // Transitive cascade via DFS with memoization. Cycles are already rejected
+    // at boot, so no cycle-breaking is needed here.
+    const effective = new Map();
+    function resolve(name) {
+        const cached = effective.get(name);
+        if (cached !== undefined)
+            return cached;
+        const rawEnabled = raw.get(name) ?? true;
+        if (!rawEnabled) {
+            effective.set(name, false);
+            return false;
+        }
+        const feature = registry.getFeature(name);
+        // Feature referenced by requires() but not loaded — registry boot should
+        // have caught this, but be defensive: treat missing deps as disabled
+        // (surfaces the same behaviour as "dep is off", not a silent pass).
+        if (!feature) {
+            effective.set(name, false);
+            return false;
+        }
+        for (const dep of feature.requires) {
+            if (!resolve(dep)) {
+                effective.set(name, false);
+                return false;
+            }
+        }
+        effective.set(name, true);
+        return true;
+    }
+    for (const feature of registry.features.values())
+        resolve(feature.name);
+    const result = new Set();
+    for (const [name, enabled] of effective) {
+        if (enabled)
+            result.add(name);
+    }
+    return result;
+}

package/dist/engine/embedded-derived.d.ts

@@ -0,0 +1,29 @@
+import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types/index.js";
+/** Computes a derived cell from its source values. Missing/non-numeric
+ *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  treat missing as 0 only when at least one source is present — if every
+ *  source is missing, return undefined (do not invent 0). Money cells are
+ *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
+ *  to the target sub-field's declared precision afterward. */
+export declare function computeDerivedCellValue(op: EmbeddedDerivedCellDef["op"], values: readonly (number | undefined)[]): number | undefined;
+export type DerivedCellRoundingTarget = {
+    readonly type: EmbeddedSubFieldDef["type"];
+    readonly scale?: number;
+};
+/** Rounds a derived cell's computed value to the precision its target
+ *  sub-field declares — commercial rounding (round-half-away-from-zero,
+ *  correct for signed minor-unit money). money → integer; decimal → `scale`
+ *  digits; every other target type passes through unchanged (the function
+ *  stays unit-agnostic for those). */
+export declare function roundDerivedCellValue(value: number, target: DerivedCellRoundingTarget): number;
+/** Recomputes every derived cell of an embedded-list row from its raw
+ *  values, overwriting whatever the client sent instead of merely checking
+ *  it — the server is the authority for derived cells. Reads source values
+ *  from the working copy so already-recomputed sources feed later cells;
+ *  boot-validator rejects derived-from-derived chains. A row that isn't a
+ *  plain object (already invalid, or not this field's shape) passes through
+ *  untouched — validation downstream rejects it. The computed value is
+ *  rounded to the target sub-field's declared precision (`schema`) before
+ *  it's written back, so a fractional product lands on a value the target
+ *  type can actually represent. */
+export declare function withDerivedCells(row: unknown, derived: Readonly<Record<string, EmbeddedDerivedCellDef>>, schema: Readonly<Record<string, EmbeddedSubFieldDef>>): unknown;

package/dist/engine/embedded-derived.js

@@ -0,0 +1,82 @@
+/** Computes a derived cell from its source values. Missing/non-numeric
+ *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  treat missing as 0 only when at least one source is present — if every
+ *  source is missing, return undefined (do not invent 0). Money cells are
+ *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
+ *  to the target sub-field's declared precision afterward. */
+export function computeDerivedCellValue(op, values) {
+    if (op === "multiply") {
+        if (values.some((value) => value === undefined))
+            return undefined;
+        return values.reduce((product, value) => product * value, 1);
+    }
+    if (values.every((value) => value === undefined))
+        return undefined;
+    const numeric = values.map((value) => value ?? 0);
+    if (op === "sum")
+        return numeric.reduce((sum, value) => sum + value, 0);
+    // subtract: first value minus every subsequent value.
+    const [first, ...rest] = numeric;
+    return rest.reduce((remainder, value) => remainder - value, first ?? 0);
+}
+/** Rounds a derived cell's computed value to the precision its target
+ *  sub-field declares — commercial rounding (round-half-away-from-zero,
+ *  correct for signed minor-unit money). money → integer; decimal → `scale`
+ *  digits; every other target type passes through unchanged (the function
+ *  stays unit-agnostic for those). */
+export function roundDerivedCellValue(value, target) {
+    if (target.type === "money")
+        return roundHalfAwayFromZero(value, 0);
+    // `scale` is required on the real decimal EmbeddedSubFieldDef (fields.ts:
+    // "no silent default that could truncate") — DerivedCellRoundingTarget
+    // only widens it to optional for the money/decimal split above. If it's
+    // ever missing anyway, pass the value through unrounded rather than
+    // guessing 0 decimals and truncating a value the caller never asked to round.
+    if (target.type === "decimal") {
+        return target.scale === undefined ? value : roundHalfAwayFromZero(value, target.scale);
+    }
+    return value;
+}
+function roundHalfAwayFromZero(value, decimals) {
+    const factor = 10 ** decimals;
+    // `toPrecision` strips the float-multiplication noise (e.g. 1.005 * 100
+    // === 100.49999999999999) before rounding, so a value that's
+    // mathematically exactly at the half-step doesn't fall to the wrong side.
+    // ponytail: toPrecision(15) can shift by ±1 minor unit for values near Number.MAX_SAFE_INTEGER (2^53); fine for realistic money amounts.
+    // ponytail: also snaps values within ~1e-16 of a half-step up (e.g. roundHalfAwayFromZero(0.49999999999999994, 0) === 1) — deliberate, the float-noise case is far more common than a genuine near-half input.
+    const scaled = Number((Math.abs(value) * factor).toPrecision(15));
+    return (Math.sign(value) * Math.round(scaled)) / factor;
+}
+/** Recomputes every derived cell of an embedded-list row from its raw
+ *  values, overwriting whatever the client sent instead of merely checking
+ *  it — the server is the authority for derived cells. Reads source values
+ *  from the working copy so already-recomputed sources feed later cells;
+ *  boot-validator rejects derived-from-derived chains. A row that isn't a
+ *  plain object (already invalid, or not this field's shape) passes through
+ *  untouched — validation downstream rejects it. The computed value is
+ *  rounded to the target sub-field's declared precision (`schema`) before
+ *  it's written back, so a fractional product lands on a value the target
+ *  type can actually represent. */
+export function withDerivedCells(row, derived, schema) {
+    if (typeof row !== "object" || row === null || Array.isArray(row))
+        return row;
+    const source = row;
+    const copy = { ...source };
+    for (const [cellName, def] of Object.entries(derived)) {
+        const sourceValues = def.from.map((sourceField) => {
+            const value = copy[sourceField];
+            return typeof value === "number" ? value : undefined;
+        });
+        const computed = computeDerivedCellValue(def.op, sourceValues);
+        if (computed === undefined) {
+            // Always clear — keeping a client value would let callers spoof required
+            // derived cells when sources are missing (server must stay authoritative).
+            delete copy[cellName];
+        }
+        else {
+            const target = schema[cellName];
+            copy[cellName] = target === undefined ? computed : roundDerivedCellValue(computed, target);
+        }
+    }
+    return copy;
+}

package/dist/engine/entity-handlers.d.ts

@@ -0,0 +1,67 @@
+import * as z from "zod";
+import { type EventStoreExecutor } from "../db/event-store-executor.js";
+import { type EntityTable } from "../db/table-builder.js";
+import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.js";
+import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.js";
+export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.js";
+export declare function isDeprecatedCrossTenantHandler(handler: object): boolean;
+export declare const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
+export declare const MAX_LIST_LIMIT = 200;
+export declare const entityListSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    sortDirection: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    totalCount: z.ZodOptional<z.ZodBoolean>;
+    includeDeleted: z.ZodOptional<z.ZodBoolean>;
+    filter: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        op: z.ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: z.ZodUnknown;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+export declare function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+export declare function defineEntityCreateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+export declare function defineEntityUpdateHandler(entityName: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
+export declare function defineEntityDeleteHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+export declare function defineEntityRestoreHandler(entityName: string, entity: EntityDefinition, options: EntityHandlerOptions): WriteHandlerDef;
+export declare function defineEntityListHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+export declare function defineEntityDetailHandler(entityName: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;
+export declare function createEntityExecutor(entityName: string, entity: EntityDefinition): {
+    readonly table: EntityTable;
+    readonly executor: EventStoreExecutor;
+};
+export declare function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: {
+    access: AccessRule;
+    unsafeAllTenants?: boolean;
+    escapeHatch?: EscapeHatchDeclaration;
+}): QueryHandlerDef;
+/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
+export declare function registerEntityCrud(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;