@pithy-sh/core 0.9.0 → 0.11.0

package/dist/access/usage.js

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { sql } from "kysely";
+//#region src/access/usage.ts
+/**
+* What an account is holding — records and bytes, per owner and per organization — for the control plane.
+*
+* ## A per-owner figure is always an organization's figure
+*
+* **A report run by an organization for user X filters by that organization's id**, because the
+* organization must never learn that the same person holds an account in another one. The number alone
+* leaks it: a per-user total summed across organizations discloses that the user exists elsewhere, with no
+* name attached and no row shown — the figure simply does not reconcile with what the organization can
+* see. So an unscoped per-owner read is not a convenience this offers. It is a read that does not exist:
+* {@link UsageQuery} refuses `groupBy: "owner"` and an `ownerId` filter unless an organization is named,
+* and every per-owner row is keyed by the organization it was counted in.
+*
+* Duplicate detection is the same disclosure in different clothes — *does anybody hold this file* against
+* *how much does this person hold* — and both are closed by the same column. Neither consults an
+* adopter's permission hook: a hook that widened a per-subject total would reopen exactly this.
+*
+* ## The organization is the column, not a join
+*
+* Counted by the `organizationId` written on each record, which is the fact at the time of the write. A
+* join through current membership would re-attribute last quarter's bytes the moment somebody changed
+* organization. Only stored records count — a pending upload holds nothing yet, and a failed one never
+* will.
+*
+* ## Indexed
+*
+* The tables carry `(organizationId, createdAt)` and `(ownerId, createdAt)`, so an organization's slice
+* over a window is one index range and a grouping by organization walks the index rather than sorting.
+*/
+/** The sentinel that names records written with no organization in force — a query string cannot say null. */
+const NO_ORGANIZATION = "none";
+const Id = z.string().min(1).max(128);
+/** What a usage read asks. */
+const UsageQuery = z.object({
+	groupBy: z.enum(["owner", "organization"]).describe("`organization` is one row per organization; `owner` is one row per owner within the organization named, never across organizations."),
+	organizationId: Id.optional().describe("Restrict to one organization. Required with `groupBy=owner` and with `ownerId`, because a per-owner figure is only ever an organization's. `none` is the records written with no organization in force."),
+	ownerId: Id.optional().describe("Restrict to one owner, within the organization named."),
+	since: z.iso.datetime().optional().describe("Count records created at or after this instant, ISO-8601."),
+	until: z.iso.datetime().optional().describe("Count records created before this instant, ISO-8601."),
+	limit: z.coerce.number().int().min(1).max(500).optional().describe("The most rows to return. 100 by default.")
+}).describe("A request for records and bytes held, grouped by owner or by organization.").check((ctx) => {
+	if (ctx.value.organizationId !== void 0) return;
+	if (ctx.value.groupBy !== "owner" && ctx.value.ownerId === void 0) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["organizationId"],
+		message: `A per-owner read names its organization. Pass organizationId, or \`${NO_ORGANIZATION}\` for records written with none.`
+	});
+});
+/** One row of a usage read. */
+const UsageRow = z.object({
+	organizationId: z.string().nullable().describe("The organization these records were written under. Null for records written with none."),
+	ownerId: z.string().nullable().optional().describe("The owner, on a per-owner read. Null for system-owned records. Absent on a per-organization read."),
+	records: z.number().int().nonnegative().describe("How many stored records."),
+	bytes: z.number().int().nonnegative().describe("Their total size in bytes. A record of unknown size counts zero.")
+}).describe("Records and bytes held by one organization, or by one owner within one organization.");
+/** What a usage read answers. */
+const UsageResponse = z.object({
+	rows: z.array(UsageRow).describe("Largest first. Capped at the requested limit."),
+	truncated: z.boolean().describe("Whether more rows matched than were returned.")
+}).describe("Records and bytes held, grouped as asked.");
+/** The default page of a usage read. */
+const DEFAULT_LIMIT = 100;
+/**
+* The statement a usage read runs, over one record table — `pithyMediaAssets`, `pithyStorageObjects` —
+* carrying `ownerId`, `organizationId`, `size`, `status` and `createdAt`. Exported so a test can ask SQLite
+* how it plans the very statement {@link usageRollup} executes. Every value is a bound parameter.
+*/
+function usageStatement(table, query) {
+	const limit = query.limit ?? DEFAULT_LIMIT;
+	const organization = sql.ref("organizationId");
+	const owner = sql.ref("ownerId");
+	const filters = [sql`${sql.ref("status")} = 'stored'`];
+	if (query.organizationId === "none") filters.push(sql`${organization} is null`);
+	else if (query.organizationId !== void 0) filters.push(sql`${organization} = ${query.organizationId}`);
+	if (query.ownerId !== void 0) filters.push(sql`${owner} = ${query.ownerId}`);
+	if (query.since !== void 0) filters.push(sql`${sql.ref("createdAt")} >= ${Date.parse(query.since)}`);
+	if (query.until !== void 0) filters.push(sql`${sql.ref("createdAt")} < ${Date.parse(query.until)}`);
+	const keys = query.groupBy === "owner" ? sql`${organization}, ${owner}` : sql`${organization}`;
+	return sql`select ${keys}, count(*) as records, coalesce(sum(${sql.ref("size")}), 0) as bytes from ${sql.table(table)} where ${sql.join(filters, sql` and `)} group by ${keys} order by bytes desc limit ${limit + 1}`;
+}
+/** Read usage off one record table through any Kysely over D1 with the `CamelCasePlugin`. */
+async function usageRollup(db, table, query) {
+	const limit = query.limit ?? DEFAULT_LIMIT;
+	const result = await usageStatement(table, query).execute(db);
+	const byOwner = query.groupBy === "owner";
+	return {
+		rows: result.rows.slice(0, limit).map((row) => ({
+			organizationId: row.organizationId ?? null,
+			...byOwner ? { ownerId: row.ownerId ?? null } : {},
+			records: Number(row.records),
+			bytes: Number(row.bytes ?? 0)
+		})),
+		truncated: result.rows.length > limit
+	};
+}
+//#endregion
+export { NO_ORGANIZATION, UsageQuery, UsageResponse, UsageRow, usageRollup, usageStatement };

package/dist/access/visibility.d.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * Who may read a record, and learn that it exists — one convention, written once, for every capability
+ * that holds a record a person owns.
+ *
+ * **Three levels, and the kit owns them.** `private` is the owner, acting for the organization the record
+ * was written under; acting for any other organization, not even them. `organization` is any member of the
+ * record's organization, acting for it. `public` is anyone holding the id or the URL, signed in or not.
+ * Media and storage share the levels, the policy shape and the rules, so a record means the same thing in
+ * both and there is one place the meaning can be wrong.
+ *
+ * **The project decides which levels exist, and which one a record gets when it names none.** `allowed` is
+ * a set rather than a mode, because a set says everything a mode would and one thing it cannot:
+ * `["private", "organization"]` is a guarantee that nothing can be published, even by mistake.
+ */
+/** Every level, weakest first. */
+export declare const RECORD_VISIBILITIES: readonly ["private", "organization", "public"];
+export declare const RecordVisibility: z.ZodEnum<{
+    organization: "organization";
+    private: "private";
+    public: "public";
+}>;
+export type RecordVisibility = z.infer<typeof RecordVisibility>;
+/**
+ * The levels a project allows, and the one a record gets when a write names none.
+ *
+ * **`default` is `private` and must be in `allowed`**, and a policy that breaks either is refused at
+ * parse — which, for a capability, is at boot. **`allowed` defaults to all three**, so a capability that
+ * accepted `public` before this policy existed is not narrowed by it.
+ */
+export declare const VisibilityPolicy: z.ZodObject<{
+    default: z.ZodDefault<z.ZodEnum<{
+        organization: "organization";
+        private: "private";
+        public: "public";
+    }>>;
+    allowed: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        organization: "organization";
+        private: "private";
+        public: "public";
+    }>>>;
+}, z.core.$strip>;
+export type VisibilityPolicy = z.output<typeof VisibilityPolicy>;
+export type VisibilityPolicyInput = z.input<typeof VisibilityPolicy>;
+/**
+ * The level a write records: the one it named, or the policy's default.
+ *
+ * **Refused, never coerced.** A level outside `allowed` is a mistake somewhere — a client that did not
+ * know the policy, or a policy narrowed under a client — and quietly writing the default instead would
+ * hide it until somebody wondered why a published file was private, or worse. `organization` with no
+ * organization in force is refused for the same reason: a record no member can ever be acting for is not
+ * an organization record, it is a private one that says otherwise.
+ *
+ * Both refusals are the caller's to fix, so the remedy is in `message`; `action` names the config key for
+ * the operator who decides the policy.
+ */
+export declare function resolveVisibility(policy: VisibilityPolicy, requested: RecordVisibility | undefined, organizationId: string | null): RecordVisibility;
+/**
+ * The levels a policy no longer allows — what `pithy doctor` searches records for after `allowed`
+ * narrows. Narrowing never rewrites a record: making a public record private breaks every link already
+ * published, so moving them is the adopter's explicit act, and this is how they find them.
+ */
+export declare function outsidePolicy(policy: VisibilityPolicy): RecordVisibility[];
+//# sourceMappingURL=visibility.d.ts.map

package/dist/access/visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../src/access/visibility.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;GAaG;AAEH,kCAAkC;AAClC,eAAO,MAAM,mBAAmB,YAAI,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAU,CAAC;AAElF,eAAO,MAAM,gBAAgB;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAsBzB,CAAC;AACL,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACjE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,cAAc,EAAE,MAAM,GAAG,IAAI,GAC5B,gBAAgB,CAmBlB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAE1E"}

package/dist/access/visibility.js

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/access/visibility.ts
+/**
+* Who may read a record, and learn that it exists — one convention, written once, for every capability
+* that holds a record a person owns.
+*
+* **Three levels, and the kit owns them.** `private` is the owner, acting for the organization the record
+* was written under; acting for any other organization, not even them. `organization` is any member of the
+* record's organization, acting for it. `public` is anyone holding the id or the URL, signed in or not.
+* Media and storage share the levels, the policy shape and the rules, so a record means the same thing in
+* both and there is one place the meaning can be wrong.
+*
+* **The project decides which levels exist, and which one a record gets when it names none.** `allowed` is
+* a set rather than a mode, because a set says everything a mode would and one thing it cannot:
+* `["private", "organization"]` is a guarantee that nothing can be published, even by mistake.
+*/
+/** Every level, weakest first. */
+const RECORD_VISIBILITIES = [
+	"private",
+	"organization",
+	"public"
+];
+const RecordVisibility = z.enum(RECORD_VISIBILITIES).describe("Who may read a record and learn it exists: `private` is the owner acting for the record's organization, `organization` is any member acting for it, `public` is anyone holding the id or URL.");
+/**
+* The levels a project allows, and the one a record gets when a write names none.
+*
+* **`default` is `private` and must be in `allowed`**, and a policy that breaks either is refused at
+* parse — which, for a capability, is at boot. **`allowed` defaults to all three**, so a capability that
+* accepted `public` before this policy existed is not narrowed by it.
+*/
+const VisibilityPolicy = z.object({
+	default: RecordVisibility.default("private").describe("The level a record gets when a write names none. Private, so a forgotten field can never publish a file. Must be one of `allowed`."),
+	allowed: z.array(RecordVisibility).min(1).default([...RECORD_VISIBILITIES]).describe("The levels a write may name. All three by default. `[\"private\", \"organization\"]` means nothing can ever be public; a write naming a level outside it is refused, never coerced.")
+}).describe("Which visibility levels this project allows, and the default for a write that names none.").check((ctx) => {
+	if (ctx.value.allowed.includes(ctx.value.default)) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["default"],
+		message: `visibility.default is \`${ctx.value.default}\`, which visibility.allowed (${ctx.value.allowed.join(", ")}) does not include.`
+	});
+});
+/**
+* The level a write records: the one it named, or the policy's default.
+*
+* **Refused, never coerced.** A level outside `allowed` is a mistake somewhere — a client that did not
+* know the policy, or a policy narrowed under a client — and quietly writing the default instead would
+* hide it until somebody wondered why a published file was private, or worse. `organization` with no
+* organization in force is refused for the same reason: a record no member can ever be acting for is not
+* an organization record, it is a private one that says otherwise.
+*
+* Both refusals are the caller's to fix, so the remedy is in `message`; `action` names the config key for
+* the operator who decides the policy.
+*/
+function resolveVisibility(policy, requested, organizationId) {
+	const level = requested ?? policy.default;
+	if (!policy.allowed.includes(level)) throw new ValidationError({
+		message: `Visibility \`${level}\` is not allowed here. Allowed: ${policy.allowed.join(", ")}.`,
+		action: "Name one of visibility.allowed, or widen visibility.allowed in this Worker's pithy.config.ts.",
+		detail: `requested ${requested ?? "(default)"} resolved to ${level}, outside ${policy.allowed.join(", ")}`,
+		params: {
+			visibility: level,
+			allowed: policy.allowed.join(", ")
+		}
+	});
+	if (level === "organization" && organizationId === null) throw new ValidationError({
+		message: "Visibility `organization` needs an organization in force. Choose one, or name another level.",
+		action: "Compose @pithy-sh/organization and choose an organization, or set a different visibility.default.",
+		detail: "organization visibility requested with no acting organization",
+		params: { visibility: level }
+	});
+	return level;
+}
+/**
+* The levels a policy no longer allows — what `pithy doctor` searches records for after `allowed`
+* narrows. Narrowing never rewrites a record: making a public record private breaks every link already
+* published, so moving them is the adopter's explicit act, and this is how they find them.
+*/
+function outsidePolicy(policy) {
+	return RECORD_VISIBILITIES.filter((level) => !policy.allowed.includes(level));
+}
+//#endregion
+export { RECORD_VISIBILITIES, RecordVisibility, VisibilityPolicy, outsidePolicy, resolveVisibility };

package/dist/asyncapi/document.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+import type { SocketChannel } from "../http/socket";
+import { type ContractInfo, type JsonSchema, type UndescribedField } from "../openapi/document";
+/**
+ * **The AsyncAPI contract: every socket a Worker serves, and every frame on it.**
+ *
+ * The OpenAPI document stops at the upgrade. This picks up after it, from the `sockets` each composed
+ * capability declares (`../http/socket.ts`): one channel per socket, one message per frame, and one operation
+ * per direction — `send` for what the Worker sends, `receive` for what it accepts, as AsyncAPI names them from
+ * the application's side. Every schema is the one the socket parses with, converted by `z.toJSONSchema` with
+ * its descriptions intact, so an engine with no generator still has typed messages to write against.
+ *
+ * AsyncAPI 3.0, whose schemas are JSON Schema — the dialect `z.toJSONSchema` writes.
+ */
+/** The AsyncAPI version this module writes. */
+export declare const ASYNCAPI_VERSION = "3.0.0";
+/** One capability's sockets. Becomes the channels tagged with its name. */
+export interface SocketGroup {
+    /** The capability's name. */
+    readonly tag: string;
+    /** The sockets it declared. */
+    readonly sockets: readonly SocketChannel[];
+}
+/** The sockets of every capability that declares one, grouped by capability, in composition order. */
+export declare function socketGroupsOf(capabilities: readonly Capability[]): SocketGroup[];
+/** The subset of an AsyncAPI 3.0 document this module writes. */
+export interface AsyncApiDocument {
+    asyncapi: string;
+    info: ContractInfo;
+    channels: Record<string, Record<string, unknown>>;
+    operations: Record<string, Record<string, unknown>>;
+    components: {
+        messages: Record<string, Record<string, unknown>>;
+        schemas: Record<string, JsonSchema>;
+    };
+}
+/** The AsyncAPI document for these capabilities' sockets. */
+export declare function asyncApiDocument(info: ContractInfo, groups: readonly SocketGroup[]): AsyncApiDocument;
+/**
+ * Every message property, schema property and channel parameter in the document without a description —
+ * the same rule as the OpenAPI document's, over the parts a client generates from.
+ */
+export declare function undescribedAsyncFields(document: AsyncApiDocument): UndescribedField[];
+//# sourceMappingURL=document.d.ts.map

package/dist/asyncapi/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/asyncapi/document.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,UAAU,EAGf,KAAK,gBAAgB,EAEtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;GAUG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,sGAAsG;AACtG,wBAAgB,cAAc,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,EAAE,CAIjF;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,UAAU,EAAE;QACV,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;KACrC,CAAC;CACH;AAyCD,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,gBAAgB,CA+CrG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAWrF"}

package/dist/asyncapi/document.js

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ErrorBody } from "../error/wire.js";
+import { jsonSchema, openApiPath, undescribedFieldsIn } from "../openapi/document.js";
+//#region src/asyncapi/document.ts
+/**
+* **The AsyncAPI contract: every socket a Worker serves, and every frame on it.**
+*
+* The OpenAPI document stops at the upgrade. This picks up after it, from the `sockets` each composed
+* capability declares (`../http/socket.ts`): one channel per socket, one message per frame, and one operation
+* per direction — `send` for what the Worker sends, `receive` for what it accepts, as AsyncAPI names them from
+* the application's side. Every schema is the one the socket parses with, converted by `z.toJSONSchema` with
+* its descriptions intact, so an engine with no generator still has typed messages to write against.
+*
+* AsyncAPI 3.0, whose schemas are JSON Schema — the dialect `z.toJSONSchema` writes.
+*/
+/** The AsyncAPI version this module writes. */
+const ASYNCAPI_VERSION = "3.0.0";
+/** The sockets of every capability that declares one, grouped by capability, in composition order. */
+function socketGroupsOf(capabilities) {
+	return capabilities.filter((capability) => (capability.sockets ?? []).length > 0).map((capability) => ({
+		tag: capability.name,
+		sockets: capability.sockets ?? []
+	}));
+}
+/** A frame's id in the document: its socket's name and its own, so two sockets' `error` frames stay apart. */
+function messageId(socket, message, direction) {
+	return `${socket.name}.${direction}.${message.name}`;
+}
+/** One `components.messages` entry: a JSON frame by its schema, a text frame by its exact text. */
+function messageOf(message) {
+	if (message.schema === void 0) return {
+		name: message.name,
+		summary: message.summary,
+		contentType: "text/plain",
+		payload: {
+			type: "string",
+			const: message.text ?? "",
+			description: message.summary
+		}
+	};
+	return {
+		name: message.name,
+		summary: message.summary,
+		contentType: "application/json",
+		payload: jsonSchema(message.schema, "input")
+	};
+}
+/** The path parameters, from the same schema the upgrade route validates them with. */
+function parametersOf(params) {
+	if (params === void 0) return {};
+	const properties = jsonSchema(params, "input").properties ?? {};
+	return Object.fromEntries(Object.entries(properties).map(([name, property]) => [name, typeof property.description === "string" ? { description: property.description } : {}]));
+}
+function strategiesOf(socket) {
+	return typeof socket.verification === "string" ? [socket.verification] : socket.verification;
+}
+/** The AsyncAPI document for these capabilities' sockets. */
+function asyncApiDocument(info, groups) {
+	const document = {
+		asyncapi: ASYNCAPI_VERSION,
+		info,
+		channels: {},
+		operations: {},
+		components: {
+			messages: {},
+			schemas: { Error: jsonSchema(ErrorBody, "input") }
+		}
+	};
+	for (const group of groups) for (const socket of group.sockets) {
+		const channelMessages = {};
+		for (const direction of ["send", "receive"]) {
+			const refs = [];
+			for (const message of socket[direction]) {
+				const id = messageId(socket, message, direction);
+				document.components.messages[id] = messageOf(message);
+				channelMessages[id] = { $ref: `#/components/messages/${id}` };
+				refs.push({ $ref: `#/channels/${socket.name}/messages/${id}` });
+			}
+			if (refs.length > 0) document.operations[`${socket.name}.${direction}`] = {
+				action: direction,
+				channel: { $ref: `#/channels/${socket.name}` },
+				summary: direction === "send" ? "Frames the Worker sends." : "Frames the Worker accepts.",
+				messages: refs
+			};
+		}
+		const parameters = parametersOf(socket.params);
+		document.channels[socket.name] = {
+			address: openApiPath(socket.path),
+			summary: socket.summary,
+			...socket.description === void 0 ? {} : { description: socket.description },
+			...Object.keys(parameters).length === 0 ? {} : { parameters },
+			messages: channelMessages,
+			tags: [{ name: group.tag }],
+			bindings: { ws: { method: "GET" } },
+			"x-pithy-verification": strategiesOf(socket),
+			"x-pithy-subprotocols": socket.versions
+		};
+		for (const [name, schema] of Object.entries(socket.schemas ?? {})) document.components.schemas[`${socket.name}.${name}`] = jsonSchema(schema, "input");
+	}
+	return document;
+}
+/**
+* Every message property, schema property and channel parameter in the document without a description —
+* the same rule as the OpenAPI document's, over the parts a client generates from.
+*/
+function undescribedAsyncFields(document) {
+	return [
+		...Object.entries(document.channels).flatMap(([channel, item]) => Object.entries(item.parameters ?? {}).filter(([, parameter]) => typeof parameter.description !== "string").map(([name]) => ({ pointer: `/channels/${channel}/parameters/${name}` }))),
+		...undescribedFieldsIn(document.components.messages, "/components/messages"),
+		...undescribedFieldsIn(document.components.schemas, "/components/schemas")
+	];
+}
+//#endregion
+export { ASYNCAPI_VERSION, asyncApiDocument, socketGroupsOf, undescribedAsyncFields };

package/dist/audit/auditEvent.d.ts

@@ -76,6 +76,11 @@ export declare const AuditEvent: z.ZodObject<{
         user: "user";
     }>;
     actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    actorKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        agent: "agent";
+        dashboard: "dashboard";
+        script: "script";
+    }>>>;
     sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     resourceType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     resourceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/audit/auditEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/audit/auditEvent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,aAM+F,CAAC;AACxH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEvD,gGAAgG;AAChG,eAAO,MAAM,YAAY;;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iGAAiG;AACjG,eAAO,MAAM,aAAa;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,mGAAmG;AACnG,eAAO,MAAM,aAAa,wCAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCiF,CAAC;AACzG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}
+{"version":3,"file":"auditEvent.d.ts","sourceRoot":"","sources":["../../src/audit/auditEvent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,aAM+F,CAAC;AACxH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAEvD,gGAAgG;AAChG,eAAO,MAAM,YAAY;;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iGAAiG;AACjG,eAAO,MAAM,aAAa;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;EAIxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,mGAAmG;AACnG,eAAO,MAAM,aAAa,wCAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2CiF,CAAC;AACzG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AACrD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/audit/auditEvent.js

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { ControlPlaneActorKind } from "../controlPlane/data/connection.js";
 import { z } from "zod";
 /**
 * The action taxonomy is **federated, not centralized**: `action` is an open, namespace-validated
@@ -57,6 +58,7 @@ const AuditEvent = z.object({
 	severity: AuditSeverity.default("info").describe("How serious the event is; defaults to `info`."),
 	actorType: AuditActorType.describe("The kind of principal that acted."),
 	actorId: z.string().nullish().describe("The acting principal's stable id (user id, service/token name); null for `system`/`anonymous`."),
+	actorKind: ControlPlaneActorKind.nullish().describe("For a `control-plane` actor, what kind of management client acted — `agent`, `dashboard` or `script` — from the connection it called through (#721). `actorType` names all three alike; this is what tells them apart. Stamped by `requireControlPlane`, so an emit site does not set it; null for every other actor type, and for a connection registered before the kind was recorded."),
 	sessionId: z.string().nullish().describe("The session this action belongs to, tying a chain of actions together; null when none."),
 	resourceType: z.string().nullish().describe("The type of resource the action targeted (e.g. `user`, `secret`); null when not resource-scoped."),
 	resourceId: z.string().nullish().describe("The id of the resource the action targeted; null when not resource-scoped."),

package/dist/capability/bindings.d.ts

@@ -1,8 +1,33 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
-export declare const BindingType: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">]>;
+export declare const BindingType: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">, z.ZodLiteral<"hyperdrive">, z.ZodLiteral<"browser">, z.ZodLiteral<"images">, z.ZodLiteral<"analytics_engine_datasets">, z.ZodLiteral<"pipelines">, z.ZodLiteral<"mtls_certificates">, z.ZodLiteral<"dispatch_namespaces">, z.ZodLiteral<"artifacts">]>;
 export type BindingType = z.infer<typeof BindingType>;
+/**
+ * **How a stanza the kit creates gets this kind's entries** (#662).
+ *
+ * Every `env.<name>` stanza Pithy creates starts from the top level, because wrangler inherits none of the keys a
+ * binding lives in. What it starts with depends on whose resource the entry names, and that is a fact about the
+ * kind, not about the JSON shape wrangler happens to give it:
+ *
+ * - **`carry`** — account-level and identical everywhere. A dataset, a certificate, a rate limiter's
+ *   `namespace_id`: the top level's entries come down whole into every stanza, because nothing in them is an
+ *   environment's own.
+ * - **`provision`** — the environment owns the resource. Seeded empty, refilled by the provisioner, because
+ *   dev's database id in staging's stanza is staging writing to dev's database.
+ * - **`branch`** — an account-level resource and a per-environment *decision*. Carried into a feature, which is a
+ *   branch of `dev`; left empty in a declared environment, which is not. A `send_email` entry names an address
+ *   verified once at the account, and where this environment's mail goes is a choice production does not inherit
+ *   from a laptop. A Hyperdrive config is one origin database's connection, and a pipeline stream feeds one sink:
+ *   the account holds both, but the top level's are dev's, and a declared environment seeded with them would read
+ *   and write dev's Postgres and dev's sink with nothing failing.
+ *
+ * Three values, not a boolean. `send_email` was carried everywhere for a day and wrote a developer's address into
+ * production's first stanza (#650 review); emptied everywhere, it left a feature with no `NOTIFY`.
+ */
+export type SeedPolicy = "carry" | "provision" | "branch";
+/** How a newly created stanza gets this kind's entries. See {@link SeedPolicy}. */
+export declare function seedPolicy(type: BindingType): SeedPolicy;
 /**
  * Whether a provision command creates the **resource** behind this kind of binding, rather than the
  * adopter standing it up themselves.
@@ -42,20 +67,40 @@ export declare function isProvisionedBinding(type: BindingType): boolean;
  *
  * `service` is in neither, deliberately: `pithy feature` writes it out of the target Worker's env-scoped
  * script name, and no shipped capability declares one.
+ *
+ * **The pure-wrangler-entry kinds are written and never provisioned (#662).** `hyperdrive`, `browser`, `images`,
+ * `analytics_engine_datasets`, `pipelines`, `mtls_certificates` and `dispatch_namespaces` each take a binding name
+ * and, where wrangler requires one, the account-level resource the spec states as `target`. Pithy writes the
+ * entry; the adopter stands the resource up. `queue` writes its `queues.producers` entry under the name
+ * `pithy provision` creates the queue with, and `email` writes `send_email` with nothing but its name.
+ *
+ * **`artifacts` is written and never provisioned (#673).** Its entry is `{ binding, namespace }`, and the namespace
+ * is `<project>-<env>`, derivable offline. There is no create call to make: Cloudflare creates a namespace the first
+ * time a repo is created in it. There is a teardown call, because repos cost storage, and `pithy feature destroy`
+ * makes it.
  */
 export declare function isWrittenBinding(type: BindingType): boolean;
+/**
+ * The kinds whose wrangler entry names an account-level resource the adopter creates, and what wrangler calls
+ * that field — what `BindingSpec.target` is written as. `true` where wrangler refuses the entry without it.
+ */
+export declare const TARGET_KINDS: Readonly<Partial<Record<BindingType, {
+    field: string;
+    required: boolean;
+}>>>;
 /**
  * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
  * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
  */
 export declare const BindingSpec: z.ZodObject<{
-    type: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">]>;
+    type: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">, z.ZodLiteral<"hyperdrive">, z.ZodLiteral<"browser">, z.ZodLiteral<"images">, z.ZodLiteral<"analytics_engine_datasets">, z.ZodLiteral<"pipelines">, z.ZodLiteral<"mtls_certificates">, z.ZodLiteral<"dispatch_namespaces">, z.ZodLiteral<"artifacts">]>;
     name: z.ZodString;
     optional: z.ZodDefault<z.ZodBoolean>;
     className: z.ZodOptional<z.ZodString>;
     classModule: z.ZodOptional<z.ZodString>;
     job: z.ZodOptional<z.ZodString>;
     service: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
     remote: z.ZodOptional<z.ZodBoolean>;
     scope: z.ZodOptional<z.ZodEnum<{
         environment: "environment";

package/dist/capability/bindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/capability/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW,sTAmBuC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAU3D;AAkCD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;iBAwHpB,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/capability/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW,4iBAuCuC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AA8B1D,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAExD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE3D;AAsBD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAMrG,CAAC;AAqCF;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;iBAuJpB,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}