@bjornpagen/bumbledb-log 0.17.0 → 0.19.0

package/src/errors.ts

@@ -4,10 +4,15 @@
  * causes carried as data properties read back with the `*Of` accessors —
  * never by message-string matching. There is deliberately no
  * `ErrAlreadyApplied`: the state it would name is absorbed by idempotent
- * replay (L10) and never surfaces.
+ * replay (L10) and never surfaces. ManifestMissing, Ambiguous, OverWidth,
+ * Exhausted, and SlotRetired are named sums of their own: a replica
+ * without a manifest, an unproved conditional write, a draw past the
+ * lease width or the u64 ceiling, and a below-floor create.
  */
 
 import * as errors from "@superbuilders/errors"
+import type { Braid } from "#descriptor.ts"
+import type { Generation, StoreKey } from "#keys.ts"
 
 /**
  * Typed refusal of a protocol object before any apply: batch shape,
@@ -35,6 +40,25 @@ const ErrChainMismatch = errors.new("bumbledb-log chainMismatch: the batch viola
 /** Bounded live-tip losses exhausted — an operational signal, not an outcome arm. */
 const ErrContention = errors.new("bumbledb-log contention: consecutive live-tip losses exhausted the bound")
 
+/** A replica (or any read-role handle) found no manifest; only the writer births a store. */
+export const ErrManifestMissing = errors.new("bumbledb-log manifestMissing: the store has no manifest")
+
+/**
+ * A conditional write the transport cannot prove (S3 409, timeout, a
+ * retried PUT). The machine GET-verifies; this identity is the unproved
+ * arm, never a proved Exists or Moved.
+ */
+const ErrAmbiguous = errors.new("bumbledb-log ambiguous: the conditional write is unproved")
+
+/** A single id draw larger than one lease width; the width is the one block size. */
+const ErrOverWidth = errors.new("bumbledb-log overWidth: the draw exceeds the lease width")
+
+/** The next lease would leave u64 — the id space is spent. */
+const ErrExhausted = errors.new("bumbledb-log exhausted: the id space is spent")
+
+/** A put_create at a slot below the published checkpoint vector. */
+const ErrSlotRetired = errors.new("bumbledb-log slotRetired: the slot is retired")
+
 /** The vendor channel: I/O and store infrastructure failures. */
 const ErrStore = errors.new("bumbledb-log store failure")
 
@@ -54,26 +78,28 @@ type RefusalCause =
 	| { readonly kind: "UnknownOpKind"; readonly op: number; readonly opKind: number }
 	| { readonly kind: "UnknownRelation"; readonly op: number; readonly relation: number }
 	| { readonly kind: "ClosedRelation"; readonly op: number; readonly relation: number }
-	| { readonly kind: "OpRelationOutsideBraid"; readonly op: number; readonly relation: number; readonly braid: string }
+	| { readonly kind: "OpRelationOutsideBraid"; readonly op: number; readonly relation: number; readonly braid: Braid }
 	| { readonly kind: "TagMismatch"; readonly relation: string; readonly row: number; readonly field: string }
 	| { readonly kind: "BoolByte"; readonly relation: string; readonly row: number; readonly field: string }
 	| { readonly kind: "InvalidUtf8"; readonly relation: string; readonly row: number; readonly field: string }
 	| { readonly kind: "EmptyInterval"; readonly relation: string; readonly row: number; readonly field: string }
 	| { readonly kind: "IntervalOverflow"; readonly relation: string; readonly row: number; readonly field: string }
 	| { readonly kind: "TrailingBytes"; readonly bytes: number }
-	| { readonly kind: "ManifestShape" }
+	| { readonly kind: "DigestWidth" }
+	| { readonly kind: "Arity"; readonly op: number; readonly relation: string; readonly row: number }
+	| { readonly kind: "Malformed"; readonly at: number }
+	| { readonly kind: "Overflow" }
 	| { readonly kind: "ManifestVersion"; readonly version: number }
-	| { readonly kind: "CheckpointShape" }
 	| { readonly kind: "CheckpointBraids"; readonly carried: readonly string[]; readonly derived: readonly string[] }
 	| { readonly kind: "CheckpointDigest"; readonly expected: string; readonly computed: string }
-	| { readonly kind: "NoOpSlot"; readonly braid: string; readonly slot: bigint; readonly writer: bigint }
+	| { readonly kind: "NoOpSlot"; readonly braid: Braid; readonly slot: Generation; readonly writer: bigint }
 
 type ChainCause = "prev" | "slot" | "timestamp"
 
 interface ChainMismatchData {
 	readonly cause: ChainCause
-	readonly braid: string
-	readonly slot: bigint
+	readonly braid: Braid
+	readonly slot: Generation
 	readonly writer: bigint
 }
 
@@ -83,16 +109,46 @@ type ContentionCause =
 			readonly statement: string
 			readonly determinants: ReadonlyArray<Readonly<Record<string, unknown>>>
 	  }
-	| { readonly kind: "slot-race"; readonly tip: bigint }
+	| { readonly kind: "slot-race"; readonly tip: Generation }
 
 interface ContentionData {
-	readonly braid: string
+	readonly braid: Braid
 	readonly cause: ContentionCause
 }
 
+type AmbiguousVerb = "create" | "swap"
+
+interface AmbiguousData {
+	readonly verb: AmbiguousVerb
+	readonly key: StoreKey
+}
+
+interface OverWidthData {
+	readonly requested: bigint
+}
+
+interface ExhaustedData {
+	readonly relation: number
+	readonly field: number
+}
+
+interface SlotRetiredData {
+	readonly braid: Braid
+	readonly slot: Generation
+}
+
+/** The id-lease algebra's refusal arms: OverWidth | Exhausted. */
+type LeaseRefusal =
+	| { readonly kind: "OverWidth"; readonly requested: bigint }
+	| { readonly kind: "Exhausted"; readonly relation: number; readonly field: number }
+
 const refusalData = new WeakMap<Error, RefusalCause>()
 const chainData = new WeakMap<Error, ChainMismatchData>()
 const contentionData = new WeakMap<Error, ContentionData>()
+const ambiguousData = new WeakMap<Error, AmbiguousData>()
+const overWidthData = new WeakMap<Error, OverWidthData>()
+const exhaustedData = new WeakMap<Error, ExhaustedData>()
+const slotRetiredData = new WeakMap<Error, SlotRetiredData>()
 
 function refuse(cause: RefusalCause, detail: string): never {
 	const error = errors.wrap(ErrRefused, detail)
@@ -112,6 +168,38 @@ function throwContention(data: ContentionData, detail: string): never {
 	throw error
 }
 
+function refuseManifestMissing(detail: string): never {
+	throw errors.wrap(ErrManifestMissing, detail)
+}
+
+function isManifestMissing(error: unknown): boolean {
+	return error instanceof Error && errors.is(error, ErrManifestMissing)
+}
+
+function throwAmbiguous(data: AmbiguousData, detail: string): never {
+	const error = errors.wrap(ErrAmbiguous, detail)
+	ambiguousData.set(error, data)
+	throw error
+}
+
+function refuseOverWidth(data: OverWidthData, detail: string): never {
+	const error = errors.wrap(ErrOverWidth, detail)
+	overWidthData.set(error, data)
+	throw error
+}
+
+function refuseExhausted(data: ExhaustedData, detail: string): never {
+	const error = errors.wrap(ErrExhausted, detail)
+	exhaustedData.set(error, data)
+	throw error
+}
+
+function refuseSlotRetired(data: SlotRetiredData, detail: string): never {
+	const error = errors.wrap(ErrSlotRetired, detail)
+	slotRetiredData.set(error, data)
+	throw error
+}
+
 function refusalOf(error: Error): RefusalCause | undefined {
 	return refusalData.get(error)
 }
@@ -124,6 +212,22 @@ function contentionOf(error: Error): ContentionData | undefined {
 	return contentionData.get(error)
 }
 
+function ambiguousOf(error: Error): AmbiguousData | undefined {
+	return ambiguousData.get(error)
+}
+
+function overWidthOf(error: Error): OverWidthData | undefined {
+	return overWidthData.get(error)
+}
+
+function exhaustedOf(error: Error): ExhaustedData | undefined {
+	return exhaustedData.get(error)
+}
+
+function slotRetiredOf(error: Error): SlotRetiredData | undefined {
+	return slotRetiredData.get(error)
+}
+
 /** Every store failure wraps the exported sentinel itself, so
  *  `errors.is(e, ErrStore)` matches by identity; the vendor error's
  *  message rides the detail verbatim. */
@@ -131,20 +235,46 @@ function wrapStore(inner: Error, detail: string): Error {
 	return errors.wrap(ErrStore, `${detail}: ${inner.message}`)
 }
 
-export type { ChainCause, ChainMismatchData, ContentionCause, ContentionData, RefusalCause }
+export type {
+	AmbiguousData,
+	AmbiguousVerb,
+	ChainCause,
+	ChainMismatchData,
+	ContentionCause,
+	ContentionData,
+	ExhaustedData,
+	LeaseRefusal,
+	OverWidthData,
+	RefusalCause,
+	SlotRetiredData
+}
 export {
+	ambiguousOf,
 	chainMismatchOf,
 	contentionOf,
+	ErrAmbiguous,
 	ErrChainMismatch,
 	ErrContention,
+	ErrExhausted,
 	ErrGapDetected,
+	ErrOverWidth,
 	ErrRefused,
 	ErrReplayDiverged,
+	ErrSlotRetired,
 	ErrSpanningCommit,
 	ErrStore,
+	exhaustedOf,
+	isManifestMissing,
+	overWidthOf,
 	refusalOf,
 	refuse,
 	refuseChain,
+	refuseExhausted,
+	refuseManifestMissing,
+	refuseOverWidth,
+	refuseSlotRetired,
+	slotRetiredOf,
+	throwAmbiguous,
 	throwContention,
 	wrapStore
 }

package/src/index.ts

@@ -3,16 +3,16 @@
  * bumbledb, a thin peer of the engine SDK. Public surface: the pure
  * protocol pair (`encodeBatch`/`decodeBatch`, `braidsOf`) mirrored
  * byte-exactly against the Rust driver, the five-verb object store
- * with its tier-1 `fsStore`, and `openReplica`/`openWriter`/
+ * with its tier-1 `fsStore`, in-process `memStore`, and the `s3Store` AWS S3 client, and `openReplica`/`openWriter`/
  * `openTenants` composed from the engine SDK's own verbs — the replica
  * hands out the SDK's `Db`, and no engine surface is duplicated.
  */
 
 export type { Braid } from "#braids.ts"
-export { braidsOf, serialAtStatementsOf } from "#braids.ts"
-export type { BatchHeader, BatchOp, ChainPosition, DecodedBatch } from "#codec.ts"
+export { braid, braidsOf, serialAtStatementsOf } from "#braids.ts"
+export type { BatchHeader, ChainEntry, DecodedBatch, EncodeHeader, Op } from "#codec.ts"
 export { decodeBatch, encodeBatch, verifyChain } from "#codec.ts"
-export type { LogDescriptor, LogTheory, SerialStatement } from "#descriptor.ts"
+export type { Descriptor, SerialStatement, Theory } from "#descriptor.ts"
 export { descriptorOf } from "#descriptor.ts"
 export type { ChainCause, ChainMismatchData, ContentionCause, ContentionData, RefusalCause } from "#errors.ts"
 export {
@@ -21,18 +21,33 @@ export {
 	ErrChainMismatch,
 	ErrContention,
 	ErrGapDetected,
+	ErrManifestMissing,
 	ErrRefused,
 	ErrReplayDiverged,
 	ErrSpanningCommit,
 	ErrStore,
+	isManifestMissing,
 	refusalOf
 } from "#errors.ts"
+export type { Generation, StoreKey } from "#keys.ts"
+export {
+	CKPT_SCRATCH_LEASE,
+	encodeCkptScratch,
+	generation,
+	LEASE_NAMESPACE,
+	parseCkptScratch,
+	scratchCkptDigest,
+	scratchCkptName,
+	storeKey
+} from "#keys.ts"
 export type { OpenReplicaOptions, Replica } from "#replica.ts"
 export { openReplica } from "#replica.ts"
-export type { Create, Fetched, ObjectStore, Poll, Swap } from "#store.ts"
-export { fsStore } from "#store.ts"
+export type { Create, Etag, Fetched, ObjectStore, Poll, S3Config, S3Credentials, Swap } from "#store.ts"
+export { etag, fsStore, memStore, s3Store } from "#store.ts"
 export type { OpenTenantsOptions, Tenants } from "#tenants.ts"
 export { openTenants } from "#tenants.ts"
-export type { LogInterval, LogValue } from "#value.ts"
-export type { BraidOutcome, Commit, CommitSplit, Durability, LogBatch, Writer } from "#writer.ts"
+export type { Interval, Value } from "#value.ts"
+export type { CheckpointOrder, VectorParse } from "#vector.ts"
+export { Overflow, Vector } from "#vector.ts"
+export type { Batch, BraidOutcome, Commit, CommitSplit, Durability, Writer } from "#writer.ts"
 export { openWriter } from "#writer.ts"

package/src/keys.ts

@@ -1,34 +1,231 @@
 /**
- * The key layout (10): generation numbers zero-padded lowercase hex,
- * 16 chars; a prefix is a store; a tenant is a prefix under `t/`.
+ * The key layout: generation numbers zero-padded lowercase hex, 16
+ * chars; a prefix is a store; a tenant is a prefix under `t/`. A
+ * StoreKey is parsed here, once — the verbs take the proof and never
+ * re-check. An empty prefix joins as the rest alone, so a leading
+ * slash is unrepresentable. Temps and leases live under a reserved
+ * tilde-family first segment no StoreKey can spell — ASCII `~` and
+ * its lookalikes — so those namespaces stay disjoint from every
+ * honest key. Format characters, line and paragraph separators, and
+ * space separators cannot hide a reserved prefix or a `.lock` suffix.
  */
 
-function hex16(g: bigint): string {
+import * as errors from "@superbuilders/errors"
+import { regex } from "arkregex"
+import type { Digest32 } from "#bytes.ts"
+import { digest32, hex32, U64_MAX } from "#bytes.ts"
+import type { Braid } from "#descriptor.ts"
+
+/** A segment wearing this suffix — after format characters are stripped — is not a key. */
+const LOCK_SUFFIX = ".lock"
+
+/** Reserved first-segment names no StoreKey can spell. Temps and leases live here. */
+const TEMP_NAMESPACE = "~tmp"
+const LEASE_NAMESPACE = "~lease"
+
+/** ASCII tilde and lookalikes that can spell a reserved first segment. */
+const TILDE_FAMILY = new Set([
+	"~",
+	"\u02DC",
+	"\u02F7",
+	"\u1FC0",
+	"\u2053",
+	"\u223C",
+	"\u223D",
+	"\u223F",
+	"\u2E1E",
+	"\u2E1F",
+	"\u301C",
+	"\u3030",
+	"\uFE4B",
+	"\uFE4F",
+	"\uFF5E"
+])
+
+const FORMAT_OR_SEPARATOR = regex("[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Zs}]", "u")
+const FORMAT_CHARS = regex("\\p{Cf}", "gu")
+const SLASH_TRIM = regex("^/+|/+$", "g")
+
+declare const storeKeyBrand: unique symbol
+type StoreKey = string & { readonly [storeKeyBrand]: typeof storeKeyBrand }
+
+declare const generationBrand: unique symbol
+type Generation = bigint & { readonly [generationBrand]: typeof generationBrand }
+
+function firstCodePoint(seg: string): string | undefined {
+	for (const ch of seg) {
+		return ch
+	}
+	return undefined
+}
+
+function tildeFamilyPrefix(seg: string): boolean {
+	const first = firstCodePoint(seg)
+	if (first === undefined) {
+		return false
+	}
+	return TILDE_FAMILY.has(first) || first.normalize("NFKC") === "~"
+}
+
+function stripFormat(seg: string): string {
+	return seg.replace(FORMAT_CHARS, "")
+}
+
+/** One path segment of a key or a tenant id: the same grammar. */
+function segmentOk(seg: string): boolean {
+	if (seg.length === 0 || seg.includes("/") || seg === "." || seg === "..") {
+		return false
+	}
+	if (FORMAT_OR_SEPARATOR.test(seg)) {
+		return false
+	}
+	const stripped = stripFormat(seg)
+	if (stripped.length === 0 || stripped === "." || stripped === "..") {
+		return false
+	}
+	return !tildeFamilyPrefix(stripped) && !stripped.endsWith(LOCK_SUFFIX)
+}
+
+function storeKey(raw: string): StoreKey {
+	const wellFormed = raw.length > 0 && !raw.startsWith("/") && !raw.endsWith("/") && raw.split("/").every(segmentOk)
+	if (!wellFormed) {
+		throw errors.new(`store key is not a slash path: ${raw}`)
+	}
+	return raw as StoreKey
+}
+
+/** Empty, or a StoreKey spelling (the same segment grammar, no leading or trailing slash). */
+function parsePrefix(raw: string): string {
+	if (raw.length === 0) {
+		return ""
+	}
+	return storeKey(raw.replace(SLASH_TRIM, ""))
+}
+
+function isReservedName(name: string): boolean {
+	return tildeFamilyPrefix(stripFormat(name))
+}
+
+function reservedTemp(pid: number, seq: number): string {
+	return `${TEMP_NAMESPACE}/${String(pid)}.${String(seq)}`
+}
+
+function reservedLease(key: string, token: bigint): string {
+	return `${LEASE_NAMESPACE}/${key}/${String(token)}`
+}
+
+/** A slash path whose first segment is `~tmp` or `~lease`. Not a StoreKey. */
+function reservedName(raw: string): string {
+	const segs = raw.split("/")
+	if (segs.length === 0 || segs.some((seg) => seg.length === 0 || seg === "." || seg === "..")) {
+		throw errors.new(`reserved name is not a slash path: ${raw}`)
+	}
+	const first = segs[0]
+	if (first !== TEMP_NAMESPACE && first !== LEASE_NAMESPACE) {
+		throw errors.new(`reserved name is not under ${TEMP_NAMESPACE} or ${LEASE_NAMESPACE}: ${raw}`)
+	}
+	return raw
+}
+
+/** Known scratch-lease document under `~lease`. One path, no LIST. */
+const CKPT_SCRATCH_LEASE = "ckpt-scratch"
+
+/** The reserved scratch name: `~lease/ckpt-scratch`. */
+function scratchCkptName(): string {
+	return reservedName(`${LEASE_NAMESPACE}/${CKPT_SCRATCH_LEASE}`)
+}
+
+const SCRATCH_VERSION = 3
+
+/** The scratch-lease body: version byte 3, then the 32-byte digest. */
+function encodeCkptScratch(digest: Digest32): Uint8Array {
+	const out = new Uint8Array(33)
+	out[0] = SCRATCH_VERSION
+	out.set(digest, 1)
+	return out
+}
+
+/** The digest a scratch-lease body names, or null. */
+function scratchCkptDigest(bytes: Uint8Array): Digest32 | null {
+	if (bytes.length !== 33) {
+		return null
+	}
+	const version = bytes[0]
+	if (version !== SCRATCH_VERSION) {
+		return null
+	}
+	return digest32(bytes.subarray(1))
+}
+
+function parseCkptScratch(bytes: Uint8Array): Digest32 | null {
+	return scratchCkptDigest(bytes)
+}
+
+function generation(raw: bigint): Generation {
+	if (raw < 0n || raw > U64_MAX) {
+		throw errors.new(`generation is a u64: ${raw}`)
+	}
+	return raw as Generation
+}
+
+function hex16(g: Generation): string {
 	return g.toString(16).padStart(16, "0")
 }
 
-function manifestKey(prefix: string): string {
-	return `${prefix}/manifest.json`
+function assemble(prefix: string, rest: string): StoreKey {
+	return storeKey(prefix.length === 0 ? rest : `${prefix}/${rest}`)
 }
 
-function logKey(prefix: string, braid: string, g: bigint): string {
-	return `${prefix}/log/${braid}/${hex16(g)}`
+function manifestKey(prefix: string): StoreKey {
+	return assemble(prefix, "manifest")
 }
 
-function checkpointMdbKey(prefix: string, digest: string): string {
-	return `${prefix}/ckpt/${digest}.mdb`
+function logKey(prefix: string, braid: Braid, g: Generation): StoreKey {
+	return assemble(prefix, `log/${braid}/${hex16(g)}`)
 }
 
-function checkpointJsonKey(prefix: string, digest: string): string {
-	return `${prefix}/ckpt/${digest}.json`
+function checkpointMdbKey(prefix: string, digest: Digest32): StoreKey {
+	return assemble(prefix, `ckpt/${hex32(digest)}.mdb`)
 }
 
-function idsKey(prefix: string, relation: number, field: number): string {
-	return `${prefix}/ids/${relation.toString(16).padStart(8, "0")}/${field.toString(16).padStart(4, "0")}`
+function ckptDocKey(prefix: string, digest: Digest32): StoreKey {
+	return assemble(prefix, `ckpt/${hex32(digest)}`)
+}
+
+function idsKey(prefix: string, relation: number, field: number): StoreKey {
+	return assemble(prefix, `ids/${relation.toString(16).padStart(8, "0")}/${field.toString(16).padStart(4, "0")}`)
 }
 
 function tenantPrefix(root: string, tenant: string): string {
-	return `${root}/t/${tenant}`
+	if (!segmentOk(tenant)) {
+		throw errors.new(`tenant id is not a single path segment: ${tenant}`)
+	}
+	return assemble(root, `t/${tenant}`)
 }
 
-export { checkpointJsonKey, checkpointMdbKey, hex16, idsKey, logKey, manifestKey, tenantPrefix }
+export type { Generation, StoreKey }
+export {
+	CKPT_SCRATCH_LEASE,
+	checkpointMdbKey,
+	ckptDocKey,
+	encodeCkptScratch,
+	generation,
+	hex16,
+	idsKey,
+	isReservedName,
+	LEASE_NAMESPACE,
+	LOCK_SUFFIX,
+	logKey,
+	manifestKey,
+	parseCkptScratch,
+	parsePrefix,
+	reservedLease,
+	reservedName,
+	reservedTemp,
+	scratchCkptDigest,
+	scratchCkptName,
+	segmentOk,
+	storeKey,
+	TEMP_NAMESPACE,
+	tenantPrefix
+}