@voltro/database 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -690,7 +690,7 @@ export declare type ChangeEvent = {
      * The trace this write happened under — the SAME id `auditPlugin` records as
      * `AuditEvent.traceId` and `voltro logs --trace` resolves.
      *
-     * This is the correlation bridge. Without it `plugin-versioning` knows WHAT
+     * This is the correlation bridge. Without it `plugin-row-history` knows WHAT
      * changed and the audit sink knows WHO called and whether it was refused, and
      * nothing joins the two. With it, "what did this call touch" is one query.
      *
@@ -991,7 +991,7 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      * under load. An integer the DATABASE owns has neither problem.
      *
      * WHAT IT DOES NOT DO. It is not a history: it records that a row changed, not
-     * what it changed to. For that use `plugin-versioning`. It is also not a
+     * what it changed to. For that use `plugin-row-history`. It is also not a
      * distributed lock — a conflicting write is REPORTED, never queued or merged,
      * because merging two intents is a decision only the application can make.
      *
@@ -1987,6 +1987,30 @@ export declare const count: (alias?: string) => AggregateColumn;
 
 export declare const countDistinct: (column: string, alias?: string) => AggregateColumn;
 
+/**
+ * A whole collaborative DOCUMENT as a column — rich text, nested maps/arrays,
+ * whatever the CRDT backend's document model holds. `crdtText()` is the
+ * single-plain-text specialisation; this is the general form an editor
+ * binding (Tiptap over Yjs) edits.
+ *
+ * Storage, nullability and the authoritative server merge are IDENTICAL to
+ * `crdtText()` — the merge primitive (`Y.mergeUpdates`) is doc-agnostic, so
+ * the same write-path fold converges whole documents. What differs is intent
+ * and the exposure rules:
+ *
+ * - `.serverOnly()` THROWS at declaration (a doc clients write but never read
+ *   cannot be collaborated on);
+ * - `.encrypted()` is allowed but makes the column ONLINE-ONLY for
+ *   local-first purposes: the client mirror refuses to persist decrypted
+ *   content on the device (see `@voltro/local-first`), so offline editing of
+ *   an encrypted doc requires local encryption the framework does not ship.
+ *   Declare it deliberately.
+ *
+ * Anchors (stable positions for inline comments) come from
+ * `@voltro/local-first`'s `CrdtDocHandle.encodeAnchor`/`resolveAnchor`.
+ */
+export declare const crdtDoc: () => ColumnBuilder<Uint8Array | null, "bytes">;
+
 /**
  * The names of a table's CRDT-managed columns (`crdtText()`). These store an
  * encoded CRDT state as `bytes` and get an authoritative SERVER-SIDE merge on
@@ -1996,6 +2020,10 @@ export declare const countDistinct: (column: string, alias?: string) => Aggregat
  */
 export declare const crdtManagedColumns: (table: TableLike) => ReadonlyArray<string>;
 
+/** The `crdtText()`/`crdtDoc()` columns of a table — the set the server merge
+ *  folds and the capture paths (undo, row history) exclude. */
+export declare const crdtManagedColumnsOf: (table: TableLike) => ReadonlyArray<string>;
+
 /**
  * CRDT-managed text column — a field whose value is a CONFLICT-FREE replicated
  * text document rather than a plain string. Two clients editing it at the same
@@ -3432,7 +3460,7 @@ export declare const formatSubjectGraph: (graph: SubjectGraph) => string;
  * start with a reserved prefix, so the prefix rule below cannot recognise them.
  *
  * Public because consumers need to tell "a table the app declares" from "one the
- * framework or a plugin brought" — `plugin-versioning` reads it to decide its
+ * framework or a plugin brought" — `plugin-row-history` reads it to decide its
  * default watch set. One copy of that rule on purpose: a second copy of it is
  * how a per-dialect difference in what `voltro dev` does got shipped once.
  */
@@ -4325,12 +4353,26 @@ export declare interface MigrationStepContext {
 export declare const min: (column: string, alias?: string) => AggregateColumn;
 
 /**
- * The `conflictColumns` an upsert names that are absent from its payload. An
- * upsert keyed on a column the row doesn't set can't match a conflict target —
- * the dialect fails obscurely (or worse, inserts a duplicate). Naming it at the
- * call is the difference between a one-line fix and reading a driver error.
+ * The `conflictColumns` an upsert names that cannot match its conflict target.
+ * An upsert keyed on a column the row doesn't set can't match — the dialect
+ * fails obscurely (or worse, silently inserts a duplicate on every re-run).
+ * Naming it at the call is the difference between a one-line fix and reading a
+ * driver error.
+ *
+ * Takes the TABLE, exactly like `missingRequiredColumns` above, and for the
+ * same reason six lines up: a generated column (`generatedAs`) is DB-computed
+ * and takes no caller value — MariaDB/Postgres REJECT an explicit one, and the
+ * framework's own stamping STRIPS one — so for a generated conflict column,
+ * absence from the payload is the only correct state. The first version took
+ * only `(conflictColumns, row)` and therefore COULD NOT know: it refused every
+ * upsert keyed on a stored generated column, a condition nobody can satisfy.
+ * The very shape that makes such a unique work (folding NULLs to a constant so
+ * a composite unique can hold, e.g. `CASE WHEN ref IS NULL THEN 1 END`) is the
+ * shape it rejected. `undefined` table = the definition is not available; no
+ * column can be recognised as generated, so none is skipped — pass the table
+ * whenever you have one.
  */
-export declare const missingConflictColumns: (conflictColumns: ReadonlyArray<string>, row: Row) => ReadonlyArray<string>;
+export declare const missingConflictColumns: (table: TableLike | undefined, conflictColumns: ReadonlyArray<string>, row: Row) => ReadonlyArray<UnmatchableConflictColumn>;
 
 /**
  * Columns the row must carry but doesn't. Empty when the row is complete.
@@ -7522,6 +7564,17 @@ export declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/** Why a conflict column cannot match its target — the two are different bugs
+ *  with different fixes, and one shared word ("missing") sent a reader hunting
+ *  for an absent field that was present-but-NULL. */
+export declare interface UnmatchableConflictColumn {
+    readonly column: string;
+    /** `absent` — not in the payload at all. `null` — present, but NULL, and
+     *  NULL never matches a unique conflict target: the write would always
+     *  INSERT. */
+    readonly reason: 'absent' | 'null';
+}
+
 /**
  * Remove ONE name this process added for a bounded operation.
  *