@cosmicdrift/kumiko-framework 0.352.0 → 0.354.0

package/dist/engine/transfer-adjacency.d.ts

@@ -0,0 +1,24 @@
+import type { EntityDefinition } from "./types/index.js";
+export declare const MAX_TRANSFER_DEPTH = 5;
+export type TransferEdgeLink = {
+    readonly kind: "parentRef";
+    readonly typeField: string;
+    readonly idField: string;
+} | {
+    readonly kind: "reference";
+    readonly field: string;
+};
+export type TransferEdge = {
+    readonly entityName: string;
+    readonly entity: EntityDefinition;
+    /** The already-resolved type this edge hangs off — its moved row ids are
+     *  the parent ids the mover matches this edge's rows against. */
+    readonly parentEntityName: string;
+    readonly link: TransferEdgeLink;
+};
+/** Outgoing edges per type: keyed by the type an edge hangs off, so the mover
+ *  can ask "what hangs off the rows I just moved" for any type it reaches, at
+ *  any depth, as often as it reaches it. */
+export type TransferAdjacency = ReadonlyMap<string, readonly TransferEdge[]>;
+export declare function resolveTransferAdjacency(entities: ReadonlyMap<string, EntityDefinition>, rootEntityType?: string): TransferAdjacency;
+export declare function findOverDeepTransferChain(adjacency: TransferAdjacency, onPath: readonly string[]): readonly string[] | undefined;

package/dist/engine/transfer-adjacency.js

@@ -0,0 +1,107 @@
+import { parseRefTargetEntityName } from "./parse-ref-target.js";
+// The single definition of the limit. It lives here rather than next to the
+// resolver in bundled-features because the dependency only runs that way:
+// bundled-features imports from the framework, never the reverse.
+//
+// Guards against a schema whose reference edges span more levels than anyone
+// intended — a runaway graph would move rows an operator never associated with
+// the handover. Deliberately a constant and not per-feature config: the limit
+// is a safety net, and a configurable one gets raised by whoever trips it
+// instead of prompting them to reconsider their graph.
+export const MAX_TRANSFER_DEPTH = 5;
+// A `multiple` reference stores a jsonb array rather than a single id column,
+// which the mover's `= ANY($ids)` match cannot address. The boot validator
+// (boot-validator/transfer-graph.ts) rejects that combination on transferable
+// entities, so skipping it here can only ever hit an entity that is not
+// transferable — never a silent partial move.
+// `handover: "stay"` is the declared opt-out: the reference crosses the tenant
+// boundary after a handover on purpose, so the edge is not walked.
+function referenceEdgesFrom(entityName, entity) {
+    const edges = [];
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+        if (field.type !== "reference")
+            continue;
+        if (field.multiple === true)
+            continue;
+        if (field.handover === "stay")
+            continue;
+        edges.push({
+            entityName,
+            entity,
+            parentEntityName: parseRefTargetEntityName(field.entity),
+            link: { kind: "reference", field: fieldName },
+        });
+    }
+    return edges;
+}
+// A parentRef names the types it accepts; without `allowedTypes` it accepts
+// any of them, so the edge is recorded against every registered type.
+function parentRefEdgesFrom(entityName, entity, allEntityNames) {
+    const parentRef = entity.parentRef;
+    if (!parentRef)
+        return [];
+    const link = {
+        kind: "parentRef",
+        typeField: parentRef.entityTypeField,
+        idField: parentRef.entityIdField,
+    };
+    return (parentRef.allowedTypes ?? allEntityNames).map((parentEntityName) => ({
+        entityName,
+        entity,
+        parentEntityName,
+        link,
+    }));
+}
+// The one definition of the transfer graph, shared by the boot validator
+// (depth limit) and the tenant-handover mover (traversal), so the limit that is
+// checked at boot is measured over exactly the edges that are walked at claim
+// time. Edges are kept for every entity, transferable or not: a
+// non-transferable node in the middle of a chain is still a hop the mover
+// takes before it fails the claim.
+//
+// A type can legitimately be reached by more than one edge — `note.vehicleId`
+// and `note.campaignId` are distinct, and collapsing them by entity name would
+// leave one edge's rows behind, the silent partial move #3088 exists to end.
+export function resolveTransferAdjacency(entities, rootEntityType) {
+    const allEntityNames = [...entities.keys()];
+    const byParent = new Map();
+    for (const [entityName, entity] of entities) {
+        // skip: the root is never collected as someone else's descendant. A self
+        // reference would otherwise drag unrelated rows of the root's own type
+        // across the tenant boundary along with the one that was claimed.
+        if (entityName === rootEntityType)
+            continue;
+        for (const edge of [
+            ...parentRefEdgesFrom(entityName, entity, allEntityNames),
+            ...referenceEdgesFrom(entityName, entity),
+        ]) {
+            const edges = byParent.get(edge.parentEntityName) ?? [];
+            edges.push(edge);
+            byParent.set(edge.parentEntityName, edges);
+        }
+    }
+    return byParent;
+}
+// `onPath` counts NODES, the limit counts EDGES: a chain of exactly
+// MAX_TRANSFER_DEPTH edges holds MAX_TRANSFER_DEPTH + 1 entities, and the
+// mover runs MAX_TRANSFER_DEPTH rounds of one hop each, so it still walks that
+// chain whole. Returns the first path that exceeds the limit.
+export function findOverDeepTransferChain(adjacency, onPath) {
+    if (onPath.length > MAX_TRANSFER_DEPTH + 1)
+        return onPath;
+    const startName = onPath[onPath.length - 1];
+    if (startName === undefined)
+        return undefined;
+    for (const edge of adjacency.get(startName) ?? []) {
+        // skip: a cycle revisits a type already on this path, and schema depth
+        // cannot measure how far it actually runs — that depends on the rows, not
+        // the declaration. The mover carries this one instead, failing with
+        // `transfer_graph_too_deep` when its rounds run out (#3131).
+        if (onPath.includes(edge.entityName))
+            continue;
+        const deeper = findOverDeepTransferChain(adjacency, [...onPath, edge.entityName]);
+        if (deeper !== undefined)
+            return deeper;
+    }
+    return undefined;
+}

package/dist/engine/where-rule-lint.js

@@ -17,9 +17,9 @@ const SELF_COMPARISON_RE = new RegExp(`(${QUALIFIED_SRC})\\s*(?<![!<>=])=(?!=)\\
 const QUALIFIED_PARSE_RE = new RegExp(`^(${IDENT_SRC})(?:\\.(${IDENT_SRC}))?$`);
 // Resolve the SQL column names a table exposes, so the lint can tell a
 // real column reference apart from a table alias / function name / SQL
-// keyword. Returns an empty set when nothing is derivable; the column-aware
-// check then finds no bare column and is effectively skipped (only the
-// self-comparison check still applies).
+// keyword. Returns an empty set when nothing is derivable; callers that need
+// the column-aware check must treat that as "unknown" (see
+// assertQualifiedWhereFragment, which fails closed on it).
 export function tableColumnSqlNames(table) {
     if (table === null || typeof table !== "object")
         return new Set();
@@ -182,6 +182,9 @@ export function assertQualifiedWhereFragment(sqlText, columnSqlNames, scope) {
     // the fail-open shape this lint targets is impossible here.
     if (!/\bSELECT\b/i.test(cleaned))
         return;
+    if (columnSqlNames.size === 0) {
+        throw new Error(`[Kumiko Ownership] ${scope}: cannot verify where-rule SQL containing a subquery — the table's column set is unknown, so unqualified column references cannot be detected.`);
+    }
     const unqualified = findUnqualifiedColumnReference(cleaned, columnSqlNames);
     if (unqualified !== null) {
         throw new Error(`[Kumiko Ownership] ${scope}: where-rule SQL references column "${unqualified}" unqualified inside a subquery. Postgres binds an unqualified name to the innermost table first, which silently turns the ownership predicate into a tautology (fail-open). Qualify it with the outer table, e.g. \`\${ctx.tableName}.${unqualified}\`.`);

package/dist/entrypoint/index.d.ts

@@ -30,6 +30,8 @@ type JobsBlock = {
     readonly onJobStart?: JobRunnerOptions["onJobStart"];
     readonly onJobComplete?: JobRunnerOptions["onJobComplete"];
     readonly onJobFailed?: JobRunnerOptions["onJobFailed"];
+    readonly onJobQueued?: JobRunnerOptions["onJobQueued"];
+    readonly onJobDropped?: JobRunnerOptions["onJobDropped"];
 };
 export type ApiEntrypointOptions = BaseEntrypointOptions & {
     readonly auth?: AuthRoutesConfig;

package/dist/entrypoint/index.js

@@ -176,6 +176,8 @@ function buildJobRunnerWithHook(registry, context, jobs, consumerLane, lifecycle
         onJobStart: jobs.onJobStart,
         onJobComplete: jobs.onJobComplete,
         onJobFailed: jobs.onJobFailed,
+        onJobQueued: jobs.onJobQueued,
+        onJobDropped: jobs.onJobDropped,
     });
     lifecycle.registerShutdownHook(hookName, async () => {
         await jobRunner.stop();

package/dist/env/index.d.ts

@@ -88,6 +88,10 @@ export type ParseEnvOptions = {
     /** When set, error suggestions include `pulumi config set <prefix>...`. */
     readonly pulumiPrefix?: string;
 };
+/** Validates `env` against `schema` and throws KumikoBootError on any issue.
+ *  A `kms: true` field delivered only as `<NAME>_CIPHERTEXT` passes validation but
+ *  is `undefined` in the result despite its `string` type — it is only set once
+ *  the boot-time decrypt (resolvePlatformKeks) has run. */
 export declare function parseEnv<S extends z.ZodObject<z.ZodRawShape>>(schema: S, env: Record<string, string | undefined>, options?: ParseEnvOptions): z.infer<S>;
 /** Dry-Run-Gegenstück zu parseEnv (KUMIKO_DRY_RUN_ENV-Pfad): parst jedes
  *  Feld einzeln und liefert ein ehrliches Partial — vorhandene Werte kommen

package/dist/env/index.js

@@ -135,6 +135,42 @@ export function withOptionalEnvKeys(schema, keys) {
     }
     return Object.keys(relaxed).length === 0 ? schema : schema.safeExtend(relaxed);
 }
+// The very same field instance is a shared fragment (several features read one
+// variable), not a conflict; the first declaring feature owns it.
+function isSharedFeatureFragment(featureFields, key, field) {
+    return featureFields.get(key) === field;
+}
+// Required beats optional, independent of feature order: a feature outside
+// optionalFeatures must not end up with a silently optional slot.
+function keepStrictestOfSharedFragment(merged, key, field, declaringFeatureIsOptional) {
+    if (!declaringFeatureIsOptional)
+        merged[key] = field;
+}
+function envVarConflictError(key, firstOwner, secondOwner) {
+    return new KumikoBootError([
+        {
+            name: key,
+            kind: "invalid",
+            message: `env-var conflict: "${key}" declared by both ` +
+                `"${firstOwner}" and "${secondOwner}" — pick one owner.`,
+        },
+    ]);
+}
+// The twin follows from the slot, so a versioned family (`…_V2`) needs no
+// second declaration. An already declared twin (apps that predate this) stays.
+function declareKmsCiphertextTwins(merged, sources, kmsFields) {
+    for (const { name, source } of kmsFields) {
+        const twin = `${name}_CIPHERTEXT`;
+        if (merged[twin] !== undefined)
+            continue;
+        merged[twin] = z
+            .string()
+            .min(1)
+            .optional()
+            .describe(`Key-Manager ciphertext of ${name}; used when ${name} is unset.`);
+        sources[twin] = source;
+    }
+}
 export function composeEnvSchema(options) {
     const optionalSet = new Set(options.optionalFeatures ?? []);
     const merged = {};
@@ -157,22 +193,20 @@ export function composeEnvSchema(options) {
             noteKms(key, field, "framework-core");
         }
     }
+    const featureFields = new Map();
     for (const feature of options.features) {
         if (!feature.envSchema)
             continue;
-        const shape = zodShape(feature.envSchema);
         const wrap = optionalSet.has(feature.name);
-        for (const [key, field] of Object.entries(shape)) {
+        for (const [key, field] of Object.entries(zodShape(feature.envSchema))) {
             if (merged[key] !== undefined) {
-                throw new KumikoBootError([
-                    {
-                        name: key,
-                        kind: "invalid",
-                        message: `env-var conflict: "${key}" declared by both ` +
-                            `"${sources[key]}" and "${feature.name}" — pick one owner.`,
-                    },
-                ]);
+                if (!isSharedFeatureFragment(featureFields, key, field)) {
+                    throw envVarConflictError(key, sources[key], feature.name);
+                }
+                keepStrictestOfSharedFragment(merged, key, field, wrap);
+                continue;
             }
+            featureFields.set(key, field);
             merged[key] = wrap ? optionalKeepingKmsMeta(field) : field;
             sources[key] = feature.name;
             noteKms(key, field, feature.name);
@@ -195,19 +229,7 @@ export function composeEnvSchema(options) {
             noteKms(key, field, "app");
         }
     }
-    // The twin follows from the slot, so a versioned family (`…_V2`) needs no
-    // second declaration. An already declared twin (apps that predate this) stays.
-    for (const { name, source } of kmsFields) {
-        const twin = `${name}_CIPHERTEXT`;
-        if (merged[twin] !== undefined)
-            continue;
-        merged[twin] = z
-            .string()
-            .min(1)
-            .optional()
-            .describe(`Key-Manager ciphertext of ${name}; used when ${name} is unset.`);
-        sources[twin] = source;
-    }
+    declareKmsCiphertextTwins(merged, sources, kmsFields);
     return {
         schema: z.object(merged),
         sources,
@@ -259,6 +281,10 @@ function safeParseReportingThrows(schema, input) {
         ]);
     }
 }
+/** Validates `env` against `schema` and throws KumikoBootError on any issue.
+ *  A `kms: true` field delivered only as `<NAME>_CIPHERTEXT` passes validation but
+ *  is `undefined` in the result despite its `string` type — it is only set once
+ *  the boot-time decrypt (resolvePlatformKeks) has run. */
 export function parseEnv(schema, env, options = {}) {
     // Filter undefined values to keep Zod's required-vs-invalid signal clean.
     // (process.env returns string|undefined; passing undefined would parse

package/dist/errors/classes.d.ts

@@ -98,6 +98,14 @@ export declare class InternalError extends KumikoError {
     readonly httpStatus = 500;
     constructor(opts?: Pick<ErrorOpts, "message" | "i18nKey" | "i18nParams" | "details" | "cause">);
 }
+export declare class MemberReadTimeoutError extends KumikoError {
+    readonly code = "member_read_timeout";
+    readonly httpStatus = 504;
+    constructor(opts: {
+        readonly timeoutMs: number;
+        readonly cause?: Error;
+    });
+}
 export type RateLimitDetails = {
     readonly bucket: string;
     readonly limit: number;

package/dist/errors/classes.js

@@ -189,6 +189,19 @@ export class InternalError extends KumikoError {
         });
     }
 }
+// A ctx.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`,
+            i18nKey: "errors.internal",
+            ...(opts.cause && { cause: opts.cause }),
+        });
+    }
+}
 export class RateLimitError extends KumikoError {
     code = "rate_limited";
     httpStatus = 429;

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export type { ErrorDocsConfig } from "./docs-url.js";
 export { resolveErrorDocsUrl } from "./docs-url.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
@@ -9,6 +9,7 @@ export type { AgentReason, FrameworkReason } from "./reasons.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
+export { subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export type { InvalidTransitionDetails } from "./transition-details.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";

package/dist/errors/index.js

@@ -1,9 +1,10 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, MemberReadTimeoutError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { resolveErrorDocsUrl } from "./docs-url.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 { 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";

package/dist/errors/reasons.d.ts

@@ -12,6 +12,7 @@ export declare const FrameworkReasons: {
     readonly publicIntakeRequired: "public_intake_required";
     readonly irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk";
     readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
+    readonly subjectErased: "subject_erased";
 };
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
 export declare const AgentReasons: {

package/dist/errors/reasons.js

@@ -61,6 +61,9 @@ export const FrameworkReasons = {
     // delegation via ctx.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
+    // key was erased (crypto-shredding); the subject can no longer receive data.
+    subjectErased: "subject_erased",
 };
 // Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
 // sister catalog to FrameworkReasons instead of extending it — see the

package/dist/errors/subject-erased.d.ts

@@ -0,0 +1,2 @@
+import { ConflictError } from "./classes.js";
+export declare function subjectErasedConflict(cause?: unknown): ConflictError;

package/dist/errors/subject-erased.js

@@ -0,0 +1,9 @@
+import { ConflictError } from "./classes.js";
+import { FrameworkReasons } from "./reasons.js";
+export function subjectErasedConflict(cause) {
+    return new ConflictError({
+        message: "the data subject was erased — its personal data can no longer be written",
+        details: { reason: FrameworkReasons.subjectErased },
+        ...(cause instanceof Error && { cause }),
+    });
+}

package/dist/es-ops/context.js

@@ -6,6 +6,7 @@
 // SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
 // config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
 // → audit-fähig.
+import { configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto/index.js";
 import { selectAllTenants, selectMembershipsOfUser, selectTemplateResources, selectUserByEmail, } from "../db/queries/seed-context.js";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
 import { parseStringArrayJson } from "../utils/parse-string-array-json.js";
@@ -63,7 +64,24 @@ export function createSeedMigrationContext(args) {
         },
         findTenants: async () => {
             const rows = await selectAllTenants(args.dbRunner);
-            return rows.map((r) => ({ id: r.id, name: r.name, tenantKey: r.tenant_key }));
+            const kms = configuredPiiSubjectKms();
+            // Sequential on purpose: each decrypt borrows from the KMS adapter's small pool.
+            const tenants = [];
+            for (const r of rows) {
+                // tenant.name is ciphertext at rest under an active KMS
+                const decrypted = kms
+                    ? await decryptPiiFieldValues({ name: r.name }, ["name"], kms, {
+                        requestId: "es-ops:find-tenants",
+                    })
+                    : { name: r.name };
+                const name = decrypted["name"];
+                tenants.push({
+                    id: r.id,
+                    name: typeof name === "string" ? name : r.name,
+                    tenantKey: r.tenant_key,
+                });
+            }
+            return tenants;
         },
         findTemplateResources: async (filter) => {
             const rows = await selectTemplateResources(args.dbRunner, {

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

@@ -8,7 +8,7 @@
 // Allowlist: samples/*/migration/, scripts/migrations/, die Definition
 // selbst, das Guard-Script selbst.
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId } from "../db/queries/event-store.js";
+import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
 function mapEventUniqueViolation(e, event) {
@@ -26,13 +26,15 @@ 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 claimXactId(runner);
-        if (event.expectedVersion === 0) {
-            await insertRawFirst(runner, event, newVersion, eventVersion);
-        }
-        else {
-            await insertRawSubsequent(runner, event, newVersion, eventVersion);
-        }
+        await runAtomicEventWrite(runner, async (tx) => {
+            await claimXactId(tx);
+            if (event.expectedVersion === 0) {
+                await insertRawFirst(tx, event, newVersion, eventVersion);
+            }
+            else {
+                await insertRawSubsequent(tx, event, newVersion, eventVersion);
+            }
+        });
     }
     catch (e) {
         if (isUniqueViolation(e)) {
@@ -90,8 +92,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 claimXactId(runner);
-        await insertRawEventBatch(runner, valuesClauses.join(", "), params);
+        await runAtomicEventWrite(runner, async (tx) => {
+            await claimXactId(tx);
+            await insertRawEventBatch(tx, valuesClauses.join(", "), params);
+        });
     }
     catch (e) {
         if (isUniqueViolation(e)) {

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

@@ -4,7 +4,7 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId, insertSubsequentEventRow, notifyPgChannel, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, } from "../db/queries/event-store.js";
+import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, } from "../db/queries/event-store.js";
 import { insertOne, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
@@ -50,14 +50,16 @@ export async function append(db, event) {
     const newVersion = toStore.expectedVersion + 1;
     const eventVersion = toStore.eventVersion ?? 1;
     try {
-        await claimXactId(db);
-        const row = toStore.expectedVersion === 0
-            ? await insertFirstEvent(db, toStore, newVersion, eventVersion, seedCreatedAt)
-            : await insertSubsequentEvent(db, toStore, newVersion, eventVersion, seedCreatedAt);
-        // NOTIFY after the INSERT: outside a transaction each statement commits
-        // on its own, so a NOTIFY sent first would wake the dispatcher before
-        // the row exists.
-        await notifyPgChannel(db, EVENTS_PUBSUB_CHANNEL);
+        const row = await runAtomicEventWrite(db, async (runner) => {
+            await claimXactId(runner);
+            const inserted = toStore.expectedVersion === 0
+                ? await insertFirstEvent(runner, toStore, newVersion, eventVersion, seedCreatedAt)
+                : await insertSubsequentEvent(runner, toStore, newVersion, eventVersion, seedCreatedAt);
+            // NOTIFY after the INSERT and inside the same transaction: PG delivers it on
+            // commit, so the dispatcher cannot wake before the row is visible.
+            await notifyPgChannel(runner, EVENTS_PUBSUB_CHANNEL);
+            return inserted;
+        });
         return buildStoredEvent(toStore, newVersion, eventVersion, row);
     }
     catch (e) {

package/dist/event-store/events-schema.js

@@ -1,7 +1,7 @@
 // sql now comes from native dialect
 import { bigserial, index, instant, integer, jsonb, table as pgTable, sql, text, uniqueIndex, uuid, } from "../db/dialect.js";
 import { tableExists } from "../db/index.js";
-import { ensureIdempotencyKeyIndex } from "../db/queries/event-store.js";
+import { ensureIdempotencyKeyIndex, ensureMembershipPayloadTenantIndex, } from "../db/queries/event-store.js";
 import { unsafePushTables } from "../stack/index.js";
 import { createArchivedStreamsTable } from "./archive.js";
 import { createSnapshotsTable } from "./snapshot.js";
@@ -61,6 +61,7 @@ export async function createEventsTable(db) {
     // that predate the idempotency-key index get healed the same way
     // ensureSnapshotVersionColumn heals kumiko_snapshots.
     await ensureIdempotencyKeyIndex(db);
+    await ensureMembershipPayloadTenantIndex(db);
     await createArchivedStreamsTable(db);
     await createSnapshotsTable(db);
 }

package/dist/files/file-handle.d.ts

@@ -2,6 +2,6 @@ import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-han
 import type { FileStorageProvider } from "./types.js";
 export type { FileContext, FileHandle };
 export declare function createFileHandle(key: string, getProvider: () => Promise<FileStorageProvider>): FileHandle;
-export declare function createFileContext(resolve: () => Promise<FileStorageProvider>): FileContext;
+export declare function createFileContext(resolve: () => Promise<FileStorageProvider>, tenantId?: string): FileContext;
 export declare function deriveKey(key: string, suffix: string): string;
 export declare function storageKeyStemPrefix(key: string): string;

package/dist/files/file-handle.js

@@ -7,8 +7,10 @@
 // the bytes, and big files stay in the storage layer where they belong.
 //
 // `derive(suffix)` is the primitive for thumbnail/variant keys: it inserts a
-// suffix before the file extension — `foo/bar.jpg` + `"medium"` →
-// `foo/bar.medium.jpg`. Stable, reversible, no extra lookup tables.
+// suffix before the file extension — `foo/bar.jpg` + `"medium-<16 hex>"` →
+// `foo/bar.medium-<16 hex>.jpg`. The suffix must be a `variantSuffix(...)` so
+// the erasure sweep recognizes it. Stable, reversible, no extra lookup tables.
+import { isDerivativeSuffix } from "../derivatives/variant-key.js";
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method
 // actually does I/O, never on every request that merely builds a ctx.
@@ -19,7 +21,15 @@ export function createFileHandle(key, getProvider) {
         write: async (data, mimeType) => (await getProvider()).write(key, data, mimeType),
         delete: async () => (await getProvider()).delete(key),
         exists: async () => (await getProvider()).exists(key),
-        derive: (suffix) => createFileHandle(deriveKey(key, suffix), getProvider),
+        derive: (suffix) => {
+            // A suffix outside the derivative grammar would write a key that the
+            // forget/tenant-destroy sweep (isDerivativeKeyOf) can never recognize,
+            // so the binary would survive erasure.
+            if (!isDerivativeSuffix(suffix)) {
+                throw new Error(`FileHandle.derive: suffix "${suffix}" must be <name>-<16 hex chars>; build it with variantSuffix(name, spec)`);
+            }
+            return createFileHandle(deriveKey(key, suffix), getProvider);
+        },
     };
 }
 // `resolve` is a tenant-bound thunk (the caller binds the tenant). The result
@@ -27,15 +37,29 @@ export function createFileHandle(key, getProvider) {
 // produces — never a process-global cache, since each FileContext is bound to a
 // single request/event tenant; sharing would leak one tenant's provider (and
 // its bucket/credentials) to another.
-export function createFileContext(resolve) {
+//
+// With `tenantId`, `ref` and `list` only accept keys/prefixes inside `${tenantId}/` —
+// the key space is the isolation boundary in a store shared by several tenants, and
+// a request-derived key or prefix (or "") would otherwise reach every tenant's keys.
+export function createFileContext(resolve, tenantId) {
     let cached;
     const getProvider = () => {
         cached ??= resolve();
         return cached;
     };
     return {
-        ref: (key) => createFileHandle(key, getProvider),
-        list: async (prefix) => (await getProvider()).list(prefix),
+        ref: (key) => {
+            if (tenantId !== undefined && !key.startsWith(`${tenantId}/`)) {
+                throw new Error(`FileContext.ref: key must start with "${tenantId}/"`);
+            }
+            return createFileHandle(key, getProvider);
+        },
+        list: async (prefix) => {
+            if (tenantId !== undefined && !prefix.startsWith(`${tenantId}/`)) {
+                throw new Error(`FileContext.list: prefix must start with "${tenantId}/"`);
+            }
+            return (await getProvider()).list(prefix);
+        },
     };
 }
 // Splits a key into the part before the last dot of its last path segment