@pithy-sh/core 0.10.0 → 0.11.0

package/dist/controlPlane/migrationState/migrationState.d.ts

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { MigrationProvider } from "kysely/migration";
+import type { Capability } from "../../capability/capability";
+import type { HealthSummary } from "../discovery/healthSummary";
+import type { MigrationDatabaseView, MigrationView } from "../http/responses";
+/**
+ * **Migration state over the control plane (#729).**
+ *
+ * A management client could not answer what is applied where, or whether a deploy left something behind:
+ * the seam registered a ping, the manifest and key rotation, and not one field of it was about a database.
+ * The read already existed — {@link readMigrationLedger} answers both directions — and it needs a D1
+ * binding and the composed provider in one process. **The Worker is the only thing holding both**, and it
+ * is the deployed build, so asked from its side the answer cannot be stale the way the project on disk is.
+ *
+ * Two halves. At assembly, {@link composeMigrationDatabases} builds what this Worker declares per bound
+ * database, through `collectMigrationSets` — the function `pithy migrate` composes with, so the route and
+ * `pithy doctor` compose the same way. Not always from the same inputs: on a D1 two Workers share, the CLI
+ * merges both Workers' sets and the route holds only its own, so `pending` and `undeclared` can differ
+ * there. On a database one Worker binds alone they agree. Per request, {@link readDatabaseMigrations} reads
+ * one database for the route and {@link readMigrationHealth} totals all of them for the manifest.
+ *
+ * **Read-only.** Nothing here runs, reverses or resets a migration. A screen somebody opened to ask must
+ * not hand them the thing that changes the schema.
+ *
+ * **`undeclared` is relative to this Worker.** Two Workers can be bound to one physical D1, and the CLI
+ * composes across all of them. A Worker composes only its own capabilities and cannot learn a co-bound
+ * Worker's, so from inside one, every migration the other shipped to the shared database reads as
+ * undeclared. That is why `undeclaredMigrations` grades nothing.
+ */
+/** One database this Worker binds, with what this build declares for it. Built once, at assembly. */
+export interface ComposedMigrationDatabase {
+    /** The database name, as capabilities declare it in `databases`. */
+    database: string;
+    /** The D1 binding it is read through. */
+    binding: string;
+    /** Every migration this build declares for it — empty for a database bound with none. */
+    provider: MigrationProvider;
+    /** Each declared migration's namespace, known from the set it came from. */
+    namespaces: ReadonlyMap<string, string>;
+}
+/**
+ * Every database this Worker binds, with the provider this build composes for it, sorted by name.
+ *
+ * One entry per database `composeDatabases` maps to a binding — the same map the request registry is built
+ * from — so a database bound with no migrations is still reported. Leaving it out would read as not bound.
+ */
+export declare function composeMigrationDatabases(capabilities: readonly Capability[]): ComposedMigrationDatabase[];
+/**
+ * One migration as the route reports it.
+ *
+ * A declared migration's namespace comes from the set it was declared in. An undeclared one has only its
+ * key, so it is decomposed — and a key no registry composed answers null rather than a guess.
+ */
+export declare function migrationView(name: string, namespaces: ReadonlyMap<string, string>): MigrationView;
+/**
+ * Read one database's migration state for the route.
+ *
+ * **A database that cannot be read is `unreadable`, and costs only itself.** The cause goes to
+ * `onUnreadable` — the route logs it, where the operator's context stays the operator's — and never into
+ * the view: a D1 error can name a table or a query, and the view crosses to a management client.
+ */
+export declare function readDatabaseMigrations(env: Record<string, unknown>, entry: ComposedMigrationDatabase, onUnreadable?: (entry: ComposedMigrationDatabase, cause: unknown) => void): Promise<MigrationDatabaseView>;
+/**
+ * The two health keys the seam contributes to its own manifest entry.
+ *
+ * Both `indexed`: one small select per bound database, bounded by the declared migration count rather
+ * than by the adopter's data. Both behind {@link MIGRATIONS_READ_SCOPE}, which the seam's own route
+ * requires, so a connection without it gets no value rather than a zero.
+ *
+ * **`undeclaredMigrations` declares no nominal, on purpose.** From inside one Worker, a database shared
+ * with another lists the other's migrations as undeclared, so `atMost: 0` would report a corrupted chain
+ * on a database that is entirely fine. Null is what a client reads as unknowable, never as healthy (#471).
+ */
+export declare const MIGRATION_HEALTH_KEYS: readonly [{
+    readonly key: "pendingMigrations";
+    readonly kind: "count";
+    readonly states: null;
+    readonly scope: string;
+    readonly cost: "indexed";
+    readonly summary: "Migrations this build declares that a bound database has not applied.";
+    readonly nominal: {
+        readonly atMost: 0;
+    };
+}, {
+    readonly key: "undeclaredMigrations";
+    readonly kind: "count";
+    readonly states: null;
+    readonly scope: string;
+    readonly cost: "indexed";
+    readonly summary: "Migrations a bound database holds that this Worker does not declare. Relative to this Worker: a database shared with another lists that Worker's migrations here.";
+    readonly nominal: null;
+}];
+/**
+ * Total pending and undeclared across every bound database, for the manifest.
+ *
+ * **Throws rather than total a database it could not read.** A partial total is a zero for the database
+ * nobody read. The seam catches the throw and reports the summary `unavailable`, which a client reads as
+ * unknown — null is never zero.
+ */
+export declare function readMigrationHealth(env: Record<string, unknown>, databases: readonly ComposedMigrationDatabase[]): Promise<HealthSummary>;
+//# sourceMappingURL=migrationState.d.ts.map

package/dist/controlPlane/migrationState/migrationState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrationState.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/migrationState/migrationState.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAQ9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAsB,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,qGAAqG;AACrG,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,4EAA4E;IAC5E,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAKD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,yBAAyB,EAAE,CAe1G;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,aAAa,CAElG;AA8BD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,EAAE,yBAAyB,EAChC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACxE,OAAO,CAAC,qBAAqB,CAAC,CAiBhC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;kBAEzB,mBAAmB;mBAClB,OAAO;;;mBAGP,SAAS;sBACN,uEAAuE;;iBACrE,MAAM,EAAE,CAAC;;;kBAGf,sBAAsB;mBACrB,OAAO;;;mBAGP,SAAS;sBAEb,mKAAmK;;EAGvH,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,SAAS,yBAAyB,EAAE,GAC9C,OAAO,CAAC,aAAa,CAAC,CAQxB"}

package/dist/controlPlane/migrationState/migrationState.js

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../../error/pithyError.js";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope.js";
+import { composeDatabases } from "../../data/databases.js";
+import { composedMigrationKey, createMigrationRegistry, decomposeMigrationKey } from "../../migrations/registry.js";
+import { collectMigrationSets } from "../../migrations/capabilitySets.js";
+import { readMigrationLedger } from "../../migrations/runner.js";
+import { readMigrationState } from "../../migrations/state.js";
+//#region src/controlPlane/migrationState/migrationState.ts
+/** A provider declaring nothing, for a database bound with no migrations: everything applied is undeclared. */
+const NOTHING_DECLARED = { getMigrations: async () => ({}) };
+/**
+* Every database this Worker binds, with the provider this build composes for it, sorted by name.
+*
+* One entry per database `composeDatabases` maps to a binding — the same map the request registry is built
+* from — so a database bound with no migrations is still reported. Leaving it out would read as not bound.
+*/
+function composeMigrationDatabases(capabilities) {
+	const sets = collectMigrationSets([...capabilities]);
+	const registry = createMigrationRegistry(sets);
+	const bound = composeDatabases([...capabilities]);
+	return Object.entries(bound).sort(([left], [right]) => left.localeCompare(right)).map(([database, group]) => {
+		const namespaces = /* @__PURE__ */ new Map();
+		for (const set of sets) {
+			if (set.database !== database) continue;
+			for (const localKey of Object.keys(set.migrations)) namespaces.set(composedMigrationKey(set, localKey), set.namespace);
+		}
+		return {
+			database,
+			binding: group.binding,
+			provider: registry[database] ?? NOTHING_DECLARED,
+			namespaces
+		};
+	});
+}
+/**
+* One migration as the route reports it.
+*
+* A declared migration's namespace comes from the set it was declared in. An undeclared one has only its
+* key, so it is decomposed — and a key no registry composed answers null rather than a guess.
+*/
+function migrationView(name, namespaces) {
+	return {
+		name,
+		namespace: namespaces.get(name) ?? decomposeMigrationKey(name)?.namespace ?? null
+	};
+}
+/** The D1 binding for `entry`, or a refusal naming it — a Worker missing the binding cannot read it. */
+function bindingOf(env, entry) {
+	const database = env[entry.binding];
+	if (database == null) throw new InternalError({
+		message: `The ${entry.binding} binding is missing, so database "${entry.database}" cannot be read.`,
+		action: `Declare ${entry.binding} in this Worker's wrangler.jsonc, then deploy again.`
+	});
+	return database;
+}
+function groupView(group, namespaces) {
+	return {
+		group: group.group,
+		appliedAt: group.appliedAt.toISOString(),
+		migrations: group.migrations.map((name) => migrationView(name, namespaces)),
+		position: group.position.state === "top" ? { state: "top" } : {
+			state: "buried",
+			above: group.position.above,
+			ungrouped: group.position.ungrouped.map((name) => migrationView(name, namespaces))
+		}
+	};
+}
+/**
+* Read one database's migration state for the route.
+*
+* **A database that cannot be read is `unreadable`, and costs only itself.** The cause goes to
+* `onUnreadable` — the route logs it, where the operator's context stays the operator's — and never into
+* the view: a D1 error can name a table or a query, and the view crosses to a management client.
+*/
+async function readDatabaseMigrations(env, entry, onUnreadable) {
+	try {
+		const state = await readMigrationState(bindingOf(env, entry), entry.provider);
+		const view = (name) => migrationView(name, entry.namespaces);
+		return {
+			state: "readable",
+			database: entry.database,
+			binding: entry.binding,
+			applied: state.applied.map(view),
+			pending: state.pending.map(view),
+			undeclared: state.undeclared.map(view),
+			lastGroup: state.lastGroup ? groupView(state.lastGroup, entry.namespaces) : null
+		};
+	} catch (cause) {
+		onUnreadable?.(entry, cause);
+		return {
+			state: "unreadable",
+			database: entry.database,
+			binding: entry.binding
+		};
+	}
+}
+/**
+* The two health keys the seam contributes to its own manifest entry.
+*
+* Both `indexed`: one small select per bound database, bounded by the declared migration count rather
+* than by the adopter's data. Both behind {@link MIGRATIONS_READ_SCOPE}, which the seam's own route
+* requires, so a connection without it gets no value rather than a zero.
+*
+* **`undeclaredMigrations` declares no nominal, on purpose.** From inside one Worker, a database shared
+* with another lists the other's migrations as undeclared, so `atMost: 0` would report a corrupted chain
+* on a database that is entirely fine. Null is what a client reads as unknowable, never as healthy (#471).
+*/
+const MIGRATION_HEALTH_KEYS = [{
+	key: "pendingMigrations",
+	kind: "count",
+	states: null,
+	scope: MIGRATIONS_READ_SCOPE,
+	cost: "indexed",
+	summary: "Migrations this build declares that a bound database has not applied.",
+	nominal: { atMost: 0 }
+}, {
+	key: "undeclaredMigrations",
+	kind: "count",
+	states: null,
+	scope: MIGRATIONS_READ_SCOPE,
+	cost: "indexed",
+	summary: "Migrations a bound database holds that this Worker does not declare. Relative to this Worker: a database shared with another lists that Worker's migrations here.",
+	nominal: null
+}];
+/**
+* Total pending and undeclared across every bound database, for the manifest.
+*
+* **Throws rather than total a database it could not read.** A partial total is a zero for the database
+* nobody read. The seam catches the throw and reports the summary `unavailable`, which a client reads as
+* unknown — null is never zero.
+*/
+async function readMigrationHealth(env, databases) {
+	const ledgers = await Promise.all(databases.map((entry) => readMigrationLedger(bindingOf(env, entry), entry.provider)));
+	return {
+		pendingMigrations: ledgers.reduce((total, ledger) => total + ledger.pending.length, 0),
+		undeclaredMigrations: ledgers.reduce((total, ledger) => total + ledger.undeclared.length, 0)
+	};
+}
+//#endregion
+export { MIGRATION_HEALTH_KEYS, composeMigrationDatabases, migrationView, readDatabaseMigrations, readMigrationHealth };

package/dist/controlPlane/migrations/0003_connection_principal.d.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Migration } from "kysely/migration";
+/**
+ * Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+ *
+ * **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+ * it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+ *
+ * **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+ * principal, and none can be recovered: most of the trail that might be mined for one names a token
+ * rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+ * end. So null means *registered before principals were recorded*, the connection keeps working exactly
+ * as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+ * is set only by registering again, under a signed-in session.
+ *
+ * **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+ * other two exist for the adopter's own review, on their own side.
+ */
+export declare const controlplane_0003_connection_principal: Migration;
+//# sourceMappingURL=0003_connection_principal.d.ts.map

package/dist/controlPlane/migrations/0003_connection_principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0003_connection_principal.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/migrations/0003_connection_principal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sCAAsC,EAAE,SAcpD,CAAC"}

package/dist/controlPlane/migrations/0003_connection_principal.js

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/migrations/0003_connection_principal.ts
+/**
+* Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+*
+* **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+* it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+*
+* **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+* principal, and none can be recovered: most of the trail that might be mined for one names a token
+* rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+* end. So null means *registered before principals were recorded*, the connection keeps working exactly
+* as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+* is set only by registering again, under a signed-in session.
+*
+* **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+* other two exist for the adopter's own review, on their own side.
+*/
+const controlplane_0003_connection_principal = {
+	up: async (db) => {
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("authorizedBy", "text").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("actorKind", "text").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("purpose", "text").execute();
+	},
+	down: async (db) => {
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("purpose").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("actorKind").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("authorizedBy").execute();
+	}
+};
+//#endregion
+export { controlplane_0003_connection_principal };

package/dist/controlPlane/scope/scope.d.ts

@@ -50,8 +50,19 @@ export declare const MANIFEST_READ_SCOPE: ControlPlaneScope;
  */
 export declare const KEYS_ROTATE_SCOPE: ControlPlaneScope;
 /**
- * Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
- * Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+ * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+ * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+ */
+export declare const MIGRATIONS_READ_SCOPE: ControlPlaneScope;
+/**
+ * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+ * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ *
+ * **{@link MIGRATIONS_READ_SCOPE} is absent on purpose.** It is a read — every route requiring it is a `GET`
+ * — so `connect` derives it from the seam's `adminRoutes` the way it derives every capability's reads. The
+ * base exists for `keys:rotate`, which is not a read and would otherwise drop out.
  */
 export declare const SEAM_SCOPES: readonly ControlPlaneScope[];
 /**

package/dist/controlPlane/scope/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}

package/dist/controlPlane/scope/scope.js

@@ -40,8 +40,19 @@ const MANIFEST_READ_SCOPE = "manifest:read";
 */
 const KEYS_ROTATE_SCOPE = "keys:rotate";
 /**
-* Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
-* Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+* Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+* and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+* nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+* manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+*/
+const MIGRATIONS_READ_SCOPE = "migrations:read";
+/**
+* The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+* because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+*
+* **{@link MIGRATIONS_READ_SCOPE} is absent on purpose.** It is a read — every route requiring it is a `GET`
+* — so `connect` derives it from the seam's `adminRoutes` the way it derives every capability's reads. The
+* base exists for `keys:rotate`, which is not a read and would otherwise drop out.
 */
 const SEAM_SCOPES = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
 /**
@@ -62,4 +73,4 @@ function scopeCovers(required, presented, granted) {
 	return granted.includes(required);
 }
 //#endregion
-export { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, SEAM_SCOPES, scopeCovers };
+export { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, MIGRATIONS_READ_SCOPE, SEAM_SCOPES, scopeCovers };

package/dist/createBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createBackend.d.ts","sourceRoot":"","sources":["../src/createBackend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EAEpB,SAAS,EACV,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAO9C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,oGAAoG;AACpG,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EAAE,GAAG,SAAS,UAAU;IAC9F,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iHAAiH;AACjH,KAAK,UAAU,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG;QACtD,EAAE,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,EAAE,EAAE,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,SAAS,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH,CAAC;AAuCF,kCAAkC;AAClC,eAAO,MAAM,UAAU;;;iBAQ+B,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CA0LrF"}
+{"version":3,"file":"createBackend.d.ts","sourceRoot":"","sources":["../src/createBackend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EAEpB,SAAS,EACV,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAO9C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,oGAAoG;AACpG,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EAAE,GAAG,SAAS,UAAU;IAC9F,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iHAAiH;AACjH,KAAK,UAAU,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG;QACtD,EAAE,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,EAAE,EAAE,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,SAAS,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH,CAAC;AAuCF,kCAAkC;AAClC,eAAO,MAAM,UAAU;;;iBAQ+B,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CA0MrF"}

package/dist/createBackend.js

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { noActingOrganization } from "./access/acting.js";
 import { noopEmit } from "./audit/recorder.js";
 import { ValidationError } from "./error/pithyError.js";
 import { pithyCommandOf } from "./cli/command.js";
@@ -8,9 +9,10 @@ import { recordComposition } from "./capability/composition.js";
 import { validateBindings } from "./capability/validateBindings.js";
 import { workerVersion } from "./worker/identity.js";
 import { describeRoute } from "./http/routeSpec.js";
+import { buildDbRegistry, composeDatabases } from "./data/databases.js";
 import { isControlPlaneCapability } from "./controlPlane/capability.js";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors.js";
-import { buildDbRegistry, composeDatabases } from "./data/databases.js";
+import { registerReadinessGuards } from "./controlPlane/http/readiness.js";
 import { noEntitlementProvider } from "./entitlement/entitlement.js";
 import { bakedTranslator } from "./i18n/translator.js";
 import { catalogFor, composeMessages } from "./i18n/registry.js";
@@ -113,10 +115,11 @@ function createBackend(options) {
 	const app = new Hono();
 	app.onError(loggingErrorHandler);
 	const baseLogger = options.logger ?? createWorkerLogger();
+	const adminSurface = corsSurface(all);
 	const controlPlane = all.find(isControlPlaneCapability);
 	if (controlPlane) {
 		const cors = controlPlane.controlPlaneConfig;
-		registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+		registerControlPlaneCors(app, adminSurface, allowedOriginSet(cors), cors.corsMaxAgeSeconds);
 	}
 	let validated = false;
 	app.use("*", async (c, next) => {
@@ -126,6 +129,7 @@ function createBackend(options) {
 			validated = true;
 		}
 		if (c.get("auth") === void 0) c.set("auth", null);
+		if (c.get("actingOrganization") === void 0) c.set("actingOrganization", noActingOrganization);
 		if (c.get("locale") === void 0) c.set("locale", null);
 		if (c.get("t") === void 0) c.set("t", defaultTranslator);
 		if (c.get("controlPlane") === void 0) c.set("controlPlane", null);
@@ -188,6 +192,7 @@ function createBackend(options) {
 		routes: app.routes.slice(healthStart)
 	});
 	for (const cap of all) for (const middleware of cap.middleware ?? []) middleware(app);
+	registerReadinessGuards(app, adminSurface, all.flatMap((cap) => cap.readiness ?? []));
 	for (const cap of all) {
 		const start = app.routes.length;
 		cap.routes?.(app);

package/dist/createEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createEntrypoint.d.ts","sourceRoot":"","sources":["../src/createEntrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAI3E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/G;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,eAAe,CAoD3D"}
+{"version":3,"file":"createEntrypoint.d.ts","sourceRoot":"","sources":["../src/createEntrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAK3E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/G;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,eAAe,CAyD3D"}

package/dist/createEntrypoint.js

@@ -3,6 +3,7 @@
 import { triggerWorkflow } from "./workflow/dispatch.js";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register.js";
 import { createBackend } from "./createBackend.js";
+import { withLocalServices } from "./worker/serviceLoopback.js";
 //#region src/createEntrypoint.ts
 /**
 * The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
@@ -31,17 +32,18 @@ function createEntrypoint(options) {
 	for (const cap of all) cap.boot?.({ capabilities: all });
 	const registry = composeWorkflows(all);
 	const scheduled = scheduledWorkflows(registry);
-	const entrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+	const entrypoint = { fetch: (request, env, ctx) => app.fetch(request, withLocalServices(env), ctx) };
 	if (scheduled.length > 0) entrypoint.scheduled = async (_controller, env) => {
 		const failures = [];
 		for (const entry of scheduled) try {
-			await triggerWorkflow(env, registry, entry.key, {});
+			await triggerWorkflow(withLocalServices(env), registry, entry.key, {});
 		} catch (error) {
 			failures.push(error);
 		}
 		if (failures[0] !== void 0) throw failures[0];
 	};
-	if (handlers.length > 0) entrypoint.email = async (message, env, ctx) => {
+	if (handlers.length > 0) entrypoint.email = async (message, given, ctx) => {
+		const env = withLocalServices(given);
 		if (handlers.length === 1) {
 			await handlers[0]?.(message, env, ctx);
 			return;

package/dist/entitlement/allowance.d.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { PithyHonoEnv } from "../capability/capability";
+import type { MeterLimit } from "./entitlement";
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+export declare function quota(c: Context<PithyHonoEnv>, name: string): Promise<number | null>;
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+export declare function feature(c: Context<PithyHonoEnv>, name: string): Promise<boolean>;
+/**
+ * The ceiling a capability enforces on a meter it counts itself, for the current caller.
+ *
+ * **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+ * keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+ * breaks an adopter who was already over it.
+ *
+ * **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+ * briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+ * as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+ * is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+ * Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+ * advisory.
+ */
+export declare function meterLimit(c: Context<PithyHonoEnv>, meter: string): Promise<MeterLimit>;
+//# sourceMappingURL=allowance.d.ts.map

package/dist/entitlement/allowance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowance.d.ts","sourceRoot":"","sources":["../../src/entitlement/allowance.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAqChD,gGAAgG;AAChG,wBAAsB,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAI1F;AAED,sEAAsE;AACtE,wBAAsB,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAItF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAa7F"}

package/dist/entitlement/allowance.js

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError, messageOf } from "../error/pithyError.js";
+//#region src/entitlement/allowance.ts
+/**
+* The allowance readers — how much the current caller may have, and whether a switch is on.
+*
+*   const seats = await quota(c, "seats");                  // number, or null for unlimited
+*   if (seats !== null && (await countMembers(orgId)) >= seats) throw new SeatLimitReached(…);
+*   if (await feature(c, "auditExport")) { … }               // boolean, never null
+*
+* **Neither takes an entitlement key, and that is the point.** A route does not know which tier the
+* caller's holder is on, and during an upgrade overlap it holds two. The provider resolves across every
+* key the holder has and answers the higher, so an adopter compares numbers and never ranks tiers.
+*
+* **Read, never enforced.** A quota denies nothing on its own and a feature set to `false` denies
+* nothing either — `requireEntitlement` still gates on the key alone. What a number means for a request
+* is the adopter's code to decide, because only the adopter can count what it owns.
+*
+* **They live in core for the reason `requireEntitlement` does.** A reader that arrived with
+* `@pithy-sh/payments` would be absent when payments is, and a route reading an allowance must then fail
+* rather than read something. So with no provider composed — or one that declares no allowances — both
+* throw `core/internal` naming the gap. Never `0`, which is a paywall shut for a reason nobody can see;
+* never unlimited, which is a paywall that does not exist.
+*/
+/** The refusal when nothing on the request can answer an allowance. The adopter's wiring, so `core/internal`. */
+function noProvider(c, kind, name) {
+	const provider = c.var.entitlements?.provider ?? null;
+	return new InternalError({
+		message: `No ${kind} "${name}" can be resolved here.`,
+		action: "Compose a payments capability that declares its entitlements in this Worker's pithy.config.ts.",
+		detail: provider === null ? `no entitlement provider is composed, so ${kind}("${name}") has nothing to read.` : `${provider} resolves entitlements and declares no allowances, so ${kind}("${name}") has nothing to read.`
+	});
+}
+/** How many of `name` the caller's holder may have: a whole number, or `null` for unlimited. */
+async function quota(c, name) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.quota) throw noProvider(c, "quota", name);
+	return resolver.quota(name);
+}
+/** Whether `name` is on for the caller's holder. Always a boolean. */
+async function feature(c, name) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.feature) throw noProvider(c, "feature", name);
+	return resolver.feature(name);
+}
+/**
+* The ceiling a capability enforces on a meter it counts itself, for the current caller.
+*
+* **No provider, or one that binds nothing to this meter, is `{ enforced: false }`** — and the capability
+* keeps its own configured ceiling. Enforcement is opt-in per meter because a cap that arrives by surprise
+* breaks an adopter who was already over it.
+*
+* **A provider that throws refuses, and logs.** Storage already says which way round to err: over-counting
+* briefly and reclaiming is the right way round, and under-counting has no recovery. Treating a failed read
+* as unenforced would hand a customer an unbounded allowance for as long as the read kept failing. The cost
+* is real and is stated rather than discovered: our bug becomes a refused write for a paying customer.
+* Enforcement being opt-in is what bounds it — an adopter who would rather over-serve leaves the meter
+* advisory.
+*/
+async function meterLimit(c, meter) {
+	const resolver = c.var.entitlements;
+	if (!resolver?.meterLimit) return { enforced: false };
+	try {
+		return await resolver.meterLimit(meter);
+	} catch (error) {
+		c.var.log?.error("meter limit resolution failed", {
+			provider: resolver.provider,
+			meter,
+			cause: messageOf(error)
+		});
+		throw new InternalError({
+			message: "Usage could not be checked, so nothing was written.",
+			action: "Read the preceding log line for why the allowance read failed.",
+			detail: `${resolver.provider} threw resolving the ${meter} meter's ceiling; refusing rather than serving unbounded.`
+		});
+	}
+}
+//#endregion
+export { feature, meterLimit, quota };

package/dist/entitlement/entitlement.d.ts

@@ -66,7 +66,48 @@ export interface EntitlementResolver {
      * See {@link EntitlementHolder} for why this is a label and a tenant rather than the holder itself.
      */
     holder?(): Promise<EntitlementHolder | undefined>;
+    /**
+     * How many of `name` the current caller's holder may have — a whole number, or `null` for unlimited.
+     * Optional: a provider with no allowances omits it, and {@link import("./allowance").quota} refuses
+     * rather than inventing a number. A provider throws for a name it does not declare, never answers 0.
+     */
+    quota?(name: string): Promise<number | null>;
+    /** Whether `name` is on for the current caller's holder. Never null. Optional, as {@link quota} is. */
+    feature?(name: string): Promise<boolean>;
+    /**
+     * The ceiling a capability that counts its own rows enforces for `meter` — storage's bytes, media's
+     * items — or `{ enforced: false }` where the provider binds no ceiling to it. Optional, and absent is
+     * `{ enforced: false }`: a capability composed with no provider keeps its own configured behavior.
+     */
+    meterLimit?(meter: string): Promise<MeterLimit>;
 }
+/**
+ * What a provider says about one meter for the current caller: whether it binds a ceiling at all, and if
+ * it does, what the ceiling is and whose rows it covers. `limit: null` is unlimited — an enforced meter on
+ * a subject whose plan or override says so.
+ *
+ * Two states rather than a nullable number, because "this meter is advisory here" and "this subject is
+ * unlimited" are different facts and a capability must fall back to its own configured ceiling on the
+ * first and never on the second.
+ *
+ * **An enforced ceiling says which rows it is the whole of**, because a ceiling counted against the wrong
+ * rows is a different allowance. Under organization billing the plan's 10 GB is the company's: counted
+ * against one member's files it becomes 10 GB per member, and a paid quota is bypassed by an invitation.
+ * So `tenant` is the organization the ceiling was resolved for, exactly as {@link EntitlementHolder.tenant}
+ * is, and a capability sums every row it holds for that tenant, whoever wrote it. `null` means the holder
+ * is not a tenant: the ceiling is the caller's own, and the caller's rows are what count.
+ *
+ * It is a counting key, never a gate. A capability that would write a row for a different tenant than the
+ * one the ceiling covers refuses the write — that row would sit outside the sum, and under-counting has no
+ * recovery.
+ */
+export type MeterLimit = {
+    readonly enforced: false;
+} | {
+    readonly enforced: true;
+    readonly limit: number | null;
+    readonly tenant: string | null;
+};
 /**
  * How a resolver's holder appears in a denial's `detail` and on the denial's audit row — and **nothing a
  * gate may compare**.

package/dist/entitlement/entitlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../../src/entitlement/entitlement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,eAAO,MAAM,cAAc,aAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;iBAqBuF,CAAC;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGpF;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAMnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC"}
+{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../../src/entitlement/entitlement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,eAAO,MAAM,cAAc,aAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW;;;;;iBAqBuF,CAAC;AAChH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGpF;AAED,2GAA2G;AAC3G,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAMnG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IAClD;;;;OAIG;IACH,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,uGAAuG;IACvG,OAAO,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,uBAAuB,CAAC"}