@pithy-sh/core 0.1.0

package/src/naming/resourceNames.ts

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError, ValidationError } from "../error/pithyError";
+import { workflowHostName, workflowScriptName } from "../workflow/naming";
+import { assertValidEnvironment, GLOBAL_SCOPE } from "./environment";
+import { type FeatureIdentity, type FeatureResourceKind, featureResourceName, featureWorkerName } from "./feature";
+import { NAMESPACE_LIMITS, type NamespaceLimit } from "./limits";
+import { assertValidProjectName, kebab, resourceName } from "./resource";
+
+/**
+ * Every Cloudflare name a project composes, behind one object — **the facade**.
+ *
+ * The free functions underneath are correct and stay exported, but they share one flaw: each takes a
+ * budget, so every call site decides for itself which limit applies. That is how one number, 63, ended
+ * up standing in for eight different namespaces. Here the budget is not an argument at all. You pick a
+ * *kind of thing* — a bucket, a KV namespace, a Workflow — and the kind carries its own cap and its own
+ * refuse-or-truncate policy from `./limits`. There is no wrong budget to pass, because there is no
+ * budget to pass.
+ *
+ * **Shape: project, then scope, then kind.**
+ *
+ * ```ts
+ * const names = resourceNames(config.name);   // the project, validated once
+ * const prod = names.env("prod");             // the environment, validated once
+ * prod.d1("DB");                              // acme-prod-db
+ * prod.workflow("email", "send");             // acme-prod-email-send
+ * names.global.secretEntry("secrets-manager-cf-api-token");
+ * names.feature({ issue, slug }).resource("DB", "d1");
+ * ```
+ *
+ * Three reasons for that order rather than a flat `worker(capability, env)`:
+ *
+ * 1. **Each thing is validated once, at the point it is named.** A bad project fails at
+ *    `resourceNames`, before a single name exists; a bad environment fails at `env`, not on the fourth
+ *    getter that happened to use it.
+ * 2. **The environment is threaded once, not through every call.** Commands are environment-scoped —
+ *    `pithy deploy --env prod` names a dozen resources in one environment — so binding it once removes a
+ *    dozen chances to pass the wrong one.
+ * 3. **`global` becomes a property, not a magic string.** It is the same interface as an environment
+ *    (`names.global.secretEntry(…)`), so no call site special-cases the literal, and no call site can
+ *    typo it into a real environment named `globl`.
+ *
+ * The feature shape hangs off the same object for the same reason it exists at all: it is the *other*
+ * scope a project's resources live in, and it shares the project segment with everything above.
+ */
+
+/** The names available within one scope — an environment, or the global scope beside them. */
+export interface ScopedNames {
+  /** A capability's Worker script — `<project>-<env>-<capability>`. Refused, not truncated, past 63. */
+  worker(capability: string): string;
+  /** One durable job's Workflow — `<project>-<env>-<capability>-<job>`. Refused, not truncated, past 64. */
+  workflow(capability: string, job: string): string;
+  /** A D1 database. No Cloudflare cap; Pithy's ceiling, truncated with a stable hash. */
+  d1(binding: string): string;
+  /** A KV namespace title. Cloudflare's 512, not the 63 this used to be held to. */
+  kv(binding: string): string;
+  /** An R2 bucket. Cloudflare's 63 — the one namespace where that number was always right. */
+  r2(binding: string): string;
+  /** A Vectorize index. 64 bytes, refused rather than truncated: a renamed index has no vectors. */
+  vectorizeIndex(index: string): string;
+  /** A Secrets Store entry. No Cloudflare cap; Pithy's ceiling. */
+  secretEntry(secret: string): string;
+  /** A Cloudflare API token label. No Cloudflare cap; Pithy's ceiling. */
+  apiToken(profile: string): string;
+}
+
+/** The names a feature environment provisions under, with the project already bound. */
+export interface FeatureNames {
+  /** A feature's D1, KV, or R2 resource — `<project>-f<issue>-<slug>-<binding>-<kind>`. */
+  resource(binding: string, kind: FeatureResourceKind): string;
+  /** A feature's Worker script — `<project>-f<issue>-<slug>-<worker>`. */
+  worker(worker: string): string;
+}
+
+/** Everything a project can be asked to name. Created once, from the project, by {@link resourceNames}. */
+export interface ProjectNames {
+  /** The kebabbed project name every name below leads with. */
+  readonly project: string;
+  /** The names in one environment. Throws if the environment is not one this scheme accepts. */
+  env(environment: string): ScopedNames;
+  /** The names shared by every environment — the `global` scope, without typing the word. */
+  readonly global: ScopedNames;
+  /** The names a feature environment provisions under. */
+  feature(identity: Omit<FeatureIdentity, "project">): FeatureNames;
+}
+
+/**
+ * Compose `<project>-<scope>-<thing>` under one namespace's rule.
+ *
+ * A `truncate` namespace hands off to {@link resourceName} with that namespace's cap, so there is still
+ * exactly one truncation rule. A `refuse` namespace composes verbatim and throws with the limit named —
+ * as an `InternalError`, because by this point the project and scope have both been validated, so an
+ * over-long name means author-controlled code asked for one.
+ *
+ * **The refuse branch here is deliberately not `../workflow/naming`'s**, though both compose
+ * `<project>-<scope>-<thing>` and both refuse rather than truncate. They answer different questions: a
+ * Workflow or Worker name is assembled from author-controlled capability and job identifiers, so that
+ * module *asserts* each segment against `NAME_SEGMENT` and measures the result in **bytes**, the
+ * unit Cloudflare states those two limits in. The kinds routed through here are named after a binding
+ * or a secret, which is an adopter's string, so it is kebabbed into shape instead. Merging the two would
+ * either start mangling a capability name or stop normalizing a binding.
+ */
+function scopedName(project: string, scope: string, thing: string, limit: NamespaceLimit): string {
+  if (limit.policy === "truncate") {
+    const name = resourceName({ project, env: scope, thing }, limit.maxLength);
+    if (name.length < limit.minLength) {
+      throw new InternalError({
+        message: `"${name}" is too short for ${limit.label}.`,
+        action: `Use a longer project, environment, or resource name — ${limit.label} needs ${limit.minLength} characters.`,
+      });
+    }
+    return name;
+  }
+
+  const segment = kebab(thing);
+  if (!segment) {
+    throw new ValidationError({
+      message: `A name needs something to name.`,
+      detail: `${limit.label} was asked for with an empty segment (raw: ${JSON.stringify(thing)}).`,
+    });
+  }
+  const name = `${kebab(project)}-${scope}-${segment}`;
+  if (name.length > limit.maxLength) {
+    throw new InternalError({
+      message: `"${name}" is ${name.length} characters. ${limit.label[0]?.toUpperCase()}${limit.label.slice(1)} stops at ${limit.maxLength}.`,
+      action: "Shorten the project, environment, or resource name.",
+      detail: `${limit.label} is refused rather than truncated — renaming it after a deploy orphans what it addresses.`,
+    });
+  }
+  return name;
+}
+
+/** The getters for one scope. `global` and every environment share this, so nothing special-cases either. */
+function scopedNames(project: string, scope: string): ScopedNames {
+  return {
+    worker: (capability) => workflowHostName({ project, capability, env: scope }),
+    workflow: (capability, job) => workflowScriptName({ project, capability, job, env: scope }),
+    d1: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.d1),
+    kv: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.kv),
+    r2: (binding) => scopedName(project, scope, binding, NAMESPACE_LIMITS.r2),
+    vectorizeIndex: (index) => scopedName(project, scope, index, NAMESPACE_LIMITS.vectorizeIndex),
+    secretEntry: (secret) => scopedName(project, scope, secret, NAMESPACE_LIMITS.secretEntry),
+    apiToken: (profile) => scopedName(project, scope, profile, NAMESPACE_LIMITS.apiToken),
+  };
+}
+
+/**
+ * Bind a project to every name it can compose.
+ *
+ * The project is validated here — charset *and* length, the one project rule — so a project that cannot
+ * carry every namespace fails before it has provisioned any of them. That is the whole reason the
+ * project is supplied once instead of per call.
+ */
+export function resourceNames(project: string): ProjectNames {
+  assertValidProjectName(project);
+  const normalized = kebab(project);
+
+  return {
+    project: normalized,
+    env(environment: string): ScopedNames {
+      assertValidEnvironment(environment);
+      return scopedNames(normalized, environment);
+    },
+    global: scopedNames(normalized, GLOBAL_SCOPE),
+    feature(identity): FeatureNames {
+      const full: FeatureIdentity = { ...identity, project: normalized };
+      return {
+        resource: (binding, kind) => featureResourceName(full, binding, kind),
+        worker: (worker) => featureWorkerName(full, worker),
+      };
+    },
+  };
+}

package/src/naming/segment.ts

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a single segment of a composed name may look like — one pattern, one home.
+ *
+ * `<project>-<env>-<thing>` is built out of segments, and every one of them answers to the same
+ * shape: a project, an environment, a capability, a job. The pattern lived in three modules,
+ * character for character, which is the arrangement where a rule stops being one rule — an edit to
+ * the environment copy would silently leave the Workflow copy behind, and the two would disagree
+ * about a name the other had already accepted.
+ *
+ * A capability that genuinely needs a different rule should declare its own pattern beside this one
+ * with a comment saying what it allows that this does not, and why. Divergence is a decision, not a
+ * stale copy. `scaffoldProject`'s `WORKER_NAME` is the standing example: a Worker *directory* under
+ * `apps/` may lead with a digit, because it is a package name rather than a Cloudflare name.
+ */
+
+/**
+ * A lowercase letter, then letters, digits, and single inner hyphens — no leading digit, no
+ * doubled or trailing hyphen, no underscore, no uppercase.
+ *
+ * This is the **strictest** rule of any namespace a name reaches, and therefore the rule for all of
+ * them. Cloudflare Worker script names, Workflow names, and Vectorize indexes must start with a
+ * letter; D1, KV, and R2 would take `1password-clone-dev-db` happily. The loose namespaces are the
+ * ones a project touches first, so holding everything to the strict rule is what keeps a name that
+ * provisions from being a name that cannot deploy.
+ *
+ * Not `/g`: `.test()` on a global regex advances `lastIndex`, and one shared instance would answer
+ * differently on alternate calls. `segment.test.ts` pins that.
+ */
+export const NAME_SEGMENT = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;

package/src/projection/asRead.ts

@@ -0,0 +1,211 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { InternalError } from "../error/pithyError";
+
+/**
+ * The reader's contract: a capability's own response object, restated for a client that does not
+ * control the Worker that wrote the response.
+ *
+ * ## One schema, two consumers, two obligations
+ *
+ * A capability states each projection once, in its `http/responses.ts`, and both consumers validate
+ * against it — the Worker's own tests and every management client. That is right for the fields and
+ * wrong for the enums, because the two consumers are answering different questions.
+ *
+ * A **Worker validating its own projection is checking itself.** It must be strict: an enum there is
+ * what the ingest path branches on and what D1 holds, and a tolerated-unknown member would license the
+ * capability to *store* a value it cannot handle. Nothing here loosens that, and nothing here should:
+ * the producer's enums are untouched, and this module never sees them at parse time.
+ *
+ * A **management client reading that response is crossing a trust boundary.** The system that wrote it
+ * is a fork, a bug, a half-finished deploy, or hostile — none of which is downstream of how anybody's
+ * releases are cut — and one member it has never heard of currently costs it the whole response rather
+ * than the one row that carried it. A support console rendered zero of twenty-five conversations that
+ * way (`pithy-sh/dashboard#15`), and the client that fixed it had to widen the kit's shape locally,
+ * which is the mirror-of-a-projection that `#113` exists to forbid.
+ *
+ * So the tolerance is published **beside** the producer's shape rather than inside it. `asRead(X)` is
+ * the whole pattern: the same object, with every enum reachable through it read as a string.
+ *
+ * ## What it is not
+ *
+ * **It is not a loosening.** A missing field, a number where a string belongs, a value outside a
+ * numeric bound, a body that is not an object — all still refuse the whole response, exactly as before.
+ * The only thing that changes is which *members* an enum-shaped field admits.
+ *
+ * **It is not a mapping.** The token is handed back verbatim. The enum stays the authority on what a
+ * value means — `SupportChannel.safeParse(value).success` is the question, and the answer is the
+ * client's license to *mark* the row. Reading an unrecognized value as the nearest one you know is a
+ * lie about a fact somebody is about to act on, and this pattern exists to make marking cheap enough
+ * that nobody reaches for mapping.
+ *
+ * **It is not selective.** A reader's obligation does not vary field by field: it does not control the
+ * writer, so *any* unknown member costs it the response. Widening two enums and leaving a third is how
+ * the same blank pane returns one field over.
+ *
+ * ## What it refuses to do
+ *
+ * It rewrites what it can see through — objects, arrays, `nullable`, `optional` — and returns anything
+ * with no enum under it as the **identical schema instance**, so a reader's view and its producer share
+ * every untouched field rather than copying it. Everything else throws at construction:
+ * {@link asRead} either produces a view with no enum left in it or refuses to produce one, because a
+ * shape that silently passed a union through would publish a "reader's contract" that still refuses an
+ * unknown member — the original defect, wearing a name that says it was handled.
+ */
+
+/** What a widened field says about itself, appended to the description the enum already carried. */
+export const TOLERATED_MEMBER =
+  "Read as a string rather than as the enum it comes from: a client does not control the Worker that wrote this, so a member the enum does not declare is handed back verbatim instead of refusing the whole response. Ask the enum what a value means, mark what it does not declare, and never map it to the nearest value you know.";
+
+/** The internal shape this module reads. Zod's own `def`, under either of the two spellings it has had. */
+interface ZodDef {
+  /** The type tag — `object`, `array`, `enum`, `nullable`, and the rest. */
+  type?: string;
+  /** An object's unknown-key rule, set by `.strict()` and `.loose()` and absent on a plain object. */
+  catchall?: z.ZodType;
+}
+
+/** Read a schema's internal def, tolerating both the `_zod.def` and `.def` shapes across Zod builds. */
+function defOf(schema: z.ZodType): ZodDef {
+  const internal = schema as unknown as { _zod?: { def?: ZodDef }; def?: ZodDef };
+  return internal._zod?.def ?? internal.def ?? {};
+}
+
+/**
+ * The type tags that hold no other schema, so nothing inside one can be an enum.
+ *
+ * **Written out, never derived.** A permitted set computed from what the walk happens to handle would
+ * grant an exemption to every kind somebody adds later, silently, which is the failure this roster is
+ * here to prevent. A tag not on this list and not rewritten below is refused.
+ *
+ * `literal` is on it deliberately. A literal is not a vocabulary a capability might extend — it is how
+ * a discriminated union tells its arms apart, and widening one would destroy the union rather than
+ * tolerate anything.
+ */
+const LEAF_TYPES: ReadonlySet<string> = new Set([
+  "string",
+  "number",
+  "int",
+  "bigint",
+  "boolean",
+  "date",
+  "literal",
+  "template_literal",
+  "file",
+  "symbol",
+  "null",
+  "undefined",
+  "void",
+  "any",
+  "unknown",
+  "never",
+  "nan",
+]);
+
+/**
+ * The refusal, with the offending schema's *path* in it and never a value.
+ *
+ * Thrown while a module is being evaluated, which is exactly where it belongs: a reader's contract is
+ * built once at import, so a capability that cannot state one finds out in its own test run rather
+ * than in front of a client.
+ */
+function unreadable(path: string, kind: string): InternalError {
+  return new InternalError({
+    message: "This projection has no reader's contract.",
+    action: `State the reader's view of ${path} by hand, or reshape it so \`asRead\` can see through it.`,
+    detail: `asRead met a \`${kind}\` at ${path}. It rewrites objects, arrays, nullable and optional wrappers, and refuses anything else rather than return a view that may still hold an enum a reader cannot survive.`,
+  });
+}
+
+/** The refusal for an object whose unknown-key rule a rebuild would change. */
+function unrebuildable(path: string): InternalError {
+  return new InternalError({
+    message: "This projection has no reader's contract.",
+    action: `Drop the unknown-key rule on ${path}, or state its reader's view by hand.`,
+    detail: `asRead met an object at ${path} that both holds an enum and declares its own unknown-key rule. Rebuilding it would silently change what it refuses, so it refuses to guess.`,
+  });
+}
+
+/** A rebuilt schema wearing the description the original carried. Nothing is described twice. */
+function describedLike<T extends z.ZodType>(rebuilt: T, original: z.ZodType): T {
+  return original.description === undefined ? rebuilt : (rebuilt.describe(original.description) as T);
+}
+
+/**
+ * One node of the rewrite. Returns the identical instance when nothing under it is an enum.
+ *
+ * The identity is not an optimization. It is what keeps a reader's view from becoming a second opinion
+ * about the fields it did not widen: a field it shares with the producer is the *same object*, so a
+ * change upstream lands in both, and a client can assert that field by field.
+ */
+function readerOf(schema: z.ZodType, path: string): z.ZodType {
+  const { type, catchall } = defOf(schema);
+
+  if (type === "enum") {
+    const said = schema.description;
+    return z.string().describe(said === undefined ? TOLERATED_MEMBER : `${said} ${TOLERATED_MEMBER}`);
+  }
+
+  if (schema instanceof z.ZodNullable || schema instanceof z.ZodOptional) {
+    const inner = schema.unwrap() as z.ZodType;
+    const read = readerOf(inner, path);
+    if (read === inner) return schema;
+    return describedLike(schema instanceof z.ZodNullable ? z.nullable(read) : z.optional(read), schema);
+  }
+
+  if (schema instanceof z.ZodArray) {
+    const element = schema.element as z.ZodType;
+    const read = readerOf(element, `${path}[]`);
+    if (read === element) return schema;
+    return describedLike(z.array(read), schema);
+  }
+
+  if (schema instanceof z.ZodObject) {
+    const shape: Record<string, z.ZodType> = {};
+    let widened = false;
+    for (const [key, field] of Object.entries(schema.shape)) {
+      const original = field as z.ZodType;
+      const read = readerOf(original, `${path}.${key}`);
+      shape[key] = read;
+      if (read !== original) widened = true;
+    }
+    if (!widened) return schema;
+    if (catchall !== undefined) throw unrebuildable(path);
+    return describedLike(z.object(shape), schema);
+  }
+
+  if (type !== undefined && LEAF_TYPES.has(type)) return schema;
+  throw unreadable(path, type ?? "schema of no stated type");
+}
+
+/**
+ * The producer's schema with every enum under it read as a string.
+ *
+ * Enum in, string out; a wrapper keeps its own description and the widened member carries the enum's,
+ * with {@link TOLERATED_MEMBER} appended so the schema still documents itself. Everything else is the
+ * schema the capability declared, by identity.
+ */
+export type AsRead<T> = T extends z.ZodEnum
+  ? z.ZodString
+  : T extends z.ZodNullable<infer Inner>
+    ? z.ZodNullable<Extract<AsRead<Inner>, z.ZodType>>
+    : T extends z.ZodOptional<infer Inner>
+      ? z.ZodOptional<Extract<AsRead<Inner>, z.ZodType>>
+      : T extends z.ZodArray<infer Element>
+        ? z.ZodArray<Extract<AsRead<Element>, z.ZodType>>
+        : T extends z.ZodObject<infer Shape>
+          ? z.ZodObject<{ [K in keyof Shape]: Extract<AsRead<Shape[K]>, z.ZodType> }>
+          : T;
+
+/**
+ * A capability's response object, as a client that does not control the writer must read it.
+ *
+ * Export the result beside the producer's schema — `XAsRead` beside `X` — so a client imports tolerance
+ * rather than building it. Throws if the projection holds a shape this cannot see through; see the
+ * module docstring for why that is a refusal rather than a pass-through.
+ */
+export function asRead<T extends z.ZodType>(schema: T): AsRead<T> {
+  return readerOf(schema, "response") as unknown as AsRead<T>;
+}

package/src/projection/published.ts

@@ -0,0 +1,210 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The gate primitive for a projection that crosses a trust boundary: **nothing left this surface but the
+ * facts it publishes.**
+ *
+ * Every such gate in this kit was first written as its negative — a list of strings that must not appear
+ * in the response. A negative list is complete only against the values somebody thought of, and a
+ * projection widens by gaining a *field*, which is exactly the event a value list cannot observe. The
+ * same argument has been lost here three times over: a tripwire banning `access` while `stat` followed
+ * links identically, an escape class that arrived as three different verbs, and a bundle sweep seeded
+ * with the credential shapes of the day.
+ *
+ * So the rule is stated positively and computed rather than enumerated. Two halves, and **both are
+ * required, because either alone lets the mistake through**:
+ *
+ * 1. **Every leaf must be a published fact.** This is what catches a forbidden value arriving under a
+ *    field name nobody predicted.
+ * 2. **Every key must be a published key.** This is what catches a leaf whose *type* has no vocabulary —
+ *    `true`, `false` and `null` belong to every JSON document, so the first half can never police them,
+ *    and a new `boolean` field is the cheapest way to widen a projection.
+ *
+ * ## Two rules for the caller, and both were paid for
+ *
+ * **Write the permitted key set out by hand.** Deriving it from `Object.keys(Schema.shape)` makes the
+ * gate read its own subject: the edit that widens the schema widens the permission, in the same commit,
+ * and the test whose entire job is to catch that passes. That happened, on the catalog read.
+ *
+ * **Seed the source with something forbidden of every JSON type.** A sweep over a document that never
+ * held anything secret passes perfectly and proves nothing. The leaf walk below once returned `[]` for
+ * every type that was not a string or a number, so booleans and nulls crossed untouched — nothing
+ * forbidden happened to be a boolean that day, which is what kept it from being a live leak, not what
+ * made it safe.
+ *
+ * ## Why it throws
+ *
+ * A value this walk cannot name is a silent exemption for a whole JSON type, granted by a fallthrough.
+ * That is the defect above, restated. So {@link unpublishedIn} refuses the document instead: a value the
+ * caller hands it must be an array, a plain object, or a JSON leaf, and anything else means a live
+ * JavaScript object rather than what a client receives. Round-trip through
+ * `JSON.parse(JSON.stringify(...))` first: that is what crosses, and what crosses is what a gate is about.
+ *
+ * **The rule is what the walk can *see*, not a list of types it distrusts.** `typeof` answers "object"
+ * for a `Date`, a `Map`, a `Set` and every class instance, and each of those descends to no keys and no
+ * leaves — a `Map`'s entries are not own properties and a getter lives on the prototype — so the descent
+ * itself was handing out the same exemption through the one branch that looked safe. So a container is
+ * one whose whole contents `Object.entries` returns: prototype `Object.prototype`, `Array.prototype`, or
+ * `null`. The first two are what `JSON.parse` produces and the third holds nothing anywhere else to
+ * find. Naming the unnameable types instead would be the enumeration this module exists to refuse, and
+ * the next class nobody thought of would walk straight through.
+ *
+ * **And `Object.entries` is then what descends, arrays included.** The rule above was stated once and only
+ * half run: the array branch still walked by position, so an own property on a plain array — a prototype
+ * this walk accepts, nothing to refuse — was contents the walk could not see. A rule the code disagrees
+ * with is a rule in a comment.
+ */
+
+/** Anything a JSON document holds that is not an object or an array. */
+export type JsonLeaf = string | number | boolean | null;
+
+/**
+ * What one surface is allowed to publish: the facts, and the field names they may sit under.
+ *
+ * `keys` is a literal written at the call site. Never `Object.keys` of the schema being policed — see
+ * the note above.
+ */
+export interface PublishedFacts {
+  /** Every value this surface may disclose, from wherever it legitimately came. */
+  readonly leaves: Iterable<JsonLeaf>;
+  /** Every object key this surface may carry, at any depth. Written out by hand. */
+  readonly keys: Iterable<string>;
+}
+
+/**
+ * Everything in `document` that {@link PublishedFacts} does not permit, as lines naming what and where.
+ *
+ * Empty means the projection published only what it declared. A non-empty result is the message: each
+ * line carries the offending key or value and its JSON path, so a failure says which field widened
+ * rather than that some string was present.
+ *
+ * @param document A JSON document — what a client actually receives, not a live object.
+ * @param published The facts and keys this surface declares.
+ * @throws If `document` holds a value JSON cannot express.
+ */
+export function unpublishedIn(document: unknown, published: PublishedFacts): string[] {
+  const leaves = new Set<JsonLeaf>(published.leaves);
+  const keys = new Set<string>(published.keys);
+  const found: string[] = [];
+  walk(document, "", leaves, keys, found);
+  return found;
+}
+
+/**
+ * Every leaf in a JSON document, wherever it sits, of every JSON type. Object keys are collected separately.
+ *
+ * @throws If `document` holds a value JSON cannot express, on the same terms as {@link unpublishedIn} —
+ * a caller builds its declaration from this, and a value walked to nothing becomes a permitted set that
+ * omits a field.
+ */
+export function leavesIn(document: unknown): JsonLeaf[] {
+  return collectLeaves(document, "");
+}
+
+/**
+ * Every object key in a JSON document, wherever it sits.
+ *
+ * @throws If `document` holds a value JSON cannot express, on the same terms as {@link unpublishedIn}.
+ */
+export function keysIn(document: unknown): string[] {
+  return collectKeys(document, "");
+}
+
+function collectLeaves(value: unknown, path: string): JsonLeaf[] {
+  const inside = descend(value, path);
+  if (inside === undefined) return [asLeaf(value, path)];
+  return inside.flatMap(({ nested, here }) => collectLeaves(nested, here));
+}
+
+function collectKeys(value: unknown, path: string): string[] {
+  const inside = descend(value, path);
+  if (inside === undefined) return [];
+  return inside.flatMap(({ key, nested, here }) => (key === undefined ? [] : [key]).concat(collectKeys(nested, here)));
+}
+
+function walk(
+  value: unknown,
+  path: string,
+  leaves: ReadonlySet<JsonLeaf>,
+  keys: ReadonlySet<string>,
+  found: string[],
+): void {
+  const inside = descend(value, path);
+  if (inside === undefined) {
+    const leaf = asLeaf(value, path);
+    if (!leaves.has(leaf)) found.push(`value ${JSON.stringify(leaf)} at ${where(path)}`);
+    return;
+  }
+  for (const { key, nested, here } of inside) {
+    if (key !== undefined && !keys.has(key)) found.push(`key ${JSON.stringify(key)} at ${here}`);
+    walk(nested, here, leaves, keys, found);
+  }
+}
+
+/** One step into a container: the object key if it has one, the value there, and the path to say where. */
+interface Step {
+  /** The object key, or `undefined` for an array element, which is a position rather than a name. */
+  readonly key: string | undefined;
+  readonly nested: unknown;
+  readonly here: string;
+}
+
+/**
+ * The contents of a container, or `undefined` for a leaf — and a refusal for anything else.
+ *
+ * This is the single place the walk decides what it can see, so the gate, {@link leavesIn} and
+ * {@link keysIn} all descend on identical terms. A value is a container only if its prototype is one
+ * `JSON.parse` produces; a `Date`, a `Map`, a `Set` or a class instance answers `"object"` to `typeof`
+ * and yields nothing to `Object.entries`, and treating that as an empty container is the exemption this
+ * module exists to refuse.
+ *
+ * So **`Object.entries` is what descends, arrays included**. An array walked by `value.map` is walked by
+ * position, and a position is not the whole of what an array holds: `rows.cursor = "…"` is an own property
+ * on a prototype this walk accepts, and the index walk went straight past it. The rule the module states and
+ * the code it runs have to be the same rule, or the exemption comes back through whichever branch still
+ * disagrees. An index key stays a position — reported as `[0]`, never as a key a caller must permit — and
+ * every other own key is a key.
+ */
+function descend(value: unknown, path: string): Step[] | undefined {
+  if (value === null || typeof value !== "object") return undefined;
+  const proto: unknown = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== Array.prototype && proto !== null) refuse(value, path);
+  const array = Array.isArray(value);
+  return Object.entries(value).map(([key, nested]) =>
+    array && isIndex(key)
+      ? { key: undefined, nested, here: `${path}[${key}]` }
+      : { key, nested, here: path === "" ? key : `${path}.${key}` },
+  );
+}
+
+/** Whether an own key of an array is one of its positions — the canonical decimal form `Object.entries` gives. */
+function isIndex(key: string): boolean {
+  return /^(?:0|[1-9]\d*)$/.test(key);
+}
+
+/** Narrow to a JSON leaf, or refuse the document. A type this walk cannot name is not a type it may skip. */
+function asLeaf(value: unknown, path: string): JsonLeaf {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  return refuse(value, path);
+}
+
+function refuse(value: unknown, path: string): never {
+  throw new Error(
+    `A ${nameOf(value)} sits at ${where(path)}. JSON cannot express it, so this is a live object rather than what a client receives — round-trip it through JSON first.`,
+  );
+}
+
+/** What to call the thing in the refusal — its class where it has one, so the message names what was found. */
+function nameOf(value: unknown): string {
+  if (value === null || typeof value !== "object") return typeof value;
+  const named: unknown = (value as { constructor?: unknown }).constructor;
+  if (typeof named === "function" && named.name !== "") return named.name;
+  return "object";
+}
+
+function where(path: string): string {
+  return path === "" ? "(root)" : path;
+}