@voltro/database 0.54.0 → 0.55.0

package/dist/index.d.ts

@@ -2478,6 +2478,38 @@ export declare interface DataStore {
      * callers guard with `if (store.refreshChangeCaptureExclusions)`.
      */
     refreshChangeCaptureExclusions?(): Promise<ChangeCaptureExclusionRefresh>;
+    /**
+     * Run an Effect that needs this store's own `SqlClient` — the raw-SQL seam.
+     *
+     * The capability the STAGED SWAP is built on. `--mode replace` loads into
+     * `_voltro_staging_<t>` tables and then swaps the CONTENT in one short
+     * transaction (`DELETE FROM t; INSERT INTO t (…) SELECT … FROM
+     * _voltro_staging_t`), which moves the long, network-bound load OUT of the
+     * destructive transaction. None of that is expressible through the typed row
+     * API: it is DDL plus a server-side `INSERT … SELECT`, and the whole point is
+     * that no row crosses the wire.
+     *
+     * OPTIONAL on the interface, and declared here rather than duck-typed at the
+     * call site for the reason the house rule gives: the four dialect stores are
+     * four hand-written copies of one interface, and a capability nothing declares
+     * is a capability nothing can be red about. A store that loses it now fails to
+     * satisfy this member instead of silently falling out of `canStage()` and
+     * taking the weaker path forever, on one dialect, in silence.
+     *
+     * The DECISION does not live per store — that would be the four-copies trap
+     * wearing a different hat. `@voltro/data-transfer`'s `stagedSwap.ts` writes
+     * the per-dialect SQL ONCE and sends it down this seam; the store contributes
+     * a connection, not a policy.
+     *
+     * Callers guard with `if (store.run)` (or `canStage(store)`), and a store
+     * without it keeps the path it already has: the in-memory store has no SQL
+     * and no catalog, and neither does a bare `DataStore` view.
+     *
+     * `R` is deliberately `SqlClient.SqlClient`: the effect asks for the client
+     * and the store provides its own, which is what makes this a SEAM rather than
+     * a way to hand a store somebody else's connection.
+     */
+    run?<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
 }
 
 /** One transfer, as the inspector reads it back. */
@@ -3828,6 +3860,13 @@ export declare interface InterruptedReplace {
     readonly tables: number | null;
     readonly capture: string | null;
     readonly via: string;
+    /** The staging tables the run created. Empty for every kind but `staging`. */
+    readonly staging: ReadonlyArray<string>;
+    /** Last sign of life from the run, or `null` when it never wrote one. */
+    readonly heartbeatAt: Date | null;
+    /** `true` when the run was started `--no-atomic` — its staging is a resume
+     *  point, not a leftover. */
+    readonly resumable: boolean;
 }
 
 /**
@@ -3972,6 +4011,41 @@ export declare const isSeedDefinition: (value: unknown) => value is SeedDefiniti
  */
 export declare const isSqliteFamily: (dialect: DialectId) => boolean;
 
+/**
+ * True when `name` is a `--mode replace` staging table.
+ *
+ * ── This is a THIRD rule, and it must not be folded into the other two ─────
+ *
+ * The framework-table filter above is deliberately ASYMMETRIC: a framework
+ * table nobody declares is never planned for a drop, and one we DO declare
+ * diffs like any other table. Collapsing those two into one filter is what
+ * produced a postgres-only evolution path for the framework's own tables, and
+ * the comment in `boot.ts` exists to stop it being collapsed again.
+ *
+ * A staging table satisfies NEITHER half. It is not a schema fact at all — it is
+ * a scratch copy of a target table that exists for the length of one import and
+ * is dropped after the swap. So:
+ *
+ *   - the DROP direction is already covered, because `_voltro_staging_` starts
+ *     with `_voltro_` and `isFrameworkOwnedLiveTable` therefore says "never
+ *     drop it". Correct: a `replace` in flight on another replica is loading
+ *     into it right now.
+ *   - the CREATE direction is NOT, and that is the gap this closes. `--mode
+ *     replace` REGISTERS each staging table as a clone of its target for the
+ *     duration of the load — it has to, or a typed write cannot resolve the
+ *     column types and a `json()` column is written unencoded. A registered
+ *     table is a DECLARED table, and by the asymmetry above a declared
+ *     framework table diffs like any other: a plan computed while an import is
+ *     in flight proposes `create-table _voltro_staging_notes` and, once
+ *     applied, a table nothing will ever declare again is kept forever.
+ *
+ * So staging is excluded from the DECLARED side (in `declaredSnapshot`, which is
+ * the one input both the plan and its fingerprint are built from) and left to
+ * the existing prefix rule on the live side. Two different rules, two different
+ * places, on purpose.
+ */
+export declare const isStagingTableName: (name: string) => boolean;
+
 /**
  * Does this table emit change events at all?
  *
@@ -6593,6 +6667,86 @@ export declare interface SqlDialect {
     readonly retryFilter: (error: unknown) => RetryDecision;
 }
 
+/**
+ * How long a staged run's silence has to last before its scratch tables are
+ * treated as abandoned.
+ *
+ * Generous on purpose. The beat is written every couple of seconds while rows
+ * land, so this is not "how long a load may take" — it is how long a load may
+ * be stalled, or its bookkeeping write failing, before a boot on another
+ * replica decides nobody is coming back. The cost of being wrong here is that
+ * an in-flight import's swap fails with a missing table and the operator
+ * re-runs it; the target is untouched either way, which is what makes an
+ * automatic sweep affordable at all.
+ *
+ * Declared as `dataTransfer.stagingStaleMinutes` in `app.config.ts`;
+ * `VOLTRO_STAGING_STALE_MINUTES` overrides that in turn, on the same rule every
+ * other tunable here follows — an operator acting on a running deployment
+ * outranks what the project declared.
+ */
+export declare const STAGING_STALE_MINUTES = 30;
+
+/**
+ * The prefix a STAGING table carries: `_voltro_staging_<target>`.
+ *
+ * Defined in this leaf module, not in `@voltro/data-transfer` where the swap
+ * lives, because the differ has to know it and `@voltro/database` cannot depend
+ * on the package that imports it. One definition; `stagedSwap.ts` re-exports
+ * this one rather than spelling the prefix a second time.
+ */
+export declare const STAGING_TABLE_PREFIX = "_voltro_staging_";
+
+/**
+ * What a boot says about them.
+ *
+ * A NOTE, never a refusal — the target of a staged run is untouched by
+ * definition. But it is said out loud, because the alternative is what shipped:
+ * a set of tables holding a whole bundle that only an introspection could find,
+ * so nobody knew they existed until a disk filled up.
+ */
+export declare const stagingLeftoverReport: (leftovers: StagingLeftovers, now: number) => string | undefined;
+
+/** One staged run's leftovers, and what a boot may do about them. */
+export declare interface StagingLeftovers {
+    /** Every `kind: 'staging'` row, for the report. */
+    readonly all: ReadonlyArray<InterruptedReplace>;
+    /**
+     * The rows whose tables a boot may DROP: the beat is stale AND the run was
+     * not resumable.
+     *
+     * Both halves are load-bearing and neither is enough alone. A fresh beat is
+     * an import in flight — on this pod or another replica — and dropping its
+     * staging would destroy a load in progress. A resumable run's staging is a
+     * RESUME POINT that is meant to outlive the process, so no amount of silence
+     * makes it collectable.
+     */
+    readonly droppable: ReadonlyArray<InterruptedReplace>;
+}
+
+/**
+ * Decide, from the marker rows alone, which staging sets a boot may collect.
+ *
+ * Pure, and separated from the boot so the DECISION can be tested without a
+ * database — the rule is three lines and every one of them has a way to be
+ * quietly wrong in the direction that destroys someone's work.
+ */
+export declare const stagingLeftovers: (rows: ReadonlyArray<InterruptedReplace>, now: number, staleAfterMs: number) => StagingLeftovers;
+
+/** Split a `kind: 'staging'` row's comma-separated name list. */
+export declare const stagingNamesOf: (raw: unknown) => ReadonlyArray<string>;
+
+/**
+ * The threshold in ms: the env override, else what the app declared, else the
+ * default above.
+ *
+ * A non-positive or unparseable value at EITHER level falls through to the next
+ * one rather than failing. This runs on a boot path whose whole contract is that
+ * scratch-table housekeeping cannot stop a boot, so a typo in a tunable must not
+ * be the thing that does — and the fall-through lands on a threshold that is
+ * generous in the safe direction.
+ */
+export declare const stagingStaleAfterMs: (env: Record<string, string | undefined>, declaredMinutes?: number) => number;
+
 /**
  * Fill `row.id` from the table's declared scheme when it is absent.
  *