@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/engine/types/ownership.ts

@@ -0,0 +1,83 @@
+// --- Ownership ---
+// Pure types for the declarative Claims → Access bridge. Runtime (from(),
+// matchesRule(), buildOwnershipClause()) stays in engine/ownership.ts, which
+// re-exports these for backwards compatibility.
+
+import type { SessionUser } from "./handlers";
+
+// Parameterised SQL fragment — produced by buildOwnershipClause + by the
+// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
+// renumbering placeholders if needed (shiftParams in engine/ownership.ts).
+export type SqlFragment = {
+  readonly sqlText: string;
+  readonly params: readonly unknown[];
+};
+
+// Reference spec supported by `from()`:
+//   "user:id"                  → user.id
+//   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
+//   "claim:<featureName>:<key>" → user.claims["<featureName>:<key>"]
+//
+// The string form is keyed so the framework can look up the referenced
+// Registry entry at boot (Claim-QN exists? Column type compatible?). A typed
+// object form would force features to import each other's handles — the
+// whole point of H.2's unified path is string-based references, no imports.
+export type OwnershipRef = string;
+
+// Resolved during `from()` — the parser eagerly splits the prefix so the
+// runtime evaluator avoids string-parsing on every row. `kind` drives the
+// evaluator branch; the rest is the resolved metadata.
+export type FromRuleKind = "user" | "claim";
+
+export type FromRule = {
+  readonly kind: "from";
+  readonly refKind: FromRuleKind;
+  // For "user:id" → "id"; for "user:tenantId" → "tenantId".
+  // For "claim:<featureName>:<key>" → "<featureName>:<key>" (the full QN,
+  // which is exactly the key under which the JWT stores the value).
+  readonly refPath: string;
+  // Row-column to match against. For claim rules defaults to the claim's
+  // shortName (second segment of the claim QN). For user-rules the column
+  // is always explicit.
+  readonly column: string;
+};
+
+// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
+// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
+// concatenates the fragment into the larger query.
+export type WhereRuleContext<TTable = unknown> = {
+  readonly table: TTable;
+  readonly tableName: string;
+  readonly paramStart: number;
+};
+
+export type WhereRule<TTable = unknown> = {
+  readonly kind: "where";
+  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
+};
+
+// "all" collapses to a primitive so map authors can write `Admin: "all"`
+// without importing a helper.
+export type OwnershipRule = "all" | FromRule | WhereRule;
+
+// Per-role map: every key is a role name, value is the rule that role
+// satisfies to pass the access check.
+export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+
+// Result of buildOwnershipClause. The discriminant lets the caller handle
+// the three outcomes without inspecting SQL internals:
+//
+//   "pass"  → user is unrestricted. Run the query as-is.
+//   "empty" → user has a role mapped but no rule accepts any row (missing
+//             claim, empty array, role not in map). Skip the DB call entirely
+//             — returning [] is equivalent and avoids a pointless roundtrip.
+//   "sql"   → apply the parameterised fragment as an AND on the query.
+//             Caller is responsible for renumbering placeholders when
+//             concatenating with other fragments (see `shiftParams`).
+//
+// "empty" vs. "pass" is the critical distinction for a safe default:
+// undefined/pass = allow, empty = deny-by-construction.
+export type OwnershipClause =
+  | { readonly kind: "pass" }
+  | { readonly kind: "empty" }
+  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };

package/src/engine/types/relations.ts

@@ -1,51 +1 @@
-import type { OnDeleteStrategy } from "../constants";
-
-// --- Relations ---
-
-export type BelongsToRelation = {
-  readonly type: "belongsTo";
-  readonly target: string;
-  readonly foreignKey: string;
-  readonly searchInclude?: readonly string[];
-  // onDelete is declared on the parent-side (hasMany / manyToMany) because
-  // that's where the "what happens to my children?" decision lives. A
-  // belongsTo node just points at a parent — the parent's onDelete drives
-  // the cleanup.
-};
-
-export type HasManyRelation = {
-  readonly type: "hasMany";
-  readonly target: string;
-  readonly foreignKey: string;
-  readonly onDelete?: OnDeleteStrategy;
-  // When true, a nested payload under this relation's key (e.g.
-  // `{ tasks: [{ ... }] }` on a `project:create` write) is auto-expanded
-  // into child writes: parent first, then one child-write per entry with
-  // the foreign key set to the parent's new id — all in the same TX.
-  // Opt-in (default false) so legacy hasMany relations that were declared
-  // purely for cascade-delete or UI-nav semantics don't silently gain a
-  // client-writable path. Children are never inferred from payload-shape
-  // alone; only relations with this flag unlock nested-write.
-  //
-  // Scope v1: depth=1, create-only, hasMany-only. Update-nested,
-  // delete-nested, and belongsTo/m2m auto-expansion are explicit future
-  // work — when they arrive, they'll take the same flag so the opt-in
-  // stays a single, consistent surface.
-  readonly nestedWrite?: boolean;
-};
-
-export type ManyToManyRelation = {
-  readonly type: "manyToMany";
-  readonly target: string;
-  readonly through: {
-    readonly table: string;
-    readonly sourceKey: string;
-    readonly targetKey: string;
-  };
-  readonly searchInclude?: readonly string[];
-  readonly onDelete?: OnDeleteStrategy;
-};
-
-export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
-
-export type EntityRelations = Readonly<Record<string, RelationDefinition>>;
+export * from "@cosmicdrift/kumiko-types/relations";

package/src/engine/types/screen.ts

@@ -539,10 +539,6 @@ export type EditExtensionSection = {
   readonly component: PlatformComponent;
 };
 
-export function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection {
-  return section.kind === "extension";
-}
-
 export type EditLayout = {
   readonly sections: readonly EditSectionSpec[];
 };
@@ -749,45 +745,3 @@ export type ScreenDefinition = (
   | ConfigEditScreenDefinition
   | CustomScreenDefinition
 ) & { readonly nav?: ScreenNavSugar };
-
-// Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
-// authors who branch on the three FieldRenderer variants without manual
-// "format" in renderer checks.
-export function isFormatSpec(r: unknown): r is FormatSpec {
-  return typeof r === "object" && r !== null && "format" in r && typeof r.format === "string";
-}
-
-// Collapse the string-shorthand into the object form. Both the boot-validator
-// and (later) ui-core's view-model builder iterate over fields/columns — the
-// helper keeps that loop from growing two branches everywhere.
-export function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string> {
-  const col = typeof c === "string" ? { field: c } : c;
-  if (
-    typeof process !== "undefined" &&
-    process.env.NODE_ENV !== "production" &&
-    col.renderer !== undefined &&
-    typeof col.renderer === "function"
-  ) {
-    // biome-ignore lint/suspicious/noConsole: dev-only warning
-    console.warn(
-      `[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`,
-    );
-  }
-  return col;
-}
-
-/** Evaluates a declarative FieldCondition against the current row/form
- *  values. THE single implementation — renderer (row-action visibility),
- *  headless view-model (visible/readOnly/required) and render-edit
- *  (form-condition closures) reuse it; three hand-rolled copies had
- *  already drifted in shape. */
-export function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean {
-  if (typeof cond === "boolean") return cond;
-  const val = values[cond.field];
-  if ("eq" in cond) return val === cond.eq;
-  return val !== cond.ne;
-}
-
-export function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string> {
-  return typeof f === "string" ? { field: f } : f;
-}

package/src/engine/types/target-ref.ts

@@ -1,21 +1 @@
-// TargetRef — runtime-Repräsentation eines typed buildTarget-Outputs.
-// Wird vom Visual-Tree-Component (renderer-web) an einen Target-Resolver
-// dispatcht; der Resolver findet die Editor-Maske via featureId.
-//
-// **Compile-time-Safety:** TargetRef wird niemals hand-getippt. Stattdessen
-// erzeugt der typed buildTarget-Builder (engine/build-target.ts) einen
-// TargetRef, dessen action + args gegen die treeActions-Map des Ziel-
-// Features validiert sind.
-//
-// **Runtime:** args sind hier untyped (Record<string, unknown>), weil
-// TargetRef die erased-runtime-Version ist. Der Resolver kennt das
-// Ziel-Feature und kann args entsprechend casten — ähnlich wie Event-
-// Payloads im Event-Store.
-//
-// Siehe docs/plans/architecture/visual-tree.md A5.
-
-export type TargetRef = {
-  readonly featureId: string;
-  readonly action: string;
-  readonly args?: Readonly<Record<string, unknown>>;
-};
+export * from "@cosmicdrift/kumiko-types/target-ref";

package/src/engine/types/tree-node.ts

@@ -1,129 +1 @@
-// TreeNode — single Knoten im Client-navProvider-Tree. Provider liefern
-// entweder statische readonly TreeNode[] oder dynamische TreeChildrenSubscribe.
-//
-// **Mental-Modell** (VS-Code-Explorer):
-//   [icon] [label] [...hover-actions]
-// optional ein target zum Klicken (öffnet Editor-Maske via
-// Target-Resolver) und optional children als nested tree.
-//
-// **State** markiert Visual-Modus für Skeleton-Pattern:
-//   - "filled" (default) — schwarz, Knoten hat Inhalt
-//   - "stub" — hellgrau, existing aber leer (Designer-Stub-File)
-//   - "empty" — Platzhalter für "+ create"-Affordance
-//   - "loading" — Children werden gerade aufgelöst
-//   - "error" — Provider hat Fehler emittiert
-// Provider die kein Skeleton-Pattern brauchen müssen state nicht setzen.
-//
-// **Subscribe-Form** für dynamic Children: Provider erhält emit(),
-// gibt unsubscribe() zurück. Initial-Emit synchron oder async, weitere
-// Emits beliebig oft (z.B. wenn Entity-Row neu erscheint via SSE).
-// Spielt natürlich mit existing SSE-Frame: ein Provider kann intern
-// auf Entity-Update-Events abonnieren und bei Änderung emit() aufrufen.
-
-import type { TargetRef } from "./target-ref";
-
-export type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
-
-export type TreeAction = {
-  // Icon-Key — vom Renderer-Icon-Registry interpretiert. Konvention
-  // matched NavDefinition.icon: unbekannte Icons surface als missing-icon
-  // im UI, nicht als Boot-Failure.
-  readonly icon: string;
-  // i18n-Translation-Key oder roher String. Vom Renderer aufgelöst, Engine
-  // behandelt opak (mirrors NavDefinition.label, WorkspaceDefinition.label).
-  readonly label: string;
-  // Klick-Ziel der Action. Pflicht — Action ohne target ist semantisch
-  // sinnlos (Hover-Icon das nichts tut).
-  readonly target: TargetRef;
-};
-
-export type TreeNode = {
-  // i18n-Translation-Key oder roher String. Vom Renderer beim Rendern
-  // aufgelöst (siehe TreeAction.label).
-  readonly label: string;
-  // Optional. Icon links neben dem Label. Selbe Konvention wie
-  // TreeAction.icon — Renderer-Icon-Registry-Lookup.
-  readonly icon?: string;
-  // Visueller State für Skeleton-Pattern. Default "filled" (kein Eintrag
-  // ⇒ schwarz/normal). Wert-Semantik im Header-Comment dieser Datei.
-  readonly state?: TreeNodeState;
-  // Optional Klick-Ziel. Fehlt → reiner Container-Knoten (nur ausklappbar,
-  // nicht klickbar). Vorhanden → Klick öffnet die Editor-Maske via
-  // Target-Resolver in renderer-web.
-  readonly target?: TargetRef;
-  // Hover-Actions rechts (Add/Refresh/Delete/etc.). Werden in der
-  // Sidebar-Row erst bei Hover sichtbar — VS-Code-Pattern. Engine
-  // ordnet die Actions in der Reihenfolge an, in der sie hier stehen.
-  readonly actions?: readonly TreeAction[];
-  // Statische Children oder dynamic Subscribe-Function. Subscribe wird
-  // erst beim Ausklappen aufgerufen (lazy); die Function-Form erlaubt
-  // SSE-gefütterte Live-Updates wenn neue Entity-Rows reinkommen.
-  readonly children?: readonly TreeNode[] | TreeChildrenSubscribe;
-  // Provider-deklarierte „+ create"-Action für Knoten mit `state: "empty"`.
-  // Tree-Component zeigt automatisch ein „+"-Icon und dispatcht
-  // `createAction.target` bei Klick — Provider weiß was „leer befüllen"
-  // für ihn bedeutet (z.B. „neuer Page-Slug" vs „neue Entity-Row"),
-  // Convention könnte das nicht raten. Konsistent zu `state` (auch
-  // Provider-explizit). Siehe visual-tree.md V.1.1-Decision D3.
-  readonly createAction?: TreeAction;
-};
-
-// Subscribe<T> — Provider implementiert: emit(initial); ...emit(updated);
-// und gibt unsubscribe-Function zurück. Caller (Tree-Component) ruft
-// unsubscribe auf wenn Knoten unmounted/eingeklappt wird.
-//
-// **V.1.4 emitError**: optional callback für async-error-Pfade (fetch-
-// fail, SSE-disconnect). Provider die explizit Errors signalisieren
-// wollen rufen `emitError(e)` statt empty-emit; VisualTree zeigt
-// Error-Banner mit Retry-Button. Sync-Throws im Provider-Body werden
-// vom useEffect-try/catch abgefangen — emitError ist nur für async.
-export type Subscribe<T> = (
-  emit: (value: T) => void,
-  emitError?: (error: Error) => void,
-) => () => void;
-
-// TreeChildrenSubscribe — Lazy-Variante für dynamic Children. Wird
-// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. Kein ctx-
-// Argument: Provider sind session-bound; Backend liest tenantId aus
-// session bei jedem fetch/dispatch. V.1.1 hatte ein ctx mit tenantId,
-// das aber im Browser nie echten Tenant trug (war auf SYSTEM_TENANT_ID
-// gepinnt) und vom einzigen V.1.2-Consumer (text-content) ignoriert
-// wurde. SR2-Rip 2026-05-18: Dead-API entfernt; wenn später ein
-// Provider tenant-aware-rendern muss (z.B. cross-tenant-Dashboards
-// für SystemAdmin), wird ctx mit echtem Tenant-Source aus dem Auth-
-// Layer re-introduziert. YAGNI bis dahin.
-export type TreeChildrenSubscribe = () => Subscribe<readonly TreeNode[]>;
-
-// TreeActionDef — Schema-Eintrag pro Action in der treeActions-Map
-// eines Features. Phase 0: Args sind ein optionales Type-Sample
-// (kein Validator zur Laufzeit — Validation passiert compile-time
-// via buildTarget-Generic, runtime via Editor-Panel-Schema).
-//
-// Lebt hier (nicht in build-target.ts) weil es konzeptuell zur
-// Visual-Tree-Domäne gehört, nicht zum Builder. build-target.ts
-// importiert den Type von hier.
-export type TreeActionDef<TArgs = Record<string, unknown>> = {
-  readonly args?: TArgs;
-};
-
-// TreeActionsHandle<T> — Return-Type von r.treeActions(...). Trägt
-// den literal-typed Action-Map durch das Feature-Export-System
-// (siehe FeatureDefinition.exports + Memory `[EventDef-Exports-
-// Pattern]`). Das ist die compile-time Bridge zu buildTarget:
-//
-//   const handle = r.treeActions({ edit: { args: { slug: "" as string } } });
-//   // handle.id        → TFeature (literal feature name)
-//   // handle.treeActions → { edit: { args: { slug: string } } } (literal-typed)
-//   buildTarget({ target: handle, action: "edit", args: { slug: "x" } });
-//   //                                ^^^^^^^^^^^^^^         ^^^^^^^^
-//   //                                literal-validated      typed-validated
-//
-// Runtime-Lookup geht über FeatureDefinition.treeActions (erased Map),
-// Compile-Time-Validation über diesen Handle.
-export type TreeActionsHandle<
-  TFeature extends string,
-  TActions extends Record<string, TreeActionDef>,
-> = {
-  readonly id: TFeature;
-  readonly treeActions: TActions;
-};
+export * from "@cosmicdrift/kumiko-types/tree-node";

package/src/entrypoint/index.ts

@@ -32,7 +32,7 @@
 
 import type { Hono } from "hono";
 import type { AuthRoutesConfig } from "../api/auth-routes";
-import type { JwtHelper } from "../api/jwt";
+import type { JwtHelper, JwtKeyring } from "../api/jwt";
 import type { KumikoServer, ServerOptions } from "../api/server";
 import { buildServer } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
@@ -54,7 +54,7 @@ import type { SystemHooks } from "../pipeline/lifecycle-pipeline";
 export type BaseEntrypointOptions = {
   readonly registry: Registry;
   readonly context: AppContext;
-  readonly jwtSecret: string;
+  readonly jwtSecret: string | JwtKeyring;
   readonly jwtIssuer?: string;
   readonly observability?: ObservabilityProvider;
   readonly observabilityOptions?: ObservabilityOptions;

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -456,6 +456,37 @@ describe("event-store: loadAllEventsByType", () => {
     expect(all.map((e) => e.version)).toEqual([1, 2, 3, 4]);
     expect(all.map((e) => (e.payload as { v: number }).v)).toEqual([0, 1, 2, 3]);
   });
+
+  test("throws once rows exceed the given rowLimit", async () => {
+    for (let v = 0; v < 3; v++) {
+      await append(testDb.db, {
+        aggregateId: uuid(),
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { v },
+        metadata: { userId: userA },
+      });
+    }
+    await expect(loadAllEventsByType(testDb.db, "task", 2)).rejects.toThrow(/exceeds 2 rows/);
+  });
+
+  test("does not throw when rows equal the given rowLimit", async () => {
+    for (let v = 0; v < 2; v++) {
+      await append(testDb.db, {
+        aggregateId: uuid(),
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { v },
+        metadata: { userId: userA },
+      });
+    }
+    const all = await loadAllEventsByType(testDb.db, "task", 2);
+    expect(all).toHaveLength(2);
+  });
 });
 
 describe("event-store: streamAllEventsByType (memory-bounded iteration)", () => {

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { Glob } from "bun";
+
+// getUnscopedAggregateStreamMaxVersion / getUnscopedAggregateStreamTenant have
+// no tenant filter — a caller can use them to probe whether a foreign tenant's
+// aggregate exists (see event-store.ts SECURITY doc). Restricted to known
+// seed/system-internal callers; extend only for genuine new ones.
+const RESTRICTED_SYMBOLS = [
+  "getUnscopedAggregateStreamMaxVersion",
+  "getUnscopedAggregateStreamTenant",
+];
+
+const ALLOWED_FILES = new Set([
+  "packages/framework/src/event-store/event-store.ts",
+  "packages/framework/src/event-store/index.ts",
+  "packages/bundled-features/src/tenant/seeding.ts",
+  "packages/bundled-features/src/tier-engine/feature.ts",
+  "packages/bundled-features/src/auth-email-password/__tests__/email-verification.integration.test.ts",
+  "packages/bundled-features/src/auth-email-password/__tests__/password-reset.integration.test.ts",
+  "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
+]);
+
+const REPO_ROOT = `${import.meta.dir}/../../../../..`;
+
+describe("unscoped stream primitives — caller allowlist", () => {
+  test("only seed/system-internal paths reference the existence-oracle primitives", async () => {
+    const glob = new Glob("packages/{framework,bundled-features}/src/**/*.ts");
+    const matches = new Set<string>();
+    for await (const relPath of glob.scan({ cwd: REPO_ROOT })) {
+      const content = await Bun.file(`${REPO_ROOT}/${relPath}`).text();
+      if (RESTRICTED_SYMBOLS.some((symbol) => content.includes(symbol))) {
+        matches.add(relPath);
+      }
+    }
+
+    // Positive control — proves the scan actually ran and found the known
+    // caller, not just that it (silently) found nothing.
+    expect(matches.has("packages/bundled-features/src/tenant/seeding.ts")).toBe(true);
+
+    const offenders = [...matches].filter((relPath) => !ALLOWED_FILES.has(relPath));
+    expect(offenders).toEqual([]);
+  });
+});

package/src/event-store/event-store.ts

@@ -15,29 +15,9 @@ import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
 import { toStoredEvent } from "./row-to-stored-event";
+import type { EventMetadata } from "./types";
 
-export type EventMetadata = {
-  readonly userId: string;
-  readonly requestId?: string;
-  // End-to-end business-operation id. Root HTTP requests get it from the
-  // x-correlation-id header (default: requestId). MSP-applies inherit it
-  // from the triggering event. Lets you trace "which user click caused
-  // this email 3 streams later?".
-  readonly correlationId?: string;
-  // Stored event id that triggered this write. Null for root commands;
-  // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
-  // correlationId forms a causation DAG across aggregate streams.
-  readonly causationId?: string;
-  // Marten-conform free key/value space for app-specific metadata that
-  // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
-  // feature-flag snapshot, geo-region, client SDK version. Persisted into
-  // events.metadata jsonb (no schema change — it's already a free-form
-  // jsonb column), survives upcasters untouched, available on every
-  // StoredEvent.metadata.headers. Framework does not interpret values; the
-  // app reads them when filtering/auditing. Keep values JSON-primitive
-  // (string|number|boolean) so JSON serialization stays bulletproof.
-  readonly headers?: Readonly<Record<string, string | number | boolean>>;
-};
+export type { EventMetadata } from "./types";
 
 export type EventToAppend = {
   readonly aggregateId: string;
@@ -281,9 +261,13 @@ export async function getStreamVersion(
   return selectStreamMaxVersion(db, aggregateId, tenantId);
 }
 
-/** MAX(version) for one aggregate — no tenant filter. Used by seed idempotency. */
+/** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
+ *  a caller can probe whether an aggregateId has any events regardless of tenant
+ *  membership. Only call from seed/system-internal paths (idempotency checks
+ *  against a known aggregateId) — never from a handler reachable with
+ *  caller-controlled input. */
 // @wrapper-known semantic-alias
-export async function getAggregateStreamMaxVersion(
+export async function getUnscopedAggregateStreamMaxVersion(
   db: DbRunner,
   aggregateId: string,
 ): Promise<number> {
@@ -291,10 +275,11 @@ export async function getAggregateStreamMaxVersion(
 }
 
 /** Stream tenant of an aggregate (the tenant_id its events live under), with no
- *  membership/tenant filter. Recovers the write target for a systemScope
- *  aggregate whose stream tenant isn't one of the subject's memberships.
- *  Returns null for unknown streams. */
-export async function getAggregateStreamTenant(
+ *  membership/tenant filter. SECURITY: existence-oracle, same caveat as
+ *  getUnscopedAggregateStreamMaxVersion — seed/system-internal use only. Recovers
+ *  the write target for a systemScope aggregate whose stream tenant isn't one of
+ *  the subject's memberships. Returns null for unknown streams. */
+export async function getUnscopedAggregateStreamTenant(
   db: DbRunner,
   aggregateId: string,
   aggregateType: string,
@@ -333,15 +318,19 @@ export async function loadEventsAfterVersion(
 
 // Load every event for an aggregate_type across all tenants. Ordered by
 // (created_at, id) — chronological replay order for projection rebuilds.
-//
-// CAUTION — buffers ALL matching events in memory. Safe for smaller
-// aggregate-types (≤ 100k events), a memory cliff for large stores.
-// For >100k events use `streamAllEventsByType` (yields batchwise).
 // Mostly called from tests today — production rebuild goes through
 // projection-rebuild's own streaming path.
+//
+// Fails loud past LOAD_ALL_EVENTS_ROW_LIMIT rather than silently buffering
+// an unbounded result set — that's the memory cliff this guard exists to
+// prevent.
+export const LOAD_ALL_EVENTS_ROW_LIMIT = 100_000;
+
+/** @deprecated buffers ALL matching events in memory — a memory cliff for large stores. Use `streamAllEventsByType` (yields batchwise) instead. */
 export async function loadAllEventsByType(
   db: DbRunner,
   aggregateType: string,
+  rowLimit: number = LOAD_ALL_EVENTS_ROW_LIMIT,
 ): Promise<readonly StoredEvent[]> {
   const rows = await selectMany<SelectedEvent>(
     db,
@@ -352,8 +341,15 @@ export async function loadAllEventsByType(
         { col: "createdAt", direction: "asc" },
         { col: "id", direction: "asc" },
       ],
+      limit: rowLimit + 1,
     },
   );
+  if (rows.length > rowLimit) {
+    throw new Error(
+      `loadAllEventsByType("${aggregateType}") exceeds ${rowLimit} rows — ` +
+        "use streamAllEventsByType instead of buffering the full result set in memory.",
+    );
+  }
   return rows.map(toStoredEvent);
 }
 

package/src/event-store/events-schema.ts

@@ -15,6 +15,7 @@ import {
 import { unsafePushTables } from "../stack";
 import { createArchivedStreamsTable } from "./archive";
 import { createSnapshotsTable } from "./snapshot";
+import type { EventMetadata } from "./types";
 
 // Event-store schema as a Drizzle table. The typed select/insert path handles
 // most operations; append() for subsequent versions uses raw SQL because
@@ -24,16 +25,6 @@ import { createSnapshotsTable } from "./snapshot";
 // (Redis-backed check + cached-response replay). The event-store itself
 // imposes no idempotency index — a single HTTP request may write N events
 // freely, metadata.requestId is purely a trace marker.
-export type EventMetadata = {
-  readonly userId: string;
-  readonly requestId?: string;
-  readonly correlationId?: string;
-  readonly causationId?: string;
-  // App-specific free key/value (Marten "headers"). Mirror of the canonical
-  // type in event-store.ts — kept duplicate because events-schema must stay
-  // import-cycle-free vs the event-store module.
-  readonly headers?: Readonly<Record<string, string | number | boolean>>;
-};
 
 export const eventsTable = pgTable(
   "kumiko_events",

package/src/event-store/index.ts

@@ -18,10 +18,11 @@ export {
   EVENTS_PUBSUB_CHANNEL,
   type EventMetadata,
   type EventToAppend,
-  getAggregateStreamMaxVersion,
-  getAggregateStreamTenant,
   getEventsHighWaterMark,
   getStreamVersion,
+  getUnscopedAggregateStreamMaxVersion,
+  getUnscopedAggregateStreamTenant,
+  LOAD_ALL_EVENTS_ROW_LIMIT,
   loadAggregate,
   loadAggregateAsOf,
   loadAllEventsByType,

package/src/event-store/types.ts

@@ -0,0 +1,22 @@
+export type EventMetadata = {
+  readonly userId: string;
+  readonly requestId?: string;
+  // End-to-end business-operation id. Root HTTP requests get it from the
+  // x-correlation-id header (default: requestId). MSP-applies inherit it
+  // from the triggering event. Lets you trace "which user click caused
+  // this email 3 streams later?".
+  readonly correlationId?: string;
+  // Stored event id that triggered this write. Null for root commands;
+  // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
+  // correlationId forms a causation DAG across aggregate streams.
+  readonly causationId?: string;
+  // Marten-conform free key/value space for app-specific metadata that
+  // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
+  // feature-flag snapshot, geo-region, client SDK version. Persisted into
+  // events.metadata jsonb (no schema change — it's already a free-form
+  // jsonb column), survives upcasters untouched, available on every
+  // StoredEvent.metadata.headers. Framework does not interpret values; the
+  // app reads them when filtering/auditing. Keep values JSON-primitive
+  // (string|number|boolean) so JSON serialization stays bulletproof.
+  readonly headers?: Readonly<Record<string, string | number | boolean>>;
+};

package/src/files/__tests__/in-memory-provider.contract.test.ts

@@ -0,0 +1,4 @@
+import { describeFileProviderContract } from "../../testing/file-provider-contract";
+import { createInMemoryFileProvider } from "../in-memory-provider";
+
+describeFileProviderContract("InMemoryFileProvider", () => createInMemoryFileProvider());

package/src/files/file-handle.ts

@@ -10,27 +10,10 @@
 // suffix before the file extension — `foo/bar.jpg` + `"medium"` →
 // `foo/bar.medium.jpg`. Stable, reversible, no extra lookup tables.
 
+import type { FileContext, FileHandle } from "@cosmicdrift/kumiko-types/file-handle-types";
 import type { FileStorageProvider } from "./types";
 
-export type FileHandle = {
-  readonly key: string;
-  read(): Promise<Uint8Array>;
-  write(data: Uint8Array, mimeType?: string): Promise<void>;
-  delete(): Promise<void>;
-  exists(): Promise<boolean>;
-  // Produce a handle for a derived key (e.g. a thumbnail). Does not touch
-  // storage; only computes the key. Writing to the derived handle is the
-  // caller's job.
-  derive(suffix: string): FileHandle;
-};
-
-// The `ctx.files` service — a factory that materialises a FileHandle for a
-// storage key. One per request/event, bound to a single tenant: the provider
-// is resolved per-tenant through file-foundation, so uploads, ctx.files and the
-// GDPR jobs all hit the same store by construction.
-export type FileContext = {
-  ref(key: string): FileHandle;
-};
+export type { FileContext, FileHandle };
 
 // `getProvider` is a lazily-resolved, memoized accessor — the provider is
 // resolved (config + s3.secretAccessKey secret read) only when a handle method