@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/observability/redis-wrapper.js

@@ -0,0 +1,121 @@
+// List of Redis commands we want to trace. Everything else (connection
+// methods like `on`, `off`, `disconnect`, `duplicate`, plus pipeline/multi)
+// falls through unwrapped. Keeping the list explicit avoids accidentally
+// wrapping things that aren't commands — `connect` is a Promise, `on` is
+// a listener registration — and keeps hot paths cheap.
+const TRACKED_COMMANDS = new Set([
+    // Strings / keys
+    "get",
+    "set",
+    "del",
+    "exists",
+    "expire",
+    "ttl",
+    "incr",
+    "decr",
+    "keys",
+    "scan",
+    "mget",
+    "mset",
+    // Hashes
+    "hget",
+    "hset",
+    "hmget",
+    "hmset",
+    "hgetall",
+    "hdel",
+    "hexists",
+    // Lists
+    "lpush",
+    "rpush",
+    "lpop",
+    "rpop",
+    "llen",
+    "lrange",
+    // Sets
+    "sadd",
+    "srem",
+    "smembers",
+    "sismember",
+    // Sorted sets
+    "zadd",
+    "zrange",
+    "zrem",
+    "zrangebyscore",
+    // Streams
+    "xadd",
+    "xread",
+    "xreadgroup",
+    "xack",
+    "xlen",
+    "xgroup",
+    "xdel",
+    "xrange",
+    "xpending",
+    // Pub/Sub
+    "publish",
+    "subscribe",
+    "unsubscribe",
+    "psubscribe",
+    "punsubscribe",
+    // Scripting
+    "eval",
+    "evalsha",
+]);
+// Extract a redaction-safe key pattern from the first command argument.
+// Actual keys often include user-generated fragments (ids, session tokens)
+// that shouldn't leak into traces — we replace everything after the second
+// `:` segment with `*`. Known namespace conventions (colon-separated) keep
+// enough signal for grouping without leaking values.
+function extractKeyPattern(arg) {
+    if (typeof arg !== "string")
+        return undefined;
+    const parts = arg.split(":");
+    if (parts.length <= 2)
+        return arg;
+    return `${parts.slice(0, 2).join(":")}:*`;
+}
+// Wrap an ioredis client in an observability-aware proxy. Traced commands
+// emit `redis.cmd` spans; everything else is passed through so pipeline,
+// transaction, and connection APIs keep working.
+export function wrapRedisClient(client, tracer) {
+    return new Proxy(client, {
+        get(target, prop, _receiver) {
+            // Symbols (e.g. internal queue) pass through unchanged.
+            if (typeof prop !== "string") {
+                return Reflect.get(target, prop, target);
+            }
+            const original = Reflect.get(target, prop, target);
+            if (prop === "duplicate") {
+                // Preserve wrapping on duplicated connections.
+                return (...args) => {
+                    // @cast-boundary engine-bridge — Reflect.get returns unknown, narrow to ioredis-method
+                    const dup = original.apply(target, args);
+                    return wrapRedisClient(dup, tracer);
+                };
+            }
+            if (typeof original !== "function" || !TRACKED_COMMANDS.has(prop)) {
+                // Pass-through for non-command methods. Bind to target so `this`
+                // inside ioredis internals still works.
+                if (typeof original === "function") {
+                    // @cast-boundary engine-bridge — Reflect.get returns unknown, narrow to ioredis-method
+                    return original.bind(target);
+                }
+                return original;
+            }
+            return function wrappedCommand(...args) {
+                const keyPattern = extractKeyPattern(args[0]);
+                return tracer.withSpan("redis.cmd", {
+                    kind: "client",
+                    attributes: {
+                        "redis.command": prop,
+                        ...(keyPattern ? { "redis.key_pattern": keyPattern } : {}),
+                    },
+                }, async () => {
+                    // @cast-boundary engine-bridge — Reflect.get returns unknown, narrow to ioredis-method
+                    return original.apply(target, args);
+                });
+            };
+        },
+    });
+}

package/dist/observability/sensitive-filter.d.ts

@@ -0,0 +1,9 @@
+import type { SensitiveFilterConfig, SpanAttributeValue } from "./types/index.js";
+export declare const REDACTED = "[REDACTED]";
+export declare const DEFAULT_SENSITIVE_CONFIG: SensitiveFilterConfig;
+export declare function mergeSensitiveConfig(override: Partial<SensitiveFilterConfig> | undefined): SensitiveFilterConfig;
+export declare function redactHeaders(headers: Readonly<Record<string, string>>, config: SensitiveFilterConfig): Record<string, string>;
+export declare function redactQueryString(input: string, config: SensitiveFilterConfig): string;
+export declare function shouldRedactAttribute(key: string, config: SensitiveFilterConfig): boolean;
+export declare function redactValue(value: SpanAttributeValue): SpanAttributeValue;
+export declare function redactAttributes(attrs: Readonly<Record<string, SpanAttributeValue>>, config: SensitiveFilterConfig): Record<string, SpanAttributeValue>;

package/dist/observability/sensitive-filter.js

@@ -0,0 +1,92 @@
+export const REDACTED = "[REDACTED]";
+// Defaults are intentionally conservative — easier to add a header to the
+// list than to explain a PII leak. All matching is case-insensitive.
+export const DEFAULT_SENSITIVE_CONFIG = {
+    redactedHeaders: ["authorization", "cookie", "set-cookie", "x-api-key", "proxy-authorization"],
+    redactedQueryParams: [
+        "token",
+        "access_token",
+        "refresh_token",
+        "password",
+        "secret",
+        "api_key",
+        "apikey",
+    ],
+    redactedAttributeKeyPatterns: [
+        /password/i,
+        /secret/i,
+        /token/i,
+        /apikey/i,
+        /privatekey/i,
+        /credential/i,
+        /session/i,
+    ],
+};
+export function mergeSensitiveConfig(override) {
+    if (!override)
+        return DEFAULT_SENSITIVE_CONFIG;
+    return {
+        redactedHeaders: override.redactedHeaders ?? DEFAULT_SENSITIVE_CONFIG.redactedHeaders,
+        redactedQueryParams: override.redactedQueryParams ?? DEFAULT_SENSITIVE_CONFIG.redactedQueryParams,
+        redactedAttributeKeyPatterns: override.redactedAttributeKeyPatterns ??
+            DEFAULT_SENSITIVE_CONFIG.redactedAttributeKeyPatterns,
+    };
+}
+function lowercaseSet(names) {
+    return new Set(names.map((n) => n.toLowerCase()));
+}
+export function redactHeaders(headers, config) {
+    const redacted = lowercaseSet(config.redactedHeaders);
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = redacted.has(key.toLowerCase()) ? REDACTED : value;
+    }
+    return out;
+}
+// Redact sensitive query params in a URL or query string. Returns a new URL
+// string with the same shape — path, fragment, and ordering preserved.
+export function redactQueryString(input, config) {
+    const redacted = lowercaseSet(config.redactedQueryParams);
+    // URL wants absolute; handle both absolute and path-only forms.
+    const hasScheme = /^[a-z][a-z0-9+\-.]*:/i.test(input);
+    const base = hasScheme ? undefined : "http://_internal";
+    const url = base ? new URL(input, base) : new URL(input);
+    for (const key of Array.from(url.searchParams.keys())) {
+        if (redacted.has(key.toLowerCase())) {
+            url.searchParams.set(key, REDACTED);
+        }
+    }
+    if (!hasScheme) {
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    return url.toString();
+}
+// Check a single attribute key against the redaction patterns.
+// Used by the Span implementation when setAttribute is called.
+export function shouldRedactAttribute(key, config) {
+    for (const pattern of config.redactedAttributeKeyPatterns) {
+        if (pattern.test(key))
+            return true;
+    }
+    return false;
+}
+// Produce a type-preserving redacted value: numbers become 0, booleans become
+// false, strings become "[REDACTED]". Keeps downstream consumers (exporters,
+// dashboards) from having to deal with type drift — a histogram bucket that
+// expected a number never suddenly sees a string.
+export function redactValue(value) {
+    if (typeof value === "number")
+        return 0;
+    if (typeof value === "boolean")
+        return false;
+    return REDACTED;
+}
+// Filter a full attribute map, replacing matching keys with a type-preserving
+// redacted value.
+export function redactAttributes(attrs, config) {
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        out[key] = shouldRedactAttribute(key, config) ? redactValue(value) : value;
+    }
+    return out;
+}

package/dist/observability/standard-metrics.d.ts

@@ -0,0 +1,41 @@
+import type { Meter, MetricDefinition } from "./types/index.js";
+export declare const STANDARD_METRIC_DEFS: readonly MetricDefinition[];
+export declare function registerStandardMetrics(meter: Meter): void;
+export declare function emitHttpRequest(meter: Meter, labels: {
+    readonly route: string;
+    readonly method: string;
+    readonly status: number;
+}, durationSeconds: number): void;
+export declare function emitDispatcherHandler(meter: Meter, labels: {
+    readonly handler: string;
+    readonly success: boolean;
+    /** completed = drained normally; aborted = consumer walked away (SSE). */
+    readonly outcome?: "completed" | "aborted";
+}, durationSeconds: number): void;
+export declare function emitDispatcherError(meter: Meter, labels: {
+    readonly handler: string;
+    readonly errorClass: string;
+}): void;
+export declare function emitDbQuery(meter: Meter, labels: {
+    readonly operation: string;
+    readonly table: string;
+}, durationSeconds: number): void;
+export declare function emitProjectionRebuild(meter: Meter, labels: {
+    readonly projection: string;
+    readonly success: boolean;
+}, durationSeconds: number, eventsReplayed: number): void;
+export declare function emitEventConsumerLag(meter: Meter, labels: {
+    readonly consumer: string;
+    readonly instanceId: string;
+}, lagEvents: number): void;
+export declare function emitEventConsumerRearmExhausted(meter: Meter, labels: {
+    readonly consumer: string;
+    readonly instanceId: string;
+}): void;
+export declare function emitEventDispatcherListenConnected(meter: Meter, connected: boolean): void;
+export declare function emitEventConsumerPassOutcome(meter: Meter, labels: {
+    readonly consumer: string;
+    readonly instanceId: string;
+}, processed: number, failed: number): void;
+export declare function emitJobQueueDepth(meter: Meter, lane: string, counts: Readonly<Record<string, number>>): void;
+export declare function emitJobLastSuccess(meter: Meter, job: string): void;

package/dist/observability/standard-metrics.js

@@ -0,0 +1,237 @@
+// Framework-level metrics registered automatically at boot. Names match the
+// Prometheus + OTel-friendly shape documented in observability-naming.md.
+// Feature code never emits these — the Framework wires them from the HTTP
+// middleware, dispatcher, and DB wrapper.
+export const STANDARD_METRIC_DEFS = [
+    {
+        name: "kumiko_http_requests_total",
+        type: "counter",
+        description: "HTTP requests counted by route, method, and status.",
+        labels: ["route", "method", "status"],
+    },
+    {
+        name: "kumiko_http_request_duration_seconds",
+        type: "histogram",
+        description: "HTTP request latency in seconds.",
+        labels: ["route", "method"],
+        buckets: [0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+    },
+    {
+        name: "kumiko_dispatcher_handler_duration_seconds",
+        type: "histogram",
+        description: "Dispatcher handler latency in seconds.",
+        labels: ["handler", "success", "outcome"],
+        buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
+    },
+    {
+        name: "kumiko_dispatcher_handler_errors_total",
+        type: "counter",
+        description: "Dispatcher handler errors by class.",
+        labels: ["handler", "error_class"],
+    },
+    {
+        name: "kumiko_db_query_duration_seconds",
+        type: "histogram",
+        description: "DB query latency in seconds.",
+        labels: ["operation", "table"],
+        buckets: [0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1],
+    },
+    // Projection-rebuild duration. Only emitted when a rebuild runs (ops-op),
+    // not continuously. Lag metric (continuous, live projections) is skipped
+    // for now — apply is synchronous, so lag is definitionally 0; a meaningful
+    // lag counter lands with async-apply in a future sprint.
+    {
+        name: "kumiko_projection_rebuild_duration_seconds",
+        type: "histogram",
+        description: "Duration of a full projection rebuild in seconds.",
+        labels: ["projection", "success"],
+        buckets: [0.01, 0.05, 0.1, 0.5, 1, 5, 30, 120, 600],
+    },
+    {
+        name: "kumiko_projection_rebuild_events_total",
+        type: "counter",
+        description: "Events replayed during a projection rebuild.",
+        labels: ["projection"],
+    },
+    // Event-dispatcher per-consumer metrics. Lag is the primary ops signal:
+    // how many events sit between the consumer's cursor and events-head.
+    // A growing lag means the consumer can't keep up; zero means fully caught up.
+    // instance_id labels each shard: SHARED_INSTANCE_SENTINEL for shared
+    // consumers (one cursor globally), or the process-local instanceId for
+    // per-instance consumers (one cursor per dispatcher). Without this,
+    // Prometheus collapses per-instance shards into last-writer-wins and
+    // per-instance lag is invisible to alerting.
+    {
+        name: "kumiko_event_consumer_lag_events",
+        type: "gauge",
+        description: "Number of events between the consumer's cursor and the events head.",
+        labels: ["consumer", "instance_id"],
+    },
+    {
+        name: "kumiko_event_consumer_events_processed_total",
+        type: "counter",
+        description: "Events successfully delivered to a consumer.",
+        labels: ["consumer", "instance_id"],
+    },
+    {
+        name: "kumiko_event_consumer_events_failed_total",
+        type: "counter",
+        description: "Event deliveries that threw. Repeated failures on the same event lead to dead-letter.",
+        labels: ["consumer", "instance_id"],
+    },
+    // Fires once per (consumer, instance) transition into "stuck dead" —
+    // the rearm-cooldown/rearm-budget in event-dispatcher-delivery.ts gave up
+    // and the consumer now needs an operator (restartConsumer()) to recover.
+    // Without this, "dead + auto-rearm exhausted" is only visible via a
+    // getConsumerState poll — ops has no push signal that a consumer crossed
+    // from "will self-heal" to "needs a human". Deliberately a counter, not a
+    // gauge: emitted once per transition (event-dispatcher.ts tracks which
+    // consumers already fired this), not once per still-dead poll pass.
+    {
+        name: "kumiko_event_consumer_rearm_exhausted_total",
+        type: "counter",
+        description: "Consumer transitioned to dead with its auto-rearm budget exhausted.",
+        labels: ["consumer", "instance_id"],
+    },
+    // LISTEN-subscription health. 1 = active, 0 = dropped. Drops to 0 while
+    // the dispatcher is running signal that delivery latency has regressed
+    // from sub-millisecond (LISTEN) to pollIntervalMs (timer fallback); ops
+    // should look at it the moment downstream latency SLOs start slipping.
+    {
+        name: "kumiko_event_dispatcher_listen_connected",
+        type: "gauge",
+        description: "1 if the event-dispatcher holds an active PG LISTEN subscription on the events channel, 0 otherwise.",
+        labels: [],
+    },
+    // BullMQ backlog per lane + state (waiting/active/delayed/failed/…). Only
+    // the process that owns a lane's consumerLane polls it (job-runner.ts
+    // start()) — the count is a global Redis-backed value, no per-instance
+    // label needed. A growing "waiting" count means the lane's worker can't
+    // keep up with dispatch; "failed" trending up means jobs are erroring
+    // silently. Motivated by apps that run every job on the "api" lane
+    // (no dedicated worker consumer) — fanout/reconcile jobs then share
+    // Redis-queue capacity with request-handling, and contention is
+    // otherwise invisible until requests slow down.
+    {
+        name: "kumiko_job_queue_depth",
+        type: "gauge",
+        description: "BullMQ job counts per lane and state.",
+        labels: ["lane", "state"],
+    },
+    // Dead-man for in-process jobs: the k8s CronJob alerts never fire for them
+    // (no CronJob object exists), and a gauge the job itself sets freezes on its
+    // last value when the job dies, so neither `absent()` nor a threshold
+    // catches a silently stopped cron. This one is stamped by the runner, so
+    // `time() - kumiko_job_last_success_timestamp_seconds{job="…"} > interval`
+    // is a true liveness check. Absent until the first success after a restart —
+    // see docs/reference/job-liveness-metric.md for the `for:` that implies.
+    {
+        name: "kumiko_job_last_success_timestamp_seconds",
+        type: "gauge",
+        description: "Unix timestamp of the last successful run, per registered job.",
+        labels: ["job"],
+    },
+];
+export function registerStandardMetrics(meter) {
+    for (const def of STANDARD_METRIC_DEFS) {
+        // Guard: if already registered (e.g. buildServer called twice with the
+        // same meter instance — rare outside of hot-reload scenarios), skip.
+        if (meter.definitions().has(def.name))
+            continue;
+        meter.registerMetric(def);
+    }
+}
+// Emit helpers — read-only surface for Auto-Instrumentation call sites.
+// Using these instead of raw meter.counter("...").inc() keeps the metric
+// names centralised.
+export function emitHttpRequest(meter, labels, durationSeconds) {
+    meter.counter("kumiko_http_requests_total").inc(1, {
+        route: labels.route,
+        method: labels.method,
+        status: String(labels.status),
+    });
+    meter
+        .histogram("kumiko_http_request_duration_seconds")
+        .observe(durationSeconds, { route: labels.route, method: labels.method });
+}
+export function emitDispatcherHandler(meter, labels, durationSeconds) {
+    meter.histogram("kumiko_dispatcher_handler_duration_seconds").observe(durationSeconds, {
+        handler: labels.handler,
+        success: String(labels.success),
+        outcome: labels.outcome ?? "completed",
+    });
+}
+export function emitDispatcherError(meter, labels) {
+    meter.counter("kumiko_dispatcher_handler_errors_total").inc(1, {
+        handler: labels.handler,
+        error_class: labels.errorClass,
+    });
+}
+export function emitDbQuery(meter, labels, durationSeconds) {
+    meter.histogram("kumiko_db_query_duration_seconds").observe(durationSeconds, {
+        operation: labels.operation,
+        table: labels.table,
+    });
+}
+export function emitProjectionRebuild(meter, labels, durationSeconds, eventsReplayed) {
+    meter.histogram("kumiko_projection_rebuild_duration_seconds").observe(durationSeconds, {
+        projection: labels.projection,
+        success: String(labels.success),
+    });
+    meter
+        .counter("kumiko_projection_rebuild_events_total")
+        .inc(eventsReplayed, { projection: labels.projection });
+}
+// Per-shard consumer labels. `instance_id` is the reserved sentinel
+// (SHARED_INSTANCE_SENTINEL) for shared-delivery consumers, and the
+// concrete dispatcher-instanceId for per-instance shards. Labelling by
+// both keeps Prometheus series distinct across instances so per-instance
+// lag is visible — without it, scraped gauges collapse last-writer-wins
+// and a single slow shard is invisible to alerting.
+export function emitEventConsumerLag(meter, labels, lagEvents) {
+    meter.gauge("kumiko_event_consumer_lag_events").set(lagEvents, {
+        consumer: labels.consumer,
+        instance_id: labels.instanceId,
+    });
+}
+// Caller (event-dispatcher.ts) is responsible for calling this exactly
+// once per (consumer, instanceId) transition into exhausted-dead — not
+// once per poll pass while it stays dead.
+export function emitEventConsumerRearmExhausted(meter, labels) {
+    meter.counter("kumiko_event_consumer_rearm_exhausted_total").inc(1, {
+        consumer: labels.consumer,
+        instance_id: labels.instanceId,
+    });
+}
+export function emitEventDispatcherListenConnected(meter, connected) {
+    meter.gauge("kumiko_event_dispatcher_listen_connected").set(connected ? 1 : 0);
+}
+export function emitEventConsumerPassOutcome(meter, labels, processed, failed) {
+    if (processed > 0) {
+        meter.counter("kumiko_event_consumer_events_processed_total").inc(processed, {
+            consumer: labels.consumer,
+            instance_id: labels.instanceId,
+        });
+    }
+    if (failed > 0) {
+        meter.counter("kumiko_event_consumer_events_failed_total").inc(failed, {
+            consumer: labels.consumer,
+            instance_id: labels.instanceId,
+        });
+    }
+}
+// counts: BullMQ's Queue.getJobCounts() result, filtered by the caller to
+// backlog-relevant states (waiting/active/delayed/failed/paused) — "completed"
+// grows unboundedly without removeOnComplete and would make the gauge series
+// monotonically increasing, useless as a backlog signal.
+export function emitJobQueueDepth(meter, lane, counts) {
+    for (const [state, count] of Object.entries(counts)) {
+        meter.gauge("kumiko_job_queue_depth").set(count, { lane, state });
+    }
+}
+// `job` is the registry-declared job name — handleJob rejects an unknown name
+// before it can reach here, so the label set is bounded by the app's r.job
+// registrations and carries no tenant or user input.
+export function emitJobLastSuccess(meter, job) {
+    meter.gauge("kumiko_job_last_success_timestamp_seconds").set(Date.now() / 1000, { job });
+}

package/dist/observability/types/index.js

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

package/dist/observability/types/metric.js

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

package/dist/observability/types/provider.js

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

package/dist/observability/types/span.js

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

package/dist/pipeline/active-membership.d.ts

@@ -0,0 +1,12 @@
+import { type PrincipalStatusPlugin, type TenantLifecycleStatusPlugin } from "../engine/active-membership.js";
+import type { TenantId } from "../engine/types/identifiers.js";
+import type { ActiveMembershipResult, Registry } from "../engine/types/index.js";
+import { type DispatchContext } from "./dispatch-shared.js";
+export type ActiveMembershipPolicy = {
+    readonly allowPendingDestruction: boolean;
+    readonly allowUnknownPrincipal: boolean;
+};
+export declare const INTERACTIVE_SIGN_IN_POLICY: ActiveMembershipPolicy;
+export declare function resolvePrincipalPlugin(registry: Registry): PrincipalStatusPlugin;
+export declare function resolveTenantLifecyclePlugin(registry: Registry, caller: string): TenantLifecycleStatusPlugin | undefined;
+export declare function resolveActiveMembershipFn(ctx: DispatchContext, userId: string, tenantId: TenantId, policy: ActiveMembershipPolicy): Promise<ActiveMembershipResult>;

package/dist/pipeline/active-membership.js

@@ -0,0 +1,124 @@
+// One framework-owned composition of membership / principal-status /
+// tenant-lifecycle checks so login, switch-tenant and MFA completion can't independently drift.
+import { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN_STATUSES, } from "../engine/active-membership.js";
+import { EXT_PRINCIPAL_STATUS, EXT_TENANT_LIFECYCLE_STATUS } from "../engine/extension-names.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { InternalError } from "../errors/index.js";
+import { executeQuery } from "./dispatch-query.js";
+import { resolveDbSource } from "./dispatch-shared.js";
+import { rootWriteOrigin } from "./write-origin.js";
+export const INTERACTIVE_SIGN_IN_POLICY = {
+    allowPendingDestruction: true,
+    allowUnknownPrincipal: true,
+};
+// membershipQuery is a per-app-registered handler — engine-payload, not
+// trusted shape. Structural validation instead of a blind cast.
+function isMembershipRow(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    if (!("tenantId" in v) || typeof v.tenantId !== "string")
+        return false;
+    if (!("roles" in v) || !Array.isArray(v.roles) || !v.roles.every((r) => typeof r === "string")) {
+        return false;
+    }
+    if ("tenantName" in v && v.tenantName !== undefined && typeof v.tenantName !== "string") {
+        return false;
+    }
+    if ("tenantKey" in v && v.tenantKey !== undefined && typeof v.tenantKey !== "string") {
+        return false;
+    }
+    return true;
+}
+async function findMembership(ctx, userId, tenantId) {
+    const membershipUser = createSystemUser(tenantId);
+    // Auth-flow entry point with no enclosing handler, so it is its own root.
+    const rawMemberships = await executeQuery(ctx, ctx.membershipQuery, { userId }, membershipUser, rootWriteOrigin(ctx.registry, ctx.membershipQuery, membershipUser));
+    if (!Array.isArray(rawMemberships) || !rawMemberships.every(isMembershipRow)) {
+        throw new InternalError({
+            message: `dispatcher.resolveActiveMembership: membershipQuery "${ctx.membershipQuery}" returned ` +
+                "a malformed result — expected an array of {tenantId, roles, tenantName?, tenantKey?} rows.",
+        });
+    }
+    return rawMemberships.find((m) => m.tenantId === tenantId);
+}
+// Exported so member-reader.ts (ctx.queryAsMember) can reach the registered
+// PrincipalStatusPlugin's resolveProfile without duplicating this lookup.
+export function resolvePrincipalPlugin(registry) {
+    const usages = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS);
+    if (usages.length !== 1) {
+        throw new InternalError({
+            message: usages.length === 0
+                ? `dispatcher.resolveActiveMembership: no "${EXT_PRINCIPAL_STATUS}" provider registered — mount the user feature.`
+                : `dispatcher.resolveActiveMembership: multiple "${EXT_PRINCIPAL_STATUS}" providers registered — exactly one is expected.`,
+        });
+    }
+    const usage = usages[0];
+    if (!usage || !isPrincipalStatusPlugin(usage.options)) {
+        throw new InternalError({
+            message: `dispatcher.resolveActiveMembership: "${usage?.entityName}" registered under "${EXT_PRINCIPAL_STATUS}" without a resolveStatus(userId, {db}) — extension options must be a PrincipalStatusPlugin.`,
+        });
+    }
+    return usage.options;
+}
+export function resolveTenantLifecyclePlugin(registry, caller) {
+    const usages = registry.getExtensionUsages(EXT_TENANT_LIFECYCLE_STATUS);
+    if (usages.length > 1) {
+        throw new InternalError({
+            message: `${caller}: multiple "${EXT_TENANT_LIFECYCLE_STATUS}" providers registered — exactly one (or zero) is expected.`,
+        });
+    }
+    const usage = usages[0];
+    if (!usage)
+        return undefined;
+    if (!isTenantLifecycleStatusPlugin(usage.options)) {
+        throw new InternalError({
+            message: `${caller}: "${usage.entityName}" registered under "${EXT_TENANT_LIFECYCLE_STATUS}" without a resolveStatus(tenantId, {db}) — extension options must be a TenantLifecycleStatusPlugin.`,
+        });
+    }
+    return usage.options;
+}
+function isTeardownRejected(status, policy) {
+    return (status !== null &&
+        TENANT_TEARDOWN_STATUSES.has(status.status) &&
+        !(status.status === "destroyRequested" && policy.allowPendingDestruction));
+}
+// Order is load-bearing: a non-member must never learn a foreign tenant's
+// lifecycle/blocked state, so membership is resolved and checked FIRST.
+export async function resolveActiveMembershipFn(ctx, userId, tenantId, policy) {
+    const { registry } = ctx;
+    const membership = await findMembership(ctx, userId, tenantId);
+    if (!membership) {
+        return { kind: "rejected", reason: "not_a_member" };
+    }
+    const principalPlugin = resolvePrincipalPlugin(registry);
+    const dbSource = resolveDbSource(ctx, undefined);
+    if (!dbSource) {
+        throw new InternalError({
+            message: "dispatcher.resolveActiveMembership requires a database connection — none is configured.",
+        });
+    }
+    // resolveDbSource(ctx, undefined) never returns a tx, only AppContext.db —
+    // the dispatcher boundary holds that as the root DbConnection, same as buildAuthClaimsContext.
+    const db = dbSource; // @cast-boundary db-operator
+    const principalStatus = await principalPlugin.resolveStatus(userId, { db });
+    if (principalStatus === "blocked" ||
+        (principalStatus === "unknown" && !policy.allowUnknownPrincipal)) {
+        return { kind: "rejected", reason: "principal_blocked" };
+    }
+    const lifecyclePlugin = resolveTenantLifecyclePlugin(registry, "dispatcher.resolveActiveMembership");
+    if (lifecyclePlugin) {
+        const lifecycle = await lifecyclePlugin.resolveStatus(tenantId, { db });
+        if (isTeardownRejected(lifecycle, policy)) {
+            return { kind: "rejected", reason: "tenant_teardown" };
+        }
+    }
+    return {
+        kind: "active",
+        membership: {
+            tenantId,
+            roles: membership.roles,
+            ...(membership.tenantName !== undefined ? { tenantName: membership.tenantName } : {}),
+            ...(membership.tenantKey !== undefined ? { tenantKey: membership.tenantKey } : {}),
+        },
+    };
+}

package/dist/pipeline/append-event-core.d.ts

@@ -0,0 +1,12 @@
+import type { DbRunner } from "../db/connection.js";
+import type { AppendEventArgs, Registry, TenantId } from "../engine/types/index.js";
+import { type StoredEvent } from "../event-store/event-store.js";
+export type AppendDomainEventCoreDeps = {
+    readonly registry: Registry;
+    readonly db: DbRunner;
+    readonly tenantId: TenantId;
+    readonly userId: string;
+    readonly callSiteLabel: string;
+    readonly callerFeature?: string;
+};
+export declare function appendDomainEventCore(deps: AppendDomainEventCoreDeps, args: AppendEventArgs): Promise<StoredEvent>;