@better-schemic/core 0.1.0-alpha.1

package/src/cli-kit/config.ts

@@ -0,0 +1,226 @@
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import type { BetterSchemicConfig } from "@better-schemic/core/config";
+import { createJiti } from "jiti";
+import type { ConnectionConfigBase, ResolveContext } from "../connection";
+
+// `better-schemic.ts` is the scaffolded name (the config IS the app's DB module — `betterSchemic.connect()`);
+// the legacy `schemic.config.*` / `schemic.ts` spellings keep working. Checked LAST + shape-guarded, so an unrelated
+// `./better-schemic.ts` helper module in a project never shadows a real `better-schemic.config.ts`.
+const CONFIG_NAMES = [
+  "better-schemic.config.ts",
+  "better-schemic.config.mjs",
+  "better-schemic.config.js",
+  "better-schemic.ts",
+  // Legacy aliases (pre-rename) — still discovered, after the canonical names.
+  "schemic.config.ts",
+  "schemic.config.mjs",
+  "schemic.config.js",
+  "schemic.ts",
+];
+
+/**
+ * Is the schema path a single file (vs a directory of schema modules)? Determined by `stat` when
+ * it exists, else inferred from a `.ts`/`.js`-ish extension.
+ */
+function schemaIsFilePath(path: string): boolean {
+  if (existsSync(path)) return statSync(path).isFile();
+  return /\.[mc]?[jt]s$/.test(path);
+}
+
+/**
+ * Load `.env(.local)` from the project root into `process.env` so the config's own explicit
+ * `process.env.X` reads resolve when run under node (bun loads `.env` itself). Does not override
+ * already-set variables, so shell env still wins; load `.env.local` first so it beats `.env`.
+ */
+function loadDotEnv(dir: string): void {
+  const proc = process as typeof process & {
+    loadEnvFile?: (path: string) => void;
+  };
+  if (typeof proc.loadEnvFile !== "function") return;
+  for (const name of [".env.local", ".env"]) {
+    const file = resolve(dir, name);
+    if (!existsSync(file)) continue;
+    try {
+      proc.loadEnvFile(file);
+    } catch {
+      // ignore a malformed .env file
+    }
+  }
+}
+
+/**
+ * A resolved, per-CONNECTION config — the dialect-NEUTRAL shape every command operates on (one
+ * connection at a time). `params` are the driver-specific connection params (opaque to core; the
+ * driver's `connect` reads them). Built by resolving one entry of `config.connections`.
+ */
+export interface ResolvedConfig {
+  /** Resolved connection name (e.g. `default`, or `tenants:abc` within a collection). */
+  connection: string;
+  /** The driver this connection uses (the package the CLI dynamically loads). */
+  driver: string;
+  /** Project root (the directory containing the config file). */
+  root: string;
+  /** Absolute schema path — a single `.ts` module, or a directory of them. */
+  schemaPath: string;
+  /** Whether `schemaPath` is a single file (vs a directory of schema modules). */
+  schemaIsFile: boolean;
+  /** Absolute migrations directory (per connection's schema). */
+  migrationsDir: string;
+  /** Absolute migration meta directory (the snapshot). */
+  metaDir: string;
+  /** Name of the table that records applied migrations. */
+  migrationsTable: string;
+  /** Driver-specific connection params (url/namespace/… or whatever the driver defines). Opaque to core. */
+  params: Record<string, unknown>;
+  /** Optional seed script (project-level). */
+  seed?: string;
+}
+
+/**
+ * A jiti instance for loading the project's TS/ESM modules. Caches are off so `--watch` re-reads
+ * edited schema files. (Bare deps like `@better-schemic/core` are native-imported, so registries stay shared.)
+ */
+export function makeJiti() {
+  return createJiti(import.meta.url, {
+    interopDefault: true,
+    fsCache: false,
+    moduleCache: false,
+  });
+}
+
+/** Find + load `better-schemic.ts` / `better-schemic.config.ts` (legacy `schemic.*` aliases included) into the dialect-neutral {@link BetterSchemicConfig}. */
+export async function loadProject(opts?: {
+  config?: string;
+  cwd?: string;
+}): Promise<{ config: BetterSchemicConfig; root: string }> {
+  const cwd = opts?.cwd ?? process.cwd();
+  const candidates = opts?.config
+    ? [resolve(cwd, opts.config)]
+    : CONFIG_NAMES.map((n) => resolve(cwd, n)).filter((p) => existsSync(p));
+  if (!candidates.length || !existsSync(candidates[0])) {
+    throw new Error(
+      "No better-schemic.ts / better-schemic.config.ts found — run `better-schemic init` first.",
+    );
+  }
+  const jiti = makeJiti();
+  for (const path of candidates) {
+    const root = dirname(path);
+    loadDotEnv(root); // populate process.env before the config module's explicit reads
+    const loaded = (await jiti.import(path)) as {
+      default?: BetterSchemicConfig;
+      betterSchemic?: BetterSchemicConfig;
+      schemic?: BetterSchemicConfig;
+    } & BetterSchemicConfig;
+    // Accept a default export OR the named `betterSchemic` export (legacy: `schemic`) — the scaffolded
+    // form is the NAMED one (`export const betterSchemic = defineConfig(...)`), so app code auto-imports
+    // a deterministic identifier (`import { betterSchemic } from "./better-schemic.config"` ->
+    // `betterSchemic.connect()`). Selected by SHAPE, not presence: jiti's interopDefault makes
+    // `loaded.default` a truthy proxy even when the module has no real default export, so a presence
+    // chain would shadow the named export.
+    const config = [
+      loaded.default,
+      loaded.betterSchemic,
+      loaded.schemic,
+      loaded,
+    ].find(
+      (c): c is BetterSchemicConfig =>
+        !!c && typeof c === "object" && "connections" in c,
+    );
+    if (config?.connections && Object.keys(config.connections).length > 0) {
+      return { config, root };
+    }
+    // An AUTO-discovered bare `better-schemic.ts` (or legacy `schemic.ts`) without a connections map is
+    // an unrelated helper module, not a config — skip it (an explicitly-passed or `*.config.*` file
+    // still errors loudly).
+    if (
+      !opts?.config &&
+      (basename(path) === "better-schemic.ts" ||
+        basename(path) === "schemic.ts")
+    )
+      continue;
+    throw new Error(`Invalid config at ${path}: expected a "connections" map.`);
+  }
+  throw new Error(
+    'No Better-schemic config found — ./better-schemic.ts exists but doesn\'t export a config with a "connections" map. Run `better-schemic init`, or export one via defineConfig.',
+  );
+}
+
+/**
+ * Build the {@link ResolvedConfig} for one connection of the project. `ctx` carries the lazy
+ * cross-connection proxy + CLI `--arg`s (the CLI provides the real one; a static connection ignores
+ * it). A resolver returning a COLLECTION yields one ResolvedConfig per keyed entry.
+ *
+ * NOTE (WIP — multi-connection): the full resolution engine (lazy proxy DAG, `--connection`/`--all`
+ * addressing, collection fan-out) lives in `@better-schemic/cli`; this builder handles a single resolved
+ * connection config. See docs/MULTI-CONNECTION.md.
+ */
+export function resolveConnectionConfig(
+  config: BetterSchemicConfig,
+  connection: string,
+  conn: ConnectionConfigBase,
+  driver: string,
+  root: string,
+): ResolvedConfig {
+  const { schema, migrations, key, ...params } = conn;
+  const schemaPath = resolve(root, schema);
+  // Default migrations dir is RELATIVE TO THE SCHEMA (the documented contract): the sibling
+  // `migrations` dir next to the schema dir (or next to a single-file schema). For the standard
+  // scaffold (`schema: "./database/schema"`) that is `./database/migrations`, unchanged; a nested
+  // schema (`./src/database/schema`) correctly gets `./src/database/migrations` instead of a
+  // root-fixed default that split state across two locations.
+  const migrationsDir = migrations
+    ? resolve(root, migrations)
+    : resolve(schemaPath, "..", "migrations");
+  return {
+    connection: key ? `${connection}:${key}` : connection,
+    driver,
+    root,
+    schemaPath,
+    schemaIsFile: schemaIsFilePath(schemaPath),
+    migrationsDir,
+    metaDir: resolve(migrationsDir, "meta"),
+    migrationsTable: config.migrationsTable ?? "_migrations",
+    params: params as Record<string, unknown>,
+    seed: config.seed,
+  };
+}
+
+/**
+ * Load the project and resolve the DEFAULT connection to a {@link ResolvedConfig} — the single-
+ * connection convenience path. (Multi-connection addressing + resolver context are added by the CLI;
+ * here a static default connection is resolved with an empty context.)
+ */
+export async function loadConfig(opts?: {
+  config?: string;
+  cwd?: string;
+}): Promise<ResolvedConfig> {
+  const { config, root } = await loadProject(opts);
+  const names = Object.keys(config.connections);
+  const name =
+    config.defaultConnection ?? (names.length === 1 ? names[0] : "default");
+  const entry = config.connections[name];
+  if (!entry) {
+    throw new Error(
+      `No connection named "${name}". Set "defaultConnection" or pass --connection. Known: ${names.join(", ")}.`,
+    );
+  }
+  const ctx: ResolveContext = { connections: {}, env: process.env };
+  const resolved = await entry.resolve(ctx);
+  if (resolved.length !== 1) {
+    throw new Error(
+      `Connection "${name}" resolved to ${resolved.length} connections (a collection); pass --connection ${name}:<key>.`,
+    );
+  }
+  return resolveConnectionConfig(config, name, resolved[0], entry.driver, root);
+}
+
+/** Per-command connection flag overrides (CLI args, applied by the driver over `params`). */
+export interface ConnectionOverrides {
+  url?: string;
+  namespace?: string;
+  database?: string;
+  username?: string;
+  password?: string;
+  authLevel?: string;
+}

package/src/cli-kit/diff.ts

@@ -0,0 +1,273 @@
+// The DIALECT-FREE diff DISPLAY + shared types. The SurrealDB statement-diff engine (buildSnapshot/
+// diffSnapshots/renderMigration) lives in `./surreal-diff` and is invoked through the driver; this
+// module is what the CLI shell uses to RENDER any driver's Diff (git-style file groups, word-diff,
+// unified patch, kind summaries). Dialect-free: `kind` is an opaque string, not a Surreal kind union.
+import type { KindRegistry } from "../kind";
+import type { SecretRef } from "../secrets";
+import { colorEnabled, style } from "./style";
+
+/**
+ * One object's change, for display. `kind` is the object kind, `table` its owner (a table name,
+ * or the object's own name for db-level objects). `add` carries the new DDL; `remove` carries the
+ * `REMOVE` statement (`ddl`) plus the dropped object's prior DDL (`old`, for the unified patch);
+ * `change` pairs old↔new.
+ */
+export type DiffItem = {
+  key: string;
+  table: string;
+  /** Dialect-defined object kind (e.g. "table"/"field"/"index") — opaque to the display. */
+  kind: string;
+  /** The source file this object lives in (or lived in, for a removal). Absent if unknown. */
+  file?: string;
+} & (
+  | { op: "add"; ddl: string }
+  | { op: "remove"; ddl: string; old: string }
+  | { op: "change"; before: string; after: string }
+);
+
+export interface Diff {
+  up: string[];
+  down: string[];
+  /**
+   * Apply-time secret bindings: `$param` name -> a write-only {@link SecretRef} (e.g. `env("X")`).
+   * Populated by a driver whose DDL emits secret placeholders (SurrealDB `DEFINE ACCESS … KEY $param`).
+   * MODEL 1: stored in the migration so it replays without the live schema; the **value never appears
+   * here** — the apply layer resolves each ref through a `SecretProvider` and binds it (`db.query(ddl,
+   * resolved)`), so secrets stay out of the schema, snapshot, and migration files. Diff-excluded +
+   * snapshot-omitted, so a redacted secret never reads as drift.
+   */
+  bindings?: Record<string, SecretRef>;
+  /** Structured per-object changes for the human display (word-level diff). */
+  items?: DiffItem[];
+  /** Every desired statement (the `next` schema), for the `--full` context view. */
+  full?: { key: string; table: string; ddl: string }[];
+}
+
+/** `true` if the two snapshots define the same objects with identical DDL. */
+export function isEmptyDiff(diff: Diff): boolean {
+  return diff.up.length === 0;
+}
+
+/**
+ * Inline word-level diff of two statements: shared tokens dim, removed tokens red, added tokens
+ * green (LCS over space-separated tokens). So a changed field shows the whole statement with only
+ * the changed words highlighted.
+ */
+export function tokenDiff(before: string, after: string): string {
+  const a = before.split(" ");
+  const b = after.split(" ");
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    new Array(n + 1).fill(0),
+  );
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i][j] =
+        a[i] === b[j]
+          ? dp[i + 1][j + 1] + 1
+          : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  // With color: red/green/dim. Without (pipe / CI / NO_COLOR): git `--word-diff=plain` markers
+  // `[-removed-]`/`{+added+}` so removed-vs-added is unambiguous and assertable.
+  const colored = colorEnabled();
+  const del = (t: string) => (colored ? style.red(t) : `[-${t}-]`);
+  const ins = (t: string) => (colored ? style.green(t) : `{+${t}+}`);
+  const eq = (t: string) => (colored ? style.dim(t) : t);
+  const out: string[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < m && j < n) {
+    if (a[i] === b[j]) {
+      out.push(eq(a[i]));
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      out.push(del(a[i++]));
+    } else {
+      out.push(ins(b[j++]));
+    }
+  }
+  while (i < m) out.push(del(a[i++]));
+  while (j < n) out.push(ins(b[j++]));
+  return out.join(" ");
+}
+
+/**
+ * Prefix EVERY line of `text` with the diff indicator — statements are multi-line now that drivers
+ * pretty-print display DDL, and a bare continuation line would read as context, not change.
+ */
+function mark(text: string, sign: string, color: (s: string) => string): string {
+  return text
+    .split("\n")
+    .map((l) => color(`  ${sign} ${l}`))
+    .join("\n");
+}
+
+/**
+ * Render one display item: `+`/`-` line for add/remove. A change renders as separate red `-` /
+ * green `+` lines by default, or as a single inline word-diff when `inline` is set (the A/B toggle).
+ */
+function renderItem(it: DiffItem, inline = false): string {
+  if (it.op === "add") return mark(it.ddl, "+", style.green);
+  if (it.op === "remove") return mark(it.ddl, "-", style.red);
+  if (inline)
+    return `    ${tokenDiff(collapseWs(it.before), collapseWs(it.after))}`;
+  return `${mark(it.before, "-", style.red)}\n${mark(it.after, "+", style.green)}`;
+}
+
+/** The inline word-diff is a one-line token view — collapse pretty-printed statements onto it. */
+function collapseWs(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Group diff items by their source file (git-style), so the display reads like a file diff. Items
+ * with no file (an older snapshot, or the live DB) fall back to a per-object group headed by the
+ * object's bare name. Returns groups in first-seen order, each with its header.
+ */
+function groupByFile(
+  items: DiffItem[],
+): { header: string; items: DiffItem[] }[] {
+  const order: string[] = [];
+  const byKey = new Map<string, DiffItem[]>();
+  for (const it of items) {
+    const key = it.file ?? `\0${it.table}`; // \0 can't collide with a real path
+    let group = byKey.get(key);
+    if (!group) {
+      group = [];
+      byKey.set(key, group);
+      order.push(key);
+    }
+    group.push(it);
+  }
+  return order.map((key) => {
+    const group = byKey.get(key) ?? [];
+    return {
+      header: group.find((i) => i.file)?.file ?? group[0].table,
+      items: group,
+    };
+  });
+}
+
+/** Render display items as a git-style file diff: each group headed by its source file path. */
+export function formatItems(items: DiffItem[], inline = false): string {
+  return groupByFile(items)
+    .map((g) =>
+      [
+        style.bold(g.header),
+        ...g.items.map((it) => renderItem(it, inline)),
+      ].join("\n"),
+    )
+    .join("\n\n");
+}
+
+/**
+ * A standard **unified diff** of the change, grouped one section per source file (git-style) — for
+ * piping through a diff viewer (git's pager / delta). Objects with no file fall back to a section
+ * headed by the object's bare name. A statement may be pretty-printed multi-line, so every LINE gets
+ * its own `+`/`-` and the hunk counts count lines, not statements.
+ */
+export function formatPatch(diff: Diff): string {
+  const items = diff.items ?? [];
+  if (!items.length) return "";
+  const out: string[] = [];
+  for (const { header, items: group } of groupByFile(items)) {
+    const lines: string[] = [];
+    let dels = 0;
+    let adds = 0;
+    const push = (text: string, sign: "+" | "-") => {
+      for (const l of text.split("\n")) {
+        lines.push(`${sign}${l}`);
+        if (sign === "+") adds++;
+        else dels++;
+      }
+    };
+    for (const it of group) {
+      if (it.op === "add") push(it.ddl, "+");
+      else if (it.op === "remove") push(it.old, "-");
+      else {
+        push(it.before, "-");
+        push(it.after, "+");
+      }
+    }
+    out.push(
+      `diff --git a/${header} b/${header}`,
+      `--- a/${header}`,
+      `+++ b/${header}`,
+      `@@ -${dels ? 1 : 0},${dels} +${adds ? 1 : 0},${adds} @@`,
+      ...lines,
+    );
+  }
+  return `${out.join("\n")}\n`;
+}
+
+/** `--full`: the whole desired schema — unchanged dim, additions green, changes word-diffed. */
+function formatFull(diff: Diff, inline = false): string {
+  const byKey = new Map((diff.items ?? []).map((it) => [it.key, it]));
+  const out: string[] = [];
+  let prev: string | undefined;
+  for (const f of diff.full ?? []) {
+    if (prev !== undefined && f.table !== prev) out.push("");
+    const it = byKey.get(f.key);
+    if (it?.op === "change") out.push(renderItem(it, inline));
+    else if (it?.op === "add") out.push(mark(f.ddl, "+", style.green));
+    else
+      out.push(
+        f.ddl
+          .split("\n")
+          .map((l) => style.dim(`    ${l}`))
+          .join("\n"),
+      );
+    prev = f.table;
+  }
+  const removed = (diff.items ?? []).filter((it) => it.op === "remove");
+  if (removed.length) {
+    out.push("");
+    for (const it of removed) out.push(renderItem(it, inline));
+  }
+  return out.join("\n");
+}
+
+/** A human-readable view of a diff's forward (and optionally reverse) changes. */
+export function formatDiff(
+  diff: Diff,
+  opts: { down?: boolean; full?: boolean; inline?: boolean } = {},
+): string {
+  if (!diff.up.length) return "No changes.";
+  let out = opts.full
+    ? formatFull(diff, opts.inline)
+    : formatItems(diff.items ?? [], opts.inline);
+  if (opts.down) {
+    const down = diff.down
+      .map((s) =>
+        s
+          .split("\n")
+          .map((l) => style.dim(`  ${l}`))
+          .join("\n"),
+      )
+      .join("\n");
+    out += `\n\n${style.dim("  rollback (down):")}\n${down}`;
+  }
+  return out;
+}
+
+/**
+ * A per-kind breakdown of a set of changes, e.g. `1 Table, 2 Fields`. Counts each item by its
+ * structured `kind` and labels it from the registry's per-kind {@link KindRegistry.display} (singular
+ * when the count is one), so the summary is correct for every dialect — no DDL parsing.
+ */
+export function summarizeKinds(
+  registry: KindRegistry,
+  items: readonly { kind: string }[],
+): string {
+  const counts = new Map<string, number>();
+  for (const it of items) counts.set(it.kind, (counts.get(it.kind) ?? 0) + 1);
+  const parts: string[] = [];
+  for (const [kind, n] of counts) {
+    const d = registry.display(kind);
+    parts.push(`${n} ${n === 1 ? d.label : d.plural}`);
+  }
+  return parts.join(", ");
+}

package/src/cli-kit/filter.ts

@@ -0,0 +1,159 @@
+import type { Command } from "commander";
+import type { KindRegistry, PortableObject } from "../kind";
+import { snapshotKinds, snapshotObjects } from "../kind";
+import type { StoredSnapshot } from "./meta";
+
+/**
+ * Per-kind object filter for `pull`/`diff`/`sync`/`generate`. Each kind is independently
+ * included (optionally name-restricted). `DEFINE ACCESS` is OPT-IN everywhere — excluded
+ * unless `--access` is given — so an introspection (which redacts access signing keys) can't
+ * silently rotate them. Table-scoped objects (fields/indexes/events) follow their table.
+ */
+interface Cat {
+  on: boolean;
+  /** When set, only these names of the kind are included. */
+  names?: Set<string>;
+}
+
+export interface Filter {
+  tables: Cat;
+  functions: Cat;
+  events: Cat;
+  access: Cat;
+}
+
+/** Commander's parse of one `--kind [names]` / `--no-kind` flag: `undefined`/`true`/string/`false`. */
+type FlagValue = string | boolean | undefined;
+
+export interface FilterOpts {
+  tables?: FlagValue;
+  functions?: FlagValue;
+  events?: FlagValue;
+  access?: FlagValue;
+}
+
+function cat(v: FlagValue, defaultOn: boolean): Cat {
+  if (v === undefined) return { on: defaultOn };
+  if (v === false) return { on: false };
+  if (v === true) return { on: true };
+  const names = new Set(
+    v
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  return names.size ? { on: true, names } : { on: true };
+}
+
+/** Build a {@link Filter} from CLI flags. Access is opt-in (`--access`); the rest default to on. */
+export function parseFilter(o: FilterOpts): Filter {
+  return {
+    tables: cat(o.tables, true),
+    functions: cat(o.functions, true),
+    events: cat(o.events, true),
+    access: cat(o.access, false), // DEFINE ACCESS is explicit everywhere — see module note.
+  };
+}
+
+/** Attach the per-kind `--tables/--functions/--events/--access [names]` (+ `--no-*`) options. */
+export function kindFlags(cmd: Command): Command {
+  return cmd
+    .option("--tables [names]", "only these tables (comma-separated)")
+    .option("--no-tables", "exclude all tables")
+    .option("--functions [names]", "only these functions")
+    .option("--no-functions", "exclude all functions")
+    .option("--events [names]", "only these events")
+    .option("--no-events", "exclude all events")
+    .option(
+      "--access [names]",
+      "include access (off by default; key not pulled)",
+    )
+    .option("--no-access", "exclude all access (the default)");
+}
+
+/** Whether a name passes a category gate (kind on + name allowed). Shared with the surreal filters. */
+export const inCat = (c: Cat, name: string): boolean =>
+  c.on && (!c.names || c.names.has(name));
+
+// The SurrealDB statement/struct filters (`included`/`filterSnapshot`/`mergeSnapshot`/
+// `filterStructured`) live in `./surreal-filter`. Below are the dialect-free kind-registry filters.
+
+// --- kind-registry filters (the stored-snapshot path) -------------------------------------------
+
+const objKey = (o: PortableObject) => `${o.kind}:${o.name}`;
+
+/** Which Filter category gates a TOP-LEVEL kind (and whose name-set its name is matched against). */
+function category(kind: string): keyof Filter {
+  if (kind === "function") return "functions";
+  if (kind === "access") return "access";
+  return "tables"; // a table (and any future top-level structural kind)
+}
+
+/**
+ * Whether a portable object passes the filter. A TOP-LEVEL object (no owner) is gated by its kind's
+ * category + name. An OWNED object (owner set — an index/event/constraint) FOLLOWS its owner table's
+ * inclusion; an `event` is ADDITIONALLY gated by the `events` category. (Fields are substrate nested
+ * in their table object, never standalone here.)
+ */
+export function passesFilter(
+  registry: KindRegistry,
+  o: PortableObject,
+  f: Filter,
+): boolean {
+  const owner = registry.engine(o.kind)?.owner?.(o);
+  if (owner) {
+    if (!inCat(f.tables, owner.name)) return false;
+    return o.kind === "event" ? inCat(f.events, o.name) : true;
+  }
+  return inCat(f[category(o.kind)], o.name);
+}
+
+/** Keep only the portable objects that pass the filter (the {@link filterStructured} analog). */
+export function filterKinds(
+  registry: KindRegistry,
+  objects: PortableObject[],
+  f: Filter,
+): PortableObject[] {
+  return objects.filter((o) => passesFilter(registry, o, f));
+}
+
+/**
+ * The stored snapshot to persist after a filtered `generate`: INCLUDED objects take their new state
+ * from `next`, EXCLUDED objects keep `prev`'s. Dedup by `kind:name` (an included `next` object wins).
+ * `files` overlays next on prev.
+ */
+export function mergeStored(
+  registry: KindRegistry,
+  prev: StoredSnapshot,
+  next: StoredSnapshot,
+  f: Filter,
+): StoredSnapshot {
+  const merged = new Map<string, PortableObject>();
+  for (const o of snapshotObjects(prev.schema))
+    if (!passesFilter(registry, o, f)) merged.set(objKey(o), o);
+  for (const o of snapshotObjects(next.schema))
+    if (passesFilter(registry, o, f)) merged.set(objKey(o), o);
+  return {
+    version: 3,
+    driver: next.driver,
+    schema: snapshotKinds([...merged.values()], registry),
+    files: { ...(prev.files ?? {}), ...(next.files ?? {}) },
+  };
+}
+
+/**
+ * Restrict the `disk` objects to those that ALSO exist `live` (intersect by `kind:name`) AND pass the
+ * filter — for `baseline`. Hand-written schema not yet in the DB stays pending; what's really there is
+ * captured. Each field/index/event/constraint is its own object, so intersect-by-key handles them.
+ */
+export function intersectKinds(
+  registry: KindRegistry,
+  disk: PortableObject[],
+  live: PortableObject[],
+  f: Filter,
+): PortableObject[] {
+  const liveKeys = new Set(live.map(objKey));
+  return disk.filter(
+    (o) => liveKeys.has(objKey(o)) && passesFilter(registry, o, f),
+  );
+}