@bjornpagen/bumbledb-log 0.20.3 → 1.0.0

package/README.md

@@ -1,127 +1,288 @@
 # @bjornpagen/bumbledb-log
 
-Braided object-store replication for [bumbledb](https://github.com/bjornpagen/bumbledb):
-a thin peer of `@bjornpagen/bumbledb` (peer `^0.19.0`). The package is
-three things:
-
-1. **The mirrored pure pair**, byte-exact against the Rust driver and
-   pinned by cross-language goldens: `encodeBatch`/`decodeBatch` (the
-   BDBL v2 command codec — a batch is header + ops, nothing else) and
-   `braidsOf(descriptor)` (the schema's own shard map, as data — with
-   `serialAtStatementsOf` naming the degenerate-serial statements beside it).
-2. **The five-verb object store** — `get`, `getIfChanged`, `putCreate`,
-   `putSwap`, `delete` — taking a branded `StoreKey` parsed once by
-   `storeKey`. `fsStore` is the tier-1 local-directory implementation;
-   `memStore` is the same five verbs over one in-process map
-   (single-process only; third `Etag` producer, blake3 like `fsStore`);
-   `s3Store` is the five verbs over S3-compatible storage (the official
-   `@aws-sdk/client-s3` client signs and talks; R2 rides region `auto`).
-3. **Replica and writer** composed from the engine SDK's existing verbs:
-   `openReplica` hands out the SDK's own `Db`; `openWriter` adds the
-   right to create log objects; `openTenants` is an LRU of per-tenant
-   replicas. No engine surface is duplicated.
-
-The package `engines` and the `.ts` test runner require Node >=24.
-
-The exported vocabulary reads as English at the call site: `Value`,
-`Interval`, `Batch`, `Theory`, `Descriptor`, `Op`, `Pending`,
-`ChainEntry`, plus the branded scalars `StoreKey`, `Generation`,
-`Etag`, and `Braid` (`storeKey`, `generation`, `etag`, `braid` parse
-at the boundary; the verbs take the proof).
-
-Async ⟺ network: `openReplica`, `refresh`, `waitFor`, `commit`,
-`commitSplit`, and disposal await store verbs; everything on
-`replica.db`, the `batch.*` recorders, and the pure pair are synchronous.
-
-## A Fluid host
+Durable named application commands over
+[Bumbledb](https://github.com/bjornpagen/bumbledb): a thin peer of
+`@bjornpagen/bumbledb` (exact peer `1.0.0`). The package adds a durable
+envelope around the exact core change/read machinery — it never duplicates
+the engine surface. Core types (`ChangeSet`, `QueryReader`,
+`ExecutionPolicy`, `DbError`, …) are the peer's own exports.
 
-```ts
-// lib/db.ts — module scope; Fluid shares this across the instance's requests
-import { fsStore, openReplica, openWriter } from "@bjornpagen/bumbledb-log"
+The API is **Effect-native**: every operation constructs a lazy
+[`Effect`](https://effect.website) and every native resource is scoped.
+There is no Promise, synchronous, or disposal twin. The package requires
+Effect `4.0.0-rc.112` exactly, as a peer dependency, and Node >= 24.
+
+The surface is small:
 
-export const replica = await openReplica({ store: s3(env), prefix: "prod/main", dir: "/tmp/store", theory: Ledger })
-export const writer = await openWriter(replica)
+1. **`LocalHistory` / `HostedHistory`** — one durable history per database.
+   Local authority is one LMDB directory; hosted authority is S3-compatible
+   object storage over immutable decisions, with a disposable local
+   materialization directory beside it. `open` of a missing or unreadable
+   configured database never creates a replacement; `create` is the explicit
+   constructor: it refuses existing authority and validates a stable
+   creation identity plus a **checked initialization artifact** (the
+   canonical schema snapshot the migration tooling renders) instead of
+   fabricating genesis.
+2. **`Command`** — `Command.seal` turns `{ scope, id, changes, precondition,
+   result }` into one owned sealed command with a copyable pre-dispatch
+   `ref`; `Command.encode`/`Command.decode` are the one bounded versioned
+   command codec. The `changes` are the core's own `ChangeSet`.
+3. **`PublishedSnapshot`** — the read side. It extends the core
+   `QueryReader` exactly (same `get`/`execute`/`session`, policies, errors
+   and result owners) and adds durable provenance: `identity`,
+   `decisionStamp`, `stateStamp`, `freshness`. `ReadOptions.consistency`
+   selects `cached`, `latest`, or `at-least` a known stamp.
+4. **`TenantCache`** — one bounded native registry of histories for
+   multi-tenant hosts: `make`/`acquire` (a `HistoryBorrow` whose `release`
+   frees only the borrow)/`inspect`/`evict`/`close`. Pressure is byte and
+   count budgets; evicting a borrowed slot refuses instead of revoking.
+5. **Maintenance and migrations** — explicit admin operations
+   (`checkpoint`, `pinRestorePoint`/`releaseRestorePoint`,
+   `rotateReceiptEpoch`, `retireReceipts`, `collectGarbage`, `backup`/
+   `verifyBackup`/`restore`, `erase`) and the generated-migration workflow
+   under the `./migrations` subpath (below).
 
-// route handler
-const out = await writer.commit((batch) => batch.insert(Booking, [row]))
-if (out.tag === "accepted") ctx.waitUntil(replica.refresh(out.braid))
+## Install
+
+```sh
+pnpm add @bjornpagen/bumbledb-log@1.0.0 @bjornpagen/bumbledb@1.0.0 effect@4.0.0-rc.112
 ```
 
-- **The `/tmp` budget gate**: checkpoint plus working set must stay
-  ≤ 400 MB (100 MB headroom under the 500 MB instance limit); the
-  leaf-blob pattern keeps metadata stores in the tens of MB. Per-tenant
-  fleets get the same gate through `openTenants({ budgetBytes, maxOpen })`.
-- **Cross-instance read-your-writes**: a commit returns
-  `{ braid, generation }`; a session token is the pointwise max of every
-  pair a flow has seen; `replica.waitFor(vector)` refreshes until the
-  local vector dominates it. The committing instance always reads its
-  own writes without waiting. A singleton map is the single-braid form.
-- **The `ErrContention` runbook**: the error carries its cause, sourced
-  from the terminal re-judgment itself — `{ kind: "hot-key", statement,
-  determinants }` names the statement and carries the offending facts'
-  raw values from the engine's own violation; the remedies are a
-  reservation relation on the hot capacity (an ordinary weighted child
-  row — the schema idiom) or resident mode. `{ kind: "slot-race", tip }`
-  means the terminal losses were accepted but out-raced: an operational
-  signal to shard the theory into more braids or move the hot braid to
-  a resident Rust writer, whose group commit batches the queue.
-
-## A local fleet
+## Quick start: one durable round trip
+
+Create a local history with its checked initialization artifact, seal one
+insert command, submit it to a decided receipt, then reopen the directory
+and resolve the retained ref to the exact recorded outcome.
 
 ```ts
-// one process per scope loop; all processes share one fsStore prefix
-import { fsStore, openReplica, openWriter } from "@bjornpagen/bumbledb-log"
-
-const replica = await openReplica({
-	store: fsStore("/data/primer/log"), // the five verbs over a directory
-	prefix: "world/v1",
-	dir: `/data/primer/replicas/${scopeName}`, // per-process local dir — never shared
-	theory: Explanation
+import * as fs from "node:fs/promises"
+import { ChangeSet, key, NativeRuntime, relation, Schema, schema, str, u64 } from "@bjornpagen/bumbledb"
+import type { ExecutionPolicy, NativeRuntimeOptions } from "@bjornpagen/bumbledb"
+import { Command, DatabaseId, IncarnationId, LocalHistory, OperationId, ReceiptEpoch, RequestId } from "@bjornpagen/bumbledb-log"
+import type { DatabaseIdentity, LocalBinding, ReadOptions, SubmitOptions } from "@bjornpagen/bumbledb-log"
+import { Effect, ManagedRuntime, Result } from "effect"
+
+const Entry = relation("Entry", { id: u64, body: str })
+const Ledger = schema("Ledger", { Entry }, [key(Entry, ["id"])])
+
+const runtimeOptions: NativeRuntimeOptions = {
+	workers: 2,
+	queueCapacity: 16,
+	cleanupCapacity: 16,
+	ownerCapacity: 16,
+	nativeHandleCapacity: 64,
+	inputBytes: 8_000_000n,
+	workingBytes: 8_000_000n,
+	scratchBytes: 8_000_000n,
+	resultBytes: 1_000_000n,
+	chunkBytes: 1_000_000n,
+	cleanupTimeout: "2 seconds"
+}
+const work: ExecutionPolicy = {
+	inputBytes: 1_000_000n,
+	workingBytes: 1_000_000n,
+	scratchBytes: 1_000_000n,
+	resultBytes: 100_000n,
+	rows: 100_000n,
+	workUnits: 10_000_000n,
+	timeout: "10 seconds"
+}
+const submitOptions: SubmitOptions = { ...work, attempts: 4, backoff: { baseMillis: 5, capMillis: 100 } }
+const readOptions: ReadOptions = { ...work, consistency: { kind: "cached" } }
+
+// Genuinely fallible small parsing is Result, not Effect.
+const unwrap = <A, E>(result: Result.Result<A, E>): A => Result.getOrThrow(result)
+
+const program = Effect.gen(function* () {
+	const compiled = yield* Schema.compile(Ledger, work)
+	// The checked initialization artifact: the canonical schema snapshot the
+	// migration generator wrote to your checked-in repository. Its native
+	// fingerprint IS the identity's schemaId — creation re-judges both.
+	const artifact: Uint8Array = yield* Effect.tryPromise(() =>
+		fs.readFile("bumbledb/migrations/meta/0000.schema.json")
+	)
+	const identity: DatabaseIdentity = {
+		databaseId: unwrap(DatabaseId.parse("abababab-abab-abab-abab-abababababab")),
+		incarnationId: unwrap(IncarnationId.parse("cdcdcdcd-cdcd-cdcd-cdcd-cdcdcdcdcdcd")),
+		schemaId: compiled.schemaId
+	}
+	const binding: LocalBinding = { kind: "local", directory: "/tmp/ledger", identity }
+
+	// Scope 1: create, seal, submit; retain the ref and receipt.
+	const retained = yield* Effect.scoped(
+		Effect.gen(function* () {
+			const history = yield* LocalHistory.create(binding, Ledger, {
+				...work,
+				creation: {
+					operationId: unwrap(OperationId.parse("e1e1e1e1-e1e1-e1e1-e1e1-e1e1e1e1e1e1")),
+					artifact
+				}
+			})
+			const draft = yield* ChangeSet.builder(Ledger, work)
+			yield* draft.insert(Entry, [{ id: 42n, body: "hello" }])
+			const changes = yield* draft.finish()
+			const command = yield* Command.seal(
+				{
+					scope: history.identity,
+					// Generate ids ONCE for an original intent and persist them;
+					// a retry resubmits the identical sealed command.
+					id: {
+						receiptEpoch: unwrap(ReceiptEpoch.from(1n)),
+						requestId: unwrap(RequestId.parse("0b0b0b0b-0b0b-0b0b-0b0b-0b0b0b0b0b0b"))
+					},
+					changes,
+					precondition: { kind: "blind" },
+					result: {}
+				},
+				work
+			)
+			// Submission certainty is data; interruption remains interruption.
+			const outcome = yield* history.submit(command, submitOptions)
+			if (outcome.kind !== "decided") {
+				return yield* Effect.die("expected a decided submit in this example")
+			}
+			return { ref: command.ref, receipt: outcome.receipt }
+		})
+	)
+
+	// Scope 2: reopen; the retained ref resolves to the recorded receipt,
+	// and the committed fact reads back through the core QueryReader.
+	yield* Effect.scoped(
+		Effect.gen(function* () {
+			const history = yield* LocalHistory.open(binding, Ledger, work)
+			const resolved = yield* history.resolve(retained.ref, work)
+			if (resolved.kind === "found" && resolved.receipt.outcome.kind === "committed") {
+				const snapshot = yield* history.snapshot(readOptions)
+				const fact = yield* snapshot.get(Entry, { id: 42n }, work)
+				yield* Effect.log(fact._tag === "Some" ? fact.value.body : "missing")
+			}
+		})
+	)
 })
-const writer = await openWriter(replica)
-
-// one pass = refresh, render, emit, lower, one commit
-await replica.refresh()
-const out = await writer.commit((batch) => {
-	batch.insert(Explanation, growth.explanations) // ids from batch.reserve
-	batch.insert(Case, growth.cases)
-	return growth.summary
+
+const runtime = ManagedRuntime.make(NativeRuntime.layer(runtimeOptions))
+await runtime.runPromise(program)
+await Effect.runPromise(runtime.disposeEffect)
+```
+
+## Certainty, receipts, and errors
+
+`submit` returns `Effect<SubmitOutcome>` with `E = never` — the outcome is a
+three-armed certainty sum, never an exception channel:
+
+- `decided` — the authority recorded a decision; the arm carries the
+  `TerminalReceipt` (`committed`, `no-change`, `precondition-failed`, or
+  `invariant-rejected` with canonical violation evidence).
+- `not-submitted` — proven never registered (a typed cause rides along);
+  safe to fix and submit a NEW command.
+- `outcome-unknown` — dispatch crossed the authority boundary but the
+  decision could not be read back. Never retried blindly: `resolve(ref)`
+  later returns `found`, `not-recorded-at`, `command-epoch-closed`, or
+  `receipt-expired-unknown`. Absence at one decision is not proof that an
+  in-flight command will never publish.
+
+Fiber interruption remains interruption in Effect's `Cause`; it joins native
+cleanup, not an invented successful outcome. Retain the command ref or admin
+operation identity before dispatch and resolve it after cancellation. A failed
+cleanup adds a `CloseFailure` defect without erasing the interruption.
+
+Receipts and refs are plain owned data: they outlive their scope, survive
+process restarts (render/parse with `renderCommandRef`/`parseCommandRef`),
+and `resolve` after reopen returns the exact recorded outcome.
+
+Failures that ARE errors use exactly two classes, checked by `_tag`, never
+message strings: the core's own `DbError`, unchanged, for core failures
+crossing the log; and `ProtocolError` for the log-specific reason roster
+(`protocolErrorCodes` spells it natively — contention, consistency
+not-yet-available, artifact/authority/identity refusals, maintenance
+backpressure, migration reasons). `LogError = DbError | ProtocolError` and
+nothing else. Interruption and finalizer defects stay in `Cause`.
+
+The same core `QueryReader` helper that lists a local `Db` snapshot lists a
+published history snapshot. There is no log-specific query wrapper. The
+packed consumer spells this as `readAttempts(snapshot, student, work)` on
+both `Db.snapshot` and `history.snapshot`.
+
+Retain the command or admin `operationId` **before** `submit` / `initialize` /
+`backup` / `restore`. `outcome-unknown` is resolved under that identity.
+A later missing receipt is not proved loss.
+
+## Backup and restore
+
+```ts
+import { NativeRuntime } from "@bjornpagen/bumbledb"
+import type { ExecutionPolicy, NativeRuntimeOptions } from "@bjornpagen/bumbledb"
+import {
+	backup,
+	OperationId,
+	restore,
+	verifyBackup,
+	type LocalBinding
+} from "@bjornpagen/bumbledb-log"
+import { Effect, Result } from "effect"
+
+declare const runtimeOptions: NativeRuntimeOptions
+declare const work: ExecutionPolicy
+declare const binding: LocalBinding
+
+const unwrap = <A, E>(result: Result.Result<A, E>): A => Result.getOrThrow(result)
+
+const cycle = Effect.gen(function* () {
+	const operationId = unwrap(OperationId.parse("a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1"))
+	const destination = { kind: "filesystem" as const, directory: "/tmp/ledger-backup" }
+	const backed = yield* backup(binding, { ...work, operationId, destination })
+	if (backed.kind !== "completed") {
+		return backed
+	}
+	yield* verifyBackup(destination, work)
+	return yield* restore(destination, binding, { ...work, operationId })
 })
-// rejected ⇒ the host re-renders against the moved world and re-lowers —
-// a K-conflict double-mint resolves to the winner's row on the next pass.
+void NativeRuntime.layer(runtimeOptions)
+void cycle
 ```
 
-What makes the case easy: an insert-only theory has no delete races to
-lose; content-keyed determinants keep concurrent scope loops off each
-other's obligations, so a lost slot re-judges to the same accepted
-verdict at the moved base; a one-braid theory serializes slot claims on
-a link publication, which at document-per-minutes commit rates is free.
-Each process owns its local replica directory outright.
-
-**`fsStore`'s discipline, stated** — the one on-disk protocol the Rust
-`FsStore` also speaks, raced against it in the interop conformance
-lane: `putCreate` writes an exclusive synced temp and publishes it with
-`fs.link` (EEXIST is the honest `exists`); etags are the blake3 of the
-content, computed on every read and never stored; `putSwap` serializes
-under a pid-lockfile beside the key, published with the same
-temp-plus-link discipline, and a lock whose owner pid is dead is broken
-and retaken. One machine is load-bearing, not descriptive — pid
-liveness and link exclusivity are the arbitration primitives, and
-network filesystems weaken both; an `fsStore` prefix on a network mount
-is a misdeployment. `putCreate` and `putSwap` resolve only after fsync
-of the object file and its parent directory.
-
-## Error identity
-
-Exported sentinel values on the SDK idiom, checked with `errors.is`,
-never by message strings: `ErrRefused` (typed per cause — batch shape,
-version, fingerprint, manifest shape, checkpoint braid-set drift),
-`ErrManifestMissing` (a replica found no manifest; only the writer
-births a store), `ErrSpanningCommit`, `ErrGapDetected`, `ErrReplayDiverged`,
-`ErrChainMismatch` (cause `"prev" | "slot" |
-"timestamp"`), `ErrContention` (cause `hot-key` or `slot-race`),
-`ErrStore` (the vendor channel, present in every wrapped store
-failure's cause chain so the `errors.is` match is by identity). There
-is deliberately no
-`ErrAlreadyApplied`: the state it would name is absorbed by idempotent
-replay and never surfaces.
+## Migrations
+
+Schema evolution is generated, checked-in, inert data — never inferred at
+runtime:
+
+- `@bjornpagen/bumbledb-log/schema` — pure intent constructors
+  (`migrationIntent`, `renameField`, `renameRelation`, `convert`,
+  `backfill`, `seed`, `dropField`, `dropRelation`). No native work at
+  import or call.
+- `@bjornpagen/bumbledb-log/migrations` — `generateMigrations` diffs the
+  declared schema against the recorded chain and appends one validated,
+  canonically rendered plan to the repository (`manifest.json`,
+  `NNNN-<label>.plan.json`, `meta/NNNN.schema.json`, `snapshots.json`,
+  `index.ts` exporting `{ manifest, plans, snapshots }`, and the
+  `runtime-contract.json` your deploy pins). The admin runner decodes that
+  triple — snapshots are the empty-base schema plus one target per entry.
+  `checkMigrations` is the same judgment without writes. Ordinary onboarding
+  is generated `initialize`,
+  then `LocalHistory.open`. `HostedHistory.open` requires an already
+  initialized hosted authority. `LocalHistory.create`
+  remains the explicit constructor when a checked artifact is already in
+  hand — it is not the Notes/Alchemy path. The runner verbs —
+  `migrationStatus`, `initialize`, `migrate`, `activateMigration`,
+  `abortMigration` — execute generated plans through the one native
+  executor, with `AdminOutcome` certainty (`completed` / `not-started` /
+  `outcome-unknown`).
+
+  **Current limitation:** these generated migration runner verbs target local
+  authorities only. The TypeScript/native bridge refuses hosted migration
+  execution; a hosted tenant's cache is not an authoritative local migration
+  target. Hosted migration orchestration is not supported in 1.0; the
+  production-ready scope is local history. Real-S3 and Graviton qualification
+  remain deferred, not passed.
+- Field arithmetic such as `Scalar.add(Scalar.field("units"), Scalar.u64(1n))`
+  is valid intent metadata. Native chain compilation binds it before any
+  new manifest write or source freeze, including zero input rows.
+- The `bumbledb-log` bin is the same generator/checker as a CLI.
+
+## Platform and packaging
+
+The native engine arrives through the peer `@bjornpagen/bumbledb`
+(darwin-arm64, linux-arm64, linux-x64); this package ships TypeScript only
+and declares both peers exactly (`@bjornpagen/bumbledb 1.0.0`, `effect
+4.0.0-rc.112`). Version lockstep across the package family is enforced in
+CI.

package/dist/admin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Maintenance operations as Effects with the chapter 35 admin certainty:
+ * mutating operations return `AdminOutcome<Value>` in A with E = never
+ * (completed / not-started / outcome-unknown around a small immutable
+ * operation reference derived BEFORE dispatch); read-only verification has
+ * typed E. These are language wrappers over each operation's existing
+ * protocol report and identity (database/epoch/root/barrier/operation) —
+ * no generic admin journal, manufactured maintenance receipts, or shared
+ * durable state machine is added. Interruption stays in Cause; the retained
+ * operation reference resolves it through `migrationStatus`/`inspect`.
+ */
+import type { AdminOperations } from "./machine.js";
+export declare const checkpoint: AdminOperations["checkpoint"];
+export declare const pinRestorePoint: AdminOperations["pinRestorePoint"];
+export declare const releaseRestorePoint: AdminOperations["releaseRestorePoint"];
+export declare const rotateReceiptEpoch: AdminOperations["rotateReceiptEpoch"];
+export declare const retireReceipts: AdminOperations["retireReceipts"];
+export declare const collectGarbage: AdminOperations["collectGarbage"];
+export declare const backup: AdminOperations["backup"];
+export declare const verifyBackup: AdminOperations["verifyBackup"];
+export declare const restore: AdminOperations["restore"];
+export declare const erase: AdminOperations["erase"];
+export type { AdminIdentityOptions, AdminOperations, BackupDestination, TenantOpenOptions } from "./machine.js";
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlD,eAAO,MAAM,UAAU,EAAE,eAAe,CAAC,YAAY,CAAwB,CAAA;AAC7E,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,iBAAiB,CAA6B,CAAA;AAC5F,eAAO,MAAM,mBAAmB,EAAE,eAAe,CAAC,qBAAqB,CAAiC,CAAA;AACxG,eAAO,MAAM,kBAAkB,EAAE,eAAe,CAAC,oBAAoB,CAAgC,CAAA;AACrG,eAAO,MAAM,cAAc,EAAE,eAAe,CAAC,gBAAgB,CAA4B,CAAA;AACzF,eAAO,MAAM,cAAc,EAAE,eAAe,CAAC,gBAAgB,CAA4B,CAAA;AACzF,eAAO,MAAM,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAoB,CAAA;AACjE,eAAO,MAAM,YAAY,EAAE,eAAe,CAAC,cAAc,CAA0B,CAAA;AACnF,eAAO,MAAM,OAAO,EAAE,eAAe,CAAC,SAAS,CAAqB,CAAA;AACpE,eAAO,MAAM,KAAK,EAAE,eAAe,CAAC,OAAO,CAAmB,CAAA;AAE9D,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/dist/admin.js

@@ -0,0 +1,12 @@
+import { log } from "#production.ts";
+export const checkpoint = log.admin.checkpoint;
+export const pinRestorePoint = log.admin.pinRestorePoint;
+export const releaseRestorePoint = log.admin.releaseRestorePoint;
+export const rotateReceiptEpoch = log.admin.rotateReceiptEpoch;
+export const retireReceipts = log.admin.retireReceipts;
+export const collectGarbage = log.admin.collectGarbage;
+export const backup = log.admin.backup;
+export const verifyBackup = log.admin.verifyBackup;
+export const restore = log.admin.restore;
+export const erase = log.admin.erase;
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AAEpC,MAAM,CAAC,MAAM,UAAU,GAAkC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAA;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAuC,GAAG,CAAC,KAAK,CAAC,eAAe,CAAA;AAC5F,MAAM,CAAC,MAAM,mBAAmB,GAA2C,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAA;AACxG,MAAM,CAAC,MAAM,kBAAkB,GAA0C,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAA;AACrG,MAAM,CAAC,MAAM,cAAc,GAAsC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAA;AACzF,MAAM,CAAC,MAAM,cAAc,GAAsC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAA;AACzF,MAAM,CAAC,MAAM,MAAM,GAA8B,GAAG,CAAC,KAAK,CAAC,MAAM,CAAA;AACjE,MAAM,CAAC,MAAM,YAAY,GAAoC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAA;AACnF,MAAM,CAAC,MAAM,OAAO,GAA+B,GAAG,CAAC,KAAK,CAAC,OAAO,CAAA;AACpE,MAAM,CAAC,MAAM,KAAK,GAA6B,GAAG,CAAC,KAAK,CAAC,KAAK,CAAA"}

package/dist/bridge.d.ts

@@ -0,0 +1,30 @@
+import type { CloseReport, CloseWire, OperationHandle } from "@bjornpagen/bumbledb/internal/log";
+import { Effect, type Scope } from "effect";
+import type { LogError } from "./errors.js";
+export type CancelVerb = (operation: OperationHandle, callback: (report: CloseWire) => void) => void;
+export declare function closeReportOf(operation: string, report: CloseWire): CloseReport;
+/**
+ * Run one native close/release transition to completion. Uninterruptible:
+ * teardown uses the runtime's reserved cleanup envelope, and abandoning the
+ * callback would fake quiescence.
+ */
+export declare function drainClose(operation: string, start: (callback: (report: CloseWire) => void) => void): Effect.Effect<CloseReport>;
+/**
+ * One bounded log operation with typed E. Registration failures and
+ * completion decode failures both fail with the typed union; interruption
+ * cancels and joins the native lease, including a late successful result.
+ */
+export declare function logOperation<Value, A>(operation: string, cancel: CancelVerb, start: (callback: () => void) => OperationHandle, take: (operation: OperationHandle) => Value, accept: (value: Value) => A): Effect.Effect<A, LogError>;
+/**
+ * Transport completion/refusal is data in the certainty union. Fiber
+ * interruption stays in Cause: it joins native cancellation, but cannot prove
+ * nonpublication. Resolve the command/operation ref retained before dispatch.
+ */
+export declare function certaintyOperation<Value, A>(operation: string, cancel: CancelVerb, start: (callback: () => void) => OperationHandle, take: (operation: OperationHandle) => Value, accept: (value: Value) => A, beforeDispatch: (error: LogError) => A, afterDispatch: (error: LogError) => A): Effect.Effect<A>;
+/**
+ * Scoped ownership of a native resource: interruptible acquisition through
+ * the cancellation-safe bridge above, and a finalizer that runs the stored
+ * native close and dies with `CloseFailure` on incomplete/failed drain.
+ */
+export declare function scopedResource<A, E>(operation: string, acquire: Effect.Effect<A, E>, close: (resource: A) => Effect.Effect<CloseReport>): Effect.Effect<A, E, Scope.Scope>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAA;AAEhG,OAAO,EAAE,MAAM,EAAQ,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAG1C,MAAM,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,KAAK,IAAI,CAAA;AAEpG,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,WAAW,CAK/E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,KAAK,IAAI,GACpD,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAQ5B;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,CAAC,EACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,eAAe,EAChD,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,KAAK,EAC3C,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,GACzB,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAE5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,CAAC,EAC1C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,eAAe,EAChD,IAAI,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,KAAK,EAC3C,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,EAC3B,cAAc,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,CAAC,EACtC,aAAa,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,CAAC,GACnC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAUlB;AA6CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,GAChD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAMlC"}

package/dist/bridge.js

@@ -0,0 +1,92 @@
+/**
+ * Effect-side adaptation of the C09 executor pattern for log operations.
+ * Registration returns the native lease before any completion runs in JS;
+ * interruption signals native cancellation and JOINS the drain (an
+ * incomplete or failed drain surfaces as a structured `CloseFailure` defect
+ * in the finalizer `Cause`, never false quiescence). No Promise or libuv
+ * job is created; there is no JS critical section, timer, or queue here.
+ */
+import { DbError } from "@bjornpagen/bumbledb";
+import { finalizeClose } from "@bjornpagen/bumbledb/internal/log";
+import { Effect, Exit } from "effect";
+import { logFailure } from "#errors.ts";
+export function closeReportOf(operation, report) {
+    if (report.kind === "failed") {
+        return { kind: "failed", error: new DbError({ operation, reason: { _tag: "Internal" } }) };
+    }
+    return report;
+}
+/**
+ * Run one native close/release transition to completion. Uninterruptible:
+ * teardown uses the runtime's reserved cleanup envelope, and abandoning the
+ * callback would fake quiescence.
+ */
+export function drainClose(operation, start) {
+    return Effect.callback((resume) => {
+        try {
+            start((report) => resume(Effect.succeed(closeReportOf(operation, report))));
+        }
+        catch (cause) {
+            resume(Effect.succeed({ kind: "failed", error: toDbError(operation, cause) }));
+        }
+    }).pipe(Effect.uninterruptible);
+}
+function toDbError(operation, cause) {
+    const typed = logFailure(operation, cause);
+    return typed instanceof DbError ? typed : new DbError({ operation, reason: { _tag: "Internal" } });
+}
+/**
+ * One bounded log operation with typed E. Registration failures and
+ * completion decode failures both fail with the typed union; interruption
+ * cancels and joins the native lease, including a late successful result.
+ */
+export function logOperation(operation, cancel, start, take, accept) {
+    return nativeOperation(operation, cancel, start, take, accept, Effect.fail, Effect.fail);
+}
+/**
+ * Transport completion/refusal is data in the certainty union. Fiber
+ * interruption stays in Cause: it joins native cancellation, but cannot prove
+ * nonpublication. Resolve the command/operation ref retained before dispatch.
+ */
+export function certaintyOperation(operation, cancel, start, take, accept, beforeDispatch, afterDispatch) {
+    return nativeOperation(operation, cancel, start, take, accept, (error) => Effect.succeed(beforeDispatch(error)), (error) => Effect.succeed(afterDispatch(error)));
+}
+/** The one lease lifecycle shared by typed-error and certainty operations. */
+function nativeOperation(operation, cancel, start, take, accept, beforeDispatch, afterDispatch) {
+    return Effect.suspend(() => {
+        let report;
+        return Effect.callback((resume, signal) => {
+            let lease;
+            try {
+                lease = start(() => {
+                    if (signal.aborted)
+                        return;
+                    try {
+                        resume(Effect.succeed(accept(take(lease))));
+                    }
+                    catch (cause) {
+                        resume(afterDispatch(logFailure(operation, cause)));
+                    }
+                });
+            }
+            catch (cause) {
+                resume(beforeDispatch(logFailure(operation, cause)));
+                return;
+            }
+            // Callback finalizers must succeed so Effect retains the interrupt.
+            return drainClose(`${operation}.cancel`, (callback) => cancel(lease, callback)).pipe(Effect.tap((closed) => {
+                report = closed;
+                return Effect.void;
+            }), Effect.asVoid);
+        }).pipe(Effect.onExit((exit) => Exit.hasInterrupts(exit) && report !== undefined ? finalizeClose(`${operation}.cancel`, report) : Effect.void));
+    });
+}
+/**
+ * Scoped ownership of a native resource: interruptible acquisition through
+ * the cancellation-safe bridge above, and a finalizer that runs the stored
+ * native close and dies with `CloseFailure` on incomplete/failed drain.
+ */
+export function scopedResource(operation, acquire, close) {
+    return Effect.acquireRelease(acquire, (resource) => close(resource).pipe(Effect.flatMap((report) => finalizeClose(operation, report))), { interruptible: true });
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

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

package/dist/codes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The log-specific error-code roster. This list must stay pinned to the
+ * native `logErrorCodes()` export (one speller, the internal Rust machine);
+ * an authored roster test compares them exactly. Core failures are never
+ * respelled here: a core failure crossing the log surface remains the exact
+ * core `DbError` with its own roster. These codes are only the protocol's
+ * additions.
+ */
+export declare const protocolErrorCodes: readonly ["ForeignIdentity", "CommandIdentityConflict", "DatabaseDeleted", "DatabaseFrozen", "CommandEpochClosed", "ReceiptExpiredUnknown", "NotInitialized", "DatabaseMissing", "AuthorityExists", "CacheIdentityMismatch", "WrongLineage", "NotYetAvailable", "WitnessUnavailable", "SnapshotExpired", "MaintenanceRequired", "MaterializationStale", "RootCapacityExceeded", "SlotBorrowed", "Contention", "IncompleteRejectionEvidence", "MigrationRequired", "MigrationDrift", "MigrationIntentRequired", "MigrationUnsupported", "MigrationRepository", "DatabaseAhead", "MigrationOutputMismatch", "OperationConflict", "InsufficientLocalDisk", "UnsupportedArtifact", "Corruption", "Backend", "Misuse"];
+export type ProtocolCode = (typeof protocolErrorCodes)[number];
+//# sourceMappingURL=codes.d.ts.map

package/dist/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../src/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,YAE9B,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EAEvB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EAEjB,qBAAqB,EAKrB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,6BAA6B,EAE7B,mBAAmB,EACnB,gBAAgB,EAChB,yBAAyB,EACzB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EAEnB,uBAAuB,EACvB,qBAAqB,EACrB,YAAY,EACZ,SAAS,EACT,QAAQ,CACC,CAAA;AAEV,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA"}