@bjornpagen/bumbledb-log 1.2.0 → 1.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 Durable named application commands over
 [Bumbledb](https://github.com/bjornpagen/bumbledb): a thin peer of
-`@bjornpagen/bumbledb` (exact peer `1.2.0`). The package adds a durable
+`@bjornpagen/bumbledb` (exact peer `1.2.1`). The package adds a durable
 envelope around the exact core change/read machinery — it never duplicates
 the engine surface. Core types (`ChangeSet`, `QueryReader`, `DbError`,
 `StorageInspection`) are the peer's own exports.
@@ -44,12 +44,12 @@ The surface is small:
 
 ## Install
 
-This guide follows the 1.2.0 source API. Use the guide from the Git tag matching
+This guide follows the 1.2.1 source API. Use the guide from the Git tag matching
 your installed package. GitHub release tarballs and npm publication are separate;
 the npm command below applies once that version is published.
 
 ```sh
-pnpm add @bjornpagen/bumbledb-log@1.2.0 @bjornpagen/bumbledb@1.2.0 effect@4.0.0-rc.112
+pnpm add @bjornpagen/bumbledb-log@1.2.1 @bjornpagen/bumbledb@1.2.1 effect@4.0.0-rc.112
 ```
 
 ## Quick start: one durable round trip
@@ -189,9 +189,10 @@ A later missing receipt is not proved loss.
 ## Backup and restore
 
 ```ts
-import { NativeRuntime } from "@bjornpagen/bumbledb"
+import { NativeRuntime, key, relation, schema, str, u64 } from "@bjornpagen/bumbledb"
 import {
 	backup,
+	IncarnationId,
 	OperationId,
 	restore,
 	verifyBackup,
@@ -200,23 +201,57 @@ import {
 import { Effect, Result } from "effect"
 
 declare const binding: LocalBinding
+// Ledger is the same declared schema used to create this history.
+const Entry = relation("Entry", { id: u64, body: str })
+const Ledger = schema("Ledger", { Entry }, [key(Entry, ["id"])])
 
 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, { operationId, destination })
+	const backed = yield* backup(binding, { operationId, destination, schema: Ledger })
 	if (backed.kind !== "completed") {
 		return backed
 	}
-	yield* verifyBackup(destination, {})
-	return yield* restore(destination, binding, { operationId })
+	yield* verifyBackup(destination, { backup: operationId })
+	const target: LocalBinding = {
+		...binding,
+		directory: "/tmp/restored-ledger",
+		identity: {
+			...binding.identity,
+			incarnationId: unwrap(IncarnationId.parse("b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2"))
+		}
+	}
+	return yield* restore(destination, target, {
+		operationId: unwrap(OperationId.parse("c3c3c3c3-c3c3-c3c3-c3c3-c3c3c3c3c3c3")),
+		backup: operationId,
+		schema: Ledger
+	})
 })
 void NativeRuntime.layer()
 void cycle
 ```
 
+Local and hosted histories produce the same independently verified backup
+format. A local capture streams one coherent native snapshot; it never copies
+live database files. The completion manifest is published last. Retry with the
+same backup operation ID to resolve the original capture, including after the
+source advances. A corrupt completed artifact refuses instead of being replaced.
+
+Persist both operation IDs and the fresh target incarnation ID before dispatch;
+the fixed IDs above are examples. Restore uses a separate operation ID, the
+backup's operation ID, and a new incarnation with the same database/schema
+identity. Adopt the completed restore's returned binding before opening it.
+Providing `schema` also supports cold administrative opens when the source is
+not already open in the runtime. Backup contains database facts and receipts;
+external documents referenced by those facts need their own retention.
+
+A completed writable restore retains its canonical genesis beside the native
+activation. Repeating the same operation, target, and backup returns that
+original result even if later commands changed the restored database. A different
+operation or backup refuses without overwriting the target.
+
 ## Migrations
 
 Schema evolution is generated, checked-in, inert data — never inferred at
@@ -242,7 +277,11 @@ runtime:
   `migrationStatus`, `initialize`, `migrate`, `activateMigration`,
   `abortMigration` — execute generated plans through the one native
   executor, with `AdminOutcome` certainty (`completed` / `not-started` /
-  `outcome-unknown`).
+  `outcome-unknown`). Cold migration opens its source from the verified
+  generated snapshot chain; applications need not retain executable retired
+  schema modules. Published local targets use the standard tenant directory
+  containing `db/`. After activation, retrying the original migration returns
+  that target binding, so adopting a retry cannot reopen the frozen source.
 
   **Current limitation:** these generated migration runner verbs target local
   authorities only. The TypeScript/native bridge refuses hosted migration
@@ -258,6 +297,6 @@ runtime:
 
 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.2.0`, `effect
+and declares both peers exactly (`@bjornpagen/bumbledb 1.2.1`, `effect
 4.0.0-rc.112`). Version lockstep across the package family is enforced in
 CI.

package/pack-provenance.json

@@ -1,7 +1,7 @@
 {
-	"candidateSourceDigest": "d4cf5cc7671b7a15bf12106752a9fb770b0d535655878f5667267e2331eae14e",
+	"candidateSourceDigest": "ca9592096bd15b3f2a56e586a074505ae6695befdad7ed4df816af59a0ae1bf5",
 	"specificationRevision": "87e9a83ee21d1f843c73ac6e7057b2b740db75aae70a553b8053b4f38e87bd2d",
-	"stagedAt": "2026-09-10T23:36:12.768Z",
+	"stagedAt": "2026-09-11T13:37:06.952Z",
 	"package": "@bjornpagen/bumbledb-log",
-	"version": "1.2.0"
+	"version": "1.2.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjornpagen/bumbledb-log",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Durable named application commands over bumbledb: LocalHistory, HostedHistory, sealed commands with retained refs, published snapshots, one native TenantCache, and explicit maintenance/migration operations (Effect-only)",
   "type": "module",
   "exports": {
@@ -49,7 +49,7 @@
   },
   "homepage": "https://github.com/bjornpagen/bumbledb#readme",
   "peerDependencies": {
-    "@bjornpagen/bumbledb": "1.2.0",
+    "@bjornpagen/bumbledb": "1.2.1",
     "effect": "4.0.0-rc.112"
   },
   "engines": {