@bjornpagen/bumbledb 0.14.0 → 0.17.0

package/src/statements.ts

@@ -1,39 +1,3 @@
-/**
- * Dependency statements as typed values (`docs/architecture/30-dependencies.md`
- * owns the semantics; `docs/architecture/70-api.md` the surface): the FD key
- * form, conditional containment, the bidirectional `==` abbreviation, and
- * the capacity statement. A statement value is opaque and inert — no
- * methods, no fluent continuation: a fact about the theory, not a builder.
- *
- * Every field reference is checked against the relation it names in the
- * TYPE — existence through {@link FaceFields} (`on(R, "nope")` does not
- * compile) and STRUCTURAL compatibility through {@link SameShapes}: the two
- * faces' projected kind/width/element/roster quadruples are read off the
- * schema type (the minimal kernel — descriptors are pure structure) and
- * constrained positionwise equal, so a u64 face against a str face, a
- * bytes width mismatch, an interval element mismatch, or a bare column
- * against a closed reference is a compile error. TWO of those walls carry
- * construction-time runtime twins here for untyped callers: ARITY
- * ({@link assertArityAgreement} — cleanup-0.5.0 ruling 9: an
- * arity-mismatched pairing fails at the statement, never by silent
- * truncation) and the ROSTER slot ({@link assertRosterAgreement} —
- * roster IDENTITY, positionwise: a closed vocabulary's referencing column
- * is spelled with the vocabulary's own id descriptor, the ONE spelling, so
- * a plain u64 column can never alias a vocabulary through a declared law
- * and the SDK's descriptor-keyed closed judgments stay sound). Domains are
- * NOT compared here — there is no domain to compare at construction: the
- * statements themselves are what define the equivalence classes, and the
- * domain wall lives where they aggregate — `schema()` (the
- * one-generator-per-class law) and query joins (class names off the schema
- * type). What is only a SEMANTIC property — the target side of a
- * containment resolving a declared key of its relation — is DELIBERATELY
- * not (and cannot be) stated here: whether `B(y)` is a key of `B` depends
- * on which `key()` statements the surrounding `schema()` collects, a set no
- * face type can see; it stays the engine's typed `SchemaError` judgment at
- * `Db.create`/`Db.open` (the two-boundary split, engine as final
- * authority).
- */
-
 import * as errors from "@superbuilders/errors"
 import {
 	type BoundsOnTarget,
@@ -52,20 +16,12 @@ import { type ClosedRoster, rosterOf } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { type CapacityWindowSpec, renderCapacityWindow, renderWeight, type WeightSpec } from "#spec.ts"
 
-/** A `key()` statement's runtime description — owner and projection carried at exact types. */
 interface KeyData<R extends AnyRelation, Projection extends readonly string[]> {
 	readonly kind: "key"
 	readonly owner: R
 	readonly projection: Projection
 }
 
-/**
- * A containment statement's runtime description — the two faces carried at
- * their EXACT types (owner names and projection tuples are honest runtime
- * properties, and they are the type-level carrier `schema()`'s law-typing
- * pairs slots through). The defaults are the wide shape renderers and the
- * wire lowering consume.
- */
 interface ContainmentData<Src extends FaceData = FaceData, Tgt extends FaceData = FaceData> {
 	readonly kind: "containment"
 	readonly source: Src
@@ -78,12 +34,6 @@ interface MirrorsData<Src extends FaceData = FaceData, Tgt extends FaceData = Fa
 	readonly target: Tgt
 }
 
-/**
- * A capacity statement's runtime description — target-left, in the
- * operator's own order (C2: target, weight, window, source), faces at
- * exact types like {@link ContainmentData}. The weight is ALWAYS present
- * (C4 — `unit` is a case, not an absence).
- */
 interface CapacityData<Tgt extends FaceData = FaceData, Src extends FaceData = FaceData> {
 	readonly kind: "capacity"
 	readonly target: Tgt
@@ -92,69 +42,31 @@ interface CapacityData<Tgt extends FaceData = FaceData, Src extends FaceData = F
 	readonly source: Src
 }
 
-/** One statement's runtime description, tagged by form. */
 type StatementData = KeyData<AnyRelation, readonly string[]> | ContainmentData | MirrorsData | CapacityData
 
-/**
- * The admission brand — a module-private symbol, deliberately unexported
- * (the `capacity.ts` pattern): `Statement` is a public structural type, so
- * without this brand a forged plain object of the right shape would walk
- * past the construction-time arity and roster walls into `schema()` — and
- * the roster wall is the one the engine cannot backstop (the wire carries
- * plain u64s, no rosters). The symbol makes the four constructors the ONLY
- * mints, so a statement that skipped the walls is unspellable.
- */
 const admitted: unique symbol = Symbol("bumbledb.statement.admitted")
 
-/** An opaque statement value — what `schema()` assembles into a theory. Only the four constructors produce one. */
 interface Statement {
 	readonly data: StatementData
 	readonly [admitted]: true
 }
 
-/**
- * Narrows any value to an admitted statement — the probe is the
- * module-private {@link admitted} brand only the four constructors set, so
- * no host-built value (fact cells are structurally OPEN — an interval with
- * an excess `kind` property is a legal cell) can ever be misread as one.
- * The keyed-get selector dispatch and `schema()`'s admission both judge
- * through here.
- */
 function isStatement(value: unknown): value is Statement {
 	return typeof value === "object" && value !== null && admitted in value
 }
 
-/**
- * A containment (or `==` bijection) statement as a TYPED value: `data`
- * carries both faces at their exact types, so the schema-level class laws
- * can read every paired (relation, field) slot off the statement type —
- * spell the statement list inline in `schema()` and the equivalence
- * classes compute at the type level too. Structurally still a plain
- * {@link Statement}.
- */
 interface ContainedStatement<Src extends FaceData, Tgt extends FaceData> extends Statement {
 	readonly data: ContainmentData<Src, Tgt> | MirrorsData<Src, Tgt>
 }
 
-/** A capacity statement as a TYPED value — the {@link ContainedStatement} of the capacity form. */
 interface CapacityStatement<Tgt extends FaceData, Src extends FaceData> extends Statement {
 	readonly data: CapacityData<Tgt, Src>
 }
 
-/**
- * A `key()` statement as a TYPED value: its `data` carries the owner
- * relation and the projection tuple at their EXACT types (honest runtime
- * properties — no phantom), which is what the key-statement-selected
- * `get(relation, keyStatement, key)` overload types its key object by
- * (`docs/architecture/70-api.md` § the freeze, the multi-key typed get) and
- * what resolves each projected field's descriptor through the owner's
- * schema type. Structurally still a plain {@link Statement}.
- */
 interface KeyStatement<R extends AnyRelation, Projection extends readonly string[]> extends Statement {
 	readonly data: KeyData<R, Projection>
 }
 
-/** Renders one face position's closedness for the roster-agreement diagnostics. */
 function renderRosterSide(roster: ClosedRoster | undefined): string {
 	return roster === undefined ? "a bare column" : `a ${roster.name} reference`
 }
@@ -176,22 +88,6 @@ function assertArityAgreement(source: FaceData, target: FaceData, statement: Sta
 	}
 }
 
-/**
- * The runtime twin of {@link SameShapes}'s roster slot: the two faces'
- * projected descriptors must agree POSITIONWISE on closedness — the same
- * roster (value identity — vocabulary identity is value identity, the
- * SDK's membership rule everywhere) or none. Without this wall a plain u64
- * column could alias a closed vocabulary through a declared containment
- * (`docs/architecture/10-data-model.md` spells the ENGINE encoding that
- * way), and every descriptor-keyed closed judgment — the orderable ban,
- * the name↔id marshal, answer decode — would silently miss it. The
- * vocabulary's own descriptor (`Kind.id`) is the ONE spelling of a closed
- * reference at this surface (the canonical-utterance law); the engine
- * cannot backstop this one — the wire carries plain u64s, no rosters.
- * Arity agreement ({@link assertArityAgreement}) runs first, so the
- * positionwise walk here never sees an unpaired position from a well-typed
- * OR an untyped caller.
- */
 function assertRosterAgreement(source: FaceData, target: FaceData, statement: Statement): void {
 	source.projection.forEach(function agreeAt(fieldName, position) {
 		const targetField = target.projection[position]
@@ -217,7 +113,12 @@ function assertRosterAgreement(source: FaceData, target: FaceData, statement: St
  * checked against `R`'s field block in the type, and the tuple is carried
  * in the returned value's type ({@link KeyStatement}) — keyed point reads
  * through THIS statement are typed field-for-field, descriptors resolvable
- * through the owner's schema type.
+ * through the owner's schema type. A DUPLICATE field in the projection is
+ * refused here, at the mint (the engine's `FieldSet` refuses the same
+ * duplicate at `Db.create`; canonical utterance says the twice-spelled
+ * field is the once-spelled projection respelled) — without this wall a
+ * `new Set`-collapsed duplicate could set-match a shorter target
+ * projection the engine refuses.
  */
 function key<
 	R extends AnyRelation,
@@ -228,6 +129,15 @@ function key<
 			`key(${relation.name}, ...): closedness already materializes ${relation.name}(id) -> ${relation.name} — an explicit key on a closed relation is rejected as a duplicate`
 		)
 	}
+	const seen = new Set<string>()
+	for (const fieldName of fields) {
+		if (seen.has(fieldName)) {
+			throw errors.new(
+				`key(${relation.name}, ...): the projection spells ${fieldName} twice — write it once (the canonical-utterance law: one meaning, one spelling)`
+			)
+		}
+		seen.add(fieldName)
+	}
 	const data: KeyData<R, Projection> = Object.freeze({
 		kind: "key",
 		owner: relation,
@@ -236,15 +146,6 @@ function key<
 	return Object.freeze({ data, [admitted]: true as const })
 }
 
-/**
- * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. Arity mismatch
- * between the two faces is a type error ({@link SameArity}); a structurally
- * mismatched pair is a type error ({@link SameShapes} — positionwise
- * equality of the projected kind/width/element triples). The target side
- * must resolve a declared key of B — a SEMANTIC property of the whole
- * statement set that no face type can state, DELIBERATELY judged by the
- * engine at `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
- */
 function contained<A extends AnyFace, B extends AnyFace>(
 	source: A,
 	target: B & SameArity<A, B> & SameShapes<A, B>
@@ -260,15 +161,6 @@ function contained<A extends AnyFace, B extends AnyFace>(
 	return statement
 }
 
-/**
- * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance: the
- * selected `==` bijection, a keyed one-to-one correspondence between the
- * two faces (each side contains the other). It lowers to the two adjacent
- * containments in the `A <= B` first order (macro parity — the engine
- * performs the split, source-first) and renders as `==` once, in the
- * written orientation. Faces pair by arity AND structural shape, exactly
- * as {@link contained}.
- */
 function mirrors<A extends AnyFace, B extends AnyFace>(
 	source: A,
 	target: B & SameArity<A, B> & SameShapes<A, B>
@@ -284,14 +176,6 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
 	return statement
 }
 
-/**
- * The runtime twin of the weight source wall ({@link WeightOnSource}): the
- * weighed field must be a u64-encoded position of the SOURCE's own row
- * (a signed weight would break the polarity scheduler — the illegal weight
- * is unrepresentable, not checked), an interval position for the
- * `Duration(...)` form. Judged at CONSTRUCTION for untyped callers; the
- * engine's `validate_capacity` stays the final authority.
- */
 function assertWeightOnSource(weight: WeightSpec, source: FaceData, statement: Statement): void {
 	if (weight.kind === "unit") {
 		return
@@ -314,14 +198,6 @@ function assertWeightOnSource(weight: WeightSpec, source: FaceData, statement: S
 	}
 }
 
-/**
- * The runtime twin of the dependent-bound target wall
- * ({@link BoundsOnTarget}): a `ref()` bound must name a u64 field of the
- * TARGET's own row, a `duration()` bound an interval field — bound names
- * resolve against the target's FULL roster (C1), never the projection.
- * `within()` mints dependent bounds in the hi slot only (C6), but the walk
- * here is total over the window's bound slots.
- */
 function assertBoundsOnTarget(window: CapacityWindowSpec, target: FaceData, statement: Statement): void {
 	const bounds = window.kind === "range" ? [window.lo, window.hi] : [window.kind === "exact" ? window.n : window.lo]
 	for (const bound of bounds) {
@@ -347,26 +223,6 @@ function assertBoundsOnTarget(window: CapacityWindowSpec, target: FaceData, stat
 	}
 }
 
-/**
- * `B(Y|ψ) <=[w]{window} A(X|φ)` — the capacity statement, the one
- * extension form: per ψ-selected target fact, the group of φ-selected
- * source facts sharing its key tuple must have its MEASURE (Σ weight; the
- * unit weight IS the count instance) inside the window. READ CAREFULLY:
- * the LEFT face is the TARGET, the per-group parent (B-family, target-left
- * — macro parity), and the RIGHT face is the weighed source. Two
- * overloads mirror the operator positionally (target, weight?, window,
- * source): `capacity(on(Holder, "id"), within(0n, 3n), on(Account,
- * "holder"))` says each Holder id groups at most three Account rows;
- * `capacity(on(Pool, "id"), weigh("watts"), within(0n, ref("supply")),
- * on(Device, "pool"))` bounds each pool's summed draw by the pool's own
- * row. The two faces pair by arity AND structural shape
- * ({@link SameShapes}), exactly as containment — the grouping join reads
- * the same positionwise field pairing. The weight-sensitive bans ride the
- * UNIT overload only: `{1..*}` ({@link UnitWindowBan} — on a weighted
- * statement "positive total" is a different, weaker law than containment)
- * and the `duration()` bound ({@link UnitDimensionBan} — a count of facts
- * bounded by a span of time mixes dimensions, C18).
- */
 function capacity<B extends AnyFace, W extends CapacityWindow, A extends AnyFace>(
 	target: B,
 	window: W & UnitWindowBan<W> & UnitDimensionBan<W> & BoundsOnTarget<W, B>,
@@ -407,10 +263,14 @@ function capacity(
 			"`{1..*}` on the unit instance says only what the bare containment says — drop the annotation and write the containment: contained(source, target)"
 		)
 	}
-	// The C18 dimension gate, unit instance (the engine's
+	if (weight.kind === "unit" && window.kind === "floor") {
+		throw errors.new(
+			"`{N..*}` on the unit instance — a bare count floor is refused; weigh the source (`<=[w]{N..*}` stays legal) or drop the bound"
+		)
+	}
+
 	// CapacityDimensionMixing twin — ruled 2026-07-24): a count of facts
-	// bounded by a span of time mixes dimensions. Judged here for untyped
-	// callers; the engine's validate_capacity stays the final authority.
+
 	if (weight.kind === "unit" && window.kind === "range" && window.hi.kind === "durationField") {
 		throw errors.new(
 			`a unit (count) window against the duration() bound on ${window.hi.field} mixes dimensions (C18) — weigh the source with weigh(duration(field)), or bound by a u64 field or literal`
@@ -431,18 +291,6 @@ function capacity(
 	return statement
 }
 
-/**
- * Renders one statement in the CANONICAL macro spelling
- * (`docs/architecture/70-api.md`; the engine's `schema/render.rs` emits the
- * same shapes for violations) — `Account(id) -> Account`,
- * `Account(holder) <= Holder(id)`,
- * `Account(id | kind == Savings) == SavingsTerms(account)`,
- * `Holder(id) <={0..3} Account(holder)`,
- * `Pool(id) <=[watts]{0..supply} Device(pool)` — so TS-side errors and
- * engine-side diagnostics read identically. A renderer, never a parser:
- * strings are output-only. The unit weight renders nothing — the count
- * utterance falls out of the one printer.
- */
 function renderStatement(statement: Statement): string {
 	const data = statement.data
 	switch (data.kind) {

package/dist/exhume.d.ts

@@ -1,143 +0,0 @@
-/**
- * The exhume surface — the SDK's ONE schema-independent read path
- * (docs/course-serialization/prd-02-sdk-exhume-surface.md; engine
- * 70-api.md § exhume): a read-only, theory-less open returning the store's
- * SELF-DESCRIBED relation shapes and raw facts by relation name. The
- * sighting it exists for: a run store whose creating schema has since
- * evolved — the record outlives the schema, and exhume is how the record
- * is read back for rebirth (exhume the old store, create the successor
- * under the new theory, copy by NAME, re-derive).
- *
- * DELIBERATELY SCHEMA-FREE: no schema type appears anywhere on this
- * surface. The caller's schema is the wrong theory for an exhumed store BY
- * DEFINITION (a store the current theory could open would never need
- * exhuming), so every value crosses TYPED at its bare structural form
- * ({@link FactValue} — bigint/string/boolean/bytes/interval, never
- * `unknown`) and every fact is keyed by field NAME. The SDK never
- * reconstructs a `Schema` value from the descriptor — that inverse mapping
- * is deliberately out of scope; the rebirth tool keys by name.
- *
- * LIFETIMES ARE DISPOSABLES, never `close()` (ruled 2026-07-23, R12): the
- * `Exhumed` value implements `Symbol.dispose` — teardown is synchronous
- * (one environment close) — and `using` is the documented idiom:
- *
- *   using exhumed = await Db.exhume(path)
- *
- * Disposal releases the engine handle AND the store's exclusive advisory
- * lock deterministically, scope-shaped in the language's own syntax, so a
- * same-path reopen (retry after a half-failed migration, a second forensic
- * read) never waits on an unforceable GC finalizer. Every verb after
- * disposal is a typed used-after-dispose refusal. The engine-side drop
- * remains the reclamation-only backstop for a collected-but-undisposed
- * value; the store is never written through this surface, so there is
- * nothing to flush.
- */
-import type { FactValue } from "./native.js";
-import type { ValueTypeSpec } from "./spec.js";
-/**
- * The typed `descriptorMissing` refusal: the store predates self-describing
- * stores and has not been adopted. The remedy is in the message — one
- * fingerprint-matching `Db.open` under the creating schema back-fills the
- * descriptor (engine 50-storage.md § the `_meta` block) and the store is
- * self-describing forever. Match with `errors.is`.
- */
-declare const ErrExhumeNoDescriptor: Error;
-/**
- * The typed `formatMismatch` refusal: the store's on-disk format version is
- * not this engine's (no migration path exists, as everywhere). Match with
- * `errors.is`.
- */
-declare const ErrExhumeFormatMismatch: Error;
-/**
- * The typed `corruption` refusal: the persisted descriptor fails its
- * integrity gates (the stored bytes hash to something other than the stored
- * fingerprint, or the bytes do not decode and re-encode faithfully). Match
- * with `errors.is`.
- */
-declare const ErrExhumeCorruption: Error;
-/**
- * One exhumed fact as a plain name-keyed record of bare structural values
- * — deliberately schema-free (module doc): `bigint` for u64/i64, `string`
- * for str, `boolean` for bool, `Uint8Array` for bytes<N>, a `{ start, end }`
- * bigint pair for intervals. Closed-relation rows open with the synthetic
- * `id` field, exactly as the descriptor's sealed field list declares.
- */
-type ExhumedFact = Readonly<Record<string, FactValue>>;
-/**
- * One field of an exhumed relation, exactly as the store's creator declared
- * it: the name and the structural type tag (byte width on `fixedBytes`,
- * element and optional width on `interval`).
- */
-interface ExhumedField {
-    readonly name: string;
-    readonly valueType: ValueTypeSpec;
-}
-/**
- * One ground axiom of an exhumed closed relation: the handle (the row's
- * identity, never a column), the declaration-order row id, and the declared
- * payload columns by name.
- */
-interface ExhumedAxiom {
-    readonly handle: string;
-    readonly id: bigint;
-    readonly values: ExhumedFact;
-}
-/**
- * One relation of an exhumed store: the name, the SEALED field list in
- * declaration order (a closed relation opens with the synthetic (`id`,
- * u64) handle field), and — exactly on closed relations — the roster of
- * ground axioms. Scan rows come back in this field order, so pairing a
- * row's positions against `fields` is the name-keyed reading `scan`
- * performs.
- */
-interface ExhumedRelation {
-    readonly name: string;
-    readonly fields: readonly ExhumedField[];
-    readonly roster: readonly ExhumedAxiom[] | undefined;
-}
-/**
- * The exhumed store's schema as declared, decoded from the store's own
- * persisted descriptor: relations in engine-id order (declaration order
- * mints every id), each with its ordered field descriptions and closed
- * roster — enough for a caller to key facts by name and re-insert them
- * into a differently-fingerprinted successor store. No schema type appears
- * here (module doc: the surface is schema-free; rows are typed bare).
- */
-interface ExhumedDescriptor {
-    readonly relations: readonly ExhumedRelation[];
-}
-/**
- * One exhumed store: the self-described relation shapes and the raw facts
- * by relation name. Read-only by construction — no write verb, no prepare
- * verb. A DISPOSABLE lifetime (R12): `Symbol.dispose` releases the engine
- * handle and the store's exclusive lock deterministically; `using` is the
- * idiom, and a disposed value's verbs are typed refusals.
- */
-interface Exhumed extends Disposable {
-    /** The store's own persisted schema, as its creator declared it. */
-    readonly descriptor: ExhumedDescriptor;
-    /**
-     * Full-relation export in row-id order, each row decoded per the
-     * STORED descriptor to a name-keyed record of natural values (str
-     * resolved through the engine's `_dict` before crossing; a closed
-     * relation scans its sealed roster). Each call reads one consistent
-     * snapshot. An unknown relation name is a typed error — the
-     * descriptor is the caller's roster.
-     */
-    scan(relation: string): readonly ExhumedFact[];
-}
-/**
- * Opens one exhumed store at an ALREADY-CANONICAL path (`Db.exhume` is the
- * public spelling — the path law lives in db.ts beside `open`/`create`).
- * The bridge's three domain refusals become the typed error constants
- * ({@link ErrExhumeNoDescriptor}, {@link ErrExhumeFormatMismatch},
- * {@link ErrExhumeCorruption}), each carrying the engine's message in its
- * wrap. The returned value is NOT cached: exhume is a forensic read whose
- * lifetime is the caller's `using` scope — disposal releases the store's
- * exclusive lock deterministically (R12), so the path is reusable the
- * moment the scope exits.
- */
-declare function exhumeStore(canonical: string): Exhumed;
-export type { Exhumed, ExhumedAxiom, ExhumedDescriptor, ExhumedFact, ExhumedField, ExhumedRelation };
-export { ErrExhumeCorruption, ErrExhumeFormatMismatch, ErrExhumeNoDescriptor, exhumeStore };
-//# sourceMappingURL=exhume.d.ts.map

package/dist/exhume.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"exhume.d.ts","sourceRoot":"","sources":["../src/exhume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAY,MAAM,YAAY,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C;;;;;;GAMG;AACH,QAAA,MAAM,qBAAqB,OAE1B,CAAA;AAED;;;;GAIG;AACH,QAAA,MAAM,uBAAuB,OAE5B,CAAA;AAED;;;;;GAKG;AACH,QAAA,MAAM,mBAAmB,OAA2F,CAAA;AAEpH;;;;;;GAMG;AACH,KAAK,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;AAEtD;;;;GAIG;AACH,UAAU,YAAY;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;CACjC;AAED;;;;GAIG;AACH,UAAU,YAAY;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,UAAU,eAAe;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,SAAS,CAAA;CACpD;AAED;;;;;;;GAOG;AACH,UAAU,iBAAiB;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAA;CAC9C;AAED;;;;;;GAMG;AACH,UAAU,OAAQ,SAAQ,UAAU;IACnC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC;;;;;;;OAOG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAA;CAC9C;AA+BD;;;;;;;;;;GAUG;AACH,iBAAS,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA8E/C;AAED,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,CAAA;AACpG,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,WAAW,EAAE,CAAA"}

package/dist/exhume.js

@@ -1,166 +0,0 @@
-/**
- * The exhume surface — the SDK's ONE schema-independent read path
- * (docs/course-serialization/prd-02-sdk-exhume-surface.md; engine
- * 70-api.md § exhume): a read-only, theory-less open returning the store's
- * SELF-DESCRIBED relation shapes and raw facts by relation name. The
- * sighting it exists for: a run store whose creating schema has since
- * evolved — the record outlives the schema, and exhume is how the record
- * is read back for rebirth (exhume the old store, create the successor
- * under the new theory, copy by NAME, re-derive).
- *
- * DELIBERATELY SCHEMA-FREE: no schema type appears anywhere on this
- * surface. The caller's schema is the wrong theory for an exhumed store BY
- * DEFINITION (a store the current theory could open would never need
- * exhuming), so every value crosses TYPED at its bare structural form
- * ({@link FactValue} — bigint/string/boolean/bytes/interval, never
- * `unknown`) and every fact is keyed by field NAME. The SDK never
- * reconstructs a `Schema` value from the descriptor — that inverse mapping
- * is deliberately out of scope; the rebirth tool keys by name.
- *
- * LIFETIMES ARE DISPOSABLES, never `close()` (ruled 2026-07-23, R12): the
- * `Exhumed` value implements `Symbol.dispose` — teardown is synchronous
- * (one environment close) — and `using` is the documented idiom:
- *
- *   using exhumed = await Db.exhume(path)
- *
- * Disposal releases the engine handle AND the store's exclusive advisory
- * lock deterministically, scope-shaped in the language's own syntax, so a
- * same-path reopen (retry after a half-failed migration, a second forensic
- * read) never waits on an unforceable GC finalizer. Every verb after
- * disposal is a typed used-after-dispose refusal. The engine-side drop
- * remains the reclamation-only backstop for a collected-but-undisposed
- * value; the store is never written through this surface, so there is
- * nothing to flush.
- */
-import * as errors from "@superbuilders/errors";
-import { bridged, native } from "#native.ts";
-/**
- * The typed `descriptorMissing` refusal: the store predates self-describing
- * stores and has not been adopted. The remedy is in the message — one
- * fingerprint-matching `Db.open` under the creating schema back-fills the
- * descriptor (engine 50-storage.md § the `_meta` block) and the store is
- * self-describing forever. Match with `errors.is`.
- */
-const ErrExhumeNoDescriptor = errors.new("bumbledb exhume: the store carries no schema descriptor (not yet adopted) — open it once under its creating schema (one fingerprint-matching Db.open back-fills the descriptor; engine 50-storage.md)");
-/**
- * The typed `formatMismatch` refusal: the store's on-disk format version is
- * not this engine's (no migration path exists, as everywhere). Match with
- * `errors.is`.
- */
-const ErrExhumeFormatMismatch = errors.new("bumbledb exhume: storage format version mismatch — the store was written by a different engine format");
-/**
- * The typed `corruption` refusal: the persisted descriptor fails its
- * integrity gates (the stored bytes hash to something other than the stored
- * fingerprint, or the bytes do not decode and re-encode faithfully). Match
- * with `errors.is`.
- */
-const ErrExhumeCorruption = errors.new("bumbledb exhume: the persisted schema descriptor fails its integrity gates");
-/**
- * Shapes the bridge's manifest rendering of the stored descriptor into the
- * SDK's {@link ExhumedDescriptor}: same relations in the same engine-id
- * order, extension rows re-keyed by column name. Pure reshaping — no
- * re-validation of engine-decoded values happens here (the bridge stays
- * dumb and so does this).
- */
-function descriptorOf(manifest) {
-    const relations = manifest.relations.map(function relationOf(relation) {
-        const fields = relation.fields.map(function fieldOf(field) {
-            return Object.freeze({ name: field.name, valueType: field.valueType });
-        });
-        let roster;
-        if (relation.extension !== undefined) {
-            roster = Object.freeze(relation.extension.map(function axiomOf(row) {
-                const values = {};
-                for (const cell of row.values) {
-                    values[cell.name] = cell.value;
-                }
-                return Object.freeze({ handle: row.handle, id: row.id, values: Object.freeze(values) });
-            }));
-        }
-        return Object.freeze({ name: relation.name, fields: Object.freeze(fields), roster });
-    });
-    return Object.freeze({ relations: Object.freeze(relations) });
-}
-/**
- * Opens one exhumed store at an ALREADY-CANONICAL path (`Db.exhume` is the
- * public spelling — the path law lives in db.ts beside `open`/`create`).
- * The bridge's three domain refusals become the typed error constants
- * ({@link ErrExhumeNoDescriptor}, {@link ErrExhumeFormatMismatch},
- * {@link ErrExhumeCorruption}), each carrying the engine's message in its
- * wrap. The returned value is NOT cached: exhume is a forensic read whose
- * lifetime is the caller's `using` scope — disposal releases the store's
- * exclusive lock deterministically (R12), so the path is reusable the
- * moment the scope exits.
- */
-function exhumeStore(canonical) {
-    const outcome = bridged(`exhume bumbledb store at ${canonical}`, function callExhume() {
-        return native.dbExhume(canonical);
-    });
-    if (!outcome.ok) {
-        switch (outcome.kind) {
-            case "descriptorMissing":
-                throw errors.wrap(ErrExhumeNoDescriptor, `exhume ${canonical}: ${outcome.message}`);
-            case "formatMismatch":
-                throw errors.wrap(ErrExhumeFormatMismatch, `exhume ${canonical}: ${outcome.message}`);
-            case "corruption":
-                throw errors.wrap(ErrExhumeCorruption, `exhume ${canonical}: ${outcome.message}`);
-        }
-    }
-    const handle = outcome.exhume;
-    const manifest = bridged("read bumbledb exhumed descriptor", function callDescriptor() {
-        return native.exhumeDescriptor(handle);
-    });
-    const descriptor = descriptorOf(manifest);
-    const fieldNames = new Map();
-    for (const relation of descriptor.relations) {
-        fieldNames.set(relation.name, relation.fields.map(function nameOf(field) {
-            return field.name;
-        }));
-    }
-    /** The lifetime record: flipped once by {@link dispose}, judged by every verb. */
-    const lifetime = { live: true };
-    /**
-     * The `Symbol.dispose` teardown (R12): idempotent — a manual call inside
-     * a `using` scope must not double-close — and deterministic: the engine
-     * handle and the store's exclusive lock release HERE, never on a GC
-     * schedule.
-     */
-    function dispose() {
-        if (!lifetime.live) {
-            return;
-        }
-        lifetime.live = false;
-        bridged(`close bumbledb exhumed store at ${canonical}`, function close() {
-            native.exhumeClose(handle);
-        });
-    }
-    function scan(relation) {
-        if (!lifetime.live) {
-            throw errors.new("bumbledb exhumed store is disposed — its using scope already exited");
-        }
-        const names = fieldNames.get(relation);
-        if (names === undefined) {
-            throw errors.new(`bumbledb exhume: the store's descriptor declares no relation ${relation}`);
-        }
-        const rows = bridged(`scan bumbledb exhumed relation ${relation}`, function callScan() {
-            return native.exhumeScan(handle, relation);
-        });
-        return Object.freeze(rows.map(function factOf(row) {
-            if (row.length !== names.length) {
-                throw errors.new(`bumbledb exhume drift: relation ${relation} row arity ${row.length} does not match the ${names.length} descriptor fields`);
-            }
-            const fact = {};
-            names.forEach(function pair(name, index) {
-                const cell = row[index];
-                if (cell === undefined) {
-                    throw errors.new(`bumbledb exhume drift: relation ${relation} row has no value at position ${index} (${name})`);
-                }
-                fact[name] = cell;
-            });
-            return Object.freeze(fact);
-        }));
-    }
-    return Object.freeze({ descriptor, scan, [Symbol.dispose]: dispose });
-}
-export { ErrExhumeCorruption, ErrExhumeFormatMismatch, ErrExhumeNoDescriptor, exhumeStore };
-//# sourceMappingURL=exhume.js.map

package/dist/exhume.js.map

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