@pithy-sh/core 0.1.2 → 0.1.3

package/dist/capability/settings.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { HostEnvReport } from "../workflow/hostEnv";
+/**
+ * How a capability checks that its own settings **work** — the seam `pithy doctor` runs (#411).
+ *
+ * Everything doctor asked before this was a question about *presence*: is the option key written, is the
+ * binding declared, is the ledger level. So a project could be entirely green while `fromAddress` named a
+ * domain nobody onboarded, the signing key was never created, `BASE_URL` was staging's URL in production's
+ * config, and no mail arrived. Presence is not the same question as correctness, and only the capability
+ * knows the second one.
+ *
+ * ## It hangs off the capability, never off the manifest
+ *
+ * The declaration sits on the {@link import("./capability").Capability} object, beside `health`, because
+ * `pithy.manifest.json` looks like the obvious signal and is the wrong one: `@pithy-sh/matchmaking` and
+ * `@pithy-sh/rating` are published capability packages that ship no manifest, and a manifest-keyed rule
+ * skips both in silence. The CLI already holds every composed instance (`project/workerScope.ts`), so
+ * discovery costs it nothing and misses nothing.
+ *
+ * A capability with nothing worth checking declares nothing. That is ordinary, silent, and not a fault.
+ *
+ * ## Two tiers, because they cost different things
+ *
+ * - **local** — does the value parse, is it the right shape, is it right for this environment. Free,
+ *   offline, and always run. It validates through the very Zod object the capability's host Worker
+ *   validates at boot ({@link hostEnvFindings} is the bridge), so the check an operator runs and the
+ *   check the host runs cannot come to two answers.
+ * - **account** — is the domain a zone here, does the secret exist, is the database there. One Cloudflare
+ *   call, so it is opt-in and it is skipped whenever the account cannot be reached.
+ *
+ * Both are faults. A local finding fails `pithy doctor`'s exit; an account finding does too, **but only
+ * when the account was reached** — an unreachable account is reported as *skipped*, never as a pass, and
+ * gates nothing. Three answers, and a boolean can hold two of them.
+ *
+ * ## Nothing here writes
+ *
+ * A check reports. `pithy upgrade`, `pithy <capability> provision` and the commands each finding names are
+ * what change anything, which is why every finding carries the action that resolves it.
+ */
+/** One setting that does not work, and the one thing an operator does about it. */
+export declare const SettingsFinding: z.ZodObject<{
+    setting: z.ZodString;
+    environment: z.ZodNullable<z.ZodString>;
+    problem: z.ZodString;
+    action: z.ZodString;
+}, z.core.$strip>;
+export type SettingsFinding = z.infer<typeof SettingsFinding>;
+/** One environment the project declares, and what this Worker's own config says about it. */
+export interface SettingsEnvironment {
+    /** The environment id — `dev`, `staging`, `prod`. Verbatim, never `production`. */
+    name: string;
+    /**
+     * The origin this Worker answers on in that environment, or `null` where its config names none.
+     *
+     * Supplied by the CLI rather than resolved by the capability: which hostname an environment serves is
+     * the adopter's declaration to make, and `project/domains.ts` is the one reader of it.
+     */
+    origin: string | null;
+}
+/** What a check is told about the project it is checking. Both tiers get it; the account tier gets more. */
+export interface SettingsCheckContext {
+    /** The root config's `name` — the leading segment of every resource this project provisions. */
+    project: string;
+    /** The Worker whose `pithy.config.ts` composed this capability. */
+    worker: string;
+    /** Every environment the project declares, in declaration order. */
+    environments: readonly SettingsEnvironment[];
+}
+/**
+ * The account questions a check may ask — a closed vocabulary, on purpose.
+ *
+ * Closed for the reason `CapabilityHealth` is: handing a capability a raw Cloudflare client would make
+ * every capability a place a network call can be invented, and would put `@pithy-sh/cloudflare` in the
+ * dependency list of packages that need none of it. Three questions cover what the first checks ask; a
+ * fourth lands here, once, when a capability actually needs it.
+ *
+ * Every method may throw. A throw is the account failing to answer, and the runner reports that
+ * capability's account tier as unchecked rather than as a pass.
+ */
+export interface SettingsAccountReader {
+    /** Every D1 database name this account holds. */
+    d1Databases(): Promise<readonly string[]>;
+    /** Whether this account holds a Cloudflare zone covering the hostname — the prerequisite for onboarding it. */
+    zone(hostname: string): Promise<boolean>;
+    /** Whether a declared secret has a value in that environment. The name is the registry's, not a binding's. */
+    secret(request: {
+        name: string;
+        environment: string;
+    }): Promise<boolean>;
+}
+/** What the account tier is told: everything the local tier gets, plus the account it may ask. */
+export interface SettingsAccountContext extends SettingsCheckContext {
+    /** The account, as the closed set of questions above. */
+    account: SettingsAccountReader;
+}
+/**
+ * A capability's settings check, as it hangs off the capability.
+ *
+ * `local` is required — a capability that declares this seam declares at least the free half of it. A
+ * check that would only ever reach the account is a check that says nothing offline, and offline is where
+ * most of these faults are cheapest to find.
+ */
+export interface CapabilitySettings {
+    /** The free half. Pure, offline, and always run. */
+    local(context: SettingsCheckContext): SettingsFinding[] | Promise<SettingsFinding[]>;
+    /** The half that costs a Cloudflare call. Omitted where a capability has nothing to ask the account. */
+    account?(context: SettingsAccountContext): Promise<SettingsFinding[]>;
+}
+/**
+ * Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
+ *
+ * A capability's local tier builds the env its host *would* be handed, runs {@link
+ * import("../workflow/hostEnv").checkHostEnv} against its own declaration, and hands the report here. The
+ * problem line is Zod's own message and the action line is {@link hostEnvProviderSentence} — the same
+ * words the host writes into its log before it refuses to start. Two readers of one declaration, and no
+ * second wording to drift.
+ */
+export declare function hostEnvFindings(report: HostEnvReport<unknown>, environment: string | null): SettingsFinding[];
+//# sourceMappingURL=settings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/capability/settings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,mFAAmF;AACnF,eAAO,MAAM,eAAe;;;;;iBA0B+D,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,4GAA4G;AAC5G,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC1C,+GAA+G;IAC/G,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,8GAA8G;IAC9G,MAAM,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED,kGAAkG;AAClG,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,yDAAyD;IACzD,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,KAAK,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACrF,wGAAwG;IACxG,OAAO,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CACvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,EAAE,CAO7G"}

package/dist/capability/settings.js

@@ -0,0 +1,66 @@
+import { hostEnvProviderSentence } from "../workflow/hostEnv.js";
+import { z } from "zod";
+//#region src/capability/settings.ts
+/**
+* How a capability checks that its own settings **work** — the seam `pithy doctor` runs (#411).
+*
+* Everything doctor asked before this was a question about *presence*: is the option key written, is the
+* binding declared, is the ledger level. So a project could be entirely green while `fromAddress` named a
+* domain nobody onboarded, the signing key was never created, `BASE_URL` was staging's URL in production's
+* config, and no mail arrived. Presence is not the same question as correctness, and only the capability
+* knows the second one.
+*
+* ## It hangs off the capability, never off the manifest
+*
+* The declaration sits on the {@link import("./capability").Capability} object, beside `health`, because
+* `pithy.manifest.json` looks like the obvious signal and is the wrong one: `@pithy-sh/matchmaking` and
+* `@pithy-sh/rating` are published capability packages that ship no manifest, and a manifest-keyed rule
+* skips both in silence. The CLI already holds every composed instance (`project/workerScope.ts`), so
+* discovery costs it nothing and misses nothing.
+*
+* A capability with nothing worth checking declares nothing. That is ordinary, silent, and not a fault.
+*
+* ## Two tiers, because they cost different things
+*
+* - **local** — does the value parse, is it the right shape, is it right for this environment. Free,
+*   offline, and always run. It validates through the very Zod object the capability's host Worker
+*   validates at boot ({@link hostEnvFindings} is the bridge), so the check an operator runs and the
+*   check the host runs cannot come to two answers.
+* - **account** — is the domain a zone here, does the secret exist, is the database there. One Cloudflare
+*   call, so it is opt-in and it is skipped whenever the account cannot be reached.
+*
+* Both are faults. A local finding fails `pithy doctor`'s exit; an account finding does too, **but only
+* when the account was reached** — an unreachable account is reported as *skipped*, never as a pass, and
+* gates nothing. Three answers, and a boolean can hold two of them.
+*
+* ## Nothing here writes
+*
+* A check reports. `pithy upgrade`, `pithy <capability> provision` and the commands each finding names are
+* what change anything, which is why every finding carries the action that resolves it.
+*/
+/** One setting that does not work, and the one thing an operator does about it. */
+const SettingsFinding = z.object({
+	setting: z.string().min(1).describe("What is wrong — the env field, config key, or account resource, spelled as the operator would find it. It leads the line, so it is the name they search for."),
+	environment: z.string().min(1).nullable().describe("The environment this is about, or `null` where the setting is the same in all of them. A per-environment fault is reported once per environment, because that is how many edits it takes."),
+	problem: z.string().min(1).describe("Why it does not work, in one sentence. The problem line, in the same voice every PithyError uses."),
+	action: z.string().min(1).describe("What resolves it: the `pithy` command, the `pithy.config.ts` key, or the one-time account action. Never optional — a finding nobody can act on is a complaint.")
+}).describe("One capability setting that does not work, with the action that resolves it.");
+/**
+* Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
+*
+* A capability's local tier builds the env its host *would* be handed, runs {@link
+* import("../workflow/hostEnv").checkHostEnv} against its own declaration, and hands the report here. The
+* problem line is Zod's own message and the action line is {@link hostEnvProviderSentence} — the same
+* words the host writes into its log before it refuses to start. Two readers of one declaration, and no
+* second wording to drift.
+*/
+function hostEnvFindings(report, environment) {
+	return report.problems.map((problem) => ({
+		setting: problem.field,
+		environment,
+		problem: problem.reason,
+		action: hostEnvProviderSentence(problem.provider)
+	}));
+}
+//#endregion
+export { SettingsFinding, hostEnvFindings };

package/dist/capability/validateBindings.d.ts

@@ -0,0 +1,4 @@
+import { type BindingSpec } from "./bindings";
+/** Throw a typed error if any non-optional binding is absent from `env`. */
+export declare function validateBindings(env: Record<string, unknown>, required: BindingSpec[]): void;
+//# sourceMappingURL=validateBindings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validateBindings.d.ts","sourceRoot":"","sources":["../../src/capability/validateBindings.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,WAAW,EAAwB,MAAM,YAAY,CAAC;AA2BpE,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAU5F"}

package/dist/capability/validateBindings.js

@@ -0,0 +1,34 @@
+import { isProvisionedBinding } from "./bindings.js";
+import { InternalError } from "../error/pithyError.js";
+//#region src/capability/validateBindings.ts
+/** How a missing binding is named in both halves of the error: `kv:SESSIONS`. */
+function label(binding) {
+	return `${binding.type}:${binding.name}`;
+}
+/**
+* What to do about the bindings that are missing — and there are two answers, not one.
+*
+* A `kv` or `d1` binding is a line the adopter adds to `wrangler.jsonc`. A `secret`, `workflow`, or
+* `vectorize` binding is not: its entry carries a provisioned value, so the old single line
+* ("Add the binding(s) to wrangler.jsonc, then redeploy.") sent anyone missing a Secrets Store entry
+* to a file that entry never appears in. Each list names only its own bindings, so a mixed failure
+* says which of them is which instead of leaving the reader to sort it out.
+*/
+function bindingAction(missing) {
+	const written = missing.filter((binding) => !isProvisionedBinding(binding.type)).map(label);
+	const provisioned = missing.filter((binding) => isProvisionedBinding(binding.type)).map(label);
+	const sentences = [];
+	if (written.length > 0) sentences.push(`Add ${written.join(", ")} to wrangler.jsonc, then redeploy.`);
+	if (provisioned.length > 0) sentences.push(`Provision ${provisioned.join(", ")} — a provision command creates those, or .dev.vars in dev.`);
+	return sentences.join(" ");
+}
+/** Throw a typed error if any non-optional binding is absent from `env`. */
+function validateBindings(env, required) {
+	const missing = required.filter((b) => !b.optional && env[b.name] == null);
+	if (missing.length > 0) throw new InternalError({
+		message: `Missing required bindings: ${missing.map(label).join(", ")}`,
+		action: bindingAction(missing)
+	});
+}
+//#endregion
+export { validateBindings };

package/dist/capability/vanishingKey.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Whether a value states no key that would vanish during parsing.
+ *
+ * Non-objects pass: they hold no keys, and the schema behind this guard is what refuses them for being the
+ * wrong type. `Object.hasOwn` and not `in`, because every object inherits `__proto__` and only an own one
+ * is data somebody wrote.
+ */
+export declare function statesNoVanishingKey(value: unknown): boolean;
+/**
+ * A schema held to keys that survive being read.
+ *
+ * Wraps rather than replaces: the schema behind it keeps its own key and value rules, and this only
+ * guarantees they are given every key the payload wrote. See {@link VANISHING_KEY} for why that is not
+ * already true.
+ *
+ * `subject` names what wrote the record, because the reader of the error is the person who has to go and
+ * change it — a capability author for a manifest, an adopter for a projection.
+ *
+ * Typed on the wrapped schema's own input rather than on `unknown`, so a guard is transparent to whatever
+ * it is composed into. Widening every wrapped schema to `unknown` would make the guard's altitude a
+ * typing question — it could only go where nothing downstream needed the input type — and altitude is the
+ * one thing about this guard that should be decided on the exposure.
+ */
+export declare function refusesVanishingKey<Output, Input>(schema: z.ZodType<Output, Input>, subject: string): z.ZodPipe<z.ZodCustom<Input, Input>, z.ZodType<Output, Input>>;
+/**
+ * A record a manifest may state. The manifest's wording of {@link refusesVanishingKey}, kept in one place
+ * so its two call sites cannot drift into two sentences for one rule.
+ */
+export declare function manifestRecord<Output, Input>(record: z.ZodType<Output, Input>): z.ZodPipe<z.ZodCustom<Input, Input>, z.ZodType<Output, Input>>;
+//# sourceMappingURL=vanishingKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vanishingKey.d.ts","sourceRoot":"","sources":["../../src/capability/vanishingKey.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0CxB;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAC/C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAChC,OAAO,EAAE,MAAM,GACd,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAMhE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,KAAK,EAC1C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,GAC/B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAEhE"}

package/dist/capability/vanishingKey.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+//#region src/capability/vanishingKey.ts
+/**
+* The one key a parsed object loses on the way through a schema, and the guard that refuses it.
+*
+* `JSON.parse` gives `__proto__` an own property, because it must — the alternative is JSON that can set
+* the prototype of every object built from it. Zod then skips that key while projecting an object or a
+* record, for exactly the same reason: assigning it onto the `{}` it builds into would run the setter on
+* `Object.prototype` instead of creating a property. Neither decision is wrong. Together they mean a key
+* enters the parse, matches no rule, raises no issue, and is not in the result.
+*
+* That is the shape worth naming: **not a value rewritten, a key that was never reported at all.** A key
+* schema would have refused `__proto__` on its first character; it never runs, because the skip happens
+* before the key type does. So this does not add a rule. It gets the rule that is already written back in
+* front of the data.
+*
+* **`Object.create(null)` does not close this, and #331 left that question open.** The idea is sound on
+* its face — a null-prototype target has no `__proto__` setter to run, so the assignment would create a
+* property and the key would survive — and it is wrong here for a reason that is worth writing down once.
+* Zod's skip is a literal `key === "__proto__"` comparison made *before* any assignment
+* (`zod/v4/core/schemas` at the object and record branches), so the prototype of the target has no bearing
+* on it, and neither does the prototype of the input: handing `z.record` a value built with
+* `Object.assign(Object.create(null), parsed)` still returns without the key. Measured, not assumed. The
+* class cannot be closed by changing what the object is; it can only be closed in front of the schema,
+* which is what this is.
+*
+* **Refuse, not degrade.** The surrounding design degrades an unrecognized *issuer* to `other` so a client
+* built today can read a manifest written tomorrow, and that is right for a value. It is wrong here twice
+* over. `__proto__` is not a name a future issuer will be called; it is a mistake or an attack. And
+* degrading a key is a merge — the defect the issuer-key rule was written to close, where two unknown keys
+* rewritten to one overwrite each other's requirements in silence. Refusing is the only answer that leaves
+* nothing to detect after the fact: a payload that will not parse is reported by every client that reads
+* it, and `pithy doctor` already names the package that shipped it.
+*
+* Applied at the schema, not at a call site, because the exposure belongs to the *shape* — any record read
+* from outside this process has it — and a rule that lives at one call site is how this codebase has
+* repeatedly fixed one field and left its siblings. `vanishingKey.test.ts` walks each guarded root and
+* attacks every record it finds, so a record added later without this guard fails on the commit that adds
+* it.
+*/
+const VANISHING_KEY = "__proto__";
+/**
+* Whether a value states no key that would vanish during parsing.
+*
+* Non-objects pass: they hold no keys, and the schema behind this guard is what refuses them for being the
+* wrong type. `Object.hasOwn` and not `in`, because every object inherits `__proto__` and only an own one
+* is data somebody wrote.
+*/
+function statesNoVanishingKey(value) {
+	if (typeof value !== "object" || value === null) return true;
+	return !Object.hasOwn(value, VANISHING_KEY);
+}
+/**
+* A schema held to keys that survive being read.
+*
+* Wraps rather than replaces: the schema behind it keeps its own key and value rules, and this only
+* guarantees they are given every key the payload wrote. See {@link VANISHING_KEY} for why that is not
+* already true.
+*
+* `subject` names what wrote the record, because the reader of the error is the person who has to go and
+* change it — a capability author for a manifest, an adopter for a projection.
+*
+* Typed on the wrapped schema's own input rather than on `unknown`, so a guard is transparent to whatever
+* it is composed into. Widening every wrapped schema to `unknown` would make the guard's altitude a
+* typing question — it could only go where nothing downstream needed the input type — and altitude is the
+* one thing about this guard that should be decided on the exposure.
+*/
+function refusesVanishingKey(schema, subject) {
+	return z.custom(statesNoVanishingKey, { error: `${subject} may not state a "${VANISHING_KEY}" key. It is the one name a parsed object loses without a word, so whatever it keyed would be gone with it.` }).pipe(schema);
+}
+/**
+* A record a manifest may state. The manifest's wording of {@link refusesVanishingKey}, kept in one place
+* so its two call sites cannot drift into two sentences for one rule.
+*/
+function manifestRecord(record) {
+	return refusesVanishingKey(record, "A manifest record");
+}
+//#endregion
+export { manifestRecord, refusesVanishingKey, statesNoVanishingKey };

package/dist/controlPlane/audit/actions.d.ts

@@ -0,0 +1,70 @@
+import type { AuditEventInput } from "../../audit/auditEvent";
+import type { AuditEmit } from "../../audit/recorder";
+import type { Logger } from "../../logger/logger";
+/**
+ * The audit action codes the `control-plane` seam emits, as `domain/reason` strings under the
+ * `controlplane` domain.
+ *
+ * **The domain is one word on purpose.** `AuditAction`'s pattern allows no hyphen, so
+ * `control-plane/call_allowed` is not a valid code at all. The route-strategy literal stays
+ * `control-plane`; every namespace token — capability, migrations, table prefix, error codes, these
+ * actions — is `controlplane`. The audit *actor kind* is the hyphenated `"control-plane"`, because
+ * that is an enum member and not a namespace. (None of this is Cloudflare's control plane; that is the
+ * outbound provisioning API behind `@pithy-sh/cloudflare`.)
+ *
+ * These are declared as a plain `as const` map rather than through `@pithy-sh/audit`'s
+ * `defineAuditActions`, because audit already depends on core — importing it back would be a cycle.
+ * `actions.test.ts` asserts every value against core's `AuditAction` pattern instead, so the map is
+ * held to the same contract the helper would have enforced.
+ *
+ * Emission goes through core's `emit` seam (`c.var.emit`), a no-op when the audit capability is
+ * absent, so the seam never imports audit at runtime either (principle 4).
+ *
+ * **Four of these are emitted by a route; three are emitted by the CLI** (#294). The connection
+ * lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
+ * directly, because those operations never reach their Worker: a first connect has no key to sign with
+ * and the Worker may not be deployed, an update re-points an address the Worker never reads, and a
+ * disconnect withdraws trust, which must not depend on a working connection (docs/CONTROL-PLANE.md §15).
+ * So there is no route in a position to record them, and the write records itself instead — in the same
+ * D1, from `connectionRegistry`. The `actorType` is what tells the two writers apart: a route records
+ * `control-plane`, meaning the management client called in and proved it, while a CLI-side event carries
+ * the adopter's own operator and no session at all.
+ *
+ * A declared code that nothing emits is a surface the trail promises and never delivers, which is what
+ * these three were until #294. `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
+ */
+export declare const ControlPlaneAuditActions: {
+    /** A verified, in-scope management call was admitted. The trail of what the dashboard actually did. */
+    readonly callAllowed: "controlplane/call_allowed";
+    /** A management call was refused — no connection, bad credential, or an ungranted scope. Outcome `denied`. */
+    readonly callDenied: "controlplane/call_denied";
+    /** A new public key was registered on a connection, opening a rotation overlap. */
+    readonly keyRegistered: "controlplane/key_registered";
+    /** A superseded public key was given an end date and stopped being accepted. */
+    readonly keyExpired: "controlplane/key_expired";
+    /** A management client was connected to this environment — a new connection, or one started over. */
+    readonly connectionRegistered: "controlplane/connection_registered";
+    /** An existing connection changed — its granted scopes, the Worker URL it points at, or the keys it trusts. */
+    readonly connectionUpdated: "controlplane/connection_updated";
+    /** A connection was removed. The seam returns to its shipped state: connected to nothing, denying everything. */
+    readonly connectionRemoved: "controlplane/connection_removed";
+};
+/** One of the control-plane audit action codes. */
+export type ControlPlaneAuditAction = (typeof ControlPlaneAuditActions)[keyof typeof ControlPlaneAuditActions];
+/**
+ * Emit an audit event and swallow any failure.
+ *
+ * **Every denial emits an event, and that is exactly why this cannot throw.** By the time the seam
+ * records a call, the security-relevant outcome is already decided — the 401 or 403 is going out
+ * whatever happens next. An audit write that threw would convert a correct denial into a 500: it would
+ * hand the caller a different response for a *failing* store than for a healthy one, and turn a
+ * transient D1 problem into an availability bug on the admin surface. The record is evidence of the
+ * decision, never part of making it.
+ *
+ * The real recorder is non-fatal by contract already ({@link AuditEmit}), so this is belt and braces —
+ * but the gate is a security boundary and does not get to assume its collaborators behave. The failure
+ * is logged when a logger is at hand, so a store that has stopped accepting writes is visible rather
+ * than silent.
+ */
+export declare function safeEmit(emit: AuditEmit, event: AuditEventInput, log?: Logger): Promise<void>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/controlPlane/audit/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/audit/actions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,wBAAwB;IACnC,uGAAuG;aACvG,WAAW,EAAE,2BAA2B;IACxC,8GAA8G;aAC9G,UAAU,EAAE,0BAA0B;IACtC,mFAAmF;aACnF,aAAa,EAAE,6BAA6B;IAC5C,gFAAgF;aAChF,UAAU,EAAE,0BAA0B;IACtC,qGAAqG;aACrG,oBAAoB,EAAE,oCAAoC;IAC1D,+GAA+G;aAC/G,iBAAiB,EAAE,iCAAiC;IACpD,iHAAiH;aACjH,iBAAiB,EAAE,iCAAiC;CAC5C,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAE/G;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnG"}

package/dist/controlPlane/audit/actions.js

@@ -0,0 +1,76 @@
+//#region src/controlPlane/audit/actions.ts
+/**
+* The audit action codes the `control-plane` seam emits, as `domain/reason` strings under the
+* `controlplane` domain.
+*
+* **The domain is one word on purpose.** `AuditAction`'s pattern allows no hyphen, so
+* `control-plane/call_allowed` is not a valid code at all. The route-strategy literal stays
+* `control-plane`; every namespace token — capability, migrations, table prefix, error codes, these
+* actions — is `controlplane`. The audit *actor kind* is the hyphenated `"control-plane"`, because
+* that is an enum member and not a namespace. (None of this is Cloudflare's control plane; that is the
+* outbound provisioning API behind `@pithy-sh/cloudflare`.)
+*
+* These are declared as a plain `as const` map rather than through `@pithy-sh/audit`'s
+* `defineAuditActions`, because audit already depends on core — importing it back would be a cycle.
+* `actions.test.ts` asserts every value against core's `AuditAction` pattern instead, so the map is
+* held to the same contract the helper would have enforced.
+*
+* Emission goes through core's `emit` seam (`c.var.emit`), a no-op when the audit capability is
+* absent, so the seam never imports audit at runtime either (principle 4).
+*
+* **Four of these are emitted by a route; three are emitted by the CLI** (#294). The connection
+* lifecycle — registered, updated, removed — is written by `pithy dashboard` opening the adopter's D1
+* directly, because those operations never reach their Worker: a first connect has no key to sign with
+* and the Worker may not be deployed, an update re-points an address the Worker never reads, and a
+* disconnect withdraws trust, which must not depend on a working connection (docs/CONTROL-PLANE.md §15).
+* So there is no route in a position to record them, and the write records itself instead — in the same
+* D1, from `connectionRegistry`. The `actorType` is what tells the two writers apart: a route records
+* `control-plane`, meaning the management client called in and proved it, while a CLI-side event carries
+* the adopter's own operator and no session at all.
+*
+* A declared code that nothing emits is a surface the trail promises and never delivers, which is what
+* these three were until #294. `packages/cli/src/ci/auditActions.test.ts` fails the build on one.
+*/
+const ControlPlaneAuditActions = {
+	/** A verified, in-scope management call was admitted. The trail of what the dashboard actually did. */
+	callAllowed: "controlplane/call_allowed",
+	/** A management call was refused — no connection, bad credential, or an ungranted scope. Outcome `denied`. */
+	callDenied: "controlplane/call_denied",
+	/** A new public key was registered on a connection, opening a rotation overlap. */
+	keyRegistered: "controlplane/key_registered",
+	/** A superseded public key was given an end date and stopped being accepted. */
+	keyExpired: "controlplane/key_expired",
+	/** A management client was connected to this environment — a new connection, or one started over. */
+	connectionRegistered: "controlplane/connection_registered",
+	/** An existing connection changed — its granted scopes, the Worker URL it points at, or the keys it trusts. */
+	connectionUpdated: "controlplane/connection_updated",
+	/** A connection was removed. The seam returns to its shipped state: connected to nothing, denying everything. */
+	connectionRemoved: "controlplane/connection_removed"
+};
+/**
+* Emit an audit event and swallow any failure.
+*
+* **Every denial emits an event, and that is exactly why this cannot throw.** By the time the seam
+* records a call, the security-relevant outcome is already decided — the 401 or 403 is going out
+* whatever happens next. An audit write that threw would convert a correct denial into a 500: it would
+* hand the caller a different response for a *failing* store than for a healthy one, and turn a
+* transient D1 problem into an availability bug on the admin surface. The record is evidence of the
+* decision, never part of making it.
+*
+* The real recorder is non-fatal by contract already ({@link AuditEmit}), so this is belt and braces —
+* but the gate is a security boundary and does not get to assume its collaborators behave. The failure
+* is logged when a logger is at hand, so a store that has stopped accepting writes is visible rather
+* than silent.
+*/
+async function safeEmit(emit, event, log) {
+	try {
+		await emit(event);
+	} catch (error) {
+		log?.warn("control-plane audit event dropped", {
+			action: event.action,
+			error
+		});
+	}
+}
+//#endregion
+export { ControlPlaneAuditActions, safeEmit };

package/dist/controlPlane/capability.d.ts

@@ -0,0 +1,47 @@
+import { type Capability } from "../capability/capability";
+import type { DatabaseSpecMap } from "../data/databases";
+import type { KvNamespaceSpecMap } from "../kv/namespaces";
+import { ControlPlaneConfig, type ControlPlaneConfigInput } from "./config/config";
+import { CONTROL_PLANE_KV_BINDING } from "./replay/kvGuard";
+/**
+ * Where the control-plane registration sorts in the app database. Composed key:
+ * `1100_controlplane_0001_init`.
+ *
+ * Taken from `NEXT_FREE_ORDER` in `packages/cli/src/migrations/orders.test.ts`, which is the one place
+ * an order may be allocated, and registered in that file's `DECLARED` table. Core used to be skipped by
+ * that scanner on the reasoning that it owns the ceiling rather than an order; that stopped being true
+ * here, and the skip was removed with this change. Stable forever — renumbering would rename the
+ * composed key and make Kysely re-run an applied migration.
+ */
+export declare const CONTROLPLANE_MIGRATION_ORDER = 1100;
+export type ControlPlaneOptions = ControlPlaneConfigInput;
+/** The control-plane capability, with its resolved config attached. */
+export interface ControlPlaneCapability extends Capability<DatabaseSpecMap, KvNamespaceSpecMap, "controlplane"> {
+    /** The resolved seam config. */
+    controlPlaneConfig: ControlPlaneConfig;
+}
+/** Narrow a composed capability to this one — the CLI and tests use it to find the seam's config. */
+export declare function isControlPlaneCapability(capability: Capability): capability is ControlPlaneCapability;
+/**
+ * The `control-plane` seam: inbound, adopter-authenticated M2M admin access to this Worker.
+ *
+ * **Not Cloudflare's control plane.** That is the outbound REST API `@pithy-sh/cloudflare` calls to
+ * provision D1, KV, and Workers, and it carries `cloudflare/*` codes. This is the inverse — a
+ * management client calling *in*, authenticated by a key the adopter registered. See
+ * `docs/CONTROL-PLANE.md`, whose first section exists entirely to keep the two apart.
+ *
+ * **Composing it grants nobody anything.** The capability ships present-and-denying: with no connection
+ * registered, every route it guards answers `controlplane/not_connected`, and there is no flag that
+ * changes that. `pithy dashboard connect` is the deliberate second step, and revoking is a row the
+ * adopter deletes without asking anyone.
+ *
+ * It lives in `@pithy-sh/core` rather than its own package because every capability contributing admin
+ * routes imports `requireControlPlane`, and a capability may depend on a core seam but never on a
+ * sibling package (principle 4). MIT with the rest of core, and never gated by tier: this is the code
+ * that runs in the adopter's own Worker, so restricting it would make "build your own client against
+ * your own Worker" untrue.
+ */
+export declare function controlplane(options?: ControlPlaneOptions): ControlPlaneCapability;
+/** Re-exported so a Worker's wrangler config and this capability cannot disagree about the binding name. */
+export { CONTROL_PLANE_KV_BINDING };
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/controlPlane/capability.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,UAAU,EAAuC,MAAM,0BAA0B,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAc,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAUnF,OAAO,EACL,wBAAwB,EAIzB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAE1D,uEAAuE;AACvE,MAAM,WAAW,sBAAuB,SAAQ,UAAU,CAAC,eAAe,EAAE,kBAAkB,EAAE,cAAc,CAAC;IAC7G,gCAAgC;IAChC,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,sBAAsB,CAErG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,sBAAsB,CAwJtF;AAED,4GAA4G;AAC5G,OAAO,EAAE,wBAAwB,EAAE,CAAC"}