@voltro/data-transfer 0.54.0 → 0.56.0

package/dist/index.d.ts

@@ -166,6 +166,9 @@ export declare type CanonicalCategory = 'string' | 'integer' | 'float' | 'boolea
  *  types (a bundle from a newer framework) fall back to 'string' passthrough. */
 export declare const canonicalType: (type: string) => CanonicalCategory;
 
+/** Can this store stage at all? */
+export declare const canStage: (store: DataStore) => store is SqlCapableStore;
+
 /**
  * Stream every asset the source enumerates into the content-addressed `assetsDir`.
  *
@@ -491,6 +494,26 @@ export declare type DriftVerdict = 'safe' | 'value-dropped' | 'filled-by-default
  *  be cleanable by the same call. */
 export declare const dropStagingSql: (table: string, dialect: StagingDialect) => string;
 
+/**
+ * The tables {@link backupCommand} actually leaves OUT of the artifact, for a
+ * given dialect — the list above is what we ASK for, and only two of the five
+ * backup paths can honour it.
+ *
+ * `pg_dump --exclude-table` and `mariadb-dump --ignore-table` drop the named
+ * tables from the artifact. The sqlite/turso path is a whole-FILE copy and the
+ * mssql path is a `sqlpackage /Action:Export` of the whole database; neither has
+ * an exclusion flag, so on those dialects the artifact carries everything.
+ *
+ * This distinction is not cosmetic bookkeeping — it decides what a faithful
+ * restore is allowed to produce. Anything that compares a restored schema
+ * against the SOURCE schema (`voltro data restore --drill`) has to subtract
+ * exactly this set on the source side, or it reads a deliberate exclusion as a
+ * corrupt artifact and fails a healthy backup. Keeping the per-dialect answer
+ * here, next to the commands that make it true, is what stops that comparison
+ * from re-deriving it and getting it wrong for two dialects out of five.
+ */
+export declare const dumpExcludedTables: (dialect: string) => ReadonlyArray<string>;
+
 export declare const emptyLedger: () => Ledger;
 
 export declare const encodeManifest: (a: {
@@ -1581,14 +1604,19 @@ declare const ScopeError_base: Schema.TaggedErrorClass<ScopeError, "ScopeError",
 /**
  * A store that can run raw SQL for us.
  *
- * The dialect stores carry `run(effect)`; the memory store does not, and neither
- * does any view that only implements the `DataStore` SPI. Feature-detected the
- * same way `emptyTables` is — an absent capability means the caller keeps the
- * path it already has, rather than a failure.
+ * `run` is a DECLARED optional capability on `DataStore`, in the shape
+ * `emptyTables` established: the four dialect stores implement it, the in-memory
+ * store and any bare view omit it, and callers feature-detect. It used to be
+ * duck-typed here — a member the interface never mentioned — which meant a store
+ * that dropped it fell out of `canStage()` silently and took the weaker,
+ * transaction-for-the-whole-load path forever, on that one dialect, without a
+ * word. Declaring it is what lets a parity assertion be red about it.
+ *
+ * This type is the NARROWING of that optional member to a store which has it.
  */
-declare interface SqlCapableStore extends DataStore {
-    readonly run: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A>;
-}
+export declare type SqlCapableStore = DataStore & {
+    readonly run: NonNullable<DataStore['run']>;
+};
 
 /**
  * One table in the swap, and the columns to carry.
@@ -1613,9 +1641,22 @@ declare interface StagedTable {
     readonly columns: ReadonlyArray<string>;
 }
 
-/** The suffix a staging table carries. `_voltro_`-prefixed so the boot differ's
- *  framework-table asymmetry treats it as ours and never plans it as a user
- *  table somebody forgot to declare. */
+/**
+ * The prefix a staging table carries.
+ *
+ * RE-EXPORTED, not spelled again. The differ has to know this prefix too — a
+ * staging clone is REGISTERED for the length of the load, and a registered table
+ * is a declared one, so without the exclusion a plan computed mid-import
+ * proposes `create-table _voltro_staging_notes` — and `@voltro/database` cannot
+ * import this package. So the string lives there (`isStagingTableName`) and this
+ * is the same value under the name the import path already used. Two copies of a
+ * prefix that two packages must agree on is exactly the drift this repo keeps
+ * paying for.
+ *
+ * `_voltro_`-prefixed so the boot differ's framework-table rule also refuses to
+ * plan a live one as a lossy DROP — an import on another replica may be loading
+ * into it right now.
+ */
 export declare const STAGING_PREFIX = "_voltro_staging_";
 
 /** Whether this run stages, and — always — WHY NOT when it does not. */