@cosmicdrift/kumiko-types 0.159.1 → 0.161.0

package/src/secrets-types.ts

@@ -0,0 +1,177 @@
+// Envelope Encryption types. Separating DEK (per-value) from KEK (central)
+// is what makes key rotation cheap: on rotation we only re-wrap the small
+// encryptedDek, never touch the ciphertext.
+
+import type { TenantId } from "./identifiers";
+
+// Plaintext-secret wrapper (branded). Carries the actual string internally
+// but the nominal typing stops it from landing in an HTTP response by
+// accident — a response-serializer guard + the reveal() cost make the leak
+// intentional. Framework code that sees `Secret<string>` knows the caller
+// has already gone through the audited ctx.secrets.get path.
+//
+// The brand is a real (non-registered) Symbol so it exists at runtime for
+// isSecret() without clashing with user-land symbols of the same name.
+const SecretBrand: unique symbol = Symbol("kumiko.secret");
+
+export type Secret<T = string> = {
+  readonly [SecretBrand]: true;
+  readonly reveal: () => T;
+};
+
+// Implementation helper — bundled-features uses this to wrap a plaintext after
+// decryption. Kept in the framework so both sides share one canonical brand.
+export function createSecret<T>(value: T): Secret<T> {
+  return {
+    [SecretBrand]: true as const,
+    reveal: () => value,
+  };
+}
+
+// True for any object carrying the Secret brand. Used by the response guard
+// to reject leaks before serialization.
+export function isSecret(v: unknown): v is Secret<unknown> {
+  return typeof v === "object" && v !== null && SecretBrand in v;
+}
+
+// --- Compile-time response guard (R6) --------------------------------------
+//
+// ContainsSecret<T> is `true` only when a Secret<> is DEFINITELY present
+// somewhere in T. The handler-registration guard (defineWriteHandler/
+// defineQueryHandler) turns a `true` into a compile error — the static twin of
+// assertNoSecretLeak's runtime walk.
+//
+// Biased to `false`: anything it cannot inspect — a bare generic type param (a
+// handler generic over its response), `unknown`/`any`, `never` — resolves to
+// `false` = allowed, with the runtime guard as the backstop. The alternative
+// (default-to-leak) false-flags every legitimate generic-over-response handler.
+//
+// Branch order is load-bearing: never/unknown/any first (uninspectable), then
+// Secret, then primitives (covers branded primitives like TenantId without
+// enumerating them), then the SafeLeaf allowlist (opaque class instances that
+// blind `{ [K in keyof T] }` recursion would mangle — the type-level mirror of
+// leak-guard.ts skipping non-plain objects), then arrays, then a "does any
+// field contain a secret" fold over plain objects.
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+// Opaque built-in leaves a response legitimately carries; never recurse into
+// them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
+// Map/Set (556/2): `keyof Map<K,V>` yields method names, not V, so these
+// already fell through to `false` via the object-mapped-type branch — listed
+// explicitly here so the compile-time treatment matches leak-guard.ts's
+// runtime `instanceof Map`/`instanceof Set` branch (walk entries separately)
+// instead of looking like an oversight.
+type SafeLeaf =
+  | Date
+  | RegExp
+  | Temporal.Instant
+  | Temporal.ZonedDateTime
+  | Temporal.PlainDate
+  | Temporal.PlainDateTime
+  | Temporal.PlainTime
+  | Temporal.PlainYearMonth
+  | Temporal.PlainMonthDay
+  | Temporal.Duration
+  | Map<unknown, unknown>
+  | Set<unknown>;
+
+export type ContainsSecret<T> = [T] extends [never]
+  ? false
+  : unknown extends T
+    ? false
+    : T extends Secret<unknown>
+      ? true
+      : T extends Primitive
+        ? false
+        : T extends SafeLeaf
+          ? false
+          : T extends readonly (infer U)[]
+            ? ContainsSecret<U>
+            : T extends object
+              ? true extends { [K in keyof T]-?: ContainsSecret<T[K]> }[keyof T]
+                ? true
+                : false
+              : false;
+
+// Per-read audit context. Populated by requireSecretsContext() wrapper so
+// handlers don't need to pass userId/handlerName manually on every call.
+// Undefined for framework-internal reads (rotation job, tests) — the audit
+// table stays a "who touched this credential" log, not a crash-report sink.
+export type SecretAuditContext = {
+  readonly userId: string;
+  readonly handlerName: string;
+};
+
+// Feature code can pass either the raw qualified-name string or a typed
+// handle returned by r.secret. The handle form is safer — renaming the
+// r.secret call updates all references through the import graph.
+export type SecretKeyRef = string | { readonly name: string };
+
+// The ctx.secrets contract. Concrete implementation lives in bundled-features
+// (createSecretsContext) where the DB and MasterKeyProvider are known. This
+// lean interface is what the framework's HandlerContext carries so engine
+// code can talk about it without pulling in bundled-features.
+export interface SecretsContext {
+  get(
+    tenantId: TenantId,
+    key: SecretKeyRef,
+    auditCtx?: SecretAuditContext,
+  ): Promise<Secret<string> | undefined>;
+  // Metadata-only existence probe: no decryption, no read-audit event.
+  // For readiness checks — use get() when the value itself is needed.
+  has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
+  set(
+    tenantId: TenantId,
+    key: SecretKeyRef,
+    value: string,
+    opts?: { redact?: (plaintext: string) => string; hint?: string; updatedBy?: string },
+  ): Promise<void>;
+  delete(tenantId: TenantId, key: SecretKeyRef, opts?: { deletedBy?: string }): Promise<boolean>;
+}
+
+export type Envelope = {
+  // AES-256-GCM ciphertext of the plaintext, keyed with a DEK.
+  readonly ciphertext: Buffer;
+  // GCM nonce (12 bytes). Generated fresh per encryption.
+  readonly iv: Buffer;
+  // GCM auth tag (16 bytes). Guarantees the ciphertext wasn't tampered.
+  readonly authTag: Buffer;
+  // DEK wrapped with the current KEK. Decryption needs provider.unwrapDek
+  // with the kekVersion to recover the DEK.
+  readonly encryptedDek: Buffer;
+  // Which KEK version was used to wrap the DEK. On rotation, rows with old
+  // versions still decrypt — the provider keeps a keyring of historical KEKs.
+  readonly kekVersion: number;
+};
+
+// BYOK hook: callers pass the tenant a value belongs to; a per-tenant-KMS
+// provider keys its wrap/unwrap on it. EnvMasterKeyProvider (app-wide
+// keyring) ignores it — the param exists so the contract doesn't have to
+// break when a tenant-scoped provider ships.
+export type KeyScope = {
+  readonly tenantId?: TenantId;
+};
+
+// The contract a KEK backend must fulfil. The framework sees only this
+// interface; concrete implementations live in separate packages
+// (@cosmicdrift/kumiko-secrets-vault, @cosmicdrift/kumiko-secrets-aws-kms, ...). The default is
+// EnvMasterKeyProvider which reads keys from environment variables.
+export interface MasterKeyProvider {
+  // Wrap a fresh DEK with the current KEK. Returns the wrapped bytes + the
+  // KEK version used — the version ends up in the Envelope so decryption
+  // later knows which KEK to ask for.
+  wrapDek(dek: Buffer, scope?: KeyScope): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
+
+  // Unwrap a previously-wrapped DEK. During rotation the provider must
+  // accept older kekVersion values (2-version window minimum), otherwise
+  // old rows become unreadable.
+  unwrapDek(encryptedDek: Buffer, kekVersion: number, scope?: KeyScope): Promise<Buffer>;
+
+  // Which KEK version new wraps use. Rotation flips this to a new value
+  // and older-version reads continue to work until rows are re-wrapped.
+  currentVersion(): number;
+
+  // Health check: can the provider talk to its backend? Used by
+  // /health/ready. Cheap probe, no KEK material read.
+  isAvailable(): Promise<boolean>;
+}

package/src/snapshot-types.ts

@@ -0,0 +1,36 @@
+import type { StoredEvent } from "./event-store-types";
+
+// Reducer used to fold events onto a state. Kept narrow and pure — the
+// caller supplies the shape and update rules. Mirrors the reducer shape
+// feature authors already write for r.projection.apply.
+export type SnapshotReducer<TState extends Record<string, unknown>> = (
+  state: TState,
+  event: StoredEvent,
+) => TState;
+
+export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
+  readonly state: TState;
+  readonly version: number;
+  readonly snapshotHit: boolean;
+};
+
+export type LoadAggregateWithSnapshotOptions = {
+  // Opt-in: include archived streams in the rehydrate. Default false — same
+  // semantics as loadAggregate / loadAggregateAsOf. Archive check is a
+  // single indexed lookup, so the cost stays negligible on the hot path.
+  readonly includeArchived?: boolean;
+  // Optional upcaster step: every delta event goes through this transform
+  // BEFORE the reducer sees it. The dispatcher wires this up with
+  // r.eventMigration so feature code always sees current-version payloads.
+  // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
+  readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
+  // Auto-snapshot policy: when the fold applied at least this many delta
+  // events, persist a fresh snapshot at the folded version (best-effort —
+  // a failed save never fails the load). Omit to keep snapshotting manual.
+  readonly snapshotEvery?: number;
+  // Reducer-shape generation stamped onto saved snapshots (default 1). A
+  // stored snapshot with a different generation is ignored — full replay
+  // through the upcaster chain — and restamped on the next auto-save. Bump
+  // whenever the reducer's state shape changes.
+  readonly snapshotVersion?: number;
+};

package/src/step.ts

@@ -0,0 +1,334 @@
+// Step-Vocabulary Types — see docs/plans/architecture/intern/step-vocabulary.md
+//
+// M.1 minimal scope:
+//   - Steps execute against the existing HandlerContext (no per-step subset).
+//   - steps-accumulator is Record<string, unknown> (no tuple-reduce typing).
+//   - Resolvers receive the full PipelineCtx as one argument.
+//
+// Strict typing on appendEvent inside steps is deferred to a later pass
+// (see TS-typing notes in the design doc). M.1 uses unsafeAppendEvent
+// semantics under the hood for r.step.aggregate.appendEvent.
+
+import type { EventStoreExecutor } from "./event-store-executor-types";
+import type { KumikoEventTypeMap } from "./event-type-map";
+import type { HandlerContext, WriteEvent, WriteResult } from "./handlers";
+import type { SaveContext } from "./hooks";
+import type { EntityId } from "./identifiers";
+import type { WhereObject } from "./where-clause-types";
+
+/**
+ * The kind discriminator for a step instance — matches the step's
+ * registration name in the step-registry (e.g. "return", "compute",
+ * "aggregate.create"). Steps register themselves at module-load time
+ * via defineStep().
+ */
+export type StepKind = string;
+
+/**
+ * Pipeline-side context handed to step argument resolvers.
+ *
+ * Contains the full HandlerContext (no per-step subset in M.1) plus
+ * the accumulated `steps` map of prior step results, and a `scope`
+ * record for forEach/branch-local bindings.
+ *
+ * `scope` is `Record<string, unknown>` — sub-step builders (forEach,
+ * branch) populate it once they land in later M.1 slices. M.1.1 ships
+ * with `r.step.return` only, which reads `event` and ignores both
+ * `steps` and `scope`.
+ */
+export type PipelineCtx<
+  TPayload = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = HandlerContext<TMap> & {
+  readonly event: WriteEvent<TPayload>;
+  readonly steps: Readonly<Record<string, unknown>>;
+  readonly scope: Readonly<Record<string, unknown>>;
+  // Workflow-run context — present only when running inside defineWorkflow.
+  // Tier-3 steps use this to write suspension events onto the correct
+  // aggregate stream and for the Resume-Loop to re-hydrate state.
+  readonly workflow?: {
+    readonly runId: string;
+    readonly workflowName: string;
+    /** Current step index in the pipeline — set by the executor before each step. */
+    readonly stepIndex: number;
+    /**
+     * Retry attempt counter for the current workflow.retry step.
+     * Set by the workflow-engine resume-loop on re-entry; starts at 1.
+     * Absent (undefined) means first attempt.
+     */
+    readonly retryAttempt?: number;
+    /**
+     * Q7 Snapshot-at-Start fingerprint of the workflow definition that
+     * started this run. Propagated into every suspension event payload so
+     * the resume-loop can detect library-upgrades that changed the closure
+     * source and surface them as a typed failure instead of running a
+     * stale-vs-new mix of steps. Optional only for legacy callers; the
+     * workflow-runner sets it on every newly-started run.
+     */
+    readonly definitionFingerprint?: string;
+  };
+};
+
+/**
+ * A resolver is either a static value or a function that derives the
+ * value from the pipeline-context. M.1 keeps the resolver signature
+ * uniform — every step accepts both forms via a normalise helper.
+ */
+export type StepResolver<T, TPayload = unknown> = T | ((ctx: PipelineCtx<TPayload>) => T);
+
+/**
+ * Per-step error strategy. M.1.1 only supports "throw" — the type is
+ * deliberately narrowed so callers cannot pass an unsupported strategy
+ * past the type-checker. The doc lists "return" / "skip" / fallback as
+ * future strategies; each lands together with its own runtime support
+ * + integration test in a later slice (no untested type expansion).
+ */
+export type StepFailureStrategy = "throw";
+
+export type StepDef<TArgs = unknown, TResult = unknown> = {
+  readonly kind: StepKind;
+  readonly defaultFailureStrategy: StepFailureStrategy;
+  // Returns the result-key for this step instance, or undefined when the
+  // step doesn't surface a result. The first-position name on the call
+  // (e.g. r.step.compute("startedAt", fn) → "startedAt") becomes the key.
+  readonly resultKey?: (args: TArgs) => string | undefined;
+  // Sub-pipeline arg-paths — names of `args.<path>` entries that hold a
+  // readonly StepInstance[] (e.g. branch's `["onTrue", "onFalse"]`, forEach's
+  // `["do"]`). The boot-validator reads these at registration time so it
+  // can recurse into nested pipelines without a hardcoded kind-list. Steps
+  // that don't carry sub-pipelines omit the field. Followup #15 self-
+  // registration: prevents future sub-step-builders from silently bypassing
+  // the unsafeProjection allowlist by forgetting to update a central map.
+  readonly subPaths?: readonly string[];
+  // Step-vocabulary tier (Q9). Tier-1 implicit, Tier-2+ requires
+  // r.requires.step("<kind>") in the owning feature. Default 1 (implicit).
+  // Tier-3 is only available inside defineWorkflow.
+  readonly tier?: 1 | 2 | 3;
+  // Runtime: resolve the args against the ctx, perform the work, return
+  // the value to land in steps.{resultKey}. Thrown errors propagate to
+  // the dispatcher's catch (M.1.1 supports "throw"-strategy only).
+  readonly run: (args: TArgs, ctx: PipelineCtx) => Promise<TResult> | TResult;
+};
+
+/**
+ * An instance of a step in a pipeline — what users build via the
+ * step-builder (`r.step.compute(...)`). Carries the kind + resolved-or-
+ * resolver args + the user-chosen onFailure override.
+ *
+ * `args` is `unknown` at this layer — the registered StepDef knows the
+ * concrete shape and casts at run() time. Cross-step type-safety lives
+ * in the per-step builder factories, not in this central type.
+ */
+export type StepInstance = {
+  readonly kind: StepKind;
+  readonly args: unknown;
+  readonly onFailure?: StepFailureStrategy;
+};
+
+/**
+ * What `stepsPipeline(closure)` returns. Carries the closure (instead of an
+ * eagerly-built array) so each handler-call sees a fresh event ref and
+ * the `r` step-builder is resolved at runtime, not at module-load time.
+ *
+ * `__kind: "pipeline"` lets defineWriteHandler distinguish a pipeline-
+ * form `perform` from accidental other shapes.
+ *
+ * `_TData` is a phantom type-parameter — held in constraint position
+ * only, never referenced in the type body. defineWriteHandler binds it
+ * via `def.perform: PipelineDef<…, TData>` (the call-site uses TData
+ * without underscore — phantom-prefix is purely a Biome
+ * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
+ * from the closure body (r.step.return has its own per-call TData), so
+ * callers must spell it explicitly:
+ *   `stepsPipeline<{ greeting: string }, { echoed: string }>(...)`
+ * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
+ */
+export type PipelineDef<TPayload = unknown, _TData = unknown> = {
+  readonly __kind: "pipeline";
+  readonly build: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[];
+};
+
+/**
+ * Argument bundle passed to the closure inside `stepsPipeline(closure)`.
+ * Build-time only — no `steps`, no `scope`, no `db`: at build time no
+ * step has run yet.
+ *
+ * The closure is invoked ONCE per handler-call and returns the immutable
+ * list of step instances. Values inside the closure that depend on prior
+ * step results MUST go through resolvers (functions) — those receive the
+ * resolver-side PipelineCtx which carries `steps` + `scope`.
+ *
+ * **Closure-body contract:** the closure must produce a deterministic
+ * step-list that doesn't depend on `event.payload` — branching on payload
+ * fields belongs inside resolvers (where they fire per-call), not in the
+ * outer closure body. Boot-validation runs the closure once with a dummy
+ * empty payload to scan unsafeProjection-* step targets; a closure that
+ * conditionally builds different step-lists per payload would silently
+ * skip validation. See validate-projection-allowlist.ts for the
+ * boot-side mechanics.
+ */
+export type PipelineBuildCtx<TPayload = unknown> = {
+  readonly event: WriteEvent<TPayload>;
+  readonly r: StepBuilder;
+};
+
+/**
+ * Step-builder namespace handed to the pipeline closure. The fields
+ * grow as M.1 adds more steps. Each is a thin factory that returns a
+ * StepInstance — the runtime resolution happens later in run().
+ *
+ * Why nested under `step`: matches the doc-API surface and leaves room
+ * for future sibling namespaces (`r.trigger`, `r.transform`) without
+ * crowding the top-level r.
+ */
+export type StepBuilder = {
+  readonly step: StepNamespace;
+};
+
+/**
+ * The collection of step factory functions. Grown incrementally —
+ * landed: return (M.1.1), compute (M.1.2), unsafeProjectionUpsert
+ * (M.1.3), aggregate.create (M.1.4). Pending: branch, forEach,
+ * read.*, aggregate.update, aggregate.appendEvent,
+ * unsafeProjectionDelete.
+ */
+export type StepNamespace = {
+  readonly return: <TData>(resolver: StepResolver<WriteResult<TData>>) => StepInstance;
+  readonly compute: <TResult>(name: string, fn: (ctx: PipelineCtx) => TResult) => StepInstance;
+  // Inline read-side projection write. Boot-validation enforces the
+  // table is in the owning feature's r.requires.projection allowlist
+  // and NOT registered as an aggregate-table via r.entity. See
+  // step-vocabulary.md "Was unsafeProjection.* überspringt".
+  readonly unsafeProjectionUpsert: (args: {
+    readonly table: unknown;
+    readonly on: readonly string[];
+    readonly row: StepResolver<Record<string, unknown>>;
+  }) => StepInstance;
+  // Sibling: delete row(s) from a read-side projection table. Same
+  // boot-validation contract as unsafeProjectionUpsert.
+  readonly unsafeProjectionDelete: (args: {
+    readonly table: unknown;
+    readonly where: StepResolver<WhereObject>;
+  }) => StepInstance;
+  // Read sub-namespace — thin wrapper on selectMany/fetchOne (bun-db).
+  // Caller-owned tenant-filter (does NOT auto-inject like ctx.queryProjection does).
+  readonly read: {
+    readonly findOne: (
+      name: string,
+      opts: {
+        readonly table: unknown;
+        readonly where: StepResolver<WhereObject | undefined>;
+      },
+    ) => StepInstance;
+    readonly findMany: (
+      name: string,
+      opts: {
+        readonly table: unknown;
+        readonly where?: StepResolver<WhereObject | undefined>;
+        readonly limit?: number;
+      },
+    ) => StepInstance;
+  };
+  // Aggregate-mutation sub-namespace — wraps the existing event-store-
+  // executor surface. Every method goes through the full ES pipeline
+  // (events + projections + lifecycle hooks + audit). The default and
+  // intended path for domain mutation; contrast with unsafeProjection.*.
+  readonly aggregate: {
+    readonly create: (
+      name: string,
+      opts: {
+        readonly executor: EventStoreExecutor;
+        readonly data: StepResolver<Record<string, unknown>>;
+      },
+    ) => StepInstance;
+    readonly update: (
+      name: string,
+      opts: {
+        readonly executor: EventStoreExecutor;
+        readonly id: StepResolver<EntityId>;
+        readonly changes: StepResolver<Record<string, unknown>>;
+        readonly version?: StepResolver<number | undefined>;
+        readonly skipOptimisticLock?: boolean;
+      },
+    ) => StepInstance;
+    readonly appendEvent: (args: {
+      readonly aggregateId: StepResolver<string>;
+      readonly aggregateType: string;
+      readonly type: string;
+      readonly payload: StepResolver<unknown>;
+      readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
+    }) => StepInstance;
+  };
+  // Conditional sub-pipeline. `onTrue` (required) and `onFalse`
+  // (optional) are static StepInstance arrays; `r` for sub-step builders
+  // is captured from the outer pipeline closure. Naming-Q14: `onTrue`/
+  // `onFalse` over `then`/`else` because Biome's noThenProperty lint
+  // flags `then` as a thenable-trap. Q12: r.step.return inside
+  // onTrue/onFalse is rejected at build time (would trigger
+  // discriminated-union TData trap). Q13: no resultKey — branch is
+  // side-effect-only.
+  readonly branch: (args: {
+    readonly if: StepResolver<boolean>;
+    readonly onTrue: readonly StepInstance[];
+    readonly onFalse?: readonly StepInstance[];
+  }) => StepInstance;
+  // Iterate a sub-pipeline over an array. `as` is required (Q15);
+  // current item lands under `scope[as]` for resolvers in `do`.
+  // Sequential only in M.1.6; concurrency is Followup #12.
+  readonly forEach: <TItem = unknown>(args: {
+    readonly over: StepResolver<readonly TItem[]>;
+    readonly as: string;
+    readonly do: readonly StepInstance[];
+    readonly concurrency?: 1;
+  }) => StepInstance;
+  // Tier-2 namespace. Each builder requires r.requires.step("<kind>")
+  // in the owning feature; boot-validation enforces.
+  readonly webhook: {
+    readonly send: (args: {
+      readonly url: StepResolver<string>;
+      readonly method?: "POST" | "PUT" | "PATCH";
+      readonly headers?: StepResolver<Readonly<Record<string, string>>>;
+      readonly body?: StepResolver<unknown>;
+      readonly auth?:
+        | { readonly kind: "bearer"; readonly secretRef: string }
+        | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+      readonly mode: "deferred";
+      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+    }) => StepInstance;
+  };
+  readonly mail: {
+    readonly send: (args: {
+      readonly to: StepResolver<string | readonly string[]>;
+      readonly subject: StepResolver<string>;
+      readonly body: StepResolver<string>;
+      readonly from?: StepResolver<string>;
+      readonly mode: "deferred";
+    }) => StepInstance;
+  };
+  readonly callFeature: (
+    name: string,
+    opts: {
+      readonly handler: string;
+      readonly payload: StepResolver<unknown>;
+      readonly as?: import("./handlers").SessionUser;
+    },
+  ) => StepInstance;
+  // --- Tier-3 / Workflow-only steps ---
+  // Only available inside defineWorkflow ({ steps: stepsPipeline(...) }).
+  // Runtime guard: throws when used inside sync defineWriteHandler.
+  readonly wait: (args: { readonly for: StepResolver<string> }) => StepInstance;
+  readonly waitForEvent: (args: {
+    readonly event: string;
+    readonly match?: StepResolver<(payload: unknown) => boolean>;
+    readonly timeout: StepResolver<string>;
+  }) => StepInstance;
+  readonly retry: (args: {
+    readonly times: number;
+    readonly backoff: "exponential" | "linear";
+    readonly do: readonly StepInstance[];
+  }) => StepInstance;
+};
+
+// SaveContext is the result-type of aggregate.create / aggregate.update;
+// re-exported for step authors who want to type their resolver bindings.
+export type AggregateStepResult = SaveContext;

package/src/tenant-db-types.ts

@@ -0,0 +1,58 @@
+import type { DbRunner } from "./db-connection";
+import type { EntityTableMeta } from "./entity-table-meta-types";
+import type { NotExecutorOnly } from "./executor-brand";
+import type { TenantId } from "./identifiers";
+import type { SchemaTable } from "./schema-table-types";
+import type { SelectOptions, WhereObject } from "./where-clause-types";
+
+// Method-form writes reject the executor-only brand exactly like the free-function
+// helpers (#742): a managed EntityTable is a rebuildable projection, so writing it
+// directly — free-function OR method-form — drifts the row past its event stream and
+// a rebuild wipes it. The permissive base stays (raw pgTables AND unmanaged entity
+// metas are not projections → writable); `& NotExecutorOnly` strips only branded
+// EntityTables (its `[EXECUTOR_ONLY]: true` violates the optional-never). Reads keep
+// the plain `SchemaTable` param.
+type WritableTable = (SchemaTable | EntityTableMeta) & NotExecutorOnly;
+
+/**
+ * TenantDb scope modes:
+ *
+ * - "tenant" (default): SELECT/UPDATE/DELETE filtered by tenantId + reference data (tenantId=SYSTEM_TENANT_ID).
+ *   INSERT forces tenantId — handler cannot override.
+ *
+ * - "system" (r.systemScope()): No tenant filter on reads/updates/deletes.
+ *   INSERT uses tenantId as default but handler can override.
+ *
+ * Tables without a tenantId column are always unfiltered regardless of mode.
+ */
+export type TenantDbMode = "tenant" | "system";
+
+export type TenantDb = {
+  readonly tenantId: TenantId;
+  readonly mode: TenantDbMode;
+  /**
+   * Underlying DbRunner. Framework-internal use (event-store, migrations) —
+   * bypasses tenant-filter. Feature code uses the typed helpers above so the
+   * automatic scoping stays intact.
+   */
+  readonly raw: DbRunner;
+  selectMany<T = Record<string, unknown>>(
+    table: SchemaTable,
+    where?: WhereObject,
+    options?: SelectOptions,
+  ): Promise<readonly T[]>;
+  fetchOne<T = Record<string, unknown>>(
+    table: SchemaTable,
+    where: WhereObject,
+  ): Promise<T | undefined>;
+  insertOne<T = Record<string, unknown>>(
+    table: WritableTable,
+    values: Record<string, unknown>,
+  ): Promise<T | undefined>;
+  updateMany<T = Record<string, unknown>>(
+    table: WritableTable,
+    set: Record<string, unknown>,
+    where: WhereObject,
+  ): Promise<readonly T[]>;
+  deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
+};

package/src/tz-context.ts

@@ -0,0 +1,63 @@
+// TzContext — the type contract for ctx.tz (pure types; the factory lives in
+// @cosmicdrift/kumiko-framework, time/tz-context.ts).
+//
+// `Temporal` here is the ambient global from TypeScript's lib
+// (lib.esnext.temporal) — at runtime the framework installs the polyfill.
+
+import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
+
+// JSON form for wall-clock + TZ — see createLocatedTimestampField() in
+// engine/factories.ts. Two fields, foolproof.
+export type LocatedTimestampJson = {
+  /** Wall-clock ISO without offset, e.g. "2026-04-03T10:00:00" */
+  readonly at: string;
+  /** IANA zone, e.g. "Europe/Lisbon" */
+  readonly tz: string;
+};
+
+export type TzContext = {
+  /** Default TZ of the tenant (from tenant.timezone, default "UTC"). */
+  readonly tenant: string;
+  /** Display TZ of the current user (profile override, fallback tenant). */
+  readonly user: string;
+
+  /** Current moment as UTC instant. */
+  now(): Temporal.Instant;
+  /** Current moment as ZonedDateTime in the requested zone. */
+  nowIn(tz: string): Temporal.ZonedDateTime;
+
+  /** Today's calendar date in the requested zone. */
+  today(tz: string): Temporal.PlainDate;
+  /** Day boundaries (00:00 to 24:00 next day) as UTC instants — for DB range queries. */
+  todayRange(tz: string): { readonly start: Temporal.Instant; readonly end: Temporal.Instant };
+
+  /** Wall-clock string + IANA zone → ZonedDateTime. */
+  parse(wallClock: string, tz: string): Temporal.ZonedDateTime;
+
+  /** ZonedDateTime → UTC instant. */
+  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant;
+
+  /** ZonedDateTime → JSON pair { at, tz } (API boundary). */
+  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson;
+
+  /** JSON pair { at, tz } → ZonedDateTime (wall-clock + IANA). */
+  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
+
+  /** Geo coordinates → IANA zone via the configured GeoTzProvider.
+   *  Throws when no provider is configured (v1 default). */
+  fromCoordinates(coords: GeoCoordinates): Promise<string>;
+  /** Postal address → IANA zone via GeoTzProvider. Throws when no provider is
+   *  configured OR the provider does not support fromAddress (the offline
+   *  lat/lng provider does not). */
+  fromAddress(address: GeoAddress): Promise<string>;
+};
+
+export type TzContextOptions = {
+  /** Tenant default TZ. Default "UTC" when unset. */
+  readonly tenant?: string;
+  /** User override. Default = tenant. */
+  readonly user?: string;
+  /** Optional geo→zone adapter for ctx.tz.fromCoordinates / fromAddress.
+   *  Without a provider those methods throw. */
+  readonly geoTz?: GeoTzProvider;
+};