@bjornpagen/bumbledb 0.7.0 → 0.8.0

package/src/db.ts

@@ -117,8 +117,10 @@ interface OffendingFact<Rels extends SchemaRelations> {
  * orientation (identical strings; the engine's `render.rs` renders each
  * partner of a mirrored pair as the `==` spelling, never a bare `<=`
  * direction). `direction` (`sourceUnsatisfied` | `targetRequired`) and
- * `count` are the containment/window form payloads, passed through from
- * the engine VERBATIM — `direction` is relative to the violated SLOT's
+ * `measure` are the containment/capacity form payloads, passed through
+ * from the engine VERBATIM (`measure` the capacity form's witnessed group
+ * total — u128-wide, crossing whole as bigint, C3) — `direction` is
+ * relative to the violated SLOT's
  * own orientation, so for a `mirrors` statement it alone cannot say which
  * side of the `==` was violated: the slot identity is carried by
  * `orientation`, present exactly for `mirrors` slots — `written` is the
@@ -131,7 +133,7 @@ interface Violation<Rels extends SchemaRelations> {
 	readonly canonical: string
 	readonly direction?: "sourceUnsatisfied" | "targetRequired"
 	readonly orientation?: "written" | "mirrored"
-	readonly count?: bigint
+	readonly measure?: bigint
 	readonly facts: readonly OffendingFact<Rels>[]
 }
 
@@ -536,10 +538,10 @@ function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 }
 
 /**
- * One declared statement's materialized slots: a key or window occupies
- * one, a `mirrors` occupies two adjacent slots (the engine lowers `==` to
- * two containments, `source <= target` first), both owned by the one SDK
- * value.
+ * One declared statement's materialized slots: a key or capacity statement
+ * occupies one, a `mirrors` occupies two adjacent slots (the engine lowers
+ * `==` to two containments, `source <= target` first), both owned by the
+ * one SDK value.
  */
 function declaredEntries(statement: Statement): StatementEntry[] {
 	const data = statement.data
@@ -562,8 +564,8 @@ function declaredEntries(statement: Statement): StatementEntry[] {
 			}
 			return [{ kind: "containment", statement, key: undefined }]
 		}
-		case "window": {
-			return [{ kind: "cardinality", statement, key: undefined }]
+		case "capacity": {
+			return [{ kind: "capacity", statement, key: undefined }]
 		}
 	}
 }
@@ -889,7 +891,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			canonical: wire.canonical,
 			direction: wire.direction,
 			orientation: orientationOf(entry.reversed),
-			count: wire.count,
+			measure: wire.measure,
 			facts: Object.freeze(wire.facts.map(offendingFactOf))
 		})
 	}
@@ -912,7 +914,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			)
 		}
 		if (entry.kind !== "functionality" || entry.key === undefined) {
-			throw errors.new("keyed get takes a key() statement — containments and windows key nothing")
+			throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing")
 		}
 		if (entry.key.owner !== relation.name) {
 			throw errors.new(

package/src/face.ts

@@ -322,6 +322,7 @@ export type {
 	FaceShapes,
 	FaceSource,
 	OwnerOf,
+	ProjectedShape,
 	SameArity,
 	SameShapes
 }

package/src/index.ts

@@ -25,6 +25,16 @@
  * `.slice`). The raw native bridge is not exported.
  */
 
+export type {
+	BoundsOnTarget,
+	CapacityWeight,
+	CapacityWindow,
+	DurationRef,
+	FieldRef,
+	UnitWindowBan,
+	WeightOnSource
+} from "#capacity.ts"
+export { duration, ref, weigh, within } from "#capacity.ts"
 export type {
 	AnyClosed,
 	AnySelectedClosed,
@@ -40,8 +50,6 @@ export type {
 	SelectedClosed
 } from "#closed.ts"
 export { closed } from "#closed.ts"
-export type { Count } from "#count.ts"
-export { atLeast, atMost, between, exactly, none } from "#count.ts"
 export type {
 	Abandon,
 	AbandonedArm,
@@ -81,6 +89,7 @@ export type {
 	FaceShapes,
 	FaceSource,
 	OwnerOf,
+	ProjectedShape,
 	SameArity,
 	SameShapes
 } from "#face.ts"
@@ -181,6 +190,8 @@ export { relation } from "#relation.ts"
 export type { AnySchema, Schema, SchemaRelation, SchemaRelations } from "#schema.ts"
 export { schema } from "#schema.ts"
 export type {
+	CapacityBoundSpec,
+	CapacityWindowSpec,
 	FieldSpec,
 	LiteralSetSpec,
 	LiteralSpec,
@@ -191,17 +202,17 @@ export type {
 	StatementSpec,
 	ValueSpec,
 	ValueTypeSpec,
-	WindowSpec
+	WeightSpec
 } from "#spec.ts"
-export { renderLiteral, renderLiteralSet, renderWindow } from "#spec.ts"
+export { renderCapacityBound, renderCapacityWindow, renderLiteral, renderLiteralSet, renderWeight } from "#spec.ts"
 export type {
+	CapacityData,
+	CapacityStatement,
 	ContainedStatement,
 	ContainmentData,
 	KeyData,
 	KeyStatement,
 	Statement,
-	StatementData,
-	WindowData,
-	WindowStatement
+	StatementData
 } from "#statements.ts"
-export { contained, key, mirrors, renderStatement, window } from "#statements.ts"
+export { capacity, contained, key, mirrors, renderStatement } from "#statements.ts"

package/src/law.ts

@@ -33,7 +33,7 @@
  *
  * Every paired face of the statement tuple unions its positionwise field
  * slots: containment (ψ-selected targets included — a selection changes
- * pairing not at all), the `==` bijection, and window source/target pairs.
+ * pairing not at all), the `==` bijection, and capacity source/target pairs.
  * `key()` statements pair nothing (an FD constrains one relation's own
  * rows; it identifies no carriers).
  *
@@ -141,7 +141,8 @@ type ZipCoords<
 
 /**
  * One statement's slot pairs: containments (bidirectional included — pair
- * unions are symmetric) and windows pair their two faces positionwise;
+ * unions are symmetric) and capacity statements pair their two faces
+ * positionwise;
  * `key()` pairs nothing. A widened face (owner name or projection no
  * longer literal) contributes nothing — the runtime map stays complete.
  */

package/src/lower.ts

@@ -98,10 +98,11 @@ function lowerStatement(statement: Statement): StatementSpec {
 				target: lowerFace(data.target),
 				bidirectional: data.bidirectional
 			}
-		case "window":
+		case "capacity":
 			return {
-				kind: "cardinality",
+				kind: "capacity",
 				target: lowerFace(data.target),
+				weight: data.weight,
 				window: data.window,
 				source: lowerFace(data.source)
 			}

package/src/native.ts

@@ -175,7 +175,7 @@ type ConditionTreeIr =
 	| { readonly kind: "or"; readonly children: readonly ConditionTreeIr[] }
 
 /** A statement's form tag. */
-type StatementKindTag = "functionality" | "containment" | "cardinality"
+type StatementKindTag = "functionality" | "containment" | "capacity"
 
 /** One field's name, dense id, and structural type. */
 interface ManifestField {
@@ -231,14 +231,17 @@ interface ViolationFact {
  * One violated statement of a rejected commit, rendered to plain data: the
  * statement id (materialized order), form tag, CANONICAL spelling (the
  * engine's one renderer — a bijection on legal statements, paste-back-able),
- * the form's direction/count payloads, and the decoded offending facts.
+ * the form's direction/measure payloads, and the decoded offending facts.
+ * `measure` is the capacity form's witnessed group total — the engine
+ * accumulates in u128 and the value crosses WHOLE as bigint (C3:
+ * truncation is unrepresentable).
  */
 interface Violation {
 	readonly statementId: number
 	readonly kind: StatementKindTag
 	readonly canonical: string
 	readonly direction?: "sourceUnsatisfied" | "targetRequired"
-	readonly count?: bigint
+	readonly measure?: bigint
 	readonly facts: readonly ViolationFact[]
 }
 

package/src/schema.ts

@@ -306,7 +306,7 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		 */
 		if (!isStatement(statement)) {
 			throw errors.new(
-				`schema ${name}: a statement is minted only by key/contained/mirrors/window — a structural literal skips the construction-time arity and roster walls`
+				`schema ${name}: a statement is minted only by key/contained/mirrors/capacity — a structural literal skips the construction-time arity and roster walls`
 			)
 		}
 		const rendered = renderStatement(statement)

package/src/spec.ts

@@ -72,10 +72,10 @@ type LiteralSetSpec =
 	| { readonly kind: "many"; readonly literals: readonly LiteralSpec[] }
 
 /**
- * One side of a containment or window: `R(fields… | field == literal…)`,
- * all names. `projection` is π in the statement's written order (positional
- * pairing with the other side); `selection` is σ as (field, literal-or-set)
- * pairs, read conjunctively.
+ * One side of a containment or capacity statement:
+ * `R(fields… | field == literal…)`, all names. `projection` is π in the
+ * statement's written order (positional pairing with the other side);
+ * `selection` is σ as (field, literal-or-set) pairs, read conjunctively.
  */
 interface SideSpec {
 	readonly relation: string
@@ -84,16 +84,43 @@ interface SideSpec {
 }
 
 /**
- * A cardinality window's bounds — the canonical-utterance law's surviving
- * spellings only, since the SDK's `Count` constructors make every banned
- * spelling unwritable or a construction error: `exact` is `{n}` (`{0}` the
- * exclusion), `range` is `{lo..hi}` with lo < hi, `floor` is `{lo..*}` with
- * lo ≥ 2.
+ * One capacity bound: a non-negative literal, a u64 field of the TARGET
+ * row (the dependent bound — per-group capacity read at judge time), or
+ * the interval-measure of a TARGET-row field (`Duration(span)`). Names,
+ * not ids — the spec is the name-level wire; the engine resolves bound
+ * names against the target's FULL roster (C1), never the projection.
  */
-type WindowSpec =
-	| { readonly kind: "exact"; readonly n: bigint }
-	| { readonly kind: "range"; readonly lo: bigint; readonly hi: bigint }
-	| { readonly kind: "floor"; readonly lo: bigint }
+type CapacityBoundSpec =
+	| { readonly kind: "lit"; readonly value: bigint }
+	| { readonly kind: "field"; readonly field: string }
+	| { readonly kind: "durationField"; readonly field: string }
+
+/**
+ * A capacity statement's weight — a TOTAL sum (C4: `unit` is a case, not
+ * an absence): the count instance (`unit`), a u64 field of the SOURCE row
+ * (`field`), or a SOURCE-row interval's measure (`durationField`). The
+ * wire always carries it — a unit statement crosses as `{ kind: "unit" }`,
+ * never by omission.
+ */
+type WeightSpec =
+	| { readonly kind: "unit" }
+	| { readonly kind: "field"; readonly field: string }
+	| { readonly kind: "durationField"; readonly field: string }
+
+/**
+ * A capacity statement's window — the canonical-utterance law's surviving
+ * spellings, per-aggregate where weight-sensitive (design § 6), since the
+ * SDK's `within()` mint makes every banned spelling unwritable or a
+ * construction error: `exact` is `{n}` (`{0}` the exclusion on the unit
+ * instance, "total is zero" on a weighted one), `range` is `{lo..hi}` with
+ * lo < hi (`{0..hi}` the canonical ceiling; the hi slot admits a dependent
+ * bound — C6: hi only), `floor` is `{lo..*}` (`{1..*}` legal on weighted
+ * statements only).
+ */
+type CapacityWindowSpec =
+	| { readonly kind: "exact"; readonly n: CapacityBoundSpec }
+	| { readonly kind: "range"; readonly lo: CapacityBoundSpec; readonly hi: CapacityBoundSpec }
+	| { readonly kind: "floor"; readonly lo: CapacityBoundSpec }
 
 /**
  * One field: name, structural type, host newtype name — the field's
@@ -148,8 +175,10 @@ interface RelationSpec {
  * One dependency statement, tagged by form. `==` is not a variant: a
  * bidirectional containment is `containment` with `bidirectional: true`,
  * lowered by the engine to the two adjacent containments (`source <=
- * target` first). `cardinality` is B-family, target-left: the target is the
- * per-group parent, the source is counted.
+ * target` first). `capacity` reads as the operator does (C2 — target,
+ * weight, window, source): the target is the per-group parent, the source
+ * is the weighed side, and the weight is ALWAYS present (`unit` the count
+ * instance).
  */
 type StatementSpec =
 	| { readonly kind: "fd"; readonly relation: string; readonly projection: readonly string[] }
@@ -160,9 +189,10 @@ type StatementSpec =
 			readonly bidirectional: boolean
 	  }
 	| {
-			readonly kind: "cardinality"
+			readonly kind: "capacity"
 			readonly target: SideSpec
-			readonly window: WindowSpec
+			readonly weight: WeightSpec
+			readonly window: CapacityWindowSpec
 			readonly source: SideSpec
 	  }
 
@@ -308,22 +338,58 @@ function renderLiteralSet(set: LiteralSetSpec): string {
 }
 
 /**
- * Renders window bounds in their one canonical spelling: `{n}` exact
+ * Renders one capacity bound in its one canonical spelling: a literal as
+ * digits, a dependent bound bare by field name, an interval-measure bound
+ * as `Duration(field)` — the spellings the engine's renderer emits.
+ */
+function renderCapacityBound(bound: CapacityBoundSpec): string {
+	switch (bound.kind) {
+		case "lit":
+			return bound.value.toString()
+		case "field":
+			return bound.field
+		case "durationField":
+			return `Duration(${bound.field})`
+	}
+}
+
+/**
+ * Renders a capacity window in its one canonical spelling: `{n}` exact
  * (`{0}` the exclusion), `{lo..hi}`, `{lo..*}` — the spelling set the
- * engine's renderer emits for sealed statements.
+ * engine's renderer emits for sealed statements, bounds through
+ * {@link renderCapacityBound}.
  */
-function renderWindow(window: WindowSpec): string {
+function renderCapacityWindow(window: CapacityWindowSpec): string {
 	switch (window.kind) {
 		case "exact":
-			return `{${window.n}}`
+			return `{${renderCapacityBound(window.n)}}`
 		case "range":
-			return `{${window.lo}..${window.hi}}`
+			return `{${renderCapacityBound(window.lo)}..${renderCapacityBound(window.hi)}}`
 		case "floor":
-			return `{${window.lo}..*}`
+			return `{${renderCapacityBound(window.lo)}..*}`
+	}
+}
+
+/**
+ * Renders a capacity weight as the operator's bracket: the unit weight
+ * renders NOTHING — the count utterance `<={lo..hi}` falls out of the one
+ * printer, never a second "legacy" arm — a field weight as `[field]`, an
+ * interval measure as `[Duration(field)]`.
+ */
+function renderWeight(weight: WeightSpec): string {
+	switch (weight.kind) {
+		case "unit":
+			return ""
+		case "field":
+			return `[${weight.field}]`
+		case "durationField":
+			return `[Duration(${weight.field})]`
 	}
 }
 
 export type {
+	CapacityBoundSpec,
+	CapacityWindowSpec,
 	ClosedSpec,
 	FieldSpec,
 	LiteralSetSpec,
@@ -335,6 +401,6 @@ export type {
 	StatementSpec,
 	ValueSpec,
 	ValueTypeSpec,
-	WindowSpec
+	WeightSpec
 }
-export { renderLiteral, renderLiteralSet, renderWindow }
+export { renderCapacityBound, renderCapacityWindow, renderLiteral, renderLiteralSet, renderWeight }

package/src/statements.ts

@@ -2,7 +2,7 @@
  * 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 cardinality window. A statement value is opaque and inert — no
+ * 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
@@ -35,12 +35,21 @@
  */
 
 import * as errors from "@superbuilders/errors"
+import {
+	type BoundsOnTarget,
+	type CapacityWeight,
+	type CapacityWindow,
+	isCapacityWeight,
+	isCapacityWindow,
+	type UnitWindowBan,
+	unitWeight,
+	type WeightOnSource
+} from "#capacity.ts"
 import { isClosedMember, sealedFieldOf } from "#closed.ts"
-import type { Count } from "#count.ts"
 import { type AnyFace, type FaceData, renderFace, type SameArity, type SameShapes } from "#face.ts"
 import { type ClosedRoster, rosterOf } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
-import { renderWindow, type WindowSpec } from "#spec.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[]> {
@@ -63,20 +72,26 @@ interface ContainmentData<Src extends FaceData = FaceData, Tgt extends FaceData
 	readonly bidirectional: boolean
 }
 
-/** A window statement's runtime description — target-left, faces at exact types like {@link ContainmentData}. */
-interface WindowData<Tgt extends FaceData = FaceData, Src extends FaceData = FaceData> {
-	readonly kind: "window"
+/**
+ * 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
-	readonly window: WindowSpec
+	readonly weight: WeightSpec
+	readonly window: CapacityWindowSpec
 	readonly source: Src
 }
 
 /** One statement's runtime description, tagged by form. */
-type StatementData = KeyData<AnyRelation, readonly string[]> | ContainmentData | WindowData
+type StatementData = KeyData<AnyRelation, readonly string[]> | ContainmentData | CapacityData
 
 /**
  * The admission brand — a module-private symbol, deliberately unexported
- * (the `count.ts` pattern): `Statement` is a public structural type, so
+ * (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
@@ -115,9 +130,9 @@ interface ContainedStatement<Src extends FaceData, Tgt extends FaceData> extends
 	readonly data: ContainmentData<Src, Tgt>
 }
 
-/** A window statement as a TYPED value — the {@link ContainedStatement} of the window form. */
-interface WindowStatement<Tgt extends FaceData, Src extends FaceData> extends Statement {
-	readonly data: WindowData<Tgt, Src>
+/** 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>
 }
 
 /**
@@ -266,29 +281,138 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
 }
 
 /**
- * `B(Y|ψ) <={window} A(X|φ)` — the cardinality window. READ CAREFULLY: the
- * LEFT face is the window's TARGET, the per-group parent (B-family,
- * target-left — macro parity), and the RIGHT face is the counted source.
- * `window(on(Holder, "id"), atMost(3n), on(Account, "holder"))` says: each
- * Holder id groups at most three Account rows by holder. The two faces
- * pair by arity AND structural shape ({@link SameShapes}), exactly as
- * containment — the grouping join reads the same positionwise field
- * pairing.
+ * 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
+	}
+	const field = sealedFieldOf(source.owner, weight.field)
+	if (field === undefined) {
+		throw errors.new(
+			`${source.owner.name} has no field ${weight.field} — a weight names a field of the SOURCE's own row (the weight vocabulary is closed at the row) — ${renderStatement(statement)}`
+		)
+	}
+	if (weight.kind === "field" && field.kind !== "u64") {
+		throw errors.new(
+			`${source.owner.name}.${weight.field} is ${field.kind}, not u64 — a weight is u64-encoded (a signed weight would break the polarity scheduler: an insert could lower a sum) — ${renderStatement(statement)}`
+		)
+	}
+	if (weight.kind === "durationField" && field.kind !== "interval") {
+		throw errors.new(
+			`${source.owner.name}.${weight.field} is ${field.kind}, not an interval — Duration(...) weighs an interval field's measure — ${renderStatement(statement)}`
+		)
+	}
+}
+
+/**
+ * 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 window<B extends AnyFace, A extends AnyFace>(
+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) {
+		if (bound.kind === "lit") {
+			continue
+		}
+		const field = sealedFieldOf(target.owner, bound.field)
+		if (field === undefined) {
+			throw errors.new(
+				`${target.owner.name} has no field ${bound.field} — a dependent bound names a field of the TARGET's own row (bound names resolve against the target's full roster) — ${renderStatement(statement)}`
+			)
+		}
+		if (bound.kind === "field" && field.kind !== "u64") {
+			throw errors.new(
+				`${target.owner.name}.${bound.field} is ${field.kind}, not u64 — a dependent bound reads a u64 field of the TARGET row (Duration(...) is the interval-measure spelling) — ${renderStatement(statement)}`
+			)
+		}
+		if (bound.kind === "durationField" && field.kind !== "interval") {
+			throw errors.new(
+				`${target.owner.name}.${bound.field} is ${field.kind}, not an interval — Duration(...) bounds by an interval field's measure — ${renderStatement(statement)}`
+			)
+		}
+	}
+}
+
+/**
+ * `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 `{1..*}` ban
+ * rides the UNIT overload only ({@link UnitWindowBan} — on a weighted
+ * statement "positive total" is a different, weaker law than containment).
+ */
+function capacity<B extends AnyFace, W extends CapacityWindow, A extends AnyFace>(
+	target: B,
+	window: W & UnitWindowBan<W> & BoundsOnTarget<W, B>,
+	source: A & SameArity<B, A> & SameShapes<B, A>
+): CapacityStatement<B["data"], A["data"]>
+function capacity<B extends AnyFace, M extends CapacityWeight, W extends CapacityWindow, A extends AnyFace>(
 	target: B,
-	count: Count,
+	weight: M & WeightOnSource<M, A>,
+	window: W & BoundsOnTarget<W, B>,
 	source: A & SameArity<B, A> & SameShapes<B, A>
-): WindowStatement<B["data"], A["data"]> {
-	const data: WindowData<B["data"], A["data"]> = Object.freeze({
-		kind: "window",
+): CapacityStatement<B["data"], A["data"]>
+function capacity(
+	target: AnyFace,
+	second: unknown,
+	third: unknown,
+	fourth?: AnyFace
+): CapacityStatement<FaceData, FaceData> {
+	const weighted = fourth !== undefined
+	const windowValue = weighted ? third : second
+	const source = weighted ? fourth : (third as AnyFace)
+	if (!isCapacityWindow(windowValue)) {
+		throw errors.new(
+			"a capacity window is minted only by within() — a structural literal skips the ban table (the canonical-utterance law)"
+		)
+	}
+	let weight: WeightSpec = unitWeight
+	if (weighted) {
+		if (!isCapacityWeight(second)) {
+			throw errors.new(
+				"a capacity weight is minted only by weigh() — a structural literal skips the row-local weight wall"
+			)
+		}
+		weight = second.weight
+	}
+	const window = windowValue.window
+	if (weight.kind === "unit" && window.kind === "floor" && window.lo.kind === "lit" && window.lo.value === 1n) {
+		throw errors.new(
+			"`{1..*}` on the unit instance says only what the bare containment says — drop the annotation and write the containment: contained(source, target)"
+		)
+	}
+	const data: CapacityData = Object.freeze({
+		kind: "capacity",
 		target: target.data,
-		window: count.window,
+		weight,
+		window,
 		source: source.data
 	})
 	const statement = Object.freeze({ data, [admitted]: true as const })
 	assertArityAgreement(data.source, data.target, statement)
 	assertRosterAgreement(data.source, data.target, statement)
+	assertWeightOnSource(weight, data.source, statement)
+	assertBoundsOnTarget(window, data.target, statement)
 	return statement
 }
 
@@ -298,9 +422,11 @@ function window<B extends AnyFace, A extends AnyFace>(
  * same shapes for violations) — `Account(id) -> Account`,
  * `Account(holder) <= Holder(id)`,
  * `Account(id | kind == Savings) == SavingsTerms(account)`,
- * `Holder(id) <={0..3} Account(holder)` — so TS-side errors and
+ * `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.
+ * 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
@@ -311,19 +437,19 @@ function renderStatement(statement: Statement): string {
 			const operator = data.bidirectional ? "==" : "<="
 			return `${renderFace(data.source)} ${operator} ${renderFace(data.target)}`
 		}
-		case "window":
-			return `${renderFace(data.target)} <=${renderWindow(data.window)} ${renderFace(data.source)}`
+		case "capacity":
+			return `${renderFace(data.target)} <=${renderWeight(data.weight)}${renderCapacityWindow(data.window)} ${renderFace(data.source)}`
 	}
 }
 
 export type {
+	CapacityData,
+	CapacityStatement,
 	ContainedStatement,
 	ContainmentData,
 	KeyData,
 	KeyStatement,
 	Statement,
-	StatementData,
-	WindowData,
-	WindowStatement
+	StatementData
 }
-export { contained, isStatement, key, mirrors, renderStatement, window }
+export { capacity, contained, isStatement, key, mirrors, renderStatement }