@pithy-sh/core 0.1.2 → 0.1.4

package/dist/projection/asRead.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/**
+ * 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 declare 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 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 declare function asRead<T extends z.ZodType>(schema: T): AsRead<T>;
+//# sourceMappingURL=asRead.d.ts.map

package/dist/projection/asRead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asRead.d.ts","sourceRoot":"","sources":["../../src/projection/asRead.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,wUAC0S,CAAC;AA2HxU;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,GACvC,CAAC,CAAC,SAAS,GACX,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,GAClC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAChD,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,GAClC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAChD,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,GACjC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAC/C,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,GAChC,CAAC,CAAC,SAAS,CAAC;KAAG,CAAC,IAAI,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAAE,CAAC,GACzE,CAAC,CAAC;AAEd;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAEhE"}

package/dist/projection/asRead.js

@@ -0,0 +1,169 @@
+import { InternalError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/projection/asRead.ts
+/**
+* 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. */
+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.";
+/** Read a schema's internal def, tolerating both the `_zod.def` and `.def` shapes across Zod builds. */
+function defOf(schema) {
+	const internal = schema;
+	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 = /* @__PURE__ */ 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, kind) {
+	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) {
+	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(rebuilt, original) {
+	return original.description === void 0 ? rebuilt : rebuilt.describe(original.description);
+}
+/**
+* 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, path) {
+	const { type, catchall } = defOf(schema);
+	if (type === "enum") {
+		const said = schema.description;
+		return z.string().describe(said === void 0 ? TOLERATED_MEMBER : `${said} ${TOLERATED_MEMBER}`);
+	}
+	if (schema instanceof z.ZodNullable || schema instanceof z.ZodOptional) {
+		const inner = schema.unwrap();
+		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;
+		const read = readerOf(element, `${path}[]`);
+		if (read === element) return schema;
+		return describedLike(z.array(read), schema);
+	}
+	if (schema instanceof z.ZodObject) {
+		const shape = {};
+		let widened = false;
+		for (const [key, field] of Object.entries(schema.shape)) {
+			const original = field;
+			const read = readerOf(original, `${path}.${key}`);
+			shape[key] = read;
+			if (read !== original) widened = true;
+		}
+		if (!widened) return schema;
+		if (catchall !== void 0) throw unrebuildable(path);
+		return describedLike(z.object(shape), schema);
+	}
+	if (type !== void 0 && LEAF_TYPES.has(type)) return schema;
+	throw unreadable(path, type ?? "schema of no stated type");
+}
+/**
+* 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.
+*/
+function asRead(schema) {
+	return readerOf(schema, "response");
+}
+//#endregion
+export { TOLERATED_MEMBER, asRead };

package/dist/projection/published.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 declare function unpublishedIn(document: unknown, published: PublishedFacts): string[];
+/**
+ * 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 declare function leavesIn(document: unknown): JsonLeaf[];
+/**
+ * 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 declare function keysIn(document: unknown): string[];
+//# sourceMappingURL=published.d.ts.map

package/dist/projection/published.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"published.d.ts","sourceRoot":"","sources":["../../src/projection/published.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,wEAAwE;AACxE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAExD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,EAAE,CAMpF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,EAAE,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,EAAE,CAElD"}

package/dist/projection/published.js

@@ -0,0 +1,114 @@
+//#region src/projection/published.ts
+/**
+* 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.
+*/
+function unpublishedIn(document, published) {
+	const leaves = new Set(published.leaves);
+	const keys = new Set(published.keys);
+	const found = [];
+	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.
+*/
+function leavesIn(document) {
+	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}.
+*/
+function keysIn(document) {
+	return collectKeys(document, "");
+}
+function collectLeaves(value, path) {
+	const inside = descend(value, path);
+	if (inside === void 0) return [asLeaf(value, path)];
+	return inside.flatMap(({ nested, here }) => collectLeaves(nested, here));
+}
+function collectKeys(value, path) {
+	const inside = descend(value, path);
+	if (inside === void 0) return [];
+	return inside.flatMap(({ key, nested, here }) => (key === void 0 ? [] : [key]).concat(collectKeys(nested, here)));
+}
+function walk(value, path, leaves, keys, found) {
+	const inside = descend(value, path);
+	if (inside === void 0) {
+		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 !== void 0 && !keys.has(key)) found.push(`key ${JSON.stringify(key)} at ${here}`);
+		walk(nested, here, leaves, keys, found);
+	}
+}
+/**
+* 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, path) {
+	if (value === null || typeof value !== "object") return void 0;
+	const proto = 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: void 0,
+		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) {
+	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, path) {
+	if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return refuse(value, path);
+}
+function refuse(value, path) {
+	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) {
+	if (value === null || typeof value !== "object") return typeof value;
+	const named = value.constructor;
+	if (typeof named === "function" && named.name !== "") return named.name;
+	return "object";
+}
+function where(path) {
+	return path === "" ? "(root)" : path;
+}
+//#endregion
+export { keysIn, leavesIn, unpublishedIn };

package/dist/schema/describedness.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/**
+ * The children of one schema, by kind. **Throws for a kind this walk has never been taught** — a
+ * walker whose unknown case is silently empty cannot report the thing it exists to report.
+ *
+ * A `pipe` is stepped through; a **codec** is not. This gate reads the schema tree, so wrapping an
+ * object in a guard — `refusesVanishingKey`, and anything else that pipes into a schema — would turn
+ * an export it checks into an export it silently skips, and losing coverage as a side effect of adding
+ * a guard is the wrong direction. A codec is the §Zod exemption spelled as a type rather than as an
+ * accident: `z.codec` builds a `ZodCodec`, so the exemption names codec helpers and nothing else.
+ * Measured in #326 — stepping through codecs too reports seven fields whose union sides carry no
+ * description, every one of them a `SQLiteDate` or a `sqliteJson`.
+ */
+export declare function childSchemas(schema: z.ZodType, path: string): z.ZodType[];
+/**
+ * Whether a description sits anywhere in a field's transparent-wrapper chain.
+ *
+ * `.describe("…").optional()` puts it on the inner type and `.optional().describe("…")` puts it on the
+ * wrapper. Both are one described field. Only {@link TRANSPARENT} wrappers are followed — an `array`
+ * or a `pipe` describes something other than what it holds.
+ */
+export declare function describedInChain(schema: z.ZodType): boolean;
+/** What one walk found: the complaints, and how much it actually looked at. */
+export interface SchemaWalk {
+    /** One line per object, enum, union or field with no `.describe()` anywhere that documents it. */
+    missing: string[];
+    /** Every field of every object reached, so an empty walk is visible as an empty walk. */
+    fields: number;
+}
+/**
+ * Record any object/enum/union missing a `.describe()` — on the schema itself or on any of its
+ * fields — following every container Zod has. Codec-helper primitives are exempt (CLAUDE.md §Zod) and
+ * are not objects/enums/unions, so they are skipped.
+ *
+ * `described` carries a transparent wrapper's own description inward; see {@link TRANSPARENT}.
+ */
+export declare function collectMissing(schema: z.ZodType, path: string, walk: SchemaWalk, seen: Set<z.ZodType>, described?: boolean): void;
+/** One schema, walked. The entry point a unit test reaches for. */
+export declare function undescribed(schema: z.ZodType, path?: string): SchemaWalk;
+/** What a package-wide sweep found, including the size of the population it swept. */
+export interface ExportWalk extends SchemaWalk {
+    /** Modules the glob handed over. Zero is a broken pattern, not a clean package. */
+    modules: number;
+    /** Exports that resolved to a Zod schema. */
+    schemas: number;
+}
+/**
+ * Every exported Zod schema in a package, walked.
+ *
+ * Takes the result of `import.meta.glob([...], { eager: true })`. The counts come back with the
+ * findings **because a sweep that found nothing and a sweep that looked at nothing are the same green
+ * run otherwise** — the caller pins all three against literals of its own.
+ */
+export declare function undescribedExports(modules: Record<string, Record<string, unknown>>): ExportWalk;
+//# sourceMappingURL=describedness.d.ts.map

package/dist/schema/describedness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describedness.d.ts","sourceRoot":"","sources":["../../src/schema/describedness.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgGxB;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,CAsCzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAU3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,kGAAkG;IAClG,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EACpB,SAAS,UAAQ,GAChB,IAAI,CAsBN;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,SAAW,GAAG,UAAU,CAI1E;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAY/F"}