@bjornpagen/bumbledb-log 0.20.0 → 0.20.2

package/dist/replica.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The replica: a local store that is a materialized view of the
+ * braids' prefixes, plus the loop that keeps it current. Disposable by
+ * construction — the sidecar is a floor cache with one wholeness
+ * check; recovery IS the catch-up loop (L10). Generation is a total
+ * function of the chain: Settled sums the vector, Pending is that sum
+ * plus one. A replica that finds no manifest refuses; only a writer
+ * births a store.
+ */
+import type { Db, Schema, SchemaRelations, WriteOutcome } from "@bjornpagen/bumbledb";
+import type { Digest32 } from "./bytes.js";
+import type { Chain, ChainEntry, Pending } from "./chain.js";
+import type { Op } from "./codec.js";
+import type { Braid, Descriptor } from "./descriptor.js";
+import type { Generation } from "./keys.js";
+import type { CheckpointFacts } from "./manifest.js";
+import type { Etag, ObjectStore } from "./store.js";
+declare const ZERO_HASH: Digest32;
+type ReplicaState = {
+    readonly tag: "bootstrapped";
+} | {
+    readonly tag: "checkpoint-seeded";
+    readonly catalog: Digest32;
+} | {
+    readonly tag: "sidecar-resumed";
+    readonly floor: ReadonlyMap<Braid, Generation>;
+};
+type RefreshOutcome = {
+    readonly tag: "advanced";
+    readonly vector: ReadonlyMap<Braid, Generation>;
+} | {
+    readonly tag: "wedged";
+    readonly braid: Braid;
+    readonly cause: string;
+} | {
+    readonly tag: "reseed";
+    readonly cause: string;
+} | {
+    readonly tag: "refused";
+    readonly detail: string;
+};
+/** The full waitFor sum: a wedged braid the target needs is an
+ *  outcome, never an infinite poll. */
+type Waited = {
+    readonly tag: "reached";
+    readonly vector: ReadonlyMap<Braid, Generation>;
+} | {
+    readonly tag: "wedged";
+    readonly braid: Braid;
+    readonly cause: string;
+} | {
+    readonly tag: "refused";
+    readonly detail: string;
+};
+interface OpenReplicaOptions<Rels extends SchemaRelations> {
+    readonly store: ObjectStore;
+    readonly prefix: string;
+    readonly dir: string;
+    readonly theory: Schema<Rels>;
+}
+interface Replica<Rels extends SchemaRelations> extends AsyncDisposable {
+    readonly db: Db<Rels>;
+    readonly vector: ReadonlyMap<Braid, Generation>;
+    refresh(braid?: Braid): Promise<ReadonlyMap<Braid, Generation>>;
+    waitFor(vector: ReadonlyMap<Braid, Generation>): Promise<Waited>;
+}
+interface Core<Rels extends SchemaRelations> {
+    readonly store: ObjectStore;
+    readonly prefix: string;
+    readonly dir: string;
+    readonly theory: Schema<Rels>;
+    readonly descriptor: Descriptor;
+    db: Db<Rels>;
+    /** Settled|Pending. Generation is chainGeneration(this.chain) — a
+     *  total function of the sum. There is no pending Option beside the
+     *  vector and no 0|1 addend a reader can skip (§30). */
+    chain: Chain;
+    manifestEtag: Etag | null;
+    checkpoint: CheckpointFacts | null;
+    checkpointDigest: Digest32 | null;
+    passes: number;
+    closed: boolean;
+    storeName: string;
+    gate: Promise<unknown>;
+    wedged: Map<Braid, string>;
+    provenance: ReplicaState;
+}
+declare function coreOf<Rels extends SchemaRelations>(replica: Replica<Rels>): Core<Rels>;
+/** One asynchronous door per replica: refreshes, commits, and disposal serialize. */
+declare function withGate<Rels extends SchemaRelations, R>(core: Core<Rels>, body: () => Promise<R>): Promise<R>;
+declare function entriesOf<Rels extends SchemaRelations>(core: Core<Rels>): Map<Braid, ChainEntry>;
+declare function chainEntry<Rels extends SchemaRelations>(core: Core<Rels>, braid: Braid): ChainEntry;
+declare function generationOf<Rels extends SchemaRelations>(core: Core<Rels>): bigint;
+/** Pending-arm payload: recorded ops and the batch header's timestamp
+ *  ride on the batch, not a third Option beside the vector. Wire
+ *  Pending is {braid,gen,bytes}; ops/ts are the in-memory fields of
+ *  that arm (§30) — null on a batch adopted as bytes the seat has not
+ *  decoded. */
+type HeldBatch = Pending & {
+    readonly ops: readonly Op[] | null;
+    readonly ts: bigint | null;
+};
+declare function holdPending<Rels extends SchemaRelations>(core: Core<Rels>, batch: Pending, ops: readonly Op[] | null, ts: bigint | null): void;
+declare function pendingOf<Rels extends SchemaRelations>(core: Core<Rels>): HeldBatch | null;
+declare function persistSidecar<Rels extends SchemaRelations>(core: Core<Rels>): Promise<void>;
+declare function clearPending<Rels extends SchemaRelations>(core: Core<Rels>): Promise<void>;
+/** One `db.write` applying ops in listed order, rows in listed order.
+ *  The positional row → named fact lift is the engine's `factOf` —
+ *  closed-ref handles included. */
+declare function applyOps<Rels extends SchemaRelations>(core: Core<Rels>, ops: readonly Op[]): WriteOutcome<Rels, number>;
+/**
+ * The published checkpoint vector is the one floor: a slot at or
+ * below it is retired, and a create must not touch the store.
+ */
+declare function belowFloor<Rels extends SchemaRelations>(core: Core<Rels>, braid: Braid, slot: Generation): boolean;
+/**
+ * Classification of a pending batch against occupant, store
+ * generation, and the floor. BelowFloor is published (`Clear`) — the
+ * slot is already in the trusted history, not a candidate to re-judge.
+ */
+type PendingFold = {
+    readonly tag: "ours";
+} | {
+    readonly tag: "theirs-unapplied";
+} | {
+    readonly tag: "theirs-applied";
+} | {
+    readonly tag: "absent-unapplied";
+} | {
+    readonly tag: "absent-applied";
+} | {
+    readonly tag: "below-floor";
+} | {
+    readonly tag: "phantom";
+};
+declare function foldPending(sum: bigint, generation: bigint, occupant: Uint8Array | null, pendingBytes: Uint8Array, covered: boolean): PendingFold;
+/** The disposable law: the directory is cache, never truth. The local
+ *  LMDB path rotates because the engine has no close verb — the old
+ *  environment is left for GC while the fresh pull takes a new path.
+ *  initializeStore writes Settled, so the open-identity is
+ *  chainGeneration(core.chain) — there is no addend a reader can skip. */
+declare function discardAndReopen<Rels extends SchemaRelations>(core: Core<Rels>): Promise<void>;
+/**
+ * Re-addresses an applied-but-unpublished batch at the braid's current
+ * tip: fresh slot, `prev` citing the new predecessor, timestamp
+ * re-clamped — the ops are exactly the recorded ops the re-judgment
+ * just accepted. Publication itself retries on the next commit (60).
+ */
+declare function readdressPending<Rels extends SchemaRelations>(core: Core<Rels>, ops: readonly Op[], writerId: bigint): Promise<void>;
+declare function maxBigint(a: bigint, b: bigint): bigint;
+declare function openReplica<Rels extends SchemaRelations>(options: OpenReplicaOptions<Rels>): Promise<Replica<Rels>>;
+export type { Core, OpenReplicaOptions, RefreshOutcome, Replica, Waited };
+export { applyOps, belowFloor, chainEntry, clearPending, coreOf, discardAndReopen, entriesOf, foldPending, generationOf, holdPending, maxBigint, openReplica, pendingOf, persistSidecar, readdressPending, withGate, ZERO_HASH };
+//# sourceMappingURL=replica.d.ts.map

package/dist/replica.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica.d.ts","sourceRoot":"","sources":["../src/replica.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAkB,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAIrG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEzC,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE3D,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAY1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGlD,QAAA,MAAM,SAAS,UAA+B,CAAA;AAS9C,KAAK,YAAY,GACd;IAAE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,GACjE;IAAE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAAE,CAAA;AAEtF,KAAK,cAAc,GAChB;IAAE,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAQvD;uCACuC;AACvC,KAAK,MAAM,GACR;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAMvD,UAAU,kBAAkB,CAAC,IAAI,SAAS,eAAe;IACxD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;CAC7B;AAED,UAAU,OAAO,CAAC,IAAI,SAAS,eAAe,CAAE,SAAQ,eAAe;IACtE,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;IAC/C,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAA;IAC/D,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAChE;AAED,UAAU,IAAI,CAAC,IAAI,SAAS,eAAe;IAC1C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAA;IACZ;;4DAEwD;IACxD,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,IAAI,GAAG,IAAI,CAAA;IACzB,UAAU,EAAE,eAAe,GAAG,IAAI,CAAA;IAClC,gBAAgB,EAAE,QAAQ,GAAG,IAAI,CAAA;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC1B,UAAU,EAAE,YAAY,CAAA;CACxB;AAID,iBAAS,MAAM,CAAC,IAAI,SAAS,eAAe,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAMhF;AAED,qFAAqF;AACrF,iBAAS,QAAQ,CAAC,IAAI,SAAS,eAAe,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAWvG;AA2CD,iBAAS,SAAS,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAEzF;AAED,iBAAS,UAAU,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,UAAU,CAO5F;AAED,iBAAS,YAAY,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAI5E;AAOD;;;;eAIe;AACf,KAAK,SAAS,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAE7F,iBAAS,WAAW,CAAC,IAAI,SAAS,eAAe,EAChD,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAChB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,EACzB,EAAE,EAAE,MAAM,GAAG,IAAI,GACf,IAAI,CAGN;AAED,iBAAS,SAAS,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,CAKnF;AAqBD,iBAAe,cAAc,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3F;AA8BD,iBAAe,YAAY,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAgCD;;mCAEmC;AACnC,iBAAS,QAAQ,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAmBhH;AAsCD;;;GAGG;AACH,iBAAS,UAAU,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAU3G;AAUD;;;;GAIG;AACH,KAAK,WAAW,GACb;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,CAAA;AAE9B,iBAAS,WAAW,CACnB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,GAAG,IAAI,EAC3B,YAAY,EAAE,UAAU,EACxB,OAAO,EAAE,OAAO,GACd,WAAW,CAiBb;AA6ND;;;;0EAI0E;AAC1E,iBAAe,gBAAgB,CAAC,IAAI,SAAS,eAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB7F;AAsOD;;;;;GAKG;AACH,iBAAe,gBAAgB,CAAC,IAAI,SAAS,eAAe,EAC3D,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAChB,GAAG,EAAE,SAAS,EAAE,EAAE,EAClB,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/C;AAsDD,iBAAe,WAAW,CAAC,IAAI,SAAS,eAAe,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAiClH;AAED,YAAY,EAAE,IAAI,EAAE,kBAAkB,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AACzE,OAAO,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,YAAY,EACZ,MAAM,EACN,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,WAAW,EACX,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,CAAA"}