@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/env/internals.d.ts

@@ -0,0 +1,87 @@
+import * as z from "zod";
+import type { FeatureDefinition } from "../engine/types/feature.ts";
+export type KumikoEnvMeta = {
+    readonly pulumi?: {
+        /** Override the auto-derived camelCase Pulumi-config-key name. Apps
+         *  setting `pulumiPrefix: "studio"` and authoring `STUDIO_ADMIN_EMAIL`
+         *  would otherwise get `studioStudioAdminEmail` — set
+         *  `.meta({ kumiko: { pulumi: { name: "adminEmail" } } })` to drop the
+         *  duplicated prefix. */
+        readonly name?: string;
+        /** Shell expression that generates a value, e.g. `openssl rand -base64 32`.
+         *  Without this, dry-run-pulumi emits `<set-me>` as the placeholder. */
+        readonly generator?: string;
+        /** Force the `--secret` flag in `pulumi config set`. Default false. */
+        readonly secret?: boolean;
+    };
+    /** The value may be delivered as a Scaleway Key Manager ciphertext in
+     *  `<NAME>_CIPHERTEXT`. `runProdApp` decrypts it at boot when `<NAME>` itself
+     *  is unset; a set plaintext always wins. A flag, not an object: every slot
+     *  uses the same `_CIPHERTEXT` twin and one shared key (`PLATFORM_KEK_KMS_*`). */
+    readonly kms?: true;
+};
+export type EnvFieldClass = "required" | "optional" | "withDefault";
+export declare function getDefaultValue(field: z.ZodType): unknown;
+export declare function getFieldDescription(field: z.ZodType): string | undefined;
+export type EmptyShape = Record<never, never>;
+export type DeclaredEnvShape<TFeature> = TFeature extends {
+    readonly envSchema: z.ZodObject<infer TShape extends z.ZodRawShape>;
+} ? string extends keyof TShape ? EmptyShape : TShape : EmptyShape;
+export type UnionToIntersection<TUnion> = (TUnion extends unknown ? (value: TUnion) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+export type OptionalShape<TShape extends z.ZodRawShape> = {
+    [Key in keyof TShape]: z.ZodOptional<TShape[Key]>;
+};
+export type FeaturesEnvShape<TFeatures extends readonly FeatureDefinition[]> = UnionToIntersection<DeclaredEnvShape<TFeatures[number]>>;
+export type FlattenShape<TShape> = {
+    [Key in keyof TShape]: TShape[Key];
+} & {};
+export type KnownShape<TShape extends z.ZodRawShape> = string extends keyof TShape ? EmptyShape : TShape;
+/** The merged shape `composeEnvSchema` returns. With `optionalFeatures`
+ *  every feature field is typed optional: the type cannot tell which feature
+ *  a name refers to, and over-reporting `undefined` is the safe side. */
+export type ComposedEnvShape<TFeatures extends readonly FeatureDefinition[], TCore extends z.ZodRawShape, TExtend extends z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined> = Extract<FlattenShape<KnownShape<TCore> & (TOptionalFeatures extends readonly string[] ? OptionalShape<FeaturesEnvShape<TFeatures> & z.ZodRawShape> : FeaturesEnvShape<TFeatures>) & KnownShape<TExtend>>, z.ZodRawShape>;
+export type ComposeEnvSchemaOptions<TFeatures extends readonly FeatureDefinition[] = readonly FeatureDefinition[], TCore extends z.ZodRawShape = z.ZodRawShape, TExtend extends z.ZodRawShape = z.ZodRawShape, TOptionalFeatures extends readonly string[] | undefined = readonly string[] | undefined> = {
+    /** All features whose envSchemas should be merged. Bundled features type
+     *  their fragment, so passing the list inline types the merged schema. */
+    readonly features: TFeatures;
+    /** App-specific env-vars (e.g. `STUDIO_ADMIN_EMAIL`). Keys here are
+     *  tagged as source "app" in the resulting sources map. */
+    readonly extend?: z.ZodObject<TExtend>;
+    /** Feature-names whose env-vars should be auto-`.optional()`-wrapped.
+     *  Lets an app opt out of e.g. `channel-email-smtp`'s vars without
+     *  manually `.partial()`-ing each shape at the call-site. */
+    readonly optionalFeatures?: TOptionalFeatures;
+    /** Framework-core env-vars (PORT, DATABASE_URL, REDIS_URL, …) from
+     *  `@cosmicdrift/kumiko-dev-server`. Keys here are tagged as source
+     *  "framework-core" in error output. Conflict-detection runs across
+     *  core/features/extend as one merged pool — same key declared in two
+     *  layers throws KumikoBootError at compose-time. */
+    readonly core?: z.ZodObject<TCore>;
+};
+export type EnvErrorKind = "missing" | "invalid";
+export type EnvError = {
+    readonly name: string;
+    readonly kind: EnvErrorKind;
+    readonly message: string;
+    /** Declaring source-name from `composeEnvSchema`'s sources map:
+     *  feature-name, "app" from `extend`, or "framework-core" from `core`.
+     *  Populated when parseEnv received `options.sources`. Surfaced by
+     *  `KumikoBootError.format()` so operators see WHICH source wants the
+     *  missing var, not just the var name. */
+    readonly source?: string;
+    /** "Set via: pulumi config set ..." line. Computed when pulumiPrefix is
+     *  passed to parseEnv. */
+    readonly suggestion?: string;
+};
+export type ParseEnvOptions = {
+    /** From composeEnvSchema's return — enables per-var feature-source
+     *  attribution in suggestions. */
+    readonly sources?: Readonly<Record<string, string>>;
+    /** When set, error suggestions include `pulumi config set <prefix>...`. */
+    readonly pulumiPrefix?: string;
+};
+export declare function ucfirst(s: string): string;
+export type EnvFieldStatus = "set" | "unset" | "missing" | "invalid";
+export declare function camelCase(snakeShout: string): string;
+export declare function pulumiConfigKey(envName: string, field: z.ZodType | undefined, prefix: string | undefined): string;
+export declare function buildPulumiSuggestion(envName: string, field: z.ZodType, prefix: string | undefined): string | undefined;

package/dist/env/internals.js

@@ -0,0 +1,53 @@
+import * as z from "zod";
+import { zodDef, zodDescription } from "./_zod-introspect.js";
+import { readKumikoMeta } from "./index.js";
+export function getDefaultValue(field) {
+    let current = field;
+    for (let i = 0; i < 8; i++) {
+        if (current instanceof z.ZodDefault) {
+            // Zod v4: defaultValue is the raw value (v3 was a factory function).
+            // Support both shapes for forward/backward safety.
+            const raw = zodDef(current)?.defaultValue;
+            // @cast-boundary schema-walk — Zod v3 stored a thunk, v4 a raw value
+            return typeof raw === "function" ? raw() : raw;
+        }
+        const inner = zodDef(current);
+        if (inner?.innerType) {
+            current = inner.innerType;
+            continue;
+        }
+        break;
+    }
+    return undefined;
+}
+// @wrapper-known semantic-alias
+export function getFieldDescription(field) {
+    return zodDescription(field);
+}
+// --- Pulumi-suggestion ---
+export function ucfirst(s) {
+    return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
+}
+export function camelCase(snakeShout) {
+    const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
+    if (parts.length === 0)
+        return snakeShout.toLowerCase();
+    return parts[0] + parts.slice(1).map(ucfirst).join("");
+}
+export function pulumiConfigKey(envName, field, prefix) {
+    const meta = field ? readKumikoMeta(field) : {};
+    if (meta.pulumi?.name) {
+        return prefix ? prefix + ucfirst(meta.pulumi.name) : meta.pulumi.name;
+    }
+    const camel = camelCase(envName);
+    return prefix ? prefix + ucfirst(camel) : camel;
+}
+export function buildPulumiSuggestion(envName, field, prefix) {
+    if (!prefix)
+        return undefined;
+    const meta = readKumikoMeta(field);
+    const key = pulumiConfigKey(envName, field, prefix);
+    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+    return `Set via: pulumi config set${secretFlag} ${key} ${value}`;
+}

package/dist/errors/classes.js

@@ -201,14 +201,14 @@ export class InternalError extends KumikoError {
         });
     }
 }
-// A ctx.queryAsMember read ran into its statement timeout (SQLSTATE 57014). Reuses the generic
+// A ctx.dispatch.queryAsMember read ran into its statement timeout (SQLSTATE 57014). Reuses the generic
 // errors.internal i18n key: the client can do nothing but retry, and the code is for log/alert routing.
 export class MemberReadTimeoutError extends KumikoError {
     code = "member_read_timeout";
     httpStatus = 504;
     constructor(opts) {
         super({
-            message: `ctx.queryAsMember read exceeded its ${opts.timeoutMs}ms statement timeout`,
+            message: `ctx.dispatch.queryAsMember read exceeded its ${opts.timeoutMs}ms statement timeout`,
             i18nKey: "errors.internal",
             ...(opts.cause && { cause: opts.cause }),
         });

package/dist/errors/index.d.ts

@@ -1,18 +1,9 @@
-export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.ts";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.ts";
+export type { FieldIssue } from "./classes.ts";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.ts";
 export type { ErrorDocsConfig } from "./docs-url.ts";
-export { resolveErrorDocsUrl } from "./docs-url.ts";
-export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.ts";
 export { isKumikoError, KumikoError } from "./kumiko-error.ts";
-export { memberResolutionReadOnlyDenied } from "./member-resolution.ts";
-export type { AgentReason, FrameworkReason } from "./reasons.ts";
-export { AgentReasons, FrameworkReasons } from "./reasons.ts";
-export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.ts";
-export { buildErrorLog, serializeError } from "./serialize.ts";
-export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.ts";
-export { toKumikoError } from "./to-kumiko-error.ts";
-export type { InvalidTransitionDetails } from "./transition-details.ts";
-export { buildInvalidTransitionDetails } from "./transition-details.ts";
+export { FrameworkReasons } from "./reasons.ts";
+export { subjectErasedConflict } from "./subject-erased.ts";
 export type { WriteErrorInfo, WriteFailure } from "./write-error-info.ts";
-export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.ts";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, writeFailure, } from "./write-error-info.ts";
 export { validationErrorFromZod } from "./zod-bridge.ts";

package/dist/errors/index.js

@@ -1,11 +1,6 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, RecordLockedError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
-export { resolveErrorDocsUrl } from "./docs-url.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, InternalError, NotFoundError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
-export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
-export { AgentReasons, FrameworkReasons } from "./reasons.js";
-export { buildErrorLog, serializeError } from "./serialize.js";
-export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
-export { toKumikoError } from "./to-kumiko-error.js";
-export { buildInvalidTransitionDetails } from "./transition-details.js";
-export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";
+export { FrameworkReasons } from "./reasons.js";
+export { subjectErasedConflict } from "./subject-erased.js";
+export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, writeFailure, } from "./write-error-info.js";
 export { validationErrorFromZod } from "./zod-bridge.js";

package/dist/errors/member-resolution.js

@@ -3,7 +3,7 @@ import { FrameworkReasons } from "./reasons.js";
 // Lives in errors/ (not pipeline/) so db/tenant-db.ts can throw it without importing pipeline.
 export function memberResolutionReadOnlyDenied(cause) {
     return new AccessDeniedError({
-        message: "a resolved member principal (ctx.queryAsMember) cannot write or reach raw SQL — read-only",
+        message: "a resolved member principal (ctx.dispatch.queryAsMember) cannot write or reach raw SQL — read-only",
         details: { reason: FrameworkReasons.memberResolutionReadOnly },
         ...(cause instanceof Error && { cause }),
     });

package/dist/errors/reasons.d.ts

@@ -24,4 +24,3 @@ export declare const AgentReasons: {
     readonly iterationLimit: "agent.iteration_limit";
     readonly highRiskNoAlways: "agent.high_risk_no_always";
 };
-export type AgentReason = (typeof AgentReasons)[keyof typeof AgentReasons];

package/dist/errors/reasons.js

@@ -33,10 +33,10 @@ export const FrameworkReasons = {
     // Distinct from access-denied — clients should surface "feature X is
     // currently unavailable" not "you don't have permission".
     featureDisabled: "feature_disabled",
-    // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryAs/ctx.dispatch.writeAs with a
     // SYSTEM identity without an r.systemScope() feature or a declared escapeHatch.
     systemIdentitySwitchDenied: "system_identity_switch_denied",
-    // AccessDeniedError: a handler/hook called ctx.queryAs/ctx.writeAs with a
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryAs/ctx.dispatch.writeAs with a
     // non-SYSTEM identity other than its own caller (different user, tenant,
     // claims, origin or extra roles) without r.systemScope() or escapeHatch.
     identitySwitchDenied: "identity_switch_denied",
@@ -44,13 +44,13 @@ export const FrameworkReasons = {
     tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin",
     // AccessDeniedError: ctx.notify was called with `to: { tenant }` naming a tenant other than the caller's.
     notifyForeignTenantBroadcast: "notify_foreign_tenant_broadcast",
-    // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
+    // AccessDeniedError: a handler/hook called ctx.dispatch.queryProjection(..., { unsafeAllTenants: true })
     // without an r.systemScope() feature or a declared escapeHatch.
     unsafeAllTenantsDenied: "unsafe_all_tenants_denied",
-    // AccessDeniedError: ctx.queryAsMember's userId is not an active member of
+    // AccessDeniedError: ctx.dispatch.queryAsMember's userId is not an active member of
     // ctx's tenant. Deliberately generic — a caller can't probe which check failed.
     memberResolutionDenied: "member_resolution_denied",
-    // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
+    // AccessDeniedError: a query handler invoked via ctx.dispatch.queryAsMember tried to
     // write — a resolved member principal is read-only by construction.
     memberResolutionReadOnly: "member_resolution_read_only",
     // AccessDeniedError: a write under an anonymous root touched a personal-data field
@@ -58,11 +58,11 @@ export const FrameworkReasons = {
     publicIntakeRequired: "public_intake_required",
     // AccessDeniedError: the directly-dispatched entry handler performs a hard
     // delete/forget but its agent.risk resolves below "high" — delegation via
-    // ctx.write/writeAs from a lower-risk handler does not inherit the gate.
+    // ctx.dispatch.write/writeAs from a lower-risk handler does not inherit the gate.
     irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk",
     // AccessDeniedError: the directly-dispatched entry handler writes a field
     // flagged readAsInstruction: true but its agent.risk resolves below "high" —
-    // delegation via ctx.write/writeAs from a lower-risk handler does not
+    // delegation via ctx.dispatch.write/writeAs from a lower-risk handler does not
     // inherit the gate.
     instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk",
     // ConflictError: a write touched a personal-data field of a data subject whose

package/dist/errors/serialize.d.ts

@@ -14,21 +14,3 @@ export type ErrorResponseBody = {
 };
 export declare const exposesCauseDetails: () => boolean;
 export declare function serializeError(err: KumikoError, requestId?: string, errorDocs?: ErrorDocsConfig): ErrorResponseBody;
-export type ErrorLogEntry = {
-    readonly name: string;
-    readonly code: string;
-    readonly httpStatus: number;
-    readonly message: string;
-    readonly i18nKey: string;
-    readonly details?: unknown;
-    readonly stack?: string;
-    readonly cause?: CauseSnapshot;
-};
-export declare function buildErrorLog(err: KumikoError): ErrorLogEntry;
-type CauseSnapshot = {
-    readonly name: string;
-    readonly message: string;
-    readonly stack?: string;
-    readonly cause?: CauseSnapshot;
-};
-export {};

package/dist/errors/serialize.js

@@ -53,30 +53,3 @@ export function serializeError(err, requestId, errorDocs) {
         },
     };
 }
-export function buildErrorLog(err) {
-    return {
-        name: err.name,
-        code: err.code,
-        httpStatus: err.httpStatus,
-        message: err.message,
-        i18nKey: err.i18nKey,
-        ...(err.details !== undefined && { details: err.details }),
-        ...(err.stack && { stack: err.stack }),
-        ...(err.cause !== undefined && { cause: serializeCause(err.cause) }),
-    };
-}
-const MAX_CAUSE_DEPTH = 10;
-function serializeCause(cause, depth = 0) {
-    if (depth >= MAX_CAUSE_DEPTH) {
-        return { name: "CauseChainTruncated", message: `depth >= ${MAX_CAUSE_DEPTH}` };
-    }
-    if (cause instanceof Error) {
-        return {
-            name: cause.name,
-            message: cause.message,
-            ...(cause.stack && { stack: cause.stack }),
-            ...(cause.cause !== undefined && { cause: serializeCause(cause.cause, depth + 1) }),
-        };
-    }
-    return { name: "NonError", message: String(cause) };
-}

package/dist/es-ops/index.d.ts

@@ -1,4 +1,4 @@
-export { type CreateSeedMigrationContextArgs, createSeedMigrationContext, } from "./context.ts";
-export { createEsOperationsTable, type EsOperationAppliedBy, type EsOperationType, esOperationsTable, } from "./operations-schema.ts";
-export { type RunPendingSeedMigrationsArgs, type RunPendingSeedMigrationsResult, runPendingSeedMigrations, } from "./runner.ts";
-export type { SeedMembershipRow, SeedMigration, SeedMigrationContext, SeedTemplateResourceFilter, SeedTemplateResourceRow, SeedTenantRow, SeedUserRow, } from "./types.ts";
+export { createSeedMigrationContext } from "./context.ts";
+export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.ts";
+export { runPendingSeedMigrations } from "./runner.ts";
+export type { SeedMigration, SeedMigrationContext, } from "./types.ts";

package/dist/es-ops/index.js

@@ -7,6 +7,6 @@
 //   - `SeedMigration`: default export type of a seed file
 //   - `runProdApp({ seedsDir })`: the framework runs pending migrations at boot
 //   - `bunx kumiko ops seed:new|status|apply` (CLI)
-export { createSeedMigrationContext, } from "./context.js";
+export { createSeedMigrationContext } from "./context.js";
 export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.js";
-export { runPendingSeedMigrations, } from "./runner.js";
+export { runPendingSeedMigrations } from "./runner.js";

package/dist/es-ops/operations-schema.d.ts

@@ -1,5 +1,5 @@
 import { type DbConnection } from "../db/index.ts";
-export type EsOperationType = "seed-migration";
+export type EsOperationType = "seed-migration" | "stream-migration";
 export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
 export declare const esOperationsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createEsOperationsTable(db: DbConnection): Promise<void>;

package/dist/es-ops/types.d.ts

@@ -30,10 +30,9 @@ export type SeedUserRow = {
 /** Read shape of a membership entry exposed to seed helpers.
  * Distinguishes two tenantIds: the logical one from the read projection
  * (`tenantId`) and the physical one from the aggregate stream
- * (`streamTenantId`). They differ when the aggregate was created by an
- * executor with a different tenantId (for example,
- * seedTenantMembership-by=systemAdmin), which is a typical
- * publicstatus driver use case. */
+ * (`streamTenantId`). They only differ for memberships written by an admin
+ * of another tenant before `backfillTenantStreamTenants` ran; afterwards
+ * `streamTenantId = tenantId`. */
 export type SeedMembershipRow = {
     readonly userId: string;
     /** Payload tenant from `read_tenant_memberships.tenant_id`; it is used
@@ -74,7 +73,7 @@ export type SeedMigrationContext = {
      * user executes it while bypassing access checks. Events have
      * inserted_by_id = SYSTEM_TENANT_ID-user, making them auditable.
      *
-     * The type signature follows existing ctx.writeAs (with payload as unknown).
+     * The type signature follows existing ctx.dispatch.writeAs (with payload as unknown).
      * Type safety comes from handler-specific wrappers in the caller; do not
      * attempt generic magic.
      *

package/dist/event-store/admin-api-internals.d.ts

@@ -0,0 +1,14 @@
+import type { TenantId } from "../engine/types/index.ts";
+import type { EventMetadata } from "./event-store.ts";
+export type RawEventToAppend = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: TenantId;
+    readonly expectedVersion: number;
+    readonly type: string;
+    readonly eventVersion?: number;
+    readonly payload: Record<string, unknown>;
+    readonly metadata: EventMetadata;
+    readonly createdAt: Temporal.Instant;
+    readonly createdBy: string;
+};

package/dist/event-store/admin-api-internals.js

@@ -0,0 +1 @@
+export {};

package/dist/event-store/admin-api.d.ts

@@ -1,18 +1,5 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { DbRunner } from "../db/index.ts";
-import type { TenantId } from "../engine/types/index.ts";
-import type { EventMetadata } from "./event-store.ts";
-export type RawEventToAppend = {
-    readonly aggregateId: string;
-    readonly aggregateType: string;
-    readonly tenantId: TenantId;
-    readonly expectedVersion: number;
-    readonly type: string;
-    readonly eventVersion?: number;
-    readonly payload: Record<string, unknown>;
-    readonly metadata: EventMetadata;
-    readonly createdAt: Temporal.Instant;
-    readonly createdBy: string;
-};
+import type { RawEventToAppend } from "./admin-api-internals.ts";
 export declare function appendRaw(runner: DbRunner, event: RawEventToAppend): Promise<void>;
 export declare function appendRawBatch(runner: DbRunner, events: readonly RawEventToAppend[]): Promise<void>;

package/dist/event-store/admin-api.js

@@ -10,7 +10,9 @@ import { instantToTimestamptzParam } from "../db/driver-value-preparation.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
+import { runInSystemRowLevelSecurityScope } from "../db/row-level-security-scope.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
+import { inEventStreamScope } from "./stream-scope.js";
 function mapEventUniqueViolation(e, event) {
     if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {
         return new IdempotentAppendConflictError(event.tenantId, event.metadata.idempotencyKey);
@@ -26,7 +28,7 @@ export async function appendRaw(runner, event) {
     try {
         // See db/queries/event-store.ts's claimXactId — gap-finality needs a
         // real xact id assigned before this holder's insert.
-        await runAtomicEventWrite(runner, async (tx) => {
+        await inEventStreamScope(event.tenantId, () => runAtomicEventWrite(runner, async (tx) => {
             await claimXactId(tx);
             if (event.expectedVersion === 0) {
                 await insertRawFirst(tx, event, newVersion, eventVersion);
@@ -34,7 +36,7 @@ export async function appendRaw(runner, event) {
             else {
                 await insertRawSubsequent(tx, event, newVersion, eventVersion);
             }
-        });
+        }));
     }
     catch (e) {
         if (isUniqueViolation(e)) {
@@ -81,8 +83,11 @@ export async function appendRawBatch(runner, events) {
     if (!firstEvent)
         return;
     verifyContiguousWithinBatch(events);
-    await verifyPredecessors(runner, events);
-    await verifyNoDuplicates(runner, events);
+    // A batch may span tenants (replay, transfer), so its pre-flight reads and the insert are system scoped.
+    await runInSystemRowLevelSecurityScope("raw event batch append writes events for arbitrary tenants", async () => {
+        await verifyPredecessors(runner, events);
+        await verifyNoDuplicates(runner, events);
+    });
     const params = [];
     const valuesClauses = events.map((e) => {
         const newVersion = e.expectedVersion + 1;
@@ -92,10 +97,10 @@ export async function appendRawBatch(runner, events) {
         return `($${baseIdx + 1}::uuid, $${baseIdx + 2}, $${baseIdx + 3}::uuid, $${baseIdx + 4}, $${baseIdx + 5}, $${baseIdx + 6}, $${baseIdx + 7}::jsonb, $${baseIdx + 8}::jsonb, $${baseIdx + 9}::timestamptz, $${baseIdx + 10})`;
     });
     try {
-        await runAtomicEventWrite(runner, async (tx) => {
+        await runInSystemRowLevelSecurityScope("raw event batch append refreshes stream state across tenants", () => runAtomicEventWrite(runner, async (tx) => {
             await claimXactId(tx);
             await insertRawEventBatch(tx, valuesClauses.join(", "), params);
-        });
+        }));
     }
     catch (e) {
         if (isUniqueViolation(e)) {

package/dist/event-store/archive.js

@@ -3,7 +3,7 @@ import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/d
 import { upsertArchivedStream } from "../db/queries/event-store.js";
 import { deleteMany, fetchOne } from "../db/query.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../db/table-push.js";
+import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
 // Marten-aligned stream archival. Archived streams become read-only: fresh
 // appendEvent on an archived aggregate throws, and loadAggregate returns
 // an empty slice unless the caller passes { includeArchived: true }.
@@ -24,8 +24,10 @@ export const archivedStreamsTable = pgTable("kumiko_archived_streams", {
 // guard:dup-ok — intentionale Parallele zu createSnapshotsTable; verschiedene Tabellen-Schemas by design
 export async function createArchivedStreamsTable(db) {
     // skip: table already exists — idempotent boot + test-setup call
-    if (await tableExists(db, "public.kumiko_archived_streams"))
+    if (await tableExists(db, "public.kumiko_archived_streams")) {
+        await ensureTableRowLevelSecurity(db, archivedStreamsTable);
         return;
+    }
     await unsafePushTables(db, { kumikoArchivedStreams: archivedStreamsTable });
 }
 // Mark a stream as archived. Idempotent — re-archiving (same tenant +

package/dist/event-store/errors.js

@@ -55,11 +55,11 @@ export class SeedTimeOrderError extends Error {
         this.predecessorCreatedAt = predecessorCreatedAt;
     }
 }
-// Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
+// Thrown when ctx.events.append targets an archived stream. Archived aggregates
 // are read-only — restoreStream() makes them writable again. The archive
 // state is not carried on the events themselves; it lives on the sparse
 // kumiko_archived_streams table. Handlers that need to branch on archive
-// state should call ctx.isStreamArchived(id) first.
+// state should call ctx.events.isArchived(id) first.
 export class ArchivedStreamError extends Error {
     tenantId;
     aggregateId;

package/dist/event-store/event-store.d.ts

@@ -19,6 +19,7 @@ export declare function append(db: DbRunner, event: EventToAppend): Promise<Stor
 export declare function loadAggregate(db: DbRunner, aggregateId: string, tenantId: TenantId, options?: {
     readonly includeArchived?: boolean;
     readonly aggregateType?: string;
+    readonly atVersion?: number;
 }): Promise<readonly StoredEvent[]>;
 export declare function loadAggregateForWriting(db: DbRunner, aggregateId: string, tenantId: TenantId, options: {
     readonly aggregateType: string;