@cosmicdrift/kumiko-framework 0.320.0 → 0.321.0

package/src/engine/feature-ast/extractors/resolve-import.ts

@@ -0,0 +1,187 @@
+// Syntactic cross-file resolution for feature-ast identifier extractors.
+// Deliberately avoids ts-morph's symbol/type-checker APIs (getSymbol,
+// getDefinitionNodes, getModuleSpecifierSourceFile, ...) — those build a full
+// TypeScript program on first use, which against this repo's workspace
+// packages pulls in ~1000 source files and costs seconds instead of
+// milliseconds.
+import type {
+  Node,
+  ParameterDeclaration,
+  SourceFile,
+  Statement,
+  VariableDeclaration,
+} from "ts-morph";
+import { SyntaxKind, ts } from "ts-morph";
+
+const MODULE_RESOLUTION_OPTIONS: ts.CompilerOptions = {
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  module: ts.ModuleKind.ESNext,
+  target: ts.ScriptTarget.ESNext,
+};
+
+const MAX_RESOLUTION_DEPTH = 24;
+
+export function resolveModuleFile(fromFile: SourceFile, specifier: string): SourceFile | undefined {
+  const project = fromFile.getProject();
+  // The project's own host, not ts.sys: it honours an in-memory file system
+  // (Designer) and exists outside Node.
+  const resolved = ts.resolveModuleName(
+    specifier,
+    fromFile.getFilePath(),
+    MODULE_RESOLUTION_OPTIONS,
+    project.getModuleResolutionHost(),
+  );
+  const resolvedFileName = resolved.resolvedModule?.resolvedFileName;
+  if (!resolvedFileName) return undefined;
+  // A declaration file has no initializers to read. Installed packages that
+  // ship .ts sources (the @cosmicdrift/* packages in a consumer repo) stay
+  // resolvable, as they were via the type checker.
+  if (resolvedFileName.endsWith(".d.ts")) return undefined;
+  return fromFile.getProject().addSourceFileAtPathIfExists(resolvedFileName);
+}
+
+export function findImportBindingForLocalName(
+  sourceFile: SourceFile,
+  localName: string,
+): { readonly moduleSpecifier: string; readonly importedName: string } | undefined {
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    const named = importDecl
+      .getNamedImports()
+      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === localName);
+    if (!named) continue;
+    return {
+      moduleSpecifier: importDecl.getModuleSpecifierValue(),
+      importedName: named.getName(),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * `visited` keys on `${filePath}#${name}`, not path alone — aliasing can
+ * legally re-export a different name from the same file — and doubles as
+ * the cycle guard; `depth` backstops pathological non-cyclic chains.
+ */
+export function resolveExportedVariable(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string> = new Set(),
+  depth = 0,
+): VariableDeclaration | undefined {
+  if (depth > MAX_RESOLUTION_DEPTH) return undefined;
+  const key = `${file.getFilePath()}#${exportedName}`;
+  if (visited.has(key)) return undefined;
+  visited.add(key);
+
+  const directDecl = file.getVariableDeclaration(exportedName);
+  if (directDecl?.getVariableStatement()?.hasExportKeyword()) return directDecl;
+
+  const namedExportMatch = resolveViaNamedExportSpecifier(file, exportedName, visited, depth);
+  if (namedExportMatch) return namedExportMatch;
+
+  return resolveViaStarExport(file, exportedName, visited, depth);
+}
+
+function resolveViaNamedExportSpecifier(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    const specifier = exportDecl
+      .getNamedExports()
+      .find((spec) => (spec.getAliasNode()?.getText() ?? spec.getName()) === exportedName);
+    if (!specifier) continue;
+    const originalName = specifier.getName();
+
+    if (!exportDecl.hasModuleSpecifier()) {
+      const resolved = resolveLocalExportBinding(file, originalName, visited, depth);
+      if (resolved) return resolved;
+      continue;
+    }
+
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, originalName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+function resolveLocalExportBinding(
+  file: SourceFile,
+  originalName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  const localDecl = file.getVariableDeclaration(originalName);
+  if (localDecl) return localDecl;
+  const binding = findImportBindingForLocalName(file, originalName);
+  if (!binding) return undefined;
+  const target = resolveModuleFile(file, binding.moduleSpecifier);
+  if (!target) return undefined;
+  return resolveExportedVariable(target, binding.importedName, visited, depth + 1);
+}
+
+function resolveViaStarExport(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    if (!exportDecl.hasModuleSpecifier()) continue;
+    if (exportDecl.getNamedExports().length > 0) continue;
+    if (exportDecl.getNamespaceExport()) continue; // `export * as ns from "./m"` is not a re-export target.
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, exportedName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+export function findScopedVariableDeclaration(
+  identifier: Node,
+  name: string,
+): VariableDeclaration | undefined {
+  for (const ancestor of [identifier, ...identifier.getAncestors()]) {
+    const params = getShadowingParameters(ancestor);
+    if (params?.some((p) => p.getName() === name)) return undefined;
+
+    const statements = getDirectStatements(ancestor);
+    if (!statements) continue;
+    for (const stmt of statements) {
+      const varStmt = stmt.asKind(SyntaxKind.VariableStatement);
+      if (!varStmt) continue;
+      const decl = varStmt
+        .getDeclarationList()
+        .getDeclarations()
+        .find((d) => d.getName() === name);
+      if (decl) return decl;
+    }
+  }
+  return undefined;
+}
+
+function getShadowingParameters(node: Node): readonly ParameterDeclaration[] | undefined {
+  const fn =
+    node.asKind(SyntaxKind.ArrowFunction) ??
+    node.asKind(SyntaxKind.FunctionExpression) ??
+    node.asKind(SyntaxKind.FunctionDeclaration);
+  return fn?.getParameters();
+}
+
+function getDirectStatements(node: Node): readonly Statement[] | undefined {
+  const block = node.asKind(SyntaxKind.Block);
+  if (block) return block.getStatements();
+  const sourceFile = node.asKind(SyntaxKind.SourceFile);
+  if (sourceFile) return sourceFile.getStatements();
+  return undefined;
+}

package/src/engine/feature-ast/extractors/shared.ts

@@ -2,6 +2,12 @@ import type { CallExpression, Node, ObjectLiteralExpression } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
+import {
+  findImportBindingForLocalName,
+  findScopedVariableDeclaration,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "./resolve-import";
 
 export type ExtractOutput<TPattern> =
   | { readonly kind: "pattern"; readonly pattern: TPattern }
@@ -200,28 +206,31 @@ function unwrapLiteralInitializer(node: Node): string | undefined {
 /**
  * Resolves a bare Identifier to the string value of its declaration's
  * initializer (`export const EXT_TENANT_DATA = "tenant-data" as const`),
- * following imports via ts-morph's definition lookup — works across files
- * and packages against a real-filesystem Project (see #1008 precedent in
- * parse.ts). Only descends into VariableDeclaration initializers; a
- * function/class/type definition or an unresolvable import (external
- * package, ambient declaration) yields undefined, never a throw.
+ * following imports syntactically across files and packages against a
+ * real-filesystem Project without ever building a TypeScript program (see
+ * resolve-import.ts). Only descends into VariableDeclaration initializers; a
+ * function/class/type definition or an unresolvable import yields undefined,
+ * never a throw.
  */
 function resolveIdentifierToStringLiteral(identifier: Node): string | undefined {
   const id = identifier.asKind(SyntaxKind.Identifier);
   if (!id) return undefined;
-  let defs: readonly Node[];
-  try {
-    defs = id.getDefinitionNodes();
-  } catch {
-    return undefined;
-  }
-  for (const def of defs) {
-    const init = def.asKind(SyntaxKind.VariableDeclaration)?.getInitializer();
-    if (!init) continue;
-    const value = unwrapLiteralInitializer(init);
+  const name = id.getText();
+
+  const scoped = findScopedVariableDeclaration(id, name);
+  if (scoped) {
+    const init = scoped.getInitializer();
+    const value = init ? unwrapLiteralInitializer(init) : undefined;
     if (value !== undefined) return value;
   }
-  return undefined;
+
+  const binding = findImportBindingForLocalName(id.getSourceFile(), name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(id.getSourceFile(), binding.moduleSpecifier);
+  if (!targetFile) return undefined;
+  const decl = resolveExportedVariable(targetFile, binding.importedName);
+  const init = decl?.getInitializer();
+  return init ? unwrapLiteralInitializer(init) : undefined;
 }
 
 /**
@@ -279,9 +288,7 @@ export function resolveSameFileObjectLiteral(node: Node): ObjectLiteralExpressio
   if (direct) return direct;
   const identifier = node.asKind(SyntaxKind.Identifier);
   if (!identifier) return undefined;
-  const valueDecl = identifier.getSymbol()?.getValueDeclaration();
-  const fromSymbol = valueDecl?.asKind(SyntaxKind.VariableDeclaration);
-  const varDecl = fromSymbol ?? node.getSourceFile().getVariableDeclaration(identifier.getText());
+  const varDecl = findScopedVariableDeclaration(identifier, identifier.getText());
   return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
 }
 

package/src/engine/feature-ast/parse.ts

@@ -73,7 +73,9 @@ import {
   extractWorkspace,
   extractWriteHandler,
   findFunctionLiteral,
+  findImportBindingForLocalName,
   readObjectPropertyInitializer,
+  resolveModuleFile,
   resolveSameFileObjectLiteral,
 } from "./extractors";
 import type { FeaturePattern, UnknownPattern } from "./patterns";
@@ -296,13 +298,13 @@ function walkSetupCallback(
 /**
  * Resolves a bare call like `registerShowPonyScreens(r)` to the callee's
  * body + its own parameter name for the registrar slot. The callee may be
- * declared in the same file (function declaration, or a const initialized
- * with an arrow/function expression), or imported by name from another
- * file — resolved via the module specifier's SourceFile (#1008; only
- * works against a real-filesystem Project, e.g. parseFeatureFile's. The
- * in-memory Designer Project has no files to resolve against and
- * getModuleSpecifierSourceFile() returns undefined there, same as any
- * other unresolvable reference).
+ * declared in the same file, or imported by name from another file —
+ * resolved syntactically via resolveModuleFile, which only works against a
+ * real-filesystem Project; the in-memory Designer Project has no files to
+ * resolve against and returns undefined there, same as any other
+ * unresolvable reference. Does not follow re-exports in the target file — a
+ * wrapper function is expected to be declared directly in the module it's
+ * imported from.
  */
 function resolveRegistrarWrapperCall(
   call: CallExpression,
@@ -328,21 +330,12 @@ function resolveRegistrarWrapperCall(
   const local = resolveWrapperDeclarationInFile(callSourceFile, name, argIndex);
   if (local) return { ...local, sourceFile: callSourceFile };
 
-  const importDecl = callSourceFile
-    .getImportDeclarations()
-    .find((d) =>
-      d.getNamedImports().some((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name),
-    );
-  if (!importDecl) return undefined;
-  const exportedName =
-    importDecl
-      .getNamedImports()
-      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name)
-      ?.getName() ?? name;
-  const targetFile = importDecl.getModuleSpecifierSourceFile();
+  const binding = findImportBindingForLocalName(callSourceFile, name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(callSourceFile, binding.moduleSpecifier);
   if (!targetFile) return undefined; // Unresolvable: in-memory project, external package, or missing file.
 
-  const imported = resolveWrapperDeclarationInFile(targetFile, exportedName, argIndex);
+  const imported = resolveWrapperDeclarationInFile(targetFile, binding.importedName, argIndex);
   return imported ? { ...imported, sourceFile: targetFile } : undefined;
 }
 

package/src/engine/steps/webhook-send.ts

@@ -25,9 +25,11 @@ export {
 
 type WebhookHttpMethod = "POST" | "PUT" | "PATCH";
 
+// Name inside the tenant-owned secrets namespace
+// `step-dispatcher:webhook-auth.<secret>` (secrets feature).
 type WebhookAuth =
-  | { readonly kind: "bearer"; readonly secretRef: string }
-  | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+  | { readonly kind: "bearer"; readonly secret: string }
+  | { readonly kind: "header"; readonly name: string; readonly secret: string };
 
 type WebhookSendArgs = {
   readonly url: StepResolver<string>;

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

@@ -0,0 +1,236 @@
+// transferAggregateStreams — the event store's own tenant-transfer primitive.
+// Pins: events, snapshots and the archive marker all move together; a system
+// aggregate.transferred event lands per moved aggregate; an empty id list is
+// a no-op; an id with no events under the given tenant/aggregateType is left
+// untouched; an aggregate belonging to an unrelated third tenant is never
+// touched by another tenant's move; an archive marker for a DIFFERENT
+// aggregate type sharing the same aggregate id stays behind.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import type { TenantId } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { generateId as uuid } from "../../utils";
+import {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  append,
+  archiveStream,
+  isStreamArchived,
+  loadAggregate,
+  loadLatestSnapshot,
+  saveSnapshot,
+  transferAggregateStreams,
+} from "../index";
+
+let bun: BunTestDb;
+const sourceTenant = uuid() as TenantId;
+const destinationTenant = uuid() as TenantId;
+const otherTenant = uuid() as TenantId;
+const userId = uuid();
+const transferredBy = uuid();
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  bun = await createTestDb();
+});
+
+afterAll(async () => {
+  await bun.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(bun.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams RESTART IDENTITY`,
+  );
+});
+
+async function seedAggregate(tenantId: TenantId, aggregateType = "counter"): Promise<string> {
+  const aggregateId = uuid();
+  await append(bun.db, {
+    aggregateId,
+    aggregateType,
+    tenantId,
+    expectedVersion: 0,
+    type: "counter.incremented",
+    payload: { by: 1 },
+    metadata: { userId },
+  });
+  return aggregateId;
+}
+
+// Each `aggregate.transferred` event lives on its OWN fresh stream (see
+// transfer.ts) — the row's own `aggregate_id` column is that stream's id,
+// not the moved aggregate's. The moved aggregate's id is in the payload.
+async function transferredEvents(tenantId: TenantId): Promise<readonly Record<string, unknown>[]> {
+  const rows = (await asRawClient(bun.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE tenant_id = $1 AND aggregate_type = $2 AND type = $3`,
+    [tenantId, AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE],
+  )) as ReadonlyArray<{ payload: Record<string, unknown> }>;
+  return rows.map((row) => row.payload);
+}
+
+describe("transferAggregateStreams", () => {
+  test("moves events, drops the snapshot, carries the archive marker, and emits one aggregate.transferred event per moved aggregate", async () => {
+    const first = await seedAggregate(sourceTenant);
+    const second = await seedAggregate(sourceTenant);
+    await saveSnapshot(bun.db, {
+      aggregateId: first,
+      tenantId: sourceTenant,
+      aggregateType: "counter",
+      version: 1,
+      state: { count: 1 },
+    });
+    await archiveStream(bun.db, {
+      tenantId: sourceTenant,
+      aggregateId: first,
+      aggregateType: "counter",
+      archivedBy: "ops",
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [first, second],
+      transferredBy,
+    });
+    expect(movedCount).toBe(2);
+
+    // Events: gone from the source tenant, present under the destination.
+    expect(
+      await loadAggregate(bun.db, first, sourceTenant, { includeArchived: true }),
+    ).toHaveLength(0);
+    expect(await loadAggregate(bun.db, second, sourceTenant)).toHaveLength(0);
+    const firstEvents = await loadAggregate(bun.db, first, destinationTenant, {
+      includeArchived: true,
+    });
+    expect(firstEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+    const secondEvents = await loadAggregate(bun.db, second, destinationTenant);
+    expect(secondEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+
+    // Snapshot dropped from the source tenant, not recreated anywhere.
+    expect(await loadLatestSnapshot(bun.db, first, sourceTenant)).toBeNull();
+    expect(await loadLatestSnapshot(bun.db, first, destinationTenant)).toBeNull();
+
+    // Archive marker moved with the stream.
+    expect(await isStreamArchived(bun.db, sourceTenant, first)).toBe(false);
+    expect(await isStreamArchived(bun.db, destinationTenant, first)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, second)).toBe(false);
+
+    // One system event per moved aggregate, in the destination tenant.
+    const events = await transferredEvents(destinationTenant);
+    expect(events).toHaveLength(2);
+    const byAggregateId = new Map(events.map((payload) => [payload["aggregateId"], payload]));
+    expect(byAggregateId.get(first)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: first,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+    expect(byAggregateId.get(second)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: second,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+  });
+
+  test("an empty id list is a no-op", async () => {
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an id with no events under this tenant/aggregateType is left untouched and gets no event", async () => {
+    const untouched = uuid();
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [untouched],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await loadAggregate(bun.db, untouched, sourceTenant)).toHaveLength(0);
+    expect(await loadAggregate(bun.db, untouched, destinationTenant)).toHaveLength(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an aggregate under an unrelated third tenant with the same id is untouched", async () => {
+    const sharedId = uuid();
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: otherTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+
+    const otherTenantEvents = await loadAggregate(bun.db, sharedId, otherTenant);
+    expect(otherTenantEvents).toHaveLength(1);
+    expect(await loadAggregate(bun.db, sharedId, sourceTenant)).toHaveLength(0);
+  });
+
+  test("an archived marker for a different aggregate type sharing the moved aggregate's id stays in the source tenant", async () => {
+    const sharedId = uuid();
+    // `append()` shares its version-conflict check across the plain
+    // aggregateId, so a real "widget" stream can't coexist with a real
+    // "counter" stream under the same id/tenant — fabricate the archived
+    // marker directly (the primary verifier of the event-store primitive,
+    // same reasoning as guard-event-store-writes' own __tests__ exclusion)
+    // to prove the WHERE clause's aggregate_type filter, not the stream's
+    // version-numbering.
+    await asRawClient(bun.db).unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_by") VALUES ($1, $2, $3, $4)`,
+      [sourceTenant, sharedId, "widget", "ops"],
+    );
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+    expect(movedCount).toBe(1);
+
+    expect(await isStreamArchived(bun.db, sourceTenant, sharedId)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, sharedId)).toBe(false);
+  });
+});

package/src/event-store/index.ts

@@ -53,6 +53,12 @@ export {
   saveSnapshot,
   snapshotsTable,
 } from "./snapshot";
+export {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  type TransferAggregateStreamsArgs,
+  transferAggregateStreams,
+} from "./transfer";
 export {
   type EventUpcasters,
   makeUpcastCtx,

package/src/event-store/transfer.ts

@@ -0,0 +1,84 @@
+// The event store's own tenant-transfer primitive: the ONE place allowed to
+// move a stream across the tenant boundary (enforced by
+// guard-event-store-writes' allowlist). Each move leaves an audit event in
+// the destination tenant.
+//
+// Runs entirely on the caller-supplied DbRunner, so the move rides whatever
+// transaction the caller is already inside (tenant-handover's claim handler
+// commits it together with the root row's ownership write — see
+// move-entity-graph.ts's file header for why that matters).
+
+import type { DbRunner } from "../db";
+import {
+  deleteSnapshotsForAggregates,
+  transferArchivedStreamRows,
+  transferEventRows,
+} from "../db/queries/event-store-transfer";
+import type { TenantId } from "../engine/types";
+import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
+import { generateId } from "../utils/ids";
+import { append } from "./event-store";
+
+export const AGGREGATE_TRANSFER_STREAM_TYPE = "aggregate-transfer";
+export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
+
+export type TransferAggregateStreamsArgs = {
+  readonly sourceTenantId: TenantId;
+  readonly destinationTenantId: TenantId;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+  readonly transferredBy: string;
+};
+
+// Moves one aggregate type's event history, drops its cached snapshots, and
+// carries any archive marker across the tenant boundary. Returns the number
+// of aggregates that actually had events (and therefore moved) — an id in
+// `aggregateIds` with no events under `sourceTenantId`/`aggregateType`
+// contributes nothing and gets no follow-up event.
+export async function transferAggregateStreams(
+  db: DbRunner,
+  args: TransferAggregateStreamsArgs,
+): Promise<number> {
+  if (args.aggregateIds.length === 0) return 0;
+
+  const movedAggregateIds = await transferEventRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: args.aggregateIds,
+  });
+  if (movedAggregateIds.length === 0) return 0;
+
+  await deleteSnapshotsForAggregates(db, {
+    tenantId: args.sourceTenantId,
+    aggregateIds: movedAggregateIds,
+  });
+  await transferArchivedStreamRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: movedAggregateIds,
+  });
+
+  for (const aggregateId of movedAggregateIds) {
+    // A fresh, own stream — not an append onto the moved aggregate's own
+    // stream — so the marker never bumps the moved aggregate's version or
+    // shows up when a projection replays that aggregate's history.
+    await append(db, {
+      aggregateId: generateId(),
+      aggregateType: AGGREGATE_TRANSFER_STREAM_TYPE,
+      tenantId: args.destinationTenantId,
+      expectedVersion: 0,
+      type: AGGREGATE_TRANSFERRED_EVENT_TYPE,
+      payload: {
+        aggregateType: args.aggregateType,
+        aggregateId,
+        sourceTenantId: args.sourceTenantId,
+        destinationTenantId: args.destinationTenantId,
+      },
+      metadata: { userId: args.transferredBy },
+    });
+  }
+
+  return movedAggregateIds.length;
+}