@opendatalabs/personal-server-ts-server 1.34.1 → 1.35.0

package/dist/storage/pdpp-replication-receiver.d.ts

@@ -0,0 +1,230 @@
+import type { Database } from "better-sqlite3";
+import { type CopyPromotion, type StagedCopy } from "./pdpp-replica-copies.js";
+import type { CopyDecision, FinalizedFact } from "@opendatalabs/personal-server-ts-core/replication/copy-promotion";
+import { type ReplicaOperation } from "@opendatalabs/personal-server-ts-core/replication/envelope";
+import type { MergeContext, ReplicaMergePlan } from "@opendatalabs/personal-server-ts-core/replication/merge-plan";
+import { type ReplicaReconcilePage } from "./pdpp-replica-reconciler.js";
+import type { ReplicaRecordStore } from "./pdpp-replica-canonical-port.js";
+import { type ReplicaReader, type ReplicaVisibilityPolicy } from "@opendatalabs/personal-server-ts-core/replication/visibility-policy";
+import { type ListRecordsOptions, type PdppVisibleRecord, type ListVisibleRecordsPage, type PdppReplicaReadStore, type VisibilitySnapshot } from "@opendatalabs/personal-server-ts-core/storage/pdpp-records";
+export declare const RECEIVER_MIGRATION = "\nCREATE TABLE IF NOT EXISTS pdpp_replica_received (operation_json TEXT PRIMARY KEY, digest TEXT NOT NULL);\nCREATE TRIGGER IF NOT EXISTS pdpp_received_no_update BEFORE UPDATE ON pdpp_replica_received BEGIN SELECT RAISE(ABORT, 'received operations are append-only'); END;\nCREATE TRIGGER IF NOT EXISTS pdpp_received_no_delete BEFORE DELETE ON pdpp_replica_received BEGIN SELECT RAISE(ABORT, 'received operations are append-only'); END;\nCREATE TABLE IF NOT EXISTS pdpp_replica_quarantined_keys (instance TEXT NOT NULL, generation INTEGER NOT NULL, stream TEXT NOT NULL, record_key TEXT NOT NULL, PRIMARY KEY(instance,generation,stream,record_key));\nCREATE TABLE IF NOT EXISTS pdpp_replica_quarantined_connections (instance TEXT PRIMARY KEY);\nCREATE TABLE IF NOT EXISTS pdpp_replica_received_bytes (blob_id TEXT PRIMARY KEY, bytes BLOB NOT NULL);\n";
+/**
+ * Replica integrity facts. Only replica tables: no main table changes.
+ * - integrity fences: how many times replica evidence hid data of a
+ *   connection (key or connection quarantine, binding conflict). With the
+ *   binding's reset_clock it forms the connection's integrity epoch.
+ * - binding conflicts: a connection whose evidence names another source or
+ *   method than its local mapping, or two sources. Append-only: later
+ *   evidence, equivocation included, can never erase the fact.
+ */
+export declare const REPLICA_INTEGRITY_MIGRATION = "\nCREATE TABLE IF NOT EXISTS pdpp_replica_integrity_fences (instance TEXT PRIMARY KEY, fences INTEGER NOT NULL);\nCREATE TABLE IF NOT EXISTS pdpp_replica_binding_conflicts (instance TEXT PRIMARY KEY, reason TEXT NOT NULL, evidence_json TEXT NOT NULL);\nCREATE TRIGGER IF NOT EXISTS pdpp_binding_conflicts_no_update BEFORE UPDATE ON pdpp_replica_binding_conflicts BEGIN SELECT RAISE(ABORT, 'binding conflicts are append-only'); END;\nCREATE TRIGGER IF NOT EXISTS pdpp_binding_conflicts_no_delete BEFORE DELETE ON pdpp_replica_binding_conflicts BEGIN SELECT RAISE(ABORT, 'binding conflicts are append-only'); END;\n";
+/**
+ * Invariant: removing a quarantine fact un-hides data, so it must raise the
+ * connection's integrity epoch in the same transaction, exactly as adding
+ * one does (fenceReplicaConnection). These triggers make that structural:
+ * any DELETE of a key or connection fact fences its connection, so no
+ * future removal path can forget it. pdpp-replica-invariants.test.ts (1).
+ */
+export declare const REPLICA_FACT_REMOVAL_MIGRATION = "\nCREATE TRIGGER IF NOT EXISTS pdpp_quarantined_keys_removal_fence AFTER DELETE ON pdpp_replica_quarantined_keys BEGIN INSERT INTO pdpp_replica_integrity_fences VALUES (OLD.instance, 1) ON CONFLICT(instance) DO UPDATE SET fences = fences + 1; END;\nCREATE TRIGGER IF NOT EXISTS pdpp_quarantined_connections_removal_fence AFTER DELETE ON pdpp_replica_quarantined_connections BEGIN INSERT INTO pdpp_replica_integrity_fences VALUES (OLD.instance, 1) ON CONFLICT(instance) DO UPDATE SET fences = fences + 1; END;\n";
+type Store = Omit<ReplicaRecordStore, "unquarantinedRecordSql"> & {
+    /**
+     * The shared quarantine predicate. `generationSql` is the generation of the
+     * aliased row's value; without it the binding's current generation applies.
+     * A store that takes one argument ignores the second.
+     */
+    unquarantinedRecordSql(alias: string, generationSql?: string): string;
+};
+/**
+ * Internal port, absent from connector routes. Bootstrap builds it only through
+ * `createNodeReplication`, behind `replication.enabled`. The host
+ * must verify a replica-specific credential before returning its owner. A payload,
+ * a collector credential, and a source declaration are never authentication.
+ * Connection ids are the registered canonical instance ids (the export profile).
+ */
+export declare function createReplicaReceiver(deps: {
+    db: Database;
+    store: Store;
+    owner: string;
+    authenticate: (credential: unknown) => string | undefined;
+    declarations: () => MergeContext["declarations"];
+    enabled?: boolean;
+    visibilityPolicy?: ReplicaVisibilityPolicy;
+}): {
+    setPendingEnabled(enabled: boolean): void;
+    /**
+     * Batch-copy custody and promotion (contract v3.1). Trusted host hooks:
+     * the caller verified every fragment's bytes against its own hash pair.
+     */
+    copies: {
+        stage(input: {
+            credential: unknown;
+            copy: Omit<StagedCopy, "envelope" | "blobs"> & {
+                envelope: unknown;
+            };
+            blobs?: {
+                blobId: string;
+                bytes: Uint8Array;
+            }[];
+            /** Verified transport staging, copied into pending custody. */
+            stagedBlobs?: {
+                blobId: string;
+                key: string;
+                sizeBytes: number;
+            }[];
+            refetch?: {
+                attempts: number;
+                budget: number;
+            };
+        }): {
+            copyKey: import("@opendatalabs/personal-server-ts-core/replication/copy-promotion").Hex | undefined;
+            decision: CopyDecision;
+        };
+        /** Append one verified finalized fact (F2). Returns true when new. */
+        recordFact(input: {
+            credential: unknown;
+            id: string;
+            scope: string;
+            fragmentIndex: number;
+            fact: FinalizedFact;
+        }): boolean;
+        decide: (id: string, refetch: {
+            attempts: number;
+            budget: number;
+        }) => CopyDecision;
+        disposition: (id: string) => import("@opendatalabs/personal-server-ts-core/replication/copy-promotion").CopyDisposition;
+        list: (id: string) => {
+            copyKey: import("@opendatalabs/personal-server-ts-core/replication/copy-promotion").Hex;
+            state: "confirmed" | "pending" | "quarantined";
+            reason: "finalized_conflict" | "copy_conflict" | null;
+            envelopeDigest: string;
+        }[];
+        apply(input: {
+            credential: unknown;
+            id: string;
+            decision: CopyDecision;
+        }): void;
+        promote(input: {
+            credential: unknown;
+            id: string;
+            copyKey?: string;
+        }): CopyPromotion;
+        terminate(input: {
+            credential: unknown;
+            id: string;
+            reason: string;
+        }): void;
+    };
+    stage(input: {
+        credential: unknown;
+        id: string;
+        envelope: unknown;
+        blobs?: {
+            blobId: string;
+            bytes: Uint8Array;
+        }[];
+        /** Verified transport staging. Copied into durable chunked pending custody. */
+        stagedBlobs?: {
+            blobId: string;
+            key: string;
+            sizeBytes: number;
+        }[];
+    }): void;
+    /** Durable state of a staged batch, or undefined when never staged. */
+    pendingState(id: string): "pending" | "confirmed" | "quarantined" | undefined;
+    quarantine(input: {
+        credential: unknown;
+        id: string;
+        reason: string;
+    }): void;
+    /** Trusted host hook: caller must verify every fragment against finalized #433 evidence first. */
+    promote(input: {
+        credential: unknown;
+        id: string;
+    }): ReplicaMergePlan | undefined;
+    connectionVisibility: (instance: string) => {
+        state: "conflicted";
+        reason: "source_binding";
+    } | undefined;
+    readVisibleRecords: (input: {
+        reader?: ReplicaReader;
+        connectionId: string;
+        stream: string;
+    }) => PdppVisibleRecord[];
+    readView: (reader: ReplicaReader, cursor?: string) => VisibilitySnapshot;
+    readRecords(input: ListRecordsOptions & {
+        stream: string;
+        reader?: ReplicaReader;
+    }): ListVisibleRecordsPage;
+    readStore(input?: {
+        reader?: ReplicaReader;
+    }): PdppReplicaReadStore & {
+        connectionVisibility: (instance: string) => {
+            state: "conflicted";
+            reason: "source_binding";
+        } | undefined;
+        withReadSnapshot: <T>(read: () => T) => T;
+    };
+    /** Called only after the transport proves a finalized immutable-slot conflict.
+     * Keep evidence, but permanently retract the authority derived from its batch.
+     */
+    quarantineImported(input: {
+        credential: unknown;
+        envelope: unknown;
+    }): void;
+    import(input: {
+        credential: unknown;
+        envelope: unknown;
+        blobs?: {
+            blobId: string;
+            bytes: Uint8Array;
+        }[];
+        stagedBlobs?: {
+            blobId: string;
+            key: string;
+            sizeBytes: number;
+            namespace?: "staging" | "pending";
+        }[];
+    }): ReplicaMergePlan;
+    /** Trusted host notification after declaration documents or validators change. */
+    reconcileDeclarations(input: {
+        credential: unknown;
+    }): ReplicaMergePlan;
+    /**
+     * Runs `run` in one write transaction whose derived state is current.
+     * Hosts that combine receiver calls with their own writes enter here, so
+     * the nested receiver calls can trust the transaction's view.
+     */
+    atomically<T>(run: () => T): T;
+    /** A full reconcile pass over retained history, finished in this call. */
+    retry(input: {
+        credential: unknown;
+    }): ReplicaMergePlan;
+    /**
+     * One bounded page of reconcile work. `restart` first queues a full pass,
+     * as `retry` does; later pages continue it. `complete` is true when no
+     * work is queued. The plan lists only this page's issues.
+     */
+    reconcileStep(input: {
+        credential: unknown;
+        page: ReplicaReconcilePage;
+        restart?: boolean;
+    }): {
+        plan: ReplicaMergePlan;
+        complete: boolean;
+    };
+    /** Whether reconcile work is queued. Reads no retained history. */
+    reconcileQueued: () => boolean;
+    /** Retained evidence reconcile has loaded, cumulatively. For bounds tests. */
+    reconcileStats: () => import("./pdpp-replica-reconciler.js").ReplicaReconcileStats;
+    /**
+     * Reconcile, then return the operations that explain canonical state: the
+     * merge's winner for each shown row and tombstone, and each available
+     * completion. A new writer's rebaseline copies order and binding only
+     * from these (host contract §4.5).
+     */
+    explainState(input: {
+        credential: unknown;
+    }): ReplicaOperation[];
+};
+export {};
+//# sourceMappingURL=pdpp-replication-receiver.d.ts.map

package/dist/storage/pdpp-replication-receiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdpp-replication-receiver.d.ts","sourceRoot":"","sources":["../../src/storage/pdpp-replication-receiver.ts"],"names":[],"mappings":"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"}