@pithy-sh/core 0.1.1 → 0.1.3

package/dist/i18n/registry.js

@@ -0,0 +1,51 @@
+import { messageDomain } from "./catalog.js";
+import { ValidationError } from "../error/pithyError.js";
+import "./translator.js";
+//#region src/i18n/registry.ts
+/**
+* Every composed capability's `messages`, merged into one set of catalogs keyed by locale.
+*
+* **A capability may only declare keys under its own domain**, and the merge refuses anything else.
+* That is the same rule as `pithy_<capability>_<table>` and `auth/invalid_token`, enforced for the same
+* reason: the domain segment is what makes two capabilities' contributions incapable of colliding, so
+* merge order stops being a thing anyone has to reason about. It applies to the adopter's own `app`
+* capability exactly as it applies to a kit package — `board/nav.settings` is theirs to declare, and
+* `auth/sign_in.title` is not.
+*
+* Library-before-app, like the migration registry: capabilities are merged in composition order, so a
+* later contribution wins a key an earlier one wrote. With the domain rule in force that can only
+* happen between two capabilities sharing a name, which `createBackend` already refuses.
+*/
+function composeMessages(capabilities) {
+	const contributions = [];
+	for (const capability of capabilities) if (capability.messages) contributions.push({
+		capability: capability.name,
+		catalogs: capability.messages
+	});
+	const merged = /* @__PURE__ */ new Map();
+	for (const { capability, catalogs } of contributions) for (const [locale, catalog] of Object.entries(catalogs)) {
+		const target = merged.get(locale) ?? /* @__PURE__ */ new Map();
+		for (const [key, message] of Object.entries(catalog)) {
+			const domain = messageDomain(key);
+			if (domain !== capability) throw new ValidationError({
+				message: "A capability may only contribute messages under its own domain.",
+				action: `Rename \`${key}\` to start with \`${capability}/\`, or move it to the capability that owns that domain.`,
+				detail: `\`${capability}\` contributed \`${key}\` in locale \`${locale}\`, whose domain is \`${domain}\`.`
+			});
+			target.set(key, message);
+		}
+		merged.set(locale, target);
+	}
+	return Object.fromEntries([...merged].map(([locale, catalog]) => [locale, Object.fromEntries(catalog)]));
+}
+/**
+* The catalog for `locale`, or the default locale's, or an empty one.
+*
+* The fallback that makes the seam optional: a Worker composing no i18n capability reads the baked
+* English and behaves byte for byte as it did before any of this landed.
+*/
+function catalogFor(catalogs, locale) {
+	return catalogs[locale] ?? catalogs["en"] ?? {};
+}
+//#endregion
+export { catalogFor, composeMessages };

package/dist/i18n/translator.d.ts

@@ -0,0 +1,107 @@
+import { type MessageCatalog, type MessageParams } from "./catalog";
+import { type TextDirection } from "./locale";
+/**
+ * The i18n seam. `@pithy-sh/core` defines this shape; `@pithy-sh/i18n` populates it from the resolved
+ * request locale. Every other capability, and every screen, depends only on this object — the same
+ * split `AuthContext` uses, and for the same reason: `@pithy-sh/email` and the error module both need
+ * a locale and neither may import an i18n capability.
+ *
+ * **The two locales are both here, as plain strings.** An adopter who already owns their date and
+ * number rendering needs the locale as a *value* to hand to `Intl`; forcing it through
+ * {@link Translator.formatDate} turns a one-line repair into an every-call-site one, against gates that
+ * exist to keep those calls in one place.
+ */
+export interface Translator {
+    /**
+     * The locale whose catalog answers {@link Translator.t} — the words the kit actually has.
+     *
+     * An `es-AR` reader gets `es` here, because `es` is what is written. See
+     * {@link Translator.formattingLocale} for the half that does not fall back.
+     */
+    readonly catalogLocale: string;
+    /**
+     * The locale handed to `Intl` — what the reader asked for, region and all.
+     *
+     * An `es-AR` reader gets `es-AR` here, which `Intl` supports natively whether or not anyone wrote a
+     * string for it. Collapsing this into {@link Translator.catalogLocale} is the bug where an Argentine
+     * reads Spanish and sees `1,234.56`.
+     */
+    readonly formattingLocale: string;
+    /** The catalog locale's text direction — what `lang`/`dir` on the document and the email shell get. */
+    readonly direction: TextDirection;
+    /**
+     * The message `key` names, with `{placeholder}` substitution.
+     *
+     * Returns the key itself when nothing has it. That is the honest answer — a blank reads like finished
+     * copy — and it is unreachable for a kit key, because catalog coverage is a CI gate.
+     */
+    t(key: string, params?: MessageParams): string;
+    /**
+     * The message `key` names, or `null` when no layer has it.
+     *
+     * **The half {@link Translator.t} cannot express, and the error path needs.** `t` is total because a
+     * screen always has to render something, so a miss comes back as the key — which is the honest thing
+     * to show and is unusable as a signal. An error is the other case: the payload already carries an
+     * English `message`, and a client that could not translate the code must render *that*, not the code.
+     *
+     * So the documented client contract is `t.maybe(payload.code, payload.params) ?? payload.message`.
+     * Written against `t` it silently never falls back — `t` returns the key, `??` sees a string, and a
+     * caller in an uncovered locale reads `auth/invalid_token` on their screen instead of the sentence
+     * the server took care to send them.
+     */
+    maybe(key: string, params?: MessageParams): string | null;
+    /**
+     * The message `key` names, in the plural form `count` calls for.
+     *
+     * Looks up `<key>.<category>` for the `Intl.PluralRules` category of `count` in the catalog locale,
+     * falling back to `<key>.other`. `count` is available to the message as `{count}` without being
+     * passed twice.
+     *
+     * Explicit rather than folded into {@link Translator.t}, because plural selection is the thing a
+     * second locale exposes: English has two forms, Spanish has two, Russian has three, and a call site
+     * that concatenated a number onto a noun has no form at all.
+     */
+    plural(key: string, count: number, params?: MessageParams): string;
+    /** `value` as a number in the formatting locale. */
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    /** `value` as an amount of `currency` in the formatting locale. */
+    formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
+    /** `value` as a date in the formatting locale. Accepts a `Date` or an epoch-milliseconds number. */
+    formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+    /** `values` as a list in the formatting locale — `a, b y c` in Spanish, `a, b, and c` in English. */
+    formatList(values: readonly string[], options?: Intl.ListFormatOptions): string;
+    /** `value` `unit`s from now, in the formatting locale — `ayer`, `in 3 days`. */
+    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+}
+/** What a translator is built from: the locales it answers in, and the layers it looks messages up through. */
+export interface TranslatorInput {
+    /** The locale whose catalog answers `t()`. */
+    readonly catalogLocale: string;
+    /** The locale handed to `Intl`; defaults to {@link TranslatorInput.catalogLocale}. */
+    readonly formattingLocale?: string;
+    /**
+     * The catalogs to walk, most-specific first. `@pithy-sh/i18n` passes adopter-locale, adopter-default,
+     * kit-locale, kit-default; a copied screen passes its own baked English and nothing else.
+     */
+    readonly layers: readonly (MessageCatalog | undefined)[];
+}
+/**
+ * A translator over `layers`.
+ *
+ * The `Intl` formatters are constructed lazily and held for the life of the translator. A translator is
+ * per request (or per mounted screen), so nothing here outlives a locale — which is the whole reason
+ * `z.config()` is banned repo-wide and a per-request global is not an option.
+ */
+export declare function createTranslator(input: TranslatorInput): Translator;
+/** The locale a project falls back to when nothing else answers, and the locale the kit writes in. */
+export declare const DEFAULT_LOCALE = "en";
+/**
+ * A translator over one baked catalog — **the seam's behavior when `@pithy-sh/i18n` is not composed.**
+ *
+ * This is what makes the capability optional. A project that never composes `i18n` renders the baked
+ * English fallback, byte for byte as it does today, with no negotiation, no merge and no config. A
+ * copied screen builds one from the English it was scaffolded with, which is the only catalog that
+ * survives being copied into an adopter's repository.
+ */
+export declare function bakedTranslator(catalog: MessageCatalog, locale?: string): Translator;
+//# sourceMappingURL=translator.d.ts.map

package/dist/i18n/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../src/i18n/translator.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8B,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAChG,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uGAAuG;IACvG,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;;;;;OAKG;IACH,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAC/C;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IACnE,oDAAoD;IACpD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC;IACxE,mEAAmE;IACnE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC;IAC5F,oGAAoG;IACpG,UAAU,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,GAAG,MAAM,CAAC;IAC/E,qGAAqG;IACrG,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,GAAG,MAAM,CAAC;IAChF,gFAAgF;IAChF,kBAAkB,CAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,CAAC,sBAAsB,EACjC,OAAO,CAAC,EAAE,IAAI,CAAC,yBAAyB,GACvC,MAAM,CAAC;CACX;AAED,+GAA+G;AAC/G,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,CAgDnE;AAED,sGAAsG;AACtG,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,GAAE,MAAuB,GAAG,UAAU,CAEpG"}

package/dist/i18n/translator.js

@@ -0,0 +1,80 @@
+import { localeDirection } from "./locale.js";
+import { interpolate, lookupMessage } from "./catalog.js";
+//#region src/i18n/translator.ts
+/**
+* A translator over `layers`.
+*
+* The `Intl` formatters are constructed lazily and held for the life of the translator. A translator is
+* per request (or per mounted screen), so nothing here outlives a locale — which is the whole reason
+* `z.config()` is banned repo-wide and a per-request global is not an option.
+*/
+function createTranslator(input) {
+	const catalogLocale = input.catalogLocale;
+	const formattingLocale = input.formattingLocale ?? catalogLocale;
+	const layers = input.layers;
+	let plurals;
+	const pluralRules = () => {
+		plurals ??= new Intl.PluralRules(catalogLocale);
+		return plurals;
+	};
+	const maybe = (key, params) => {
+		const message = lookupMessage(layers, key);
+		return message === null ? null : interpolate(message, params);
+	};
+	const translate = (key, params) => maybe(key, params) ?? key;
+	return {
+		catalogLocale,
+		formattingLocale,
+		direction: localeDirection(catalogLocale),
+		t: translate,
+		maybe,
+		plural(key, count, params) {
+			const category = pluralRules().select(count);
+			const withCount = {
+				count,
+				...params
+			};
+			const exact = lookupMessage(layers, `${key}.${category}`);
+			if (exact !== null) return interpolate(exact, withCount);
+			const other = lookupMessage(layers, `${key}.other`);
+			return other === null ? key : interpolate(other, withCount);
+		},
+		formatNumber(value, options) {
+			return new Intl.NumberFormat(formattingLocale, options).format(value);
+		},
+		formatCurrency(value, currency, options) {
+			return new Intl.NumberFormat(formattingLocale, {
+				...options,
+				style: "currency",
+				currency
+			}).format(value);
+		},
+		formatDate(value, options) {
+			return new Intl.DateTimeFormat(formattingLocale, options).format(value);
+		},
+		formatList(values, options) {
+			return new Intl.ListFormat(formattingLocale, options).format(values);
+		},
+		formatRelativeTime(value, unit, options) {
+			return new Intl.RelativeTimeFormat(formattingLocale, options).format(value, unit);
+		}
+	};
+}
+/** The locale a project falls back to when nothing else answers, and the locale the kit writes in. */
+const DEFAULT_LOCALE = "en";
+/**
+* A translator over one baked catalog — **the seam's behavior when `@pithy-sh/i18n` is not composed.**
+*
+* This is what makes the capability optional. A project that never composes `i18n` renders the baked
+* English fallback, byte for byte as it does today, with no negotiation, no merge and no config. A
+* copied screen builds one from the English it was scaffolded with, which is the only catalog that
+* survives being copied into an adopter's repository.
+*/
+function bakedTranslator(catalog, locale = "en") {
+	return createTranslator({
+		catalogLocale: locale,
+		layers: [catalog]
+	});
+}
+//#endregion
+export { DEFAULT_LOCALE, bakedTranslator, createTranslator };

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `pithy add controlplane` surface — **not a barrel over `@pithy-sh/core`.**
+ *
+ * `pithy add` writes `import { <name> } from "<package>/src/index";` into a Worker's `pithy.config.ts`,
+ * so a capability has to be reachable at its package's `src/index`. Core ships one capability — the
+ * `control-plane` seam — and this file exists to name it and nothing else.
+ *
+ * Everything else in core stays deep-imported (`@pithy-sh/core/src/error/pithyError`,
+ * `@pithy-sh/core/src/data/codecs`), which is the rule and which nothing here relaxes. The exports
+ * below are the ones an adopter's own code plausibly touches: the factory their config calls, the
+ * config schema behind it, the table and row schemas they may read against, the audit actions their
+ * queries filter on, and — because the seam is MIT and never gated — the minting side, so "build your
+ * own management client" is a real option rather than a slogan.
+ *
+ * `@pithy-sh/storage/src/index.ts` documents itself the same way, for the same reason.
+ */
+export { type ControlPlaneAuditAction, ControlPlaneAuditActions } from "./controlPlane/audit/actions";
+export { CONTROL_PLANE_KV_BINDING, CONTROLPLANE_MIGRATION_ORDER, type ControlPlaneCapability, type ControlPlaneOptions, controlplane, isControlPlaneCapability, } from "./controlPlane/capability";
+export { ControlPlaneConfig, type ControlPlaneConfigInput } from "./controlPlane/config/config";
+export { ControlPlaneContext } from "./controlPlane/context";
+export { ControlPlaneConnection, Ed25519PublicJwk, RegisteredKey } from "./controlPlane/data/connection";
+export { CONTROL_PLANE_CONNECTIONS_TABLE, type ControlPlaneDatabase, controlPlaneDatabase, } from "./controlPlane/data/tables";
+export { AdminRoute, type AdminRouteMethod, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest, type ControlPlaneManifestWire, } from "./controlPlane/discovery/adminRoute";
+export { type CapabilityManifestConfig, type CapabilityManifestConfigInput, defineManifestConfig, ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, type NamedConfigValue, namedConfigValues, } from "./controlPlane/discovery/configuration";
+export { type AdminRouteDrift, missingAdminRoutes } from "./controlPlane/discovery/drift";
+export { type CapabilityHealth, type CapabilityHealthInput, type CapabilityHealthSource, capabilityHealthSources, defineCapabilityHealth, readCapabilityHealth, } from "./controlPlane/discovery/health";
+export { CapabilityHealthReport, type CapabilityHealthWire, HealthCountNominal, HealthNominal, type HealthStanding, HealthSummary, HealthSummaryKey, HealthSummaryValue, HealthValueCost, HealthValueKind, healthAttention, healthReport, healthWire, type NamedHealthValue, namedHealthValues, standingOf, } from "./controlPlane/discovery/healthSummary";
+export { requireControlPlane } from "./controlPlane/http/guard";
+export { ANY_VERIFIED_CALLER, type ControlPlaneRequirement, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, SEAM_SCOPES, } from "./controlPlane/scope/scope";
+export { exportPublicJwk, type MintControlPlaneToken, mintControlPlaneToken } from "./controlPlane/token/mint";
+export { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, type WorkerBuild, workerBuildChanged, } from "./controlPlane/wire";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACtG,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,YAAY,EACZ,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAChG,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,EACL,+BAA+B,EAC/B,KAAK,oBAAoB,EACzB,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EACL,UAAU,EACV,KAAK,gBAAgB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAClC,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,iBAAiB,GAClB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,KAAK,eAAe,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAQ1F,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,aAAa,EACb,KAAK,cAAc,EACnB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,eAAe,EACf,YAAY,EACZ,UAAU,EACV,KAAK,gBAAgB,EACrB,iBAAiB,EACjB,UAAU,GACX,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,GACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAI/G,OAAO,EACL,oBAAoB,EACpB,oCAAoC,EACpC,4BAA4B,EAC5B,KAAK,WAAW,EAChB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+import { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, SEAM_SCOPES } from "./controlPlane/scope/scope.js";
+import { ControlPlaneConfig } from "./controlPlane/config/config.js";
+import { ControlPlaneConnection, Ed25519PublicJwk, RegisteredKey } from "./controlPlane/data/connection.js";
+import { CONTROL_PLANE_CONNECTIONS_TABLE, controlPlaneDatabase } from "./controlPlane/data/tables.js";
+import { CapabilityHealthReport, HealthCountNominal, HealthNominal, HealthSummary, HealthSummaryKey, HealthSummaryValue, HealthValueCost, HealthValueKind, healthAttention, healthReport, healthWire, namedHealthValues, standingOf } from "./controlPlane/discovery/healthSummary.js";
+import { capabilityHealthSources, defineCapabilityHealth, readCapabilityHealth } from "./controlPlane/discovery/health.js";
+import { ControlPlaneAuditActions } from "./controlPlane/audit/actions.js";
+import { CONTROL_PLANE_HEADER, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, workerBuildChanged } from "./controlPlane/wire.js";
+import { ControlPlaneContext } from "./controlPlane/context.js";
+import { requireControlPlane } from "./controlPlane/http/guard.js";
+import { CONTROL_PLANE_KV_BINDING } from "./controlPlane/replay/kvGuard.js";
+import { CONTROLPLANE_MIGRATION_ORDER, controlplane, isControlPlaneCapability } from "./controlPlane/capability.js";
+import { ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, defineManifestConfig, namedConfigValues } from "./controlPlane/discovery/configuration.js";
+import { AdminRoute, CapabilityDeclaration, CapabilityDescriptor, ControlPlaneManifest } from "./controlPlane/discovery/adminRoute.js";
+import { missingAdminRoutes } from "./controlPlane/discovery/drift.js";
+import { exportPublicJwk, mintControlPlaneToken } from "./controlPlane/token/mint.js";
+export { ANY_VERIFIED_CALLER, AdminRoute, CONTROLPLANE_MIGRATION_ORDER, CONTROL_PLANE_CONNECTIONS_TABLE, CONTROL_PLANE_HEADER, CONTROL_PLANE_KV_BINDING, CONTROL_PLANE_VERSION_CREATED_HEADER, CONTROL_PLANE_VERSION_HEADER, CapabilityDeclaration, CapabilityDescriptor, CapabilityHealthReport, ControlPlaneAuditActions, ControlPlaneConfig, ControlPlaneConnection, ControlPlaneContext, ControlPlaneManifest, ControlPlaneScope, Ed25519PublicJwk, HealthCountNominal, HealthNominal, HealthSummary, HealthSummaryKey, HealthSummaryValue, HealthValueCost, HealthValueKind, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, ManifestConfigKey, ManifestConfigValue, ManifestConfigValues, RegisteredKey, SEAM_SCOPES, capabilityHealthSources, controlPlaneDatabase, controlplane, defineCapabilityHealth, defineManifestConfig, exportPublicJwk, healthAttention, healthReport, healthWire, isControlPlaneCapability, mintControlPlaneToken, missingAdminRoutes, namedConfigValues, namedHealthValues, readCapabilityHealth, requireControlPlane, standingOf, workerBuildChanged };

package/dist/kv/kv.d.ts

@@ -0,0 +1,166 @@
+import type { KVNamespace } from "@cloudflare/workers-types";
+import type { z } from "zod";
+import type { Logger } from "../logger/logger";
+/** Cloudflare's hard limit on a KV entry's metadata, in bytes. */
+export declare const KV_METADATA_MAX_BYTES = 1024;
+/**
+ * Wrap a metadata schema with KV's size limit.
+ *
+ * WARNING: metadata travels with **every** `list` entry and is capped at
+ * {@link KV_METADATA_MAX_BYTES} bytes serialized. It is for small, list-time
+ * fields you want without reading each value — a status flag, a type, a
+ * timestamp — never a payload. This refinement fails a value that would exceed
+ * the cap, turning a late KV rejection into an early, clear validation error.
+ */
+export declare function kvMetadata<T extends z.ZodType>(schema: T): T;
+/** Configuration for a {@link TypedKv} store. */
+export interface TypedKvConfig<V extends z.ZodType, K extends z.ZodObject, M extends z.ZodType> {
+    /** Capability namespace, the fixed first key segment (e.g. `auth`, `assets`). */
+    prefix: string;
+    /**
+     * The ordered key segments after the prefix, as a Zod object. Declared field
+     * order **is** key order, and each segment is validated before a key is built
+     * (e.g. `z.object({ assetType: z.enum([...]), uuid: z.uuid() })` →
+     * `assets:photo:<uuid>`). Segment values must serialize to a string that does
+     * not contain the separator.
+     */
+    key: K;
+    /** Schema validating the stored value on every read and write. */
+    value: V;
+    /** Optional schema for metadata. Wrap with {@link kvMetadata} to bound its size. */
+    metadata?: M;
+    /**
+     * Derive metadata from the value, making the value the single source of truth.
+     *
+     * When set (requires `metadata`), `put` computes metadata from the value
+     * automatically — callers need not pass it — and `list` **self-heals**: any
+     * entry whose metadata is missing has its value read, metadata re-derived, and
+     * written back (value bytes and expiration preserved). This protects against
+     * external edits — notably the Cloudflare dashboard, which drops metadata when
+     * a value is hand-edited. Note: self-heal performs a read and a write per
+     * missing entry during `list`.
+     */
+    deriveMetadata?: (value: z.output<V>) => z.input<M>;
+    /** Key segment separator. Defaults to `:`. */
+    separator?: string;
+    /** Default TTL, in seconds, applied to every `put` unless overridden. KV's floor is 60. */
+    ttlSeconds?: number;
+}
+/**
+ * Validate a {@link TypedKvConfig} at construction — config is a boundary, so it
+ * is checked, not trusted. Catches the misconfigurations the type system can't
+ * (or won't, for JS callers and casts): an empty namespace, a separator that
+ * collides with the prefix, a key with no segments, `deriveMetadata` without a
+ * `metadata` schema to validate against, or a non-positive default TTL.
+ */
+export declare function assertValidConfig(config: TypedKvConfig<z.ZodType, z.ZodObject, z.ZodType>): void;
+/** Construction options for a {@link TypedKv} store beyond its config. */
+export interface TypedKvOptions {
+    /**
+     * The logger a store routes its observable best-effort failures through — notably the `list`
+     * self-heal metadata write-back, which must not fail the surrounding list but should be seen.
+     * `createBackend` passes the per-request `c.var.log`; defaults to the no-op logger.
+     */
+    logger?: Logger;
+}
+/** Per-call options for {@link TypedKv.put}. */
+export interface PutOptions<M extends z.ZodType> {
+    /** TTL, in seconds, for this value. Overrides the store default. KV's floor is 60. */
+    ttlSeconds?: number;
+    /** Metadata to store. Validated against the schema; overrides `deriveMetadata` for this write. */
+    metadata?: z.input<M>;
+}
+/** Options for {@link TypedKv.list}. */
+export interface ListOptions<K extends z.ZodObject> {
+    /**
+     * A leading run of key segments to scope the listing — `{ assetType: "photo" }`
+     * lists `assets:photo:*`. Must be contiguous from the first segment; omit to
+     * list the whole namespace.
+     */
+    prefix?: Partial<z.input<K>>;
+    /** Maximum entries to return in this page. */
+    limit?: number;
+    /** Cursor from a previous page's result. */
+    cursor?: string;
+}
+/** One entry from {@link TypedKv.list}: the key, its parsed segments, and validated metadata. */
+export interface ListEntry<K extends z.ZodObject, M extends z.ZodType> {
+    /** The full physical KV key. */
+    name: string;
+    /** The key's segments, split back out by name. */
+    key: Record<keyof z.input<K>, string>;
+    /** Validated metadata, or `null` when none was stored or no metadata schema is configured. */
+    metadata: z.output<M> | null;
+    /** Absolute expiration time (seconds since epoch), if the entry has a TTL. */
+    expiration?: number;
+}
+/** A page of {@link TypedKv.list} results. */
+export interface ListResult<K extends z.ZodObject, M extends z.ZodType> {
+    /** The entries on this page. */
+    keys: ListEntry<K, M>[];
+    /** Cursor for the next page, or `undefined` when the listing is complete. */
+    cursor?: string;
+    /** Whether this page completed the listing. */
+    listComplete: boolean;
+}
+/**
+ * Typed, validated access to one Workers KV namespace.
+ *
+ * Keys are structured: a fixed capability `prefix` followed by ordered,
+ * Zod-validated segments — so a single store models `pages:<uuid>` or
+ * `assets:<assetType>:<uuid>` and `list` can scope by any leading run of those
+ * segments. Values are validated on the way in and out; there is no untyped
+ * `JSON.parse`. Metadata is validated too and rides along with `list`; with
+ * `deriveMetadata` the value is the source of truth and `list` rebuilds metadata
+ * that external edits have dropped.
+ */
+export declare class TypedKv<V extends z.ZodType, K extends z.ZodObject, M extends z.ZodType = z.ZodNever> {
+    #private;
+    constructor(namespace: KVNamespace, config: TypedKvConfig<V, K, M>, options?: TypedKvOptions);
+    /** Build the full physical KV key (name) from validated segments. */
+    name(key: z.input<K>): string;
+    /**
+     * Read and validate the value at `key`. Returns `null` on a miss. The stored
+     * JSON is parsed and validated against the schema before it is returned.
+     */
+    get(key: z.input<K>): Promise<z.output<V> | null>;
+    /** Read the value at `key` together with its validated metadata. `null` on a miss. */
+    getWithMetadata(key: z.input<K>): Promise<{
+        value: z.output<V>;
+        metadata: z.output<M> | null;
+    } | null>;
+    /**
+     * Validate `value` (and any `metadata`) against their schemas, then store the
+     * value as JSON under the namespaced key. With `deriveMetadata`, metadata is
+     * computed from the value unless overridden per call. Throws (before writing)
+     * on an invalid value, invalid metadata, or metadata over
+     * {@link KV_METADATA_MAX_BYTES}. A per-call `ttlSeconds` overrides the default.
+     */
+    put(key: z.input<K>, value: z.input<V>, options?: PutOptions<M>): Promise<void>;
+    /**
+     * Partially update the value at `key`: read it, merge `changes` over the
+     * current fields, validate the merged result, and write it back. Returns the
+     * merged value. Throws if the key does not exist — there is nothing to merge.
+     *
+     * Metadata stays correct: a `deriveMetadata` store recomputes it from the
+     * merged value; an explicit-metadata store preserves the current metadata
+     * (pass `metadata` to override). TTL resets to the store default unless
+     * `ttlSeconds` is given.
+     *
+     * WARNING: KV has no compare-and-set, so this read-modify-write is
+     * last-write-wins. Concurrent patches to the same key can lose updates — do
+     * not use it where atomicity matters.
+     */
+    patch(key: z.input<K>, changes: Partial<z.output<V>>, options?: PutOptions<M>): Promise<z.output<V>>;
+    /** Delete the value at `key`. A miss is a no-op. */
+    delete(key: z.input<K>): Promise<void>;
+    /**
+     * List entries under a leading run of key segments. Each entry carries its
+     * parsed key segments and validated metadata — no value reads, unless
+     * `deriveMetadata` is configured and an entry's metadata is missing, in which
+     * case it is rebuilt from the value and written back. Pass `options.prefix` to
+     * scope (e.g. `{ assetType: "photo" }`); omit to list the whole namespace.
+     */
+    list(options?: ListOptions<K>): Promise<ListResult<K, M>>;
+}
+//# sourceMappingURL=kv.d.ts.map

package/dist/kv/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/kv/kv.ts"],"names":[],"mappings":"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"}