@pithy-sh/core 0.11.0 → 0.12.0

package/dist/privacy/retirement.d.ts

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **The retirement guard's verdict, apart from the counts that feed it** (#390).
+ *
+ * Its own module, and a leaf, so a browser may import it: the manifest's posture block names
+ * {@link RetirementVerdict}, and the management client validates that block in a browser. The counts are read by
+ * `./fieldRotation`, which reaches D1 and the Workers types; it imports this, never the other way.
+ */
+/** Why the guard is not clean: what holds a version that is due to leave. */
+export declare const RetirementReason: z.ZodEnum<{
+    "incomplete-coverage": "incomplete-coverage";
+    stale: "stale";
+    unrotatable: "unrotatable";
+}>;
+export type RetirementReason = z.output<typeof RetirementReason>;
+/** The guard's verdict, as the manifest's posture block reports it. */
+export declare const RetirementVerdict: z.ZodObject<{
+    blocked: z.ZodBoolean;
+    reasons: z.ZodArray<z.ZodEnum<{
+        "incomplete-coverage": "incomplete-coverage";
+        stale: "stale";
+        unrotatable: "unrotatable";
+    }>>;
+    liveVersions: z.ZodNumber;
+}, z.core.$strip>;
+export type RetirementVerdict = z.output<typeof RetirementVerdict>;
+/** What the guard reads. */
+export interface RetirementInput {
+    /** Every live version, newest first. */
+    versions: readonly number[];
+    /** The version every write seals under. Absent where the key set could not be read: then nothing is due. */
+    current?: number | undefined;
+    /** Rows still under any version due to leave, summed over every stamped envelope and index column. */
+    stale: number;
+    /** Whether every schema source the stamp derives from was read. */
+    coverageComplete: boolean;
+    /** How many encrypted fields rest outside D1. */
+    unrotatable: number;
+}
+/**
+ * The version `current` replaced: the highest live version below it. A version above current is staged and never
+ * promoted, so it replaced nothing and is never the previous one.
+ */
+export declare function previousVersion(versions: readonly number[], current: number): number | undefined;
+/**
+ * The versions staged over `current` and never promoted, oldest first. A rotation whose confirm failed leaves one in
+ * the entry; the next rotation promotes it rather than minting past it, so the window stays anchored on current.
+ */
+export declare function stagedVersions(versions: readonly number[], current: number): number[];
+/**
+ * The versions due to leave the window: every live version older than the one `current` replaced. Current and
+ * previous are the normal state, and the previous version is still sealing rows lazily, so only an older one is
+ * due. Anchored on the pointer, never on the two highest numbers: a version staged over current and never promoted
+ * would otherwise take the previous slot, and make the version that was current, or current itself, due.
+ */
+export declare function versionsDue(versions: readonly number[], current: number): number[];
+/**
+ * **The retirement guard.** Clean only when all three hold: the stale count is zero across every stamped envelope
+ * and index column, coverage is complete, and no unrotatable field was observed. `blocked` is whether a version is
+ * due and the guard is not clean. Retiring a version is the one irreversible act in the feature — every ciphertext
+ * still under it becomes unopenable — so nothing short of clean retires one, and nothing implies it.
+ */
+export declare function retirementVerdict(input: RetirementInput): RetirementVerdict;
+/** Whether a verdict lets the rotator retire: nothing at all holds a version. */
+export declare function guardIsClean(verdict: RetirementVerdict): boolean;
+//# sourceMappingURL=retirement.d.ts.map

package/dist/privacy/retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retirement.d.ts","sourceRoot":"","sources":["../../src/privacy/retirement.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,uEAAuE;AACvE,eAAO,MAAM,iBAAiB;;;;;;;;iBAY6D,CAAC;AAC5F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,4BAA4B;AAC5B,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,4GAA4G;IAC5G,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sGAAsG;IACtG,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhG;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,iBAAiB,CAU3E;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAEhE"}

package/dist/privacy/retirement.js

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/privacy/retirement.ts
+/**
+* **The retirement guard's verdict, apart from the counts that feed it** (#390).
+*
+* Its own module, and a leaf, so a browser may import it: the manifest's posture block names
+* {@link RetirementVerdict}, and the management client validates that block in a browser. The counts are read by
+* `./fieldRotation`, which reaches D1 and the Workers types; it imports this, never the other way.
+*/
+/** Why the guard is not clean: what holds a version that is due to leave. */
+const RetirementReason = z.enum([
+	"unrotatable",
+	"incomplete-coverage",
+	"stale"
+]).describe("`unrotatable` — an encrypted field rests outside D1, so nothing can prove it re-sealed. `incomplete-coverage` — a schema source the guard derives from was not read. `stale` — a row still holds an envelope or an index under a version due to leave.");
+/** The guard's verdict, as the manifest's posture block reports it. */
+const RetirementVerdict = z.object({
+	blocked: z.boolean().describe("Whether a version due to leave the window is being held live by one of `reasons`."),
+	reasons: z.array(RetirementReason).describe("Every reason the guard is not clean now, empty when it is. Read directly: never inferred."),
+	liveVersions: z.number().int().nonnegative().describe("How many field-key versions are live. Two is the normal state: current and previous.")
+}).describe("Whether the field key's oldest live version can be retired, and if not, why.");
+/**
+* The version `current` replaced: the highest live version below it. A version above current is staged and never
+* promoted, so it replaced nothing and is never the previous one.
+*/
+function previousVersion(versions, current) {
+	const below = versions.filter((version) => version < current);
+	return below.length === 0 ? void 0 : Math.max(...below);
+}
+/**
+* The versions staged over `current` and never promoted, oldest first. A rotation whose confirm failed leaves one in
+* the entry; the next rotation promotes it rather than minting past it, so the window stays anchored on current.
+*/
+function stagedVersions(versions, current) {
+	return versions.filter((version) => version > current).sort((left, right) => left - right);
+}
+/**
+* The versions due to leave the window: every live version older than the one `current` replaced. Current and
+* previous are the normal state, and the previous version is still sealing rows lazily, so only an older one is
+* due. Anchored on the pointer, never on the two highest numbers: a version staged over current and never promoted
+* would otherwise take the previous slot, and make the version that was current, or current itself, due.
+*/
+function versionsDue(versions, current) {
+	const previous = previousVersion(versions, current);
+	if (previous === void 0) return [];
+	return versions.filter((version) => version < previous).sort((left, right) => right - left);
+}
+/**
+* **The retirement guard.** Clean only when all three hold: the stale count is zero across every stamped envelope
+* and index column, coverage is complete, and no unrotatable field was observed. `blocked` is whether a version is
+* due and the guard is not clean. Retiring a version is the one irreversible act in the feature — every ciphertext
+* still under it becomes unopenable — so nothing short of clean retires one, and nothing implies it.
+*/
+function retirementVerdict(input) {
+	const reasons = [];
+	if (input.unrotatable > 0) reasons.push("unrotatable");
+	if (!input.coverageComplete) reasons.push("incomplete-coverage");
+	if (input.stale > 0) reasons.push("stale");
+	return {
+		blocked: input.current !== void 0 && versionsDue(input.versions, input.current).length > 0 && reasons.length > 0,
+		reasons,
+		liveVersions: input.versions.length
+	};
+}
+/** Whether a verdict lets the rotator retire: nothing at all holds a version. */
+function guardIsClean(verdict) {
+	return verdict.reasons.length === 0;
+}
+//#endregion
+export { RetirementReason, RetirementVerdict, guardIsClean, previousVersion, retirementVerdict, stagedVersions, versionsDue };

package/dist/privacy/sealed.d.ts

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { z } from "zod";
+import { type FieldKeys } from "../crypto/fieldKeys";
+import { type SqliteJsonSchema } from "../data/codecs";
+import { type EncryptedIndexOf, type EncryptedInner } from "./encrypted";
+/**
+ * **`sealed()`: the round trip for a table with an encrypted field** (#390).
+ *
+ * The codecs stay synchronous (`./encrypted`), so AES-GCM happens one step above them, in a seam the repository builds
+ * per request from `env` — which is how the key reaches the encode without a module-level schema ever holding one.
+ *
+ * ```ts
+ * const patients = sealed(Patient, { keys: env.PITHY_FIELD_KEYS });
+ *
+ * const record = await patients.seal(value);   // seal each marked field, then Patient.encode
+ * await db.insertInto("patient").values(record).execute();
+ *
+ * const value = await patients.open(row);      // Patient.parse, then open each marked field
+ *
+ * const hashes = await patients.match("email", input);   // one per live version
+ * await db.selectFrom("patient").where("emailIndex", "in", hashes).selectAll().execute();
+ * ```
+ *
+ * ## What each seal binds
+ *
+ * The AAD is `pithy/enc/1:<name>:<field path>:<pk>` ({@link fieldContext}): the stable name `encryptedTable()`
+ * declared, the field's path, and the row's primary key. A ciphertext moved to another field, row or table does not
+ * open. The declared name is not the SQL table name, so renaming a table in a migration leaves every row openable. A
+ * column's SQL name is always its key in snake case, so renaming an encrypted column changes its field path. The key
+ * is app-assigned and never updated, which is the immutability guarantee. Changing the name, a path (a column rename
+ * included) or a key is a re-seal migration through `sealed()`: read with the old schema, write with the new.
+ *
+ * ## What it refuses, at build
+ *
+ * A schema with an encrypted field and no `encryptedTable()` declaration, and every problem `encryptedLayout` names:
+ * an encrypted field no path of object keys reaches, an indexed field with no index column, an index column naming no
+ * indexed field. Each is refused when `sealed()` is called, before any key is read, naming the schema.
+ *
+ * Every write seals under the key set's current version. Every read opens under whichever version sealed the value,
+ * for as long as that version is live.
+ */
+/** The versioned prefix of every field's AAD. Changing what is bound changes this, so the break is deliberate. */
+export declare const FIELD_CONTEXT_PREFIX = "pithy/enc/1";
+/** The AAD one field binds: `pithy/enc/1:<name>:<field path>:<pk>`. */
+export declare function fieldContext(name: string, path: string, pk: string): string;
+/** Depth countdown for {@link Opened}. */
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8];
+/**
+ * The value `open` returns and `seal` takes: the schema's output, with every encrypted field the output of the schema
+ * it seals — the plaintext, carrying that schema's privacy brand — instead of an envelope. Read through the presence
+ * wrappers, objects, and the kit's JSON columns, to eight levels.
+ */
+export type Opened<S, D extends number = 8> = [D] extends [never] ? z.output<S> : [EncryptedInner<S>] extends [never] ? S extends z.ZodOptional<infer I> ? Opened<I, Prev[D]> | undefined : S extends z.ZodNullable<infer I> ? Opened<I, Prev[D]> | null : S extends z.ZodDefault<infer I> ? Exclude<Opened<I, Prev[D]>, undefined> : S extends z.ZodReadonly<infer I> ? Readonly<Opened<I, Prev[D]>> : [SqliteJsonSchema<S>] extends [never] ? S extends z.ZodObject<infer Shape> ? {
+    [K in keyof z.output<S>]: K extends keyof Shape ? Opened<Shape[K], Prev[D]> : z.output<S>[K];
+} : z.output<S> : Opened<SqliteJsonSchema<S>, Prev[D]> : z.output<EncryptedInner<S>>;
+/** A field through its presence wrappers. */
+type Unwrapped<S> = S extends z.ZodOptional<infer I> ? Unwrapped<I> : S extends z.ZodNullable<infer I> ? Unwrapped<I> : S extends z.ZodDefault<infer I> ? Unwrapped<I> : S;
+/** The top-level fields of a table schema that declare a blind index: what `match` takes. */
+export type IndexedField<S> = S extends z.ZodObject<infer Shape> ? {
+    [K in keyof Shape & string]: [EncryptedIndexOf<Unwrapped<Shape[K]>>] extends [never] ? never : K;
+}[keyof Shape & string] : never;
+/** What {@link sealed} takes. */
+export interface SealedOptions {
+    /** The field key: `env.PITHY_FIELD_KEYS`, or a resolved key set. Read on the first seal, open or match. */
+    keys: FieldKeys | undefined;
+}
+/** The repository seam over one table with encrypted fields. */
+export interface Sealed<S extends z.ZodType> {
+    /** The table schema. */
+    readonly schema: S;
+    /** The schema of the opened value: every encrypted field replaced by the schema it seals. `redact` takes it. */
+    readonly opened: z.ZodType<Opened<S>>;
+    /** Seal every encrypted field under the current version, write each blind index, then `Schema.encode`. */
+    seal(value: Opened<S>): Promise<z.input<S>>;
+    /** `Schema.parse`, then open every encrypted field and validate it against the schema it seals. */
+    open(row: z.input<S>): Promise<Opened<S>>;
+    /** The blind index of `value` for `field` under every live version, newest first: what an `IN (…)` looks for. */
+    match(field: IndexedField<S>, value: string): Promise<string[]>;
+}
+/**
+ * Build the seam for one table, from the request's `env`. Refuses, before any key is read, a schema with an encrypted
+ * field and no `encryptedTable()` declaration, and every layout problem. See the module note.
+ */
+export declare function sealed<S extends z.ZodType>(schema: S, options: SealedOptions): Sealed<S>;
+export {};
+//# sourceMappingURL=sealed.d.ts.map

package/dist/privacy/sealed.d.ts.map

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

package/dist/privacy/sealed.js

@@ -0,0 +1,221 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { ValidationError, fromZodError } from "../error/pithyError.js";
+import { decryptValue, encryptValue } from "../crypto/envelope.js";
+import { FIELD_KEYS_BINDING, liveVersions, resolveFieldKeys } from "../crypto/fieldKeys.js";
+import { isSqliteJson, sqliteJson } from "../data/codecs.js";
+import { encryptedLayout, encryptedSpecOf, hasEncryptedFields } from "./encrypted.js";
+import { blindIndexValue } from "./blindIndex.js";
+//#region src/privacy/sealed.ts
+/**
+* **`sealed()`: the round trip for a table with an encrypted field** (#390).
+*
+* The codecs stay synchronous (`./encrypted`), so AES-GCM happens one step above them, in a seam the repository builds
+* per request from `env` — which is how the key reaches the encode without a module-level schema ever holding one.
+*
+* ```ts
+* const patients = sealed(Patient, { keys: env.PITHY_FIELD_KEYS });
+*
+* const record = await patients.seal(value);   // seal each marked field, then Patient.encode
+* await db.insertInto("patient").values(record).execute();
+*
+* const value = await patients.open(row);      // Patient.parse, then open each marked field
+*
+* const hashes = await patients.match("email", input);   // one per live version
+* await db.selectFrom("patient").where("emailIndex", "in", hashes).selectAll().execute();
+* ```
+*
+* ## What each seal binds
+*
+* The AAD is `pithy/enc/1:<name>:<field path>:<pk>` ({@link fieldContext}): the stable name `encryptedTable()`
+* declared, the field's path, and the row's primary key. A ciphertext moved to another field, row or table does not
+* open. The declared name is not the SQL table name, so renaming a table in a migration leaves every row openable. A
+* column's SQL name is always its key in snake case, so renaming an encrypted column changes its field path. The key
+* is app-assigned and never updated, which is the immutability guarantee. Changing the name, a path (a column rename
+* included) or a key is a re-seal migration through `sealed()`: read with the old schema, write with the new.
+*
+* ## What it refuses, at build
+*
+* A schema with an encrypted field and no `encryptedTable()` declaration, and every problem `encryptedLayout` names:
+* an encrypted field no path of object keys reaches, an indexed field with no index column, an index column naming no
+* indexed field. Each is refused when `sealed()` is called, before any key is read, naming the schema.
+*
+* Every write seals under the key set's current version. Every read opens under whichever version sealed the value,
+* for as long as that version is live.
+*/
+/** The versioned prefix of every field's AAD. Changing what is bound changes this, so the break is deliberate. */
+const FIELD_CONTEXT_PREFIX = "pithy/enc/1";
+/** The AAD one field binds: `pithy/enc/1:<name>:<field path>:<pk>`. */
+function fieldContext(name, path, pk) {
+	return `${FIELD_CONTEXT_PREFIX}:${name}:${path}:${pk}`;
+}
+/** How a refusal names a schema: its description, or what it holds. */
+function schemaLabel(schema, paths) {
+	const description = schema.description;
+	if (description) return `The schema "${description}"`;
+	return paths.length > 0 ? `The schema holding ${paths.join(", ")}` : "This schema";
+}
+/** The value at a path, or `undefined` where any step is absent. */
+function readPath(value, segments) {
+	let at = value;
+	for (const segment of segments) {
+		if (typeof at !== "object" || at === null) return void 0;
+		at = at[segment];
+	}
+	return at;
+}
+/**
+* A copy of `value` with `next` at `segments`, copying each object on the way so the caller's value is never
+* written to. A step that is absent stays absent: there is nothing there to seal.
+*/
+function writePath(value, segments, next) {
+	const [head, ...rest] = segments;
+	if (head === void 0) return next;
+	if (typeof value !== "object" || value === null) return value;
+	const copy = { ...value };
+	copy[head] = rest.length === 0 ? next : writePath(copy[head], rest, next);
+	return copy;
+}
+/** The plaintext a value seals to: its schema's encoded form, as JSON. Refused without echoing the value. */
+function plaintextOf(field, value) {
+	const encoded = field.spec.inner.safeEncode(value);
+	if (!encoded.success) throw fromZodError(encoded.error, { message: `The encrypted field "${field.path}" does not hold a value its schema accepts.` });
+	const json = JSON.stringify(encoded.data);
+	if (typeof json !== "string") throw new ValidationError({ message: `The encrypted field "${field.path}" holds a value JSON cannot carry.` });
+	return json;
+}
+/** The opened schema: each encrypted field replaced by the schema it seals, along the paths that reach one. */
+function openedSchemaOf(schema) {
+	if (encryptedSpecOf(schema)) {
+		const def = schema._zod.def;
+		if (def.innerType && (def.type === "optional" || def.type === "nullable" || def.type === "readonly")) return schema.clone({
+			...def,
+			innerType: openedSchemaOf(def.innerType)
+		});
+		return encryptedSpecOf(schema).inner;
+	}
+	if (!hasEncryptedFields(schema)) return schema;
+	const def = schema._zod.def;
+	if (def.innerType && [
+		"optional",
+		"nullable",
+		"default",
+		"prefault",
+		"readonly"
+	].includes(def.type)) return schema.clone({
+		...def,
+		innerType: openedSchemaOf(def.innerType)
+	});
+	if (isSqliteJson(schema) && def.out) {
+		const meta = schema.meta();
+		const column = sqliteJson(openedSchemaOf(def.out));
+		return meta ? column.meta(meta) : column;
+	}
+	if (def.type === "object") {
+		const object = schema;
+		const changed = {};
+		for (const [key, field] of Object.entries(object.shape)) if (hasEncryptedFields(field)) changed[key] = openedSchemaOf(field);
+		return object.extend(changed);
+	}
+	return schema;
+}
+/**
+* Build the seam for one table, from the request's `env`. Refuses, before any key is read, a schema with an encrypted
+* field and no `encryptedTable()` declaration, and every layout problem. See the module note.
+*/
+function sealed(schema, options) {
+	const layout = encryptedLayout(schema);
+	const paths = layout.fields.map((field) => field.path);
+	if (layout.declaration === null) {
+		if (layout.fields.length > 0 || hasEncryptedFields(schema)) throw new ValidationError({
+			message: `${schemaLabel(schema, paths)} holds an encrypted field and declares no table.`,
+			action: "Wrap it in encryptedTable(schema, { name, key }): the name and key are what every sealed field binds."
+		});
+		throw new ValidationError({
+			message: `${schemaLabel(schema, paths)} holds no encrypted field.`,
+			action: "Read and write it with Schema.parse and Schema.encode; sealed() is for a table with an encrypted field."
+		});
+	}
+	if (layout.problems.length > 0) throw new ValidationError({
+		message: `${schemaLabel(schema, paths)} cannot be sealed as declared. ${layout.problems.join(" ")}`,
+		action: "Fix the schema's encrypted fields and their blindIndex columns."
+	});
+	const { name, key } = layout.declaration;
+	let resolved;
+	const config = () => {
+		resolved ??= resolveFieldKeys(options.keys);
+		return resolved;
+	};
+	let opened;
+	const primaryKey = (value, doing) => {
+		const pk = readPath(value, [key]);
+		if (typeof pk !== "string" || pk.length === 0) throw new ValidationError({
+			message: `The ${name} row has no ${key} to bind, so it cannot be ${doing}.`,
+			action: `Assign ${key} in the app before the insert: every encrypted field binds it.`
+		});
+		return pk;
+	};
+	return {
+		schema,
+		get opened() {
+			opened ??= openedSchemaOf(schema);
+			return opened;
+		},
+		async seal(value) {
+			const pk = primaryKey(value, "sealed");
+			const keys = await config();
+			const current = Number(keys.currentVersion);
+			let out = value;
+			for (const field of layout.fields) {
+				const plain = readPath(value, field.segments);
+				if (plain === void 0 || plain === null) {
+					if (field.indexField) out = writePath(out, [field.indexField], plain === null ? null : void 0);
+					continue;
+				}
+				const envelope = await encryptValue(keys, fieldContext(name, field.path, pk), plaintextOf(field, plain), { keys: FIELD_KEYS_BINDING });
+				out = writePath(out, field.segments, envelope);
+				if (field.indexField && field.spec.index) {
+					if (typeof plain !== "string") throw new ValidationError({ message: `The encrypted field "${field.path}" has a blind index, so it holds a string.` });
+					out = writePath(out, [field.indexField], await blindIndexValue(keys, current, field.spec.index, plain));
+				}
+			}
+			const encoded = schema.safeEncode(out);
+			if (!encoded.success) throw fromZodError(encoded.error);
+			return encoded.data;
+		},
+		async open(row) {
+			const parsed = schema.safeParse(row);
+			if (!parsed.success) throw fromZodError(parsed.error);
+			const pk = primaryKey(parsed.data, "opened");
+			const keys = await config();
+			let out = parsed.data;
+			for (const field of layout.fields) {
+				const envelope = readPath(parsed.data, field.segments);
+				if (envelope === void 0 || envelope === null) continue;
+				const plaintext = await decryptValue(keys, fieldContext(name, field.path, pk), envelope, { keys: FIELD_KEYS_BINDING });
+				let json;
+				try {
+					json = JSON.parse(plaintext);
+				} catch {
+					throw new ValidationError({ message: `The encrypted field "${field.path}" opened to something that is not JSON.` });
+				}
+				const value = field.spec.inner.safeParse(json);
+				if (!value.success) throw fromZodError(value.error);
+				out = writePath(out, field.segments, value.data);
+			}
+			return out;
+		},
+		async match(field, value) {
+			const located = layout.fields.find((one) => one.path === field && one.indexField !== null);
+			if (!located?.spec.index) throw new ValidationError({
+				message: `"${String(field)}" is not a field of the ${name} table with a blind index.`,
+				action: `Declare it encrypted(x, { index: "exact" | "email" }) with a blindIndex("${String(field)}") column.`
+			});
+			const keys = await config();
+			const normalizer = located.spec.index;
+			return Promise.all(liveVersions(keys).map((version) => blindIndexValue(keys, version, normalizer, value)));
+		}
+	};
+}
+//#endregion
+export { FIELD_CONTEXT_PREFIX, fieldContext, sealed };