@pithy-sh/core 0.10.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/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"}

package/dist/capability/bindings.js

@@ -16,9 +16,47 @@ const BindingType = z.union([
 	z.literal("secret").describe("Secret from the Secrets Store, encrypted at rest."),
 	z.literal("workflow").describe("Cloudflare Workflow — durable, multi-step execution."),
 	z.literal("service").describe("Service binding — direct RPC to another Worker."),
-	z.literal("durable_object").describe("Durable Object — a single-threaded, stateful actor with its own storage. Backed by an exported DO class; the CLI wires the namespace binding and the class migration tag.")
+	z.literal("durable_object").describe("Durable Object — a single-threaded, stateful actor with its own storage. Backed by an exported DO class; the CLI wires the namespace binding and the class migration tag."),
+	z.literal("hyperdrive").describe("Hyperdrive — a pooled, cached connection to an existing database. The adopter creates the config."),
+	z.literal("browser").describe("Browser Rendering — a headless browser the Worker drives."),
+	z.literal("images").describe("Cloudflare Images — transform and optimize images from the Worker."),
+	z.literal("analytics_engine_datasets").describe("Workers Analytics Engine — write data points to a dataset, query them with SQL."),
+	z.literal("pipelines").describe("Pipelines — send records into a stream that lands in R2. The adopter creates it."),
+	z.literal("mtls_certificates").describe("mTLS certificate — present a client certificate on outbound requests. The adopter uploads it."),
+	z.literal("dispatch_namespaces").describe("Workers for Platforms dispatch namespace — call Workers uploaded into it. The adopter creates it."),
+	z.literal("artifacts").describe("Artifacts — versioned storage that speaks Git, one namespace of repositories per environment. Cloudflare creates the namespace on its first repo.")
 ]).describe("Kind of Cloudflare resource a binding refers to.");
 /**
+* The policy per kind, as a total record — so a kind added to {@link BindingType} without one is a type error
+* here, and `bindings.test.ts` fails on a member whose answer it does not state.
+*/
+const SEED_POLICY = {
+	ai: "carry",
+	ratelimit: "carry",
+	browser: "carry",
+	images: "carry",
+	hyperdrive: "branch",
+	analytics_engine_datasets: "carry",
+	mtls_certificates: "carry",
+	dispatch_namespaces: "carry",
+	pipelines: "branch",
+	d1: "provision",
+	kv: "provision",
+	r2: "provision",
+	vectorize: "provision",
+	queue: "provision",
+	durable_object: "provision",
+	workflow: "provision",
+	service: "provision",
+	secret: "provision",
+	email: "branch",
+	artifacts: "provision"
+};
+/** How a newly created stanza gets this kind's entries. See {@link SeedPolicy}. */
+function seedPolicy(type) {
+	return SEED_POLICY[type];
+}
+/**
 * Whether a provision command creates the **resource** behind this kind of binding, rather than the
 * adopter standing it up themselves.
 *
@@ -59,10 +97,66 @@ function isProvisionedBinding(type) {
 *
 * `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.
 */
 function isWrittenBinding(type) {
-	return type === "d1" || type === "kv" || type === "r2" || type === "ai" || type === "durable_object" || type === "ratelimit" || type === "workflow";
+	return WRITTEN.has(type);
 }
+const WRITTEN = /* @__PURE__ */ new Set([
+	"d1",
+	"kv",
+	"r2",
+	"ai",
+	"durable_object",
+	"ratelimit",
+	"workflow",
+	"queue",
+	"email",
+	"hyperdrive",
+	"browser",
+	"images",
+	"analytics_engine_datasets",
+	"pipelines",
+	"mtls_certificates",
+	"dispatch_namespaces",
+	"artifacts"
+]);
+/**
+* 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.
+*/
+const TARGET_KINDS = {
+	hyperdrive: {
+		field: "id",
+		required: true
+	},
+	mtls_certificates: {
+		field: "certificate_id",
+		required: true
+	},
+	pipelines: {
+		field: "stream",
+		required: true
+	},
+	dispatch_namespaces: {
+		field: "namespace",
+		required: true
+	},
+	analytics_engine_datasets: {
+		field: "dataset",
+		required: false
+	}
+};
 /**
 * A JavaScript class name — what `className` may be.
 *
@@ -80,13 +174,15 @@ const CLASS_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 * landed on, which is `configImports.isInside`'s argument in a regex.
 */
 const CLASS_MODULE = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*(\/[A-Za-z0-9_~-][A-Za-z0-9._~-]*)*$/;
+/** What a `target` may be: a Cloudflare id or resource name, starting alphanumeric. */
+const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /**
 * The kinds whose resource Pithy names and creates — the only kinds `scope` and `resource` mean anything
 * for.
 *
 * {@link FEATURE_RESOURCE_KINDS} rather than a fresh literal, because it is already the repo's answer to
 * "which bindings does a provisioning run compose a `<project>-<scope>-<thing>` name for": it is the
-* domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same three. Every
+* domain of `ProvisionScope.resource`, and the CLI's own `PROVISIONABLE` map is the same four. Every
 * other kind's name is composed by a different rule with no `<thing>` slot to fill — a Workflow's from
 * the capability and the job, a Worker script's by wrangler — and a `secret` already states its scope in
 * `defineSecretRegistry`, where the value it names lives.
@@ -104,9 +200,10 @@ const BindingSpec = z.object({
 	classModule: z.string().min(1).regex(CLASS_MODULE, "A classModule is a bare module specifier: a package, optionally with a path into it.").optional().describe("The module the class is exported from (e.g. \"@pithy-sh/multiplayer/src/session/durableObject\") — what the CLI writes the Worker entry's `export { <className> } from \"<classModule>\";` against. Required for a `durable_object` binding, because wrangler resolves `class_name` against the entry `main` names and refuses the deploy when nothing there exports it. Its own module, never the package entry point, which `pithy.config.ts` loads in Node. Ignored for every other kind."),
 	job: z.string().min(1).regex(NAME_SEGMENT, "A job is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The job within the capability this Workflow runs (e.g. \"send\") — the `<job>` segment of the deployed `<project>-<env>-<capability>-<job>` name, and the second half of the `<capability>/<job>` dispatch key. Meaningful only for a `workflow` binding, where it is what lets `pithy add` name the Workflow offline instead of leaving the binding unwritten. Ignored for every other kind."),
 	service: z.string().min(1).optional().describe("The Worker this binding calls, named as it appears in `apps/<name>/` (e.g. \"api\"). Meaningful only for a `service` binding — the CLI resolves it to that Worker's environment-scoped script name when writing `services` into wrangler.jsonc, so worker-to-worker RPC targets the right deployment per environment. Ignored for every other kind."),
+	target: z.string().min(1).regex(TARGET, "A target is a resource id or name: letters, digits, `.`, `_` and `-`.").optional().describe("The account-level resource this binding addresses, which the adopter creates themselves: a Hyperdrive config id, an mTLS certificate id, a Pipelines stream, a dispatch namespace, or an Analytics Engine dataset. Written into the field wrangler names for it (`id`, `certificate_id`, `stream`, `namespace`, `dataset`), and carried whole into every environment, because the resource is the account's. Required for `hyperdrive`, `mtls_certificates`, `pipelines` and `dispatch_namespaces`; optional for `analytics_engine_datasets`. Refused on every other kind."),
 	remote: z.boolean().optional().describe("Reach the real Cloudflare resource during local development instead of a local emulation. Set it for a binding that has none — Vectorize and Workers AI both lack local simulation — so `wrangler dev` and any Workflow host, which always runs locally, still work. Left unset rather than defaulting to false, so a spec that does not care emits no flag at all. Ignored in a deployed Worker."),
-	scope: z.enum(["environment", "global"]).optional().describe("Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv` or `r2` binding."),
-	resource: z.string().min(1).regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv` or `r2` binding.")
+	scope: z.enum(["environment", "global"]).optional().describe("Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding."),
+	resource: z.string().min(1).regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding.")
 }).describe("Declares a Cloudflare binding a capability requires in the Worker env.").check((ctx) => {
 	if (ctx.value.type === "durable_object" && ctx.value.className === void 0) ctx.issues.push({
 		code: "custom",
@@ -132,9 +229,22 @@ const BindingSpec = z.object({
 			code: "custom",
 			input: ctx.value,
 			path: [field],
-			message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv or r2 binding has — this one is a ${ctx.value.type}.`
+			message: `Binding "${ctx.value.name}" declares a ${field}, which only a d1, kv, r2 or queue binding has — this one is a ${ctx.value.type}.`
 		});
 	}
+	const target = TARGET_KINDS[ctx.value.type];
+	if (target?.required && ctx.value.target === void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["target"],
+		message: `Binding "${ctx.value.name}" needs a target — the ${ctx.value.type} resource it addresses, written as \`${target.field}\`.`
+	});
+	if (target === void 0 && ctx.value.target !== void 0) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["target"],
+		message: `Binding "${ctx.value.name}" declares a target, which a ${ctx.value.type} binding does not take.`
+	});
 });
 //#endregion
-export { BindingSpec, BindingType, isProvisionedBinding, isWrittenBinding };
+export { BindingSpec, BindingType, TARGET_KINDS, isProvisionedBinding, isWrittenBinding, seedPolicy };