@bjornpagen/bumbledb 0.7.0 → 0.8.0

package/COOKBOOK.md

@@ -1,6 +1,6 @@
 # The cookbook — modeling intuition as schemas, in TypeScript
 
-The bumbledb engine's 30 cookbook recipes (`bumbledb/docs/cookbook.md`),
+The bumbledb engine's 32 cookbook recipes (`bumbledb/docs/cookbook.md`),
 translated to this SDK's structural API. **This document is illustrative,
 never normative**: where a recipe and an engine architecture chapter disagree,
 the chapter wins (`docs/architecture/README.md` rule 5) — the SDK is the same
@@ -39,9 +39,11 @@ import {
 	bool,
 	by,
 	bytes,
+	capacity,
 	closed,
 	contained,
 	desc,
+	duration,
 	eq,
 	i64,
 	interval,
@@ -53,11 +55,14 @@ import {
 	pointIn,
 	program,
 	query,
+	ref,
 	relation,
 	schema,
 	str,
 	u64,
-	v
+	v,
+	weigh,
+	within
 } from "@bjornpagen/bumbledb"
 ```
 
@@ -66,7 +71,7 @@ import {
 Relation declarations are pure structure — `kind`, `width`, `element`,
 `fresh`, nothing else. Domains are never declared: `schema()` computes every
 field's equivalence class FROM the statement list, by union-find across every
-paired face (containment, `mirrors`, window targets, ψ-selected faces
+paired face (containment, `mirrors`, capacity targets, ψ-selected faces
 included). Three laws govern the classes:
 
 1. **A fresh field is a generator** and names its class by its declaration
@@ -1606,3 +1611,100 @@ exists — `snap.scan(Program).find((row) => row.grp === grp)` — re-derives
 in the host what the store already enforces. The uniqueness the fold
 quietly assumes IS the declared key statement; spell the law and the point
 read comes with it.
+
+## Capacity laws
+
+## 31. The power budget
+
+Guarantee: Lean theorem + validator/runtime premises — the capacity law
+bounds each pool's summed draw by the pool's own row
+(`lean/Bumbledb/Capacity.lean: CapacityLaw`; per touched parent, one keyed
+probe plus one measure walk, `lean/Bumbledb/Oracle.lean:
+capacity_plan_decides`); the pinned-column containment proves a device's
+watts equals its model's at every commit.
+
+Per-group capacity is one statement — the `capacity` builder mirrors the
+operator positionally (target, weight, window, source): `weigh` names the
+measure on the SOURCE row, and `ref` reads each group's ceiling from the
+TARGET row (hi slot only — ruled 2026-07-24, C6; bound names resolve
+against the target's full roster, ruled 2026-07-24, C1).
+
+```ts
+const Pool = relation("Pool", { id: u64.fresh, supply: u64 })
+const Model = relation("Model", { id: u64.fresh, watts: u64 })
+const Device = relation("Device", {
+	id: u64.fresh,
+	pool: u64,
+	model: u64,
+	watts: u64
+})
+
+const Racks = schema("Racks", { Pool, Model, Device }, [
+	contained(on(Device, "pool"), on(Pool, "id")),
+	// The pinned column: a device's watts provably equals its model's — the
+	// two-column containment IS the join, stated as a law. The superkey it
+	// targets is deliberate write-amplification rent.
+	key(Model, ["id", "watts"]),
+	contained(on(Device, ["model", "watts"]), on(Model, ["id", "watts"])),
+	// Σ watts over a pool's devices stays within the pool's own supply:
+	capacity(on(Pool, "id"), weigh("watts"), within(0n, ref("supply")), on(Device, "pool"))
+])
+
+// utilization is a query, never a column (the ledger's law, recipe 19):
+const draw = query(Racks).rule((r) => {
+	const { id, pool, watts } = v(Device)
+	return r.match(Device, { id, pool, watts }).find({ pool, total: r.sum(watts) })
+})
+```
+
+A path weight (`weigh("model.watts")`) is a typed refusal whose diagnostic
+names exactly this pair — the weight vocabulary is closed at the row (ruled
+2026-07-24, ruling 6): a weight read through a reference would be a
+maintained copy of another relation's field, and a catalog edit would
+silently re-weigh deployed fleets. Pinned, the inconsistent commit refuses
+at the device site and the migration is explicit.
+
+## 32. Calendar capacity
+
+Guarantee: Lean theorem + validator/runtime premises — the Duration weight
+sums each booking's interval measure against the room's own span measure
+(`lean/Bumbledb/Capacity.lean: CapacityLaw`; Duration weights pair with
+Duration-capable bounds, ruled 2026-07-24, C18; a ray-valued weight or
+bound refuses typed at the law site, ruled 2026-07-24, C10).
+
+"Total booked time per room stays within the room's span" — one statement.
+The interval enters through the measure argument, never the group key.
+
+```ts
+const Room = relation("Room", { id: u64.fresh, span: interval(i64) })
+const Booking = relation("Booking", {
+	id: u64.fresh,
+	room: u64,
+	booked: interval(i64)
+})
+
+const Rooms = schema("Rooms", { Room, Booking }, [
+	contained(on(Booking, "room"), on(Room, "id")),
+	// The pointwise key forbids double-booking (recipe 1); the capacity law
+	// bounds the TOTAL. Different laws — a schema usually wants both.
+	key(Booking, ["room", "booked"]),
+	capacity(
+		on(Room, "id"),
+		weigh(duration("booked")),
+		within(0n, duration("span")),
+		on(Booking, "room")
+	)
+])
+
+// the booked time per room, read back:
+const booked = query(Rooms).rule((r) => {
+	const { id, room, booked } = v(Booking)
+	return r.match(Booking, { id, room, booked }).find({ room, total: r.sum(r.duration(booked)) })
+})
+```
+
+Mind the weighted `{0}` and the weighted floor: on a weighted statement
+`within(0n)` says "the group's total is zero" (zero-measure rows may exist
+— the weaker law than the unit exclusion), and `within(1n, "*")` under a
+weight ("positive total") is not "at least one booking" — that intent is
+the bare `contained`. Choose by what you mean.

package/README.md

@@ -2,7 +2,7 @@
 
 Type-theoretic TypeScript SDK for the [bumbledb](https://github.com/bjornpagen/bumbledb) embedded relational engine.
 
-bumbledb models data as relations judged by statements (functionality, containment, cardinality) and queried with Datalog expressed as plain values — no SQL, no query-string parser. The SDK is a thin, fully typed surface over an in-process native engine (LMDB storage, MVCC snapshots, a single-writer witnessed write loop).
+bumbledb models data as relations judged by statements (functionality, containment, capacity) and queried with Datalog expressed as plain values — no SQL, no query-string parser. The SDK is a thin, fully typed surface over an in-process native engine (LMDB storage, MVCC snapshots, a single-writer witnessed write loop).
 
 The surface is structural to the bone. Relation declarations are pure structure — kind, width, element, fresh, nothing else — and domains are never declared anywhere: **the laws type the columns**. `schema()` computes every field's equivalence class from the statement list itself, so the containments and mirrors you already write ARE the typing, at compile time and again at construction. Values stay bare (`bigint`, `string`, …); identity lives in the class the laws compute, not in a wrapper.
 
@@ -131,14 +131,14 @@ real surface by `test/readme.test.ts` — the examples cannot drift.
 The drizzle law governs this surface: the SDK's job at the host boundary is translation, not abstraction — every database idiom arrives as the modern TypeScript idiom for that concept, and the SDK never invents an operator where the language already has one.
 
 - The structural type kernel — fields as pure structure (`bool`, `bytes`, `i64`, `u64`, `str`, `interval`, `span`), `relation()`, and `closed()` sealed rosters with typed axiom payloads. A closed reference's value type IS the handle union (`Infer` speaks it); dispatch is native `switch` narrowing with `satisfies never` exhaustiveness. Domains are never declared: `schema()` computes every field's class from the statement list.
-- The statement algebra — `schema()`, `key`, `contained`, `mirrors`, `window`; faces via `on` (set membership is a plain array in `.where`); counts via `exactly`, `atLeast`, `atMost`, `between`, `none`; ψ-selection via `.where` on relations and closed rosters.
+- The statement algebra — `schema()`, `key`, `contained`, `mirrors`, `capacity`; faces via `on` (set membership is a plain array in `.where`); windows via `within` (`within(n)` exact, `within(lo, hi)` range, `within(lo, "*")` floor), measures via `weigh` (`weigh("f")` a u64 field, `weigh(duration("f"))` an interval's measure), dependent bounds via `ref`/`duration` read from the target row; ψ-selection via `.where` on relations and closed rosters.
 - The `Db` runtime — `Db.create`/`Db.open`, path-cached stores, transactions, typed violations, scoped snapshot reads (`db.read(fn)`, or `using snap = db.read()` — lifetimes are disposables, never `close()`), the write verbs with `abandon` (returning `abandon(payload)` from `write` or `writeWitnessed` rolls the transaction back; the outcome arm is in the result type), and `db.explain` — the prepared plan as data.
 - The query surface — Datalog as values, `query(S).rule(r => ...)`: `v(R)`-minted vars (identity is the object reference — reusing one across binding positions IS the join), `find({...})` named result heads (renames are real), params typed by use unchanged, negation, aggregates, and the free comparison/connective exports (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`, `allen`/`ALLEN`, `pointIn`); set membership at a closed field is a plain array in the match record (`r.match(Ticket, { priority: ["Normal", "Urgent"] })` — closed-only there: an ordinary field's membership is a bound `r.inSet` param); stratified recursion via `program()`; `db.prepare` as a plain value.
 - The exhume surface — `Db.exhume`, the schema-independent read path: a store's self-described shapes and raw facts by name, with typed refusals (`ErrExhumeNoDescriptor`, `ErrExhumeFormatMismatch`, `ErrExhumeCorruption`). A disposable lifetime: `using exhumed = await Db.exhume(path)` releases the store's exclusive lock at scope exit.
 
 ## Cookbook
 
-The engine cookbook's 29 modeling recipes, translated to this SDK's structural API: [COOKBOOK.md](./COOKBOOK.md). Two referees hold it: `test/cookbook-doc.test.ts` extracts the document's own `ts` fences and type-checks them against the real surface (the doc itself cannot drift), and `test/cookbook.test.ts` runs compiled copies of the recipes — each schema admitted by the real engine, its fingerprint asserted against the cross-host goldens the Rust cookbook suite also pins, every query snippet lowered through `db.prepare`.
+The engine cookbook's 32 modeling recipes, translated to this SDK's structural API: [COOKBOOK.md](./COOKBOOK.md). Two referees hold it: `test/cookbook-doc.test.ts` extracts the document's own `ts` fences and type-checks them against the real surface (the doc itself cannot drift), and `test/cookbook.test.ts` runs compiled copies of the recipes — each schema admitted by the real engine, its fingerprint asserted against the cross-host goldens the Rust cookbook suite also pins, every query snippet lowered through `db.prepare`.
 
 ## Architecture
 

package/dist/capacity.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Capacity-law mints — the window, weight, and dependent-bound vocabulary
+ * the one `capacity()` statement constructor consumes
+ * (`docs/architecture/70-api.md` § the canonical-utterance law, restated
+ * around the aggregate form). `within()` is the ONE window spelling —
+ * `within(n)` exact (`within(0n)` IS the exclusion's one spelling),
+ * `within(lo, hi)` range (`within(0n, hi)` the canonical ceiling),
+ * `within(lo, "*")` floor — `weigh()` names the measure on the SOURCE row
+ * (`weigh("watts")` a u64 field, `weigh(duration("booked"))` an interval's
+ * measure), and `ref()`/`duration()` read a dependent bound from the
+ * TARGET row (hi slot only — ruled 2026-07-24, C6). The ban table is
+ * enforced REPRESENTATIONALLY in two tiers, split per-aggregate where
+ * weight-sensitive (design § 6: a ban is canonical-utterance policing when
+ * it is weight-independent, semantic deduplication when it is not):
+ *
+ * - **The type tier**: a banned spelling written as a LITERAL does not
+ *   compile — every negative bound, `within(n, n)`, `within(0n, 0n)`, and
+ *   `within(0n, "*")` are type errors naming the canonical form. The
+ *   weight-SENSITIVE row rides the `capacity()` overloads themselves:
+ *   `within(1n, "*")` is banned on the unit overload only (`{1..*}` on the
+ *   count instance is the bare containment respelled —
+ *   `window_floor_containment`), and LEGAL on the weighted one ("positive
+ *   total" is not an existence claim over rows).
+ * - **The construction tier**: a bound the type level cannot judge — a
+ *   COMPUTED `bigint`, or an inverted `within(lo, hi)` order — is judged at
+ *   construction with the same canonical-naming errors; and past both
+ *   tiers the engine's own spec validation remains the law for a hostile
+ *   FFI caller (the standing two-tier ban enforcement).
+ *
+ * The weight vocabulary is closed at the row (ruled 2026-07-24, ruling 6):
+ * a path weight (`weigh("model.watts")`) is a typed refusal at BOTH tiers
+ * whose diagnostic names the pinned-column idiom — the two-column
+ * containment IS the join, stated as a law. Bounds are `bigint` (u64
+ * crosses as bigint always, PRD-04's law); the witnessed measure comes
+ * back as `bigint` too (u128-wide engine accumulator, C3).
+ */
+import type { AnyFace, FaceFields, FaceSource, ProjectedShape } from "#face.ts";
+import type { CapacityWindowSpec, WeightSpec } from "#spec.ts";
+/**
+ * The admission brand — a module-private symbol, deliberately unexported
+ * (the standing statement-mint pattern): `CapacityWindowSpec` and
+ * `WeightSpec` are public wire types, so without this brand every banned
+ * spelling in the ban table would be writable as a plain object literal.
+ * The symbol makes `within()` and `weigh()` the ONLY producers of the
+ * values `capacity()` accepts, which is what "the ban table is unwritable"
+ * means.
+ */
+declare const admitted: unique symbol;
+/**
+ * An admitted capacity window — opaque and inert: a fact about the theory,
+ * not a builder. Only `within()` produces one; the spec is carried at its
+ * EXACT type so the weight-sensitive `{1..*}` ban and the dependent-bound
+ * target wall are judged at the `capacity()` call.
+ */
+interface CapacityWindow<S extends CapacityWindowSpec = CapacityWindowSpec> {
+    readonly window: S;
+    readonly [admitted]: true;
+}
+/**
+ * An admitted measure — `weigh()`'s product, the `[w]` bracket of the
+ * operator. The spec is carried at its exact type so the u64/interval
+ * source wall ({@link WeightOnSource}) reads the weighed field's name off
+ * the value.
+ */
+interface CapacityWeight<S extends WeightSpec = WeightSpec> {
+    readonly weight: S;
+    readonly [admitted]: true;
+}
+/**
+ * A dependent bound naming a u64 field of the TARGET row — `ref()`'s
+ * product, legal in `within()`'s hi slot only (C6: a dependent floor has
+ * no use case; inversion with idents is unrepresentable). Carries no
+ * value: bounds resolve per target row at judge time.
+ */
+interface FieldRef<F extends string = string> {
+    readonly kind: "field";
+    readonly field: F;
+}
+/**
+ * A dependent interval-measure bound (`Duration(field)` of the TARGET
+ * row), or — handed to `weigh()` — the interval-measure weight of the
+ * SOURCE row. One mint, both slots: the interval enters through the
+ * measure argument, never the group key.
+ */
+interface DurationRef<F extends string = string> {
+    readonly kind: "durationField";
+    readonly field: F;
+}
+/** Narrows any value to an admitted capacity window through the module-private brand. */
+declare function isCapacityWindow(value: unknown): value is CapacityWindow;
+/** Narrows any value to an admitted capacity weight through the module-private brand. */
+declare function isCapacityWeight(value: unknown): value is CapacityWeight;
+/**
+ * The legible banned-spelling verdict: intersected into a mint's parameter
+ * when the LITERAL argument spells a banned window, naming the canonical
+ * form — the compile-time face of the ban table.
+ */
+interface BannedWindow<Canonical extends string> {
+    readonly "banned window spelling — the canonical-utterance law names the one legal form": Canonical;
+}
+/**
+ * The path-weight refusal (ruling 6 — a boundary, not a deferral): the
+ * verdict names the pinned-column idiom, the same diagnostic the macro
+ * expansion and the spec resolver carry.
+ */
+interface RefusedPath<Idiom extends string> {
+    readonly "path spelling refused — the vocabulary is closed at the row": Idiom;
+}
+/** `true` exactly when the literal bigint `N` is negative (out of the u64 bound domain). */
+type IsNegative<N extends bigint> = `${N}` extends `-${string}` ? true : false;
+/**
+ * The dotted-name ban, both mints: a `a.b` spelling is a typed refusal
+ * whose verdict names the composition idiom — pin the column with a
+ * two-column containment (`Device(model, watts) <= Model(id, watts)`) and
+ * name the local field.
+ */
+type PathBan<F extends string> = string extends F ? unknown : F extends `${string}.${string}` ? RefusedPath<"pin the column — a two-column containment (Source(ref, f) <= Catalog(id, f)) proves the local copy, then name the local field"> : unknown;
+/** The ban verdict on a single bound: negatives are out of the u64 domain. */
+type NegativeBan<N extends bigint> = bigint extends N ? unknown : IsNegative<N> extends true ? BannedWindow<"capacity bounds are u64 — a negative bound is out of domain"> : unknown;
+/**
+ * The ban verdict on `within(lo, "*")`: `{0..*}` is vacuous —
+ * weight-independent (sums are ≥ 0). `{1..*}` is NOT judged here: the ban
+ * is weight-sensitive (Count-instance only) and rides the `capacity()`
+ * unit overload ({@link UnitWindowBan}).
+ */
+type FloorBan<N extends bigint> = bigint extends N ? unknown : IsNegative<N> extends true ? BannedWindow<"capacity bounds are u64 — a negative bound is out of domain"> : N extends 0n ? BannedWindow<"`{0..*}` is vacuous — it provably says nothing; delete the statement"> : unknown;
+/**
+ * The ban verdict on `within(lo, hi)` with both literals known: `{n..n}`
+ * is the exact measure respelled (`within(n)`, or `within(0n)` at 0) —
+ * weight-independent canonical policing. Bound ORDER (`{hi..lo}` inverted)
+ * is not type-expressible — bigint literals have no type-level comparison
+ * — so inversion stays a construction error.
+ */
+type RangeBan<Lo extends bigint, Hi extends bigint> = bigint extends Lo ? unknown : bigint extends Hi ? unknown : IsNegative<Lo> extends true ? BannedWindow<"capacity bounds are u64 — a negative bound is out of domain"> : IsNegative<Hi> extends true ? BannedWindow<"capacity bounds are u64 — a negative bound is out of domain"> : Lo extends Hi ? Hi extends Lo ? Lo extends 0n ? BannedWindow<"`{0..0}` — the point window is written `{0}`: use within(0n)"> : BannedWindow<"`{n..n}` — an exact measure is written `{n}`: use within(n)"> : unknown : unknown;
+/**
+ * The weight-SENSITIVE ban row, judged at the `capacity()` call where the
+ * aggregate instance is known (design § 6): on the UNIT overload a
+ * `{1..*}` floor says only what the bare containment says
+ * (`window_floor_containment`) and is banned naming `contained`; on the
+ * weighted overload the same window is LEGAL — "positive total" admits
+ * zero-weight rows and is a different, weaker law.
+ */
+type UnitWindowBan<W extends CapacityWindow> = W["window"] extends {
+    readonly kind: "floor";
+    readonly lo: {
+        readonly kind: "lit";
+        readonly value: 1n;
+    };
+} ? BannedWindow<"`{1..*}` on the unit instance says only what the bare containment says — write contained(source, target)"> : unknown;
+/** The projected kind of one field of a face's source, read off the schema type. */
+type KindAt<S extends FaceSource, K extends string> = ProjectedShape<S, K> extends readonly [infer Kind, ...unknown[]] ? Kind : undefined;
+/**
+ * The legible off-roster verdict for a dependent bound: bound names
+ * resolve against the TARGET's full field roster (C1 — the written
+ * projection tuple stays the pure grouping key), and the verdict names
+ * that roster.
+ */
+interface BoundOffTargetRoster<K, Roster> {
+    readonly "dependent bound must name a field of the TARGET's own row — bound names resolve against the target's full roster": readonly [
+        K,
+        Roster
+    ];
+}
+/** The legible kind-mismatch verdict for a dependent bound: `ref()` needs u64, `duration()` an interval. */
+interface BoundKindMismatch<K, Want> {
+    readonly "dependent bound kind mismatch — ref() reads a u64 field, duration() an interval field, of the TARGET row": readonly [
+        K,
+        Want
+    ];
+}
+/**
+ * One dependent-bound slot judged against the target face's roster and
+ * kinds. A WIDE field name (the untyped-caller path — literal identity
+ * already lost) passes the type tier and is judged at construction.
+ */
+type BoundOnTarget<K extends string, Want extends "u64" | "interval", B extends AnyFace> = string extends K ? unknown : K extends FaceFields<B["source"]> ? KindAt<B["source"], K> extends Want ? unknown : BoundKindMismatch<K, Want> : BoundOffTargetRoster<K, FaceFields<B["source"]>>;
+/**
+ * The dependent-bound target wall (type tier): for a `ref(K)` bound in the
+ * window's hi slot, `K` must name a u64 field of the TARGET face's own
+ * row; for a `duration(K)` bound, an interval field. Literal-bound windows
+ * pass untouched. The runtime twin for untyped callers lives at the
+ * `capacity()` construction (`statements.ts`).
+ */
+type BoundsOnTarget<W extends CapacityWindow, B extends AnyFace> = W["window"] extends {
+    readonly hi: FieldRef<infer K>;
+} ? BoundOnTarget<K, "u64", B> : W["window"] extends {
+    readonly hi: DurationRef<infer K>;
+} ? BoundOnTarget<K, "interval", B> : unknown;
+/** The legible off-roster verdict for a weight: the vocabulary is closed at the SOURCE row. */
+interface WeightOffSourceRoster<K, Roster> {
+    readonly "weight must name a field of the SOURCE's own row — the weight vocabulary is closed at the row": readonly [
+        K,
+        Roster
+    ];
+}
+/**
+ * The legible kind-mismatch verdict for a weight: a signed weight would
+ * break the polarity scheduler (an insert could lower a sum), so the
+ * illegal weight is unrepresentable, not checked.
+ */
+interface WeightKindMismatch<K, Want> {
+    readonly "weight kind mismatch — weigh(field) reads a u64 field, weigh(duration(field)) an interval field, of the SOURCE row": readonly [
+        K,
+        Want
+    ];
+}
+/**
+ * The weight source wall (type tier): `weigh(K)`'s field must be a
+ * u64-encoded position of the SOURCE face's own row (signed encodings are
+ * the typed polarity refusal), `weigh(duration(K))`'s an interval
+ * position. Checked at the `capacity()` call where the source face is
+ * inferred — the proven constrain-after-inference pattern.
+ */
+type WeightOnSource<M extends CapacityWeight, A extends AnyFace> = M["weight"] extends {
+    readonly kind: "field";
+    readonly field: infer K extends string;
+} ? string extends K ? unknown : K extends FaceFields<A["source"]> ? KindAt<A["source"], K> extends "u64" ? unknown : WeightKindMismatch<K, "u64"> : WeightOffSourceRoster<K, FaceFields<A["source"]>> : M["weight"] extends {
+    readonly kind: "durationField";
+    readonly field: infer K extends string;
+} ? string extends K ? unknown : K extends FaceFields<A["source"]> ? KindAt<A["source"], K> extends "interval" ? unknown : WeightKindMismatch<K, "interval"> : WeightOffSourceRoster<K, FaceFields<A["source"]>> : unknown;
+/** The unit weight — a case, not an absence (C4): the count instance's one wire spelling. */
+declare const unitWeight: WeightSpec;
+/**
+ * `{n}` — THE exact-measure spelling; `within(0n)` IS the exclusion's one
+ * spelling on the unit instance, and the weaker "total is zero" law on a
+ * weighted one (zero-weight rows may exist — design § 6, stated loudly).
+ */
+declare function within<const N extends bigint>(n: N & NegativeBan<N>): CapacityWindow<{
+    readonly kind: "exact";
+    readonly n: {
+        readonly kind: "lit";
+        readonly value: N;
+    };
+}>;
+/**
+ * `{lo..*}` — a floor with no ceiling. `within(0n, "*")` is vacuous
+ * (unwritable as a literal); `within(1n, "*")` constructs — the `{1..*}`
+ * ban is weight-sensitive and judged at the `capacity()` call (unit
+ * instance only).
+ */
+declare function within<const Lo extends bigint>(lo: Lo & FloorBan<Lo>, hi: "*"): CapacityWindow<{
+    readonly kind: "floor";
+    readonly lo: {
+        readonly kind: "lit";
+        readonly value: Lo;
+    };
+}>;
+/**
+ * `{lo..field}` / `{lo..Duration(field)}` — the dependent ceiling, read
+ * from the TARGET row per group (C6: hi slot only). The ref carries no
+ * value, so no inversion judgment exists at construction — a per-row
+ * inverted window is the judge's typed refusal.
+ */
+declare function within<const Lo extends bigint, const R extends FieldRef | DurationRef>(lo: Lo & NegativeBan<Lo>, hi: R): CapacityWindow<{
+    readonly kind: "range";
+    readonly lo: {
+        readonly kind: "lit";
+        readonly value: Lo;
+    };
+    readonly hi: R;
+}>;
+/**
+ * `{lo..hi}` — both bounds explicit, lo < hi; `within(0n, hi)` is the
+ * canonical ceiling. `lo === hi` is the exact measure respelled
+ * (unwritable as literals — {@link RangeBan} names `within(n)`), rejected
+ * at construction when computed; an inverted window is unsatisfiable and
+ * rejected at construction (bigint literals carry no type-level order).
+ */
+declare function within<const Lo extends bigint, const Hi extends bigint>(lo: Lo, hi: Hi & RangeBan<Lo, Hi>): CapacityWindow<{
+    readonly kind: "range";
+    readonly lo: {
+        readonly kind: "lit";
+        readonly value: Lo;
+    };
+    readonly hi: {
+        readonly kind: "lit";
+        readonly value: Hi;
+    };
+}>;
+/**
+ * `[field]` — the measure: a u64-encoded field of the SOURCE row summed
+ * per target group. A dotted path is the typed refusal naming the
+ * pinned-column idiom (ruling 6); `weigh(duration(field))` is the
+ * interval-measure weight — calendar capacity as one statement.
+ */
+declare function weigh<const F extends string>(field: F & PathBan<F>): CapacityWeight<{
+    readonly kind: "field";
+    readonly field: F;
+}>;
+declare function weigh<const F extends string>(measure: DurationRef<F>): CapacityWeight<{
+    readonly kind: "durationField";
+    readonly field: F;
+}>;
+/**
+ * A dependent bound by name — `within(0n, ref("supply"))` reads each
+ * group's ceiling from the TARGET row's u64 field (bound names resolve
+ * against the target's FULL roster, C1 — the projection tuple stays the
+ * pure grouping key). Carries no value.
+ */
+declare function ref<const F extends string>(field: F & PathBan<F>): FieldRef<F>;
+/**
+ * `Duration(field)` — the interval-measure spelling, one mint for both
+ * slots: handed to `weigh()` it is the SOURCE row's interval measure;
+ * in `within()`'s hi slot it is the TARGET row's interval-measure bound
+ * (Duration weights pair with Duration-capable bounds — C18).
+ */
+declare function duration<const F extends string>(field: F & PathBan<F>): DurationRef<F>;
+export type { BoundsOnTarget, CapacityWeight, CapacityWindow, DurationRef, FieldRef, UnitWindowBan, WeightOnSource };
+export { duration, isCapacityWeight, isCapacityWindow, ref, unitWeight, weigh, within };
+//# sourceMappingURL=capacity.d.ts.map

package/dist/capacity.d.ts.map

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

package/dist/capacity.js

@@ -0,0 +1,138 @@
+/**
+ * Capacity-law mints — the window, weight, and dependent-bound vocabulary
+ * the one `capacity()` statement constructor consumes
+ * (`docs/architecture/70-api.md` § the canonical-utterance law, restated
+ * around the aggregate form). `within()` is the ONE window spelling —
+ * `within(n)` exact (`within(0n)` IS the exclusion's one spelling),
+ * `within(lo, hi)` range (`within(0n, hi)` the canonical ceiling),
+ * `within(lo, "*")` floor — `weigh()` names the measure on the SOURCE row
+ * (`weigh("watts")` a u64 field, `weigh(duration("booked"))` an interval's
+ * measure), and `ref()`/`duration()` read a dependent bound from the
+ * TARGET row (hi slot only — ruled 2026-07-24, C6). The ban table is
+ * enforced REPRESENTATIONALLY in two tiers, split per-aggregate where
+ * weight-sensitive (design § 6: a ban is canonical-utterance policing when
+ * it is weight-independent, semantic deduplication when it is not):
+ *
+ * - **The type tier**: a banned spelling written as a LITERAL does not
+ *   compile — every negative bound, `within(n, n)`, `within(0n, 0n)`, and
+ *   `within(0n, "*")` are type errors naming the canonical form. The
+ *   weight-SENSITIVE row rides the `capacity()` overloads themselves:
+ *   `within(1n, "*")` is banned on the unit overload only (`{1..*}` on the
+ *   count instance is the bare containment respelled —
+ *   `window_floor_containment`), and LEGAL on the weighted one ("positive
+ *   total" is not an existence claim over rows).
+ * - **The construction tier**: a bound the type level cannot judge — a
+ *   COMPUTED `bigint`, or an inverted `within(lo, hi)` order — is judged at
+ *   construction with the same canonical-naming errors; and past both
+ *   tiers the engine's own spec validation remains the law for a hostile
+ *   FFI caller (the standing two-tier ban enforcement).
+ *
+ * The weight vocabulary is closed at the row (ruled 2026-07-24, ruling 6):
+ * a path weight (`weigh("model.watts")`) is a typed refusal at BOTH tiers
+ * whose diagnostic names the pinned-column idiom — the two-column
+ * containment IS the join, stated as a law. Bounds are `bigint` (u64
+ * crosses as bigint always, PRD-04's law); the witnessed measure comes
+ * back as `bigint` too (u128-wide engine accumulator, C3).
+ */
+import * as errors from "@superbuilders/errors";
+/**
+ * The admission brand — a module-private symbol, deliberately unexported
+ * (the standing statement-mint pattern): `CapacityWindowSpec` and
+ * `WeightSpec` are public wire types, so without this brand every banned
+ * spelling in the ban table would be writable as a plain object literal.
+ * The symbol makes `within()` and `weigh()` the ONLY producers of the
+ * values `capacity()` accepts, which is what "the ban table is unwritable"
+ * means.
+ */
+const admitted = Symbol("bumbledb.capacity.admitted");
+/** Narrows any value to an admitted capacity window through the module-private brand. */
+function isCapacityWindow(value) {
+    return typeof value === "object" && value !== null && admitted in value && "window" in value;
+}
+/** Narrows any value to an admitted capacity weight through the module-private brand. */
+function isCapacityWeight(value) {
+    return typeof value === "object" && value !== null && admitted in value && "weight" in value;
+}
+/** The unit weight — a case, not an absence (C4): the count instance's one wire spelling. */
+const unitWeight = Object.freeze({ kind: "unit" });
+/** The construction-tier twin of {@link PathBan}: a dotted name refuses naming the idiom. */
+function assertRowLocal(field, role) {
+    if (field.includes(".")) {
+        throw errors.new(`${role} \`${field}\` walks a reference — the vocabulary is closed at the row (ruling 6): pin the column with a two-column containment (Source(ref, f) <= Catalog(id, f)) and name the local field`);
+    }
+    return field;
+}
+/** Stamps one admitted window spec as a frozen branded value. */
+function admitWindow(window) {
+    const value = { window, [admitted]: true };
+    return Object.freeze(value);
+}
+/** One literal bound. */
+function lit(value) {
+    return Object.freeze({ kind: "lit", value });
+}
+function within(lo, hi) {
+    if (lo < 0n) {
+        throw errors.new(`capacity bounds are u64: within(${lo}${hi === undefined ? "" : ", …"}) is out of domain`);
+    }
+    if (hi === undefined) {
+        return admitWindow({ kind: "exact", n: lit(lo) });
+    }
+    if (hi === "*") {
+        if (lo === 0n) {
+            throw errors.new("the `{0..*}` window is vacuous — it provably says nothing; delete the statement");
+        }
+        return admitWindow({ kind: "floor", lo: lit(lo) });
+    }
+    if (typeof hi === "bigint") {
+        if (hi < 0n) {
+            throw errors.new(`capacity bounds are u64: within(${lo}, ${hi}) is out of domain`);
+        }
+        if (hi < lo) {
+            throw errors.new(`the window \`{${lo}..${hi}}\` is inverted — no measure satisfies it; bounds are \`{lo..hi}\` with lo < hi (an exact measure is \`{n}\`: within(n))`);
+        }
+        if (lo === hi) {
+            if (lo === 0n) {
+                throw errors.new("`{0..0}` — the point window is written `{0}`: use within(0n)");
+            }
+            throw errors.new(`\`{${lo}..${lo}}\` — an exact measure is written \`{${lo}}\`: use within(${lo}n)`);
+        }
+        return admitWindow({ kind: "range", lo: lit(lo), hi: lit(hi) });
+    }
+    const field = assertRowLocal(hi.field, "dependent bound");
+    if (hi.kind === "durationField") {
+        return admitWindow({ kind: "range", lo: lit(lo), hi: Object.freeze({ kind: "durationField", field }) });
+    }
+    return admitWindow({ kind: "range", lo: lit(lo), hi: Object.freeze({ kind: "field", field }) });
+}
+/** Stamps one admitted weight spec as a frozen branded value. */
+function admitWeight(weight) {
+    const value = { weight, [admitted]: true };
+    return Object.freeze(value);
+}
+function weigh(measure) {
+    if (typeof measure === "string") {
+        return admitWeight({ kind: "field", field: assertRowLocal(measure, "weight") });
+    }
+    return admitWeight({ kind: "durationField", field: assertRowLocal(measure.field, "weight") });
+}
+/**
+ * A dependent bound by name — `within(0n, ref("supply"))` reads each
+ * group's ceiling from the TARGET row's u64 field (bound names resolve
+ * against the target's FULL roster, C1 — the projection tuple stays the
+ * pure grouping key). Carries no value.
+ */
+function ref(field) {
+    return Object.freeze({ kind: "field", field: assertRowLocal(field, "dependent bound") });
+}
+/**
+ * `Duration(field)` — the interval-measure spelling, one mint for both
+ * slots: handed to `weigh()` it is the SOURCE row's interval measure;
+ * in `within()`'s hi slot it is the TARGET row's interval-measure bound
+ * (Duration weights pair with Duration-capable bounds — C18).
+ */
+function duration(field) {
+    return Object.freeze({ kind: "durationField", field: assertRowLocal(field, "Duration measure") });
+}
+export { duration, isCapacityWeight, isCapacityWindow, ref, unitWeight, weigh, within };
+//# sourceMappingURL=capacity.js.map

package/dist/capacity.js.map

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