@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/src/search-adapter.ts

@@ -1,45 +0,0 @@
-import type { EntityId, TenantId } from "./identifiers";
-
-export type SearchAdapterConfig = {
-  searchableFields: readonly string[];
-  rankingFields?: readonly string[];
-};
-
-export type SearchDocument = {
-  entityType: string;
-  entityId: EntityId;
-  weight: number;
-  fields: Record<string, unknown>;
-};
-
-export type SearchResult = {
-  entityType: string;
-  entityId: EntityId;
-};
-
-export type SearchOptions = {
-  limit?: number;
-  filterType?: string;
-};
-
-export type SearchAdapter = {
-  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
-  // The adapter is built before the registry exists (app boot order), so it
-  // can't derive this itself. The framework hands it the registry-derived
-  // config once the registry is available; the adapter uses it to configure
-  // each tenant index lazily on that tenant's first access instead of
-  // requiring every app to call `configure` per tenant up front.
-  setDefaultConfig?(config: SearchAdapterConfig): void;
-  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
-  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
-  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
-  // Bulk variants. Default implementations loop over the single-doc methods —
-  // adapters should override when the backend supports a real batch call
-  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
-  // N sequential HTTP + waitTask round-trips to one.
-  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
-  removeBatch?(
-    tenantId: TenantId,
-    items: readonly { entityType: string; entityId: EntityId }[],
-  ): Promise<void>;
-};

package/src/secrets-types.ts

@@ -1,182 +0,0 @@
-// 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.
-//
-// Registered symbol, matching KUMIKO_*_SYMBOL in schema-table-types.ts. A
-// plain Symbol() is per-copy: two resolved copies of this package brand with
-// two different symbols, so createSecret() from one and isSecret() from the
-// other disagree — and isSecret() is the ONLY thing assertNoSecretLeak has,
-// so a false there serializes the plaintext into the response. The namespaced
-// key makes accidental user-land collision implausible; a deliberate forge
-// would only over-trigger the guard, which fails safe.
-const SecretBrand: unique symbol = Symbol.for("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

@@ -1,36 +0,0 @@
-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

@@ -1,390 +0,0 @@
-// 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);
-
-// Branded event-type string — the only route r.step.waitForEvent's `event`
-// can reach a value. A workflow's `awaits` declaration (D4,
-// workflow-resume-loop.md) is the only source of these; buildPipelineSteps
-// mints them from that declaration's raw strings when it builds the
-// closure's `awaits` binding. A raw string literal at waitForEvent.event is
-// a compile error, so a typo in the awaited key surfaces at build time
-// instead of a run that waits forever.
-export type AwaitedEventType = string & { readonly __awaitedEvent: unique symbol };
-
-// Serializable AST for r.step.waitForEvent's `match` argument. Persisted
-// verbatim into the waiting-for-event suspension payload (jsonb), so it
-// must survive a JSON round-trip — a closure cannot.
-export type EventMatchValue = string | number | boolean | null;
-
-export type EventMatchOp =
-  | { readonly kind: "eq"; readonly value: EventMatchValue }
-  | { readonly kind: "ne"; readonly value: EventMatchValue }
-  | { readonly kind: "in"; readonly values: readonly EventMatchValue[] }
-  | { readonly kind: "gt"; readonly value: number | string }
-  | { readonly kind: "gte"; readonly value: number | string }
-  | { readonly kind: "lt"; readonly value: number | string }
-  | { readonly kind: "lte"; readonly value: number | string };
-
-export type EventMatchExpr =
-  | { readonly kind: "and"; readonly nodes: readonly EventMatchExpr[] }
-  | { readonly kind: "or"; readonly nodes: readonly EventMatchExpr[] }
-  | { readonly kind: "atom"; readonly path: readonly string[]; readonly op: EventMatchOp };
-
-export type EventMatch = { readonly version: 1; readonly expr: EventMatchExpr };
-
-/**
- * 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,
-  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
-> = {
-  readonly __kind: "pipeline";
-  // Raw (unbranded) awaits map, set by defineWorkflow — absent for
-  // non-workflow pipelines (plain defineWriteHandler perform).
-  // buildPipelineSteps reads it and brands it into the closure's `awaits`
-  // binding, so every existing buildPipelineSteps caller keeps working
-  // unchanged. Deliberately typed as plain strings, NOT `TAwaits` — an
-  // extra covariant occurrence of TAwaits here (alongside its contravariant
-  // occurrence in `build`'s parameter) breaks TypeScript's contextual
-  // inference for a `stepsPipeline(...)` passed inline as `steps` (verified
-  // empirically; see fw#2513 Phase 3a).
-  readonly awaits?: Readonly<Record<string, string>>;
-  readonly build: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => 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,
-  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
-> = {
-  readonly event: WriteEvent<TPayload>;
-  readonly r: StepBuilder;
-  // Declared awaited events (D4, workflow-resume-loop.md) — the only way
-  // r.step.waitForEvent's `event` arg can reference an event type. `{}` for
-  // non-workflow pipelines and workflows without an `awaits` declaration.
-  readonly awaits: TAwaits;
-};
-
-/**
- * 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).
-  // Tenant-filtered like ctx.db; unsafeAllTenants needs escapeHatch on the handler (or systemScope).
-  readonly read: {
-    readonly findOne: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where: StepResolver<WhereObject | undefined>;
-        readonly unsafeAllTenants?: { readonly reason: string };
-      },
-    ) => StepInstance;
-    readonly findMany: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where?: StepResolver<WhereObject | undefined>;
-        readonly limit?: number;
-        readonly unsafeAllTenants?: { readonly reason: string };
-      },
-    ) => 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>;
-      // Name inside the tenant-owned secrets namespace
-      // `step-dispatcher:webhook-auth.<secret>` (secrets feature). Resolved
-      // per-tenant at dispatch time — never a global/env-scoped secret.
-      readonly auth?:
-        | { readonly kind: "bearer"; readonly secret: string }
-        | { readonly kind: "header"; readonly name: string; readonly secret: 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: AwaitedEventType;
-    readonly match?: StepResolver<EventMatch>;
-    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/tenancy-brand.ts

@@ -1,9 +0,0 @@
-// Makes `db.global()` on a "tenant" table a compile error, mirroring executor-brand.ts's
-// approach for the executor-only write path.
-export type EntityTenancy = "global" | "tenant";
-
-declare const TENANCY: unique symbol;
-
-export interface TenancyBrand<T extends EntityTenancy> {
-  readonly [TENANCY]: T;
-}