@voltro/runtime 0.83.1 → 0.84.0

package/dist/index.d.ts

@@ -18,6 +18,8 @@ import { ConstraintFacts } from '@voltro/database';
 import { ConstraintKind } from '@voltro/database';
 import { ConstraintViolation } from '@voltro/protocol';
 import { Context } from 'effect';
+import { CrdtBackend } from '@voltro/local-first';
+import { CrdtMigration } from '@voltro/local-first';
 import { createServer } from 'node:http';
 import { Cron } from 'effect';
 import { DataStore } from '@voltro/database';
@@ -3011,8 +3013,98 @@ export declare const counter: (name: string, description?: string) => Metric.Met
  */
 export declare const countRunningWorkflows: (store: DataStore) => Promise<number>;
 
+export declare const CRDT_VERSIONS_TABLE = "_voltro_crdt_versions";
+
+export declare interface CrdtAdmission {
+    readonly maxUpdateBytes?: number | null;
+    readonly maxDocumentBytes?: number | null;
+    readonly rebaseMaxBytes?: number | null;
+    /** Content migrations per table and column — see `crdt.migrations`. */
+    readonly migrations?: Readonly<Record<string, Readonly<Record<string, ReadonlyArray<CrdtMigration>>>>> | null;
+    readonly validate?: CrdtValidator | null;
+}
+
+/** A CRDT backend the server can be configured with (`crdt.backend`). */
+export declare type CrdtBackendChoice = CrdtBackend;
+
+/** A CRDT cell: table + row id + column. */
+export declare interface CrdtCellRef {
+    readonly table: string;
+    readonly id: string;
+    readonly column: string;
+}
+
+/** What a CRDT cell looks like from the inside — the data an inspector panel
+ *  or an alert reads to see a document approaching its limits. */
+export declare interface CrdtCellStats {
+    /** Stored bytes of the encoded state. */
+    readonly bytes: number;
+    /** The epoch it was last rebased into (`null`: never). */
+    readonly epoch: string | null;
+    /** How many writer sessions its history holds — what grows it. */
+    readonly authors: number;
+    /** Archived versions (snapshots, restores, rebases). */
+    readonly versions: number;
+    /** The limits the write path applies to it. */
+    readonly limits: {
+        readonly compactMaxBytes: number;
+        readonly rebaseMaxBytes: number;
+        readonly maxDocumentBytes: number;
+        readonly maxUpdateBytes: number;
+    };
+}
+
+/** The cell's size, epoch, author count and history length, through the
+ *  caller's scope. `undefined` when the row is not visible. */
+export declare const crdtCellStats: (store: CrdtHistoryStore, cell: CrdtCellRef) => Promise<CrdtCellStats | undefined>;
+
 export declare const crdtCompactMaxBytes: () => number;
 
+/** The slice of a store these functions use — `ctx.store` satisfies it. */
+export declare interface CrdtHistoryStore {
+    readonly query: (descriptor: never) => Promise<ReadonlyArray<unknown>>;
+    readonly insert: (table: never, row: never) => Promise<unknown>;
+    readonly update: (table: never, id: never, patch: never) => Promise<unknown>;
+}
+
+/** The effective per-document limit in bytes (`0` = unlimited). */
+export declare const crdtMaxDocumentBytes: () => number;
+
+/** The effective per-update limit in bytes (`0` = unlimited). */
+export declare const crdtMaxUpdateBytes: () => number;
+
+/** The content migrations declared for a CRDT column (`crdt.migrations`). */
+export declare const crdtMigrationsFor: (table: string, column: string) => ReadonlyArray<CrdtMigration>;
+
+/** The effective hard-compaction threshold in bytes (`0` = never). */
+export declare const crdtRebaseMaxBytes: () => number;
+
+/** Refuse a write by returning a message key (`'doc.tooLong'`); accept with
+ *  `undefined`. Runs on the server, synchronously, on the write path. */
+export declare type CrdtValidator = (write: CrdtWriteToValidate) => string | undefined;
+
+/** One version as a history list shows it — never the bytes. */
+export declare interface CrdtVersion {
+    readonly id: string;
+    readonly reason: 'snapshot' | 'restore' | 'rebase';
+    readonly label: string | null;
+    readonly epoch: string | null;
+    readonly createdBy: string | null;
+    readonly createdAt: Date;
+}
+
+/** What `crdt.validate` is handed for every merged CRDT write. */
+export declare interface CrdtWriteToValidate {
+    readonly table: string;
+    readonly column: string;
+    /** The merged state about to be stored. */
+    readonly state: Uint8Array;
+    /** The stored state before this write, `undefined` on the first. */
+    readonly previous: Uint8Array | undefined;
+    /** The client's incoming update. */
+    readonly update: Uint8Array;
+}
+
 /**
  * The cron expression that fires `intervalMs` apart, or `undefined` when no
  * five-field expression does.
@@ -3332,6 +3424,15 @@ export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
 
 export declare const DEFAULT_CRDT_COMPACT_MAX_BYTES: number;
 
+export declare const DEFAULT_CRDT_MAX_DOCUMENT_BYTES: number;
+
+export declare const DEFAULT_CRDT_MAX_UPDATE_BYTES: number;
+
+/** Above this, a merged document is HARD-compacted into a new epoch (its old
+ *  lineage archived first). Soft compaction keeps every struct of a document
+ *  edited by many sessions; this is what bounds it. */
+export declare const DEFAULT_CRDT_REBASE_MAX_BYTES: number;
+
 /**
  * How many subscribers one change event is delivered to CONCURRENTLY.
  *
@@ -3684,6 +3785,14 @@ export declare const deliveredRowCount: (value: unknown) => number;
  */
 export declare const deriveKey: (passphrase: string) => Buffer;
 
+/** Size-only facts about a stored CRDT state — its epoch and how many writer
+ *  sessions its history carries. For inspection; `undefined` when the bytes
+ *  do not decode (an `.encrypted()` column stores ciphertext). */
+export declare const describeCrdtState: (state: Uint8Array) => {
+    readonly epoch: string | null;
+    readonly authors: number;
+} | undefined;
+
 export declare const describeOtelReasons: (why: OtelNeededBecause) => ReadonlyArray<string>;
 
 /**
@@ -6417,6 +6526,10 @@ export declare class LinearScanMatcher implements Matcher {
 /** Every connection the app declares, projected for ONE subject. */
 export declare const listConnectionStates: (store: VaultStore, registry: ConnectionRegistry, subjectId: string) => Promise<ReadonlyArray<ConnectionState_2>>;
 
+/** The cell's versions, newest first — without their bytes. Empty when the
+ *  row is not visible to the caller. */
+export declare const listCrdtVersions: (store: CrdtHistoryStore, cell: CrdtCellRef) => Promise<ReadonlyArray<CrdtVersion>>;
+
 export declare const listResourcePolicies: () => ReadonlyArray<ResourcePolicy>;
 
 export { listRetentionConflicts }
@@ -7245,6 +7358,25 @@ export declare type MetricSampleType = 'counter' | 'gauge' | 'histogram' | 'summ
  *  into the OTel MeterProvider when a `metricReader` is configured. */
 export declare type MetricsMode = 'off' | 'console' | 'otlp' | 'memory';
 
+/**
+ * Bring every stored document of a CRDT column to the latest content schema
+ * (`crdt.migrations`) — the batch half of a migration. Documents are migrated
+ * on their next write anyway; this does it now, so readers that never write
+ * see the new shape too. Each row is touched with an EMPTY update, which runs
+ * the write path's fold — and with it the migrations, under the same
+ * compare-and-swap, so running this from two replicas at once migrates each
+ * document once. Rows are read through the store it is given, so tenant scope
+ * applies; run it with a system store to cover every tenant.
+ */
+export declare const migrateCrdtColumn: (store: CrdtHistoryStore, options: {
+    readonly table: string;
+    readonly column: string;
+    readonly batchSize?: number;
+}) => Promise<{
+    readonly scanned: number;
+    readonly migrated: number;
+}>;
+
 /** The lowest cadence any platform scheduler can express. */
 export declare const MIN_EXTERNALIZABLE_INTERVAL_MS = 60000;
 
@@ -8128,6 +8260,24 @@ export declare type PluginScheduleCoordinated = (name: string, intervalMs: numbe
 
 export declare const powerOfTwoSelector: (options?: P2COptions) => ReplicaSelector;
 
+/**
+ * The server's half of restoring a SEALED (`crdtSealed()`) cell. The server
+ * cannot read the content, so it cannot compute the restore — it archives the
+ * current log as a `restore` version (the restore stays undoable) and hands
+ * out the version's ciphertext. The client opens it with `openSealedLog` and
+ * calls the hook's `restore(target)`, which writes the change as an ordinary
+ * sealed edit. The cell's row is read through the caller's store first, as
+ * for every history read. An open column is refused — `restoreCrdtVersion`
+ * restores it on the server, and its history bytes stay `serverOnly()`.
+ */
+export declare const prepareSealedCrdtRestore: (store: CrdtHistoryStore, input: {
+    readonly versionId: string;
+    readonly createdBy?: string;
+}) => Promise<{
+    readonly undoPoint: CrdtVersion;
+    readonly versionLog: Uint8Array;
+} | undefined>;
+
 /**
  * Whether a `Referrer-Policy` value leaves the `Origin` header intact on a
  * same-origin state-changing request.
@@ -9133,6 +9283,8 @@ export declare interface RegistryTableLike {
         };
         /** `crdtText()` column — server-merged on write (see crdtColumns above). */
         readonly crdtManaged?: boolean;
+        /** `crdtSealed()` column — an append-only log of encrypted frames. */
+        readonly crdtSealed?: boolean;
     }>;
     readonly appliedMixins?: ReadonlyArray<{
         readonly id?: string;
@@ -9760,6 +9912,17 @@ export declare interface ResourcePolicy {
     readonly implies?: Readonly<Record<string, ReadonlyArray<string>>>;
 }
 
+/**
+ * Bring a version back: the cell's content becomes the version's, written as
+ * an ordinary CRDT edit (concurrent edits still merge), after archiving the
+ * state it replaces as a `restore` version. `undefined` when the version or
+ * its row is not visible to the caller.
+ */
+export declare const restoreCrdtVersion: (store: CrdtHistoryStore, input: {
+    readonly versionId: string;
+    readonly createdBy?: string;
+}) => Promise<CrdtVersion | undefined>;
+
 /**
  * Mark everything read inside `fn` as RESTRICTING.
  *
@@ -11050,6 +11213,8 @@ export declare interface SchemaInfo {
      * so concurrent clients converge. Empty set for the common non-CRDT table.
      */
     readonly crdtColumns: ReadonlySet<string>;
+    /** End-to-end-sealed CRDT columns (`crdtSealed()`): appended, never merged. */
+    readonly sealedColumns: ReadonlySet<string>;
     /**
      * Columns that a query predicate can hit and benefit from an index:
      *   - column-level `.index()`-flagged columns
@@ -11167,6 +11332,8 @@ export declare interface SchemaRegistry {
      * CRDT merge (`mergeCrdtStates`) before an INSERT/UPDATE persists.
      */
     crdtColumns(table: string): ReadonlySet<string>;
+    /** `crdtSealed()` columns of a table — see `SchemaInfo.sealedColumns`. */
+    sealedColumns(table: string): ReadonlySet<string>;
     /**
      * Optional pre-INSERT schema decoder for a table. `undefined` when
      * the table didn't ship `.validate(schema)`. The MutationStore runs
@@ -11477,6 +11644,14 @@ export declare const setBufferedBytes: (label: string, bytes: number) => void;
  *  Called by the CLI at boot; tests call it directly. */
 export declare const setConnectionResolver: (resolver: ConnectionResolver | undefined) => void;
 
+/** Boot/test override — the slot `wireCrdtTunables` writes. Fields left out
+ *  keep env/default resolution. */
+export declare const setCrdtAdmission: (admission: CrdtAdmission | null) => void;
+
+/** Boot wiring for `crdt.backend` — every default call site (the merge, the
+ *  history, the inspection) follows it. `null` restores Yjs. */
+export declare const setCrdtBackend: (backend: CrdtBackendChoice | null) => void;
+
 /** Boot/test override — the slot `wireCrdtTunables` writes. `null` restores
  *  env/default resolution. */
 export declare const setCrdtCompactMaxBytes: (maxBytes: number | null) => void;
@@ -11623,6 +11798,15 @@ export declare interface SnapshotCacheBinding {
     readonly swrMs: number | undefined;
 }
 
+/**
+ * Archive the cell's current state as a named version. `undefined` when the
+ * row is not visible to the caller.
+ */
+export declare const snapshotCrdt: (store: CrdtHistoryStore, cell: CrdtCellRef & {
+    readonly label?: string;
+    readonly createdBy?: string;
+}) => Promise<CrdtVersion | undefined>;
+
 /** Snapshot the whole registry, normalized to `MetricSample[]` — plus the
  *  socket-backpressure counters (`subscriptionSocketMetrics.ts`), appended
  *  HERE so every reader (Prometheus exporter, inspect Metrics panel) sees
@@ -12984,6 +13168,8 @@ export declare const _voltroConnectionGrantsTable: TableLike;
  */
 export declare const _voltroConnectionsTable: TableLike;
 
+export declare const _voltroCrdtVersionsTable: TableLike;
+
 /** `_voltro_rebac_tuples` — the relationship tuples `can()` reads. One row =
  *  "`subjectId` has `relation` on `<resourceType>:<resourceId>`". Grant by
  *  inserting; revoke by deleting (a delete is the live-revocation trigger). */