@pithy-sh/core 0.1.0

package/src/capability/secretOrigin.ts

@@ -0,0 +1,253 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { manifestRecord } from "./vanishingKey";
+
+/**
+ * How a secret's value comes to exist, and how it is replaced.
+ *
+ * A secret the kit cannot mint leaves an adopter on their own. The registry has always known which
+ * those are — no `devValue` — and nothing about how a human is supposed to get one, so every client
+ * that wanted to help had to carry its own table of names, and a capability added tomorrow silently
+ * fell off it.
+ *
+ * It lives in core, and in its own module, for the reason `devSecret.ts` does: both ends need it and
+ * neither can import the other. The owning capability declares it on its `@pithy-sh/secrets` registry
+ * entry; a client — `pithy doctor`, `pithy secrets ls`, a management dashboard — reads the same
+ * declaration off `pithy.manifest.json`, which it must, since `pithy add` wires a capability without
+ * ever executing it.
+ *
+ * **A function cannot cross into the manifest. A tag can.** So everything here is data, and the code
+ * that knows what `random` means stays in the CLI — exactly as it already does for `devValue`.
+ */
+
+export const SecretIssuer = z
+  .enum([
+    "project",
+    "cloudflare",
+    "apple",
+    "google",
+    "github",
+    "facebook",
+    "microsoft",
+    "stripe",
+    "lemonSqueezy",
+    "paddle",
+    "gitlab",
+    "atlassian",
+    "other",
+  ])
+  .describe(
+    "Who issues this value. `project` means it is arbitrary and ours to make. Every other member is a third party whose console or API is the only source: payments rails, auth's social providers, `cloudflare` for R2, Turnstile and API tokens, and the repository hosts an adopter may rotate CI credentials against. `other` is the floor an unrecognized issuer lands on, so a capability added tomorrow is renderable by a client built today.",
+  );
+export type SecretIssuer = z.output<typeof SecretIssuer>;
+
+/**
+ * The issuer **as a field**, with its one degradation rule attached.
+ *
+ * **An unrecognized issuer degrades to `other` rather than failing.** A manifest is read from
+ * `node_modules`, so it can be newer than the client reading it — and a client that threw on an issuer
+ * it had not been built against would blank a pane over a name it did not need to understand. `other`
+ * is the honest answer: *somebody issues this, and I cannot help you with them.*
+ *
+ * A field holds one value, so rewriting it destroys nothing. {@link IssuerKey} is the same name in the
+ * one position where that is false.
+ */
+const IssuerName = SecretIssuer.catch("other");
+
+/** The issuer as a field, with the sentence that site needs. The rule comes from {@link IssuerName}. */
+function issuedBy(description: string): z.ZodType<SecretIssuer, unknown> {
+  return IssuerName.describe(description);
+}
+
+/** The characters an issuer's name may hold, where that name is a record key rendered into a heading. */
+const ISSUER_KEY = /^[A-Za-z][A-Za-z0-9_.-]*$/;
+
+/**
+ * The issuer **as a record key**, where the field's degradation rule would destroy data.
+ *
+ * **A key cannot degrade the way a field does, and the attempt to share one rule between them was the
+ * defect.** `SecretIssuer.catch("other")` rewrites what it parses. On a field that is a rename; on a key
+ * it is a *merge*, and the merge is silent. Keyed by the field's rule, `{ vercel: ["a"], netlify: ["b"] }`
+ * parsed to `{ other: ["b"] }` — vercel's requirement gone, the parse successful, nothing anywhere
+ * reporting it. Requirements lost without a word are worse than a manifest that refuses to parse, because
+ * a refusal is at least visible.
+ *
+ * So a key keeps the name it was written with. What a client loses by that is nothing it had: a reader
+ * that branches on the closed set runs `SecretIssuer.safeParse(key)` at the point of use and falls back to
+ * `other` for rendering, which is the same answer the schema used to force on it — except that the scopes
+ * are still there beside it, and a second unknown issuer is still a second entry.
+ *
+ * A preserved key reaches a rendered command and a rendered heading unchanged, so it is held to the shape
+ * of a name. That constraint is not a degradation path: an issuer a client has never heard of is still
+ * spelled like an issuer, and anything that is not is hostile data rather than a newer manifest.
+ */
+const IssuerKey = z
+  .string()
+  .regex(ISSUER_KEY)
+  .describe(
+    "An issuer, as the key of a record. Preserved exactly as written — unlike the field, which degrades to `other` — because two unrecognized issuers rewritten to one key overwrite each other's requirements with no error. A client that only knows the closed set narrows this with `SecretIssuer.safeParse` where it renders.",
+  );
+
+/** The characters a secret name may hold. Excludes `/`, which separates a keyspace from a member key. */
+const SECRET_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+/** What a helper must supply, per item. Permission groups and scope names, and nothing that reads as code. */
+const HELPER_NEED = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$/;
+
+/**
+ * A documentation link, held to `https:` and nothing else.
+ *
+ * `z.url()` on its own is not enough here: it accepts `javascript:alert(1)`, and it accepts `http:`. A
+ * manifest is third-party data read out of `node_modules`, and this is the one field in it whose whole
+ * purpose is to be turned into an anchor an operator clicks. So the scheme is constrained at the schema,
+ * where a client cannot forget to.
+ */
+const DOCUMENTATION_URL = /^https:\/\//;
+
+/** The documentation field, wherever it appears: a real URL, and an `https:` one. */
+function documentedAt(description: string) {
+  return z.url().regex(DOCUMENTATION_URL).describe(description);
+}
+
+export const SecretRecipe = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z
+          .literal("random")
+          .describe(
+            "Random bytes rendered as a string. Any value works, because nothing outside the project reads it.",
+          ),
+        bytes: z
+          .int()
+          .positive()
+          .describe(
+            "Entropy before encoding. Stated because 32 and 16 are not interchangeable — a value sized for AES-256 that arrives half that long fails at decrypt, not at write, and by then it is stored.",
+          ),
+        encoding: z
+          .enum(["base64url", "base64", "hex"])
+          .describe(
+            "How the bytes are rendered. The kit mints `base64url`, unpadded, so a value survives a `.dev.vars` line, a shell export and a URL without quoting.",
+          ),
+      })
+      .describe("A minted value the kit makes from entropy: how many bytes, and how they are rendered."),
+    z
+      .object({
+        kind: z
+          .literal("encryptionConfig")
+          .describe(
+            "An `EncryptionConfig` — `currentVersion`, a `versions` map, `lastRotatedAt` — minted by `initialMasterKeyConfig`. `SECRETS_ENCRYPTION_KEYS` is the one, and the reason this is a union rather than an enum: it is minted, and a random string is not one of these. It states no `bytes` or `encoding` because the structure states its own.",
+          ),
+      })
+      .describe(
+        "A minted structure rather than a string. The tag is the whole recipe; nothing about it is configurable.",
+      ),
+  ])
+  .describe(
+    "What produces a minted value. A tag the CLI resolves to code, never the code itself, because this crosses into the manifest.",
+  );
+export type SecretRecipe = z.output<typeof SecretRecipe>;
+
+export const SecretOrigin = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z
+          .literal("minted")
+          .describe("The kit produces this value. Nothing outside the project has to agree with it."),
+        recipe: SecretRecipe.describe("What produces it."),
+      })
+      .describe("Minted by the kit. The recipe says how, and no third party has to agree with the result."),
+    z
+      .object({
+        kind: z
+          .literal("helped")
+          .describe(
+            "The kit cannot produce it, but knows enough to compose the command that does — a Cloudflare API token, whose permission groups an operator should not have to look up.",
+          ),
+        issuer: issuedBy("Whose console or API issues it."),
+        needs: manifestRecord(z.partialRecord(IssuerKey, z.array(z.string().regex(HELPER_NEED)))).describe(
+          "What a helper must supply, keyed by issuer. Cloudflare's key is its permission groups. Keyed rather than flat so a second issuer does not widen a shape every consumer must handle. An unrecognized key is kept verbatim rather than degraded — see `IssuerKey`: rewriting two of them onto `other` loses one issuer's requirements silently. Wrapped in `manifestRecord` so the key rule is given every key the manifest wrote, including the one a parse would otherwise drop before the rule ran.",
+        ),
+        documentation: documentedAt(
+          "Where the command's arguments come from, for an operator who would rather check them by hand.",
+        ).optional(),
+      })
+      .describe("Issued elsewhere, but the kit knows enough to compose the command that asks for it."),
+    z
+      .object({
+        kind: z
+          .literal("obtained")
+          .describe(
+            "A human gets it from a third party and there is no command. An OAuth client secret is the case, and always will be.",
+          ),
+        issuer: issuedBy("Whose console issues it."),
+        documentation: documentedAt(
+          "Where a human goes. The specific settings page, not a product homepage — the point is to end a search, not to start one.",
+        ),
+      })
+      .describe("Fetched by a human from a third party. There is no command, and the link is the whole help."),
+  ])
+  .describe(
+    "How this secret's value first comes to exist. Closed, so a consumer branches rather than parses, and so an unhandled member is a type error rather than a blank screen.",
+  );
+export type SecretOrigin = z.output<typeof SecretOrigin>;
+
+export const SecretRotation = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z
+          .literal("local")
+          .describe(
+            'Replaced by producing a new value the same way it was minted. Every `origin.kind: "minted"` secret, and nothing else — if the kit can make one it can make another.',
+          ),
+      })
+      .describe("Rotated by the kit, on its own. The tag carries everything; there is nobody to call."),
+    z
+      .object({
+        kind: z
+          .literal("provider")
+          .describe(
+            "Replaced by calling the issuer, which returns the new value. The kit cannot invent this call; the capability or the adopter supplies it, and it changes state in somebody else's system.",
+          ),
+        issuer: issuedBy("Who is called."),
+        documentation: documentedAt(
+          "What the call does, for an operator deciding whether to trust it with a live credential.",
+        ).optional(),
+      })
+      .describe("Rotated by calling the issuer. The new value comes back from somebody else's system."),
+    z
+      .object({
+        kind: z
+          .literal("manual")
+          .describe(
+            "A human, in a console. No API returns the new value — a GitHub or Google OAuth client secret. This is a real answer, not a missing one.",
+          ),
+        issuer: issuedBy("Whose console."),
+        documentation: documentedAt("The page where it is done."),
+      })
+      .describe("Rotated by a human, in a console. A real answer, and the page is the whole help."),
+  ])
+  .describe(
+    "How this secret is replaced, declared separately from `origin` because neither follows from the other: a GitLab token is `obtained` and rotates by `provider`, while an OAuth client secret is `obtained` and rotates only by `manual`. Declared per secret, never per issuer — some Cloudflare secrets roll and some do not.",
+  );
+export type SecretRotation = z.output<typeof SecretRotation>;
+
+export const DeclaredSecret = z
+  .object({
+    name: z
+      .string()
+      .regex(SECRET_NAME)
+      .describe(
+        "The registry name the secret is declared under. Constrained, because a manifest is third-party data read from `node_modules` and this name reaches a rendered command.",
+      ),
+    origin: SecretOrigin.describe("How its value first comes to exist. Must match the registry entry's `origin`."),
+    rotation: SecretRotation.describe("How it is replaced. Must match the registry entry's `rotation`."),
+  })
+  .describe(
+    "One declared secret, as a manifest carries it: its registry name and both axes. Both, always — an origin without a rotation answers half of what an operator holding an overdue secret needs to know. The manifest's projection of the registry entry, and each capability's own tests assert the two agree.",
+  );
+export type DeclaredSecret = z.output<typeof DeclaredSecret>;

package/src/capability/settings.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { HostEnvReport } from "../workflow/hostEnv";
+import { hostEnvProviderSentence } 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 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.");
+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 function hostEnvFindings(report: HostEnvReport<unknown>, environment: string | null): SettingsFinding[] {
+  return report.problems.map((problem) => ({
+    setting: problem.field,
+    environment,
+    problem: problem.reason,
+    action: hostEnvProviderSentence(problem.provider),
+  }));
+}

package/src/capability/validateBindings.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "../error/pithyError";
+import { type BindingSpec, isProvisionedBinding } from "./bindings";
+
+/** How a missing binding is named in both halves of the error: `kv:SESSIONS`. */
+function label(binding: BindingSpec): string {
+  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: BindingSpec[]): string {
+  const written = missing.filter((binding) => !isProvisionedBinding(binding.type)).map(label);
+  const provisioned = missing.filter((binding) => isProvisionedBinding(binding.type)).map(label);
+  const sentences: string[] = [];
+  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`. */
+export function validateBindings(env: Record<string, unknown>, required: BindingSpec[]): void {
+  const missing = required.filter((b) => !b.optional && env[b.name] == null);
+  if (missing.length > 0) {
+    // A missing binding is a Worker misconfiguration, not a client-facing fault. The names are
+    // config keys, not secrets, so they ride in the public message; this surfaces at startup.
+    throw new InternalError({
+      message: `Missing required bindings: ${missing.map(label).join(", ")}`,
+      action: bindingAction(missing),
+    });
+  }
+}

package/src/capability/vanishingKey.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * 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.
+ */
+export function statesNoVanishingKey(value: unknown): boolean {
+  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.
+ */
+export function refusesVanishingKey<Output, Input>(
+  schema: z.ZodType<Output, Input>,
+  subject: string,
+): z.ZodPipe<z.ZodCustom<Input, Input>, z.ZodType<Output, Input>> {
+  return z
+    .custom<Input>(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.
+ */
+export function manifestRecord<Output, Input>(
+  record: z.ZodType<Output, Input>,
+): z.ZodPipe<z.ZodCustom<Input, Input>, z.ZodType<Output, Input>> {
+  return refusesVanishingKey(record, "A manifest record");
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`,
+// matching the Miniflare config in `vitest.workers.config.ts`: D1 `DB` and
+// `ANALYTICS` (a second database, to exercise the multi-database registry), KV
+// `SESSIONS`, and KV `CONTROL_PLANE` (the control-plane seam's replay set, which
+// gets its own namespace rather than sharing sessions).
+// `cloudflare:test` types its `env` as `Cloudflare.Env`, so the test bindings are
+// declared by augmenting that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    ANALYTICS: D1Database;
+    SESSIONS: KVNamespace;
+    CONTROL_PLANE: KVNamespace;
+  }
+}

package/src/controlPlane/audit/actions.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+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 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",
+} as const;
+
+/** 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 async function safeEmit(emit: AuditEmit, event: AuditEventInput, log?: Logger): Promise<void> {
+  try {
+    await emit(event);
+  } catch (error) {
+    log?.warn("control-plane audit event dropped", { action: event.action, error });
+  }
+}