@bjornpagen/bumbledb-log 0.20.1 → 0.20.2

package/src/keys.ts

@@ -1,224 +0,0 @@
-/**
- * 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 — the generated
- * table under `conformance/v3/keys/` is the set, read at module init
- * — 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: a segment
- * containing one is refused outright.
- */
-
-import * as fs from "node:fs"
-import { internalLogParseCkptScratch, internalLogRenderCkptScratch } from "@bjornpagen/bumbledb"
-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 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"
-
-/**
- * The one tilde table both drivers consume: ASCII `~`, its lookalikes, and
- * the NFKC preimage of U+007E. The packaged copy beside this module is the
- * census-pinned byte-identical twin of the generator's output at
- * crates/bumbledb-log/conformance/v3/keys/tilde-family.json, so the read
- * never leaves the published files roster.
- */
-const TILDE_TABLE_URL = new URL("./tilde-family.json", import.meta.url)
-
-const CODE_POINT_SPELLING = regex("^U\\+[0-9A-F]{4,6}$")
-
-function loadTildeFamily(): Set<string> {
-	const raw = fs.readFileSync(TILDE_TABLE_URL, "utf8")
-	const table: unknown = JSON.parse(raw)
-	if (typeof table !== "object" || table === null || !("codePoints" in table)) {
-		throw errors.new(`tilde table is not a codePoints document: ${TILDE_TABLE_URL.pathname}`)
-	}
-	const { codePoints } = table
-	if (!Array.isArray(codePoints) || codePoints.length === 0) {
-		throw errors.new(`tilde table codePoints is not a nonempty array: ${TILDE_TABLE_URL.pathname}`)
-	}
-	const family = new Set<string>()
-	for (const spelling of codePoints) {
-		if (typeof spelling !== "string" || !CODE_POINT_SPELLING.test(spelling)) {
-			throw errors.new(`tilde table entry is not a U+XXXX code point: ${String(spelling)}`)
-		}
-		family.add(String.fromCodePoint(Number.parseInt(spelling.slice(2), 16)))
-	}
-	if (!family.has("~")) {
-		throw errors.new(`tilde table does not reserve ASCII tilde: ${TILDE_TABLE_URL.pathname}`)
-	}
-	return family
-}
-
-/** First-segment code points that spell a reserved name. The table is the set; no local spelling. */
-const TILDE_FAMILY = loadTildeFamily()
-
-const FORMAT_OR_SEPARATOR = regex("[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Zs}]", "u")
-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)
-}
-
-/** 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
-	}
-	return !tildeFamilyPrefix(seg) && !seg.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 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}`)
-}
-
-/** The scratch-lease body, spelled by the one grammar (`crates/bumbledb-log`). */
-function encodeCkptScratch(digest: Digest32): Uint8Array {
-	return internalLogRenderCkptScratch(digest)
-}
-
-/** The digest a scratch-lease body names, or null — the one grammar's
- *  parse, branded; the refusal is undifferentiated by law. */
-function parseCkptScratch(bytes: Uint8Array): Digest32 | null {
-	const named = internalLogParseCkptScratch(bytes)
-	if (named === null) {
-		return null
-	}
-	return digest32(named)
-}
-
-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 assemble(prefix: string, rest: string): StoreKey {
-	return storeKey(prefix.length === 0 ? rest : `${prefix}/${rest}`)
-}
-
-function manifestKey(prefix: string): StoreKey {
-	return assemble(prefix, "manifest")
-}
-
-function logKey(prefix: string, braid: Braid, g: Generation): StoreKey {
-	return assemble(prefix, `log/${braid}/${hex16(g)}`)
-}
-
-function checkpointMdbKey(prefix: string, digest: Digest32): StoreKey {
-	return assemble(prefix, `ckpt/${hex32(digest)}.mdb`)
-}
-
-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 {
-	if (!segmentOk(tenant)) {
-		throw errors.new(`tenant id is not a single path segment: ${tenant}`)
-	}
-	return assemble(root, `t/${tenant}`)
-}
-
-export type { Generation, StoreKey }
-export {
-	CKPT_SCRATCH_LEASE,
-	checkpointMdbKey,
-	ckptDocKey,
-	encodeCkptScratch,
-	generation,
-	idsKey,
-	LEASE_NAMESPACE,
-	logKey,
-	manifestKey,
-	parseCkptScratch,
-	parsePrefix,
-	reservedLease,
-	reservedName,
-	reservedTemp,
-	scratchCkptName,
-	storeKey,
-	TEMP_NAMESPACE,
-	tenantPrefix
-}

package/src/manifest.ts

@@ -1,161 +0,0 @@
-/**
- * The protocol's one mutable object and its checkpoint, as typed
- * payloads. The byte grammar has one implementation —
- * `crates/bumbledb-log` behind the napi bridge — so parse and render
- * here are marshal walks: branded `Digest32` and `Braid` values in,
- * bridge-tagged payloads across, never a second reader of the bytes.
- * The vector algebra over checkpoint heads and the seed transition's
- * catalog audit are machine logic and stay here.
- */
-
-import type { LogCheckpointDoc, LogCheckpointKind, LogCodecHandle, LogManifestKind } from "@bjornpagen/bumbledb"
-import {
-	internalLogParseCheckpoint,
-	internalLogParseManifest,
-	internalLogRenderCheckpoint,
-	internalLogRenderManifest
-} from "@bjornpagen/bumbledb"
-import type { Digest32 } from "#bytes.ts"
-import { bytesEqual, digest32, hex32 } from "#bytes.ts"
-import type { Braid } from "#descriptor.ts"
-import { braidHex } from "#descriptor.ts"
-import { refuse } from "#errors.ts"
-import type { Generation } from "#keys.ts"
-import { generation } from "#keys.ts"
-import { Vector } from "#vector.ts"
-
-interface Manifest {
-	readonly fingerprint: Digest32
-	readonly checkpoint: Digest32 | null
-}
-
-/**
- * Remints a bridge refusal row as the driver's typed refusal. The
- * boundary carries `{ kind, message }` only: the kind is the log
- * core's own identity string, so the cause payload holds the data this
- * side owns — the document's length, its version byte (byte 0 of every
- * v:3 document) — and nothing invented. The raw braid id of an
- * `UnknownBraid` rides the message; the drifted set of a `BraidSet`
- * rides the message the same way.
- */
-function refuseBridged(kind: LogManifestKind | LogCheckpointKind, message: string, bytes: Uint8Array): never {
-	switch (kind) {
-		case "Version":
-			return refuse({ kind: "Version", version: bytes[0] ?? 0 }, message)
-		case "Overflow":
-			return refuse({ kind: "Overflow" }, message)
-		case "UnknownBraid":
-			return refuse({ kind: "UnknownBraid" }, message)
-		case "BraidSet":
-			return refuse({ kind: "BraidSet" }, message)
-		case "Malformed":
-			return refuse({ kind: "Malformed", at: bytes.length }, message)
-	}
-}
-
-function braidIdOf(id: Braid): number {
-	return Number.parseInt(id.slice(1), 16)
-}
-
-function renderManifest(manifest: Manifest): Uint8Array {
-	return internalLogRenderManifest(
-		manifest.checkpoint === null
-			? { fingerprint: manifest.fingerprint }
-			: { fingerprint: manifest.fingerprint, checkpoint: manifest.checkpoint }
-	)
-}
-
-function parseManifest(bytes: Uint8Array): Manifest {
-	const parsed = internalLogParseManifest(bytes)
-	if (!parsed.ok) {
-		refuseBridged(parsed.kind, parsed.message, bytes)
-	}
-	return {
-		fingerprint: digest32(parsed.value.fingerprint),
-		checkpoint: parsed.value.checkpoint === undefined ? null : digest32(parsed.value.checkpoint)
-	}
-}
-
-interface CheckpointHead {
-	readonly g: Generation
-	readonly hash: Digest32
-	readonly ts: bigint
-}
-
-interface CheckpointFacts {
-	readonly braids: ReadonlyMap<Braid, CheckpointHead>
-	readonly catalog: Digest32
-	readonly writer: bigint
-	readonly prev: Digest32 | null
-	readonly sum: bigint
-}
-
-function vectorOfHeads(braids: ReadonlyMap<Braid, CheckpointHead>): Vector {
-	const counts = new Map<Braid, bigint>()
-	for (const [id, head] of braids) {
-		counts.set(id, head.g)
-	}
-	return Vector.from(counts)
-}
-
-function checkpointVector(facts: CheckpointFacts): Vector {
-	return vectorOfHeads(facts.braids)
-}
-
-function renderCheckpoint(codec: LogCodecHandle, facts: CheckpointFacts): Uint8Array {
-	const braids = [...facts.braids.entries()]
-		.sort(function ascending(a, b) {
-			return braidIdOf(a[0]) - braidIdOf(b[0])
-		})
-		.map(function headOf([id, head]) {
-			return { braid: braidIdOf(id), g: head.g, hash: head.hash, ts: head.ts }
-		})
-	const doc: LogCheckpointDoc =
-		facts.prev === null
-			? { braids, catalog: facts.catalog, writer: facts.writer }
-			: { braids, catalog: facts.catalog, writer: facts.writer, prev: facts.prev }
-	return internalLogRenderCheckpoint(codec, doc)
-}
-
-function parseCheckpoint(codec: LogCodecHandle, bytes: Uint8Array): CheckpointFacts {
-	const parsed = internalLogParseCheckpoint(codec, bytes)
-	if (!parsed.ok) {
-		refuseBridged(parsed.kind, parsed.message, bytes)
-	}
-	const braids = new Map<Braid, CheckpointHead>()
-	for (const head of parsed.value.braids) {
-		braids.set(braidHex(head.braid), { g: generation(head.g), hash: digest32(head.hash), ts: head.ts })
-	}
-	/** The core refuses `Overflow` at parse; the narrowing here is the
-	 *  derived sum's own type gate over the same heads. */
-	const summed = vectorOfHeads(braids).sum()
-	if (typeof summed !== "bigint") {
-		refuse({ kind: "Overflow" }, "checkpoint vector sum overflows u64")
-	}
-	return {
-		braids,
-		catalog: digest32(parsed.value.catalog),
-		writer: parsed.value.writer,
-		prev: parsed.value.prev === undefined ? null : digest32(parsed.value.prev),
-		sum: summed
-	}
-}
-
-/** The seed transition's catalog claim: a present checkpoint
- *  compares the opened store's `catalog_digest` against the document.
- *  Genesis (no checkpoint) has no claim. A mismatch names the publisher. */
-function auditCatalog(facts: CheckpointFacts | null, computed: Digest32): void {
-	if (facts === null) {
-		return
-	}
-	if (bytesEqual(facts.catalog, computed)) {
-		return
-	}
-	refuse(
-		{ kind: "CheckpointDigest", expected: hex32(facts.catalog), computed: hex32(computed) },
-		`checkpoint catalog ${hex32(facts.catalog)} disagrees with the opened store ${hex32(computed)}; publisher ${facts.writer}`
-	)
-}
-
-export type { CheckpointFacts, CheckpointHead }
-export { auditCatalog, checkpointVector, parseCheckpoint, parseManifest, renderCheckpoint, renderManifest }