ankka 0.15.0 → 0.16.0

package/dist/personal.js

@@ -0,0 +1,209 @@
+// Personal fields (feature 042): a value about one data subject, never held in the clear.
+//
+// Marked in a shape with `s.personal(inner)` and built with `personal(subject("player/8c1f"), value)`.
+// Written by a serializer (a payload sent to the sidecar) it is the personal envelope of
+// protocol/ENCODING.md, sealed with AES-256-GCM under the subject's key; read back it is present, or
+// erased once the key is destroyed. Where no serializer is writing (an endpoint's reply or a caller's
+// body) it is the value with its subject beside it. Its textual form names the subject, never the value.
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { CommandError, ErrorCode } from "./effects/common.js";
+/** The rule, in the words every SDK refuses with. */
+export const DATA_SUBJECT_RULE = "a data subject is 1 to 253 characters from letters, digits, '.', '_', '-', '/' and ':'";
+const SUBJECT = /^[A-Za-z0-9._/:-]{1,253}$/;
+/**
+ * Why `value` is not a data subject, or `undefined` when it is one. The reason names the rule and never
+ * the value, which may be the personal data a caller meant to protect (FR-029).
+ */
+export function subjectProblem(value) {
+    if (typeof value === "string" && SUBJECT.test(value))
+        return undefined;
+    return `the value given is not a data subject: ${DATA_SUBJECT_RULE}`;
+}
+/** `value` as a data subject; throws a `TypeError` naming the rule when it is not one. */
+export function subject(value) {
+    const problem = subjectProblem(value);
+    if (problem !== undefined)
+        throw new TypeError(problem);
+    return value;
+}
+// ── the field ────────────────────────────────────────────────────────────────
+const inspect = Symbol.for("nodejs.util.inspect.custom");
+/** A personal field holding its value. */
+export class Present {
+    kind = "present";
+    subject;
+    value;
+    constructor(subject, value) {
+        this.subject = subject;
+        this.value = value;
+        Object.freeze(this);
+    }
+    /** The value; a present field ignores `fallback`. */
+    orElse(_fallback) {
+        return this.value;
+    }
+    get isErased() {
+        return false;
+    }
+    toString() {
+        return `Personal(${this.subject})`;
+    }
+    [inspect]() {
+        return this.toString();
+    }
+    /**
+     * The subject alone, never the value: `JSON.stringify` is how an object is logged, and a personal
+     * field's textual form holds no value (FR-029). A payload's and an endpoint's forms come from the
+     * field's schema, which never calls this.
+     */
+    toJSON() {
+        return { subject: this.subject };
+    }
+}
+/** A personal field whose data subject was erased: only decoding makes one. */
+export class Erased {
+    kind = "erased";
+    subject;
+    constructor(subject) {
+        this.subject = subject;
+        Object.freeze(this);
+    }
+    orElse(fallback) {
+        return fallback;
+    }
+    get isErased() {
+        return true;
+    }
+    toString() {
+        return `Personal(${this.subject})`;
+    }
+    [inspect]() {
+        return this.toString();
+    }
+    toJSON() {
+        return { subject: this.subject };
+    }
+}
+/** A personal field about `about` holding `value`. */
+export function personal(about, value) {
+    const problem = subjectProblem(about);
+    if (problem !== undefined)
+        throw new TypeError(problem);
+    return new Present(about, value);
+}
+/** @internal An erased field, as decoding makes one. */
+export function erased(about) {
+    return new Erased(about);
+}
+// The project of each field read from an envelope, by the field's identity and held weakly (FR-027):
+// a field a handler makes, even with the same value, is a different object and the service's own.
+const origins = new WeakMap();
+/** @internal Remembers that `field` was read from an envelope of `project`; answers it. */
+export function readFrom(field, project) {
+    origins.set(field, project);
+    return field;
+}
+/** @internal The project whose envelope `field` was read from, or `undefined` when a handler made it. */
+export function originOf(field) {
+    return origins.get(field);
+}
+export function isPersonal(value) {
+    return value instanceof Present || value instanceof Erased;
+}
+/**
+ * Why a personal field could not be written or read. A `CommandError` whose `details.personal` is the
+ * reason: `unavailable` (no keyring, or it did not answer), `erased` (a write for an erased data
+ * subject), `corrupt` (an envelope that fails authentication). Reading an erased subject is never one.
+ */
+export class PersonalError extends CommandError {
+    reason;
+    constructor(reason, message) {
+        const code = reason === "unavailable" ? ErrorCode.Unavailable : reason === "erased" ? ErrorCode.Conflict : ErrorCode.Internal;
+        super({ message, code, details: { personal: reason } });
+        this.name = "PersonalError";
+        this.reason = reason;
+    }
+    static unavailable(why) {
+        return new PersonalError("unavailable", `the keyring is unavailable: ${why}`);
+    }
+    static erased(about) {
+        return new PersonalError("erased", `the data subject '${about}' is erased; nothing was written`);
+    }
+    static corrupt(about, why) {
+        return new PersonalError("corrupt", `the personal envelope of '${about}' is corrupt: ${why}`);
+    }
+}
+// ── the envelope's cipher ────────────────────────────────────────────────────
+/** The envelope's version; a reader refuses one it does not know. */
+export const ENVELOPE_VERSION = 1;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const utf8 = new TextEncoder();
+/** Subject, project and manifest, each as a 4-byte big-endian length and its UTF-8 bytes. */
+export function associatedData(about, project, manifest) {
+    const parts = [about, project, manifest].map((p) => utf8.encode(p));
+    const out = new Uint8Array(parts.reduce((n, p) => n + 4 + p.length, 0));
+    const view = new DataView(out.buffer);
+    let at = 0;
+    for (const p of parts) {
+        view.setUint32(at, p.length, false);
+        out.set(p, at + 4);
+        at += 4 + p.length;
+    }
+    return out;
+}
+/** `nonce ‖ ciphertext ‖ tag`. A nonce is random unless given, which only the fixtures' tests do. */
+export function seal(key, plaintext, ad, nonce) {
+    const iv = nonce ?? randomBytes(NONCE_BYTES);
+    if (iv.length !== NONCE_BYTES)
+        throw new RangeError(`a nonce is ${NONCE_BYTES} bytes, was ${iv.length}`);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    cipher.setAAD(ad);
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return new Uint8Array(Buffer.concat([iv, body, cipher.getAuthTag()]));
+}
+/** The plaintext, or `undefined` when the tag does not verify under this key and associated data. */
+export function open(key, boxed, ad) {
+    if (boxed.length < NONCE_BYTES + TAG_BYTES)
+        return undefined;
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, boxed.subarray(0, NONCE_BYTES));
+        decipher.setAAD(ad);
+        decipher.setAuthTag(boxed.subarray(boxed.length - TAG_BYTES));
+        return new Uint8Array(Buffer.concat([decipher.update(boxed.subarray(NONCE_BYTES, boxed.length - TAG_BYTES)), decipher.final()]));
+    }
+    catch {
+        return undefined;
+    }
+}
+let bound;
+/** @internal The scope bound now, if any. */
+export function currentScope() {
+    return bound;
+}
+/**
+ * @internal Runs `body` (synchronous: a codec's encode or decode) as a serializer writing under
+ * `manifest`. `nonce` fixes the nonce every envelope in `body` is sealed with, which only the fixtures'
+ * tests may do: a nonce used twice under one key breaks GCM.
+ */
+export function withinScope(manifest, body, nonce) {
+    const before = bound;
+    bound = nonce === undefined ? { manifest } : { manifest, nonce };
+    try {
+        return body();
+    }
+    finally {
+        bound = before;
+    }
+}
+/** @internal Runs `body` at the edge, with no scope bound. */
+export function outsideScope(body) {
+    const before = bound;
+    bound = undefined;
+    try {
+        return body();
+    }
+    finally {
+        bound = before;
+    }
+}

package/dist/schema.d.ts

@@ -1,4 +1,5 @@
 import type { Duration, Instant, LocalDate, LocalDateTime } from "./time.ts";
+import type { Personal } from "./personal.ts";
 /** The one value of type `Done`: a handler that has nothing to say. */
 export declare const done: Readonly<{
     readonly done: true;
@@ -32,6 +33,9 @@ export type Shape = {
 } | {
     readonly kind: "lazy";
     readonly thunk: () => Schema;
+} | {
+    readonly kind: "personal";
+    readonly inner: Schema;
 };
 interface Typed<T> {
     /** Phantom: carries the TypeScript type. Never set. */
@@ -90,6 +94,13 @@ export declare const s: Readonly<{
     sumType<C extends Readonly<Record<string, Readonly<Record<string, Schema>>>>>(name: string, cases: C): Schema<InferCases<C>>;
     /** A fieldless enumeration used as a field: `{"type":"Ready"}` on the wire, `"Ready"` in TypeScript. */
     enumeration<const V extends readonly [string, ...string[]]>(name: string, ...values: V): Schema<V[number]>;
+    /**
+     * A personal field (feature 042): `s.personal(s.string)` is a `Personal<string>`, built with
+     * `personal(subject("player/8c1f"), value)`. A payload holds it as the personal envelope, sealed under
+     * the data subject's key; an endpoint's reply or body as `{"subject": s, "value": v}`, or
+     * `{"subject": s}` once the subject is erased.
+     */
+    personal<T>(inner: Schema<T>): Schema<Personal<T>>;
     /** A reference to a schema declared later, for recursive shapes: `s.list(s.lazy(() => Tree))`. */
     lazy<T>(thunk: () => Schema<T>): Schema<T>;
 }>;
@@ -109,4 +120,6 @@ export declare function defaultManifest(schema: Schema): string;
  * unknown properties; integers are `integer`; instants are `string` with `format: date-time`.
  */
 export declare function toJsonSchema(schema: Schema): Record<string, unknown>;
+/** Whether `schema` holds a personal field anywhere in it. */
+export declare function holdsPersonal(schema: Schema, seen?: Set<Schema>): boolean;
 export {};

package/dist/schema.js

@@ -82,6 +82,15 @@ export const s = Object.freeze({
             throw new SchemaError(`enumeration ${name} repeats a value`);
         return Object.freeze({ kind: "enumeration", name, values: Object.freeze([...values]) });
     },
+    /**
+     * A personal field (feature 042): `s.personal(s.string)` is a `Personal<string>`, built with
+     * `personal(subject("player/8c1f"), value)`. A payload holds it as the personal envelope, sealed under
+     * the data subject's key; an endpoint's reply or body as `{"subject": s, "value": v}`, or
+     * `{"subject": s}` once the subject is erased.
+     */
+    personal(inner) {
+        return Object.freeze({ kind: "personal", inner });
+    },
     /** A reference to a schema declared later, for recursive shapes: `s.list(s.lazy(() => Tree))`. */
     lazy(thunk) {
         return Object.freeze({ kind: "lazy", thunk });
@@ -114,6 +123,8 @@ export function describe(schema) {
             return `list<${describe(r.inner)}>`;
         case "stringMap":
             return `map<string, ${describe(r.inner)}>`;
+        case "personal":
+            return `personal<${describe(r.inner)}>`;
         default:
             return r.kind;
     }
@@ -132,6 +143,8 @@ export function defaultManifest(schema) {
             return `list[${defaultManifest(r.inner)}]`;
         case "stringMap":
             return `map[${defaultManifest(r.inner)}]`;
+        case "personal":
+            return `personal[${defaultManifest(r.inner)}]`;
         default:
             return r.kind;
     }
@@ -186,6 +199,36 @@ export function toJsonSchema(schema) {
             };
         case "enumeration":
             return { type: "object", properties: { type: { enum: [...r.values] } }, required: ["type"], additionalProperties: false };
+        case "personal":
+            // The edge form: the value with its subject beside it, or the subject alone once erased.
+            return {
+                type: "object",
+                properties: { subject: { type: "string", pattern: "^[A-Za-z0-9._/:-]{1,253}$" }, value: toJsonSchema(r.inner) },
+                required: ["subject"],
+                additionalProperties: false,
+            };
+    }
+}
+/** Whether `schema` holds a personal field anywhere in it. */
+export function holdsPersonal(schema, seen = new Set()) {
+    if (seen.has(schema))
+        return false;
+    seen.add(schema);
+    switch (schema.kind) {
+        case "personal":
+            return true;
+        case "lazy":
+            return holdsPersonal(schema.thunk(), seen);
+        case "option":
+        case "list":
+        case "stringMap":
+            return holdsPersonal(schema.inner, seen);
+        case "record":
+            return Object.values(schema.fields).some((f) => holdsPersonal(f, seen));
+        case "sumType":
+            return Object.values(schema.cases).some((fields) => Object.values(fields).some((f) => holdsPersonal(f, seen)));
+        default:
+            return false;
     }
 }
 function objectSchema(fields) {

package/dist/server/agent.js

@@ -10,7 +10,7 @@ import { ErrorCode } from "../effects/common.js";
 import { decodeJsonValue, reviver } from "../json.js";
 import { errorCodeToProto } from "../kinds.js";
 import { decodeResult } from "../autonomous.js";
-import { decodePayload } from "./payloads.js";
+import { decodePayload, prefetchPayload } from "./payloads.js";
 function messageOf(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -33,6 +33,7 @@ export async function handlePlan(req, ctx) {
     const agent = new registered.cls();
     agent._bind(req.sessionId, metadata, ctx.client.withMetadata(metadata));
     let effect;
+    await prefetchPayload(req.payload);
     try {
         const input = handler.input ? decodePayload(codecFor(handler.input), req.payload) : undefined;
         effect = (await handler.run(agent, input));

package/dist/server/discovery.d.ts

@@ -10,7 +10,14 @@ export declare function refusal(spec: Spec, sidecarProtocol: string): string | u
 export declare const STORAGE_SINCE: readonly [number, number];
 /** Every problem the sidecar has reported to this process, in order. */
 export declare const problems: string[];
-export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void): void;
+/** What discovery needs beside the spec to judge personal data (1.23), and to start following its notices. */
+export interface PersonalDiscovery {
+    /** The components and endpoints whose shapes hold a personal field. */
+    readonly users: () => readonly string[];
+    /** Told the runtime's protocol once discovery has been answered. */
+    readonly discovered?: (protocolVersion: string) => void;
+}
+export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void, personal?: PersonalDiscovery): void;
 /** The protocol version whose runtimes serve socket routes. */
 export declare const SOCKETS_SINCE: readonly [number, number];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
@@ -21,6 +28,11 @@ export declare const GRANTS_SINCE: readonly [number, number];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
  * does not know `Callers.granted`, and would admit nobody by it. */
 export declare function grantsRefusal(spec: Spec, runtime: string): string | undefined;
+/** The protocol version whose runtimes serve a subject's key, its notices and the erasure handler. */
+export declare const PERSONAL_SINCE: readonly [number, number];
+/** Why a service with personal fields (`users`) or an erasure handler cannot run on a runtime speaking
+ * `runtime`, or undefined. A runtime before 1.23 has no keyring to ask and would never call the handler. */
+export declare function personalRefusal(spec: Spec, users: readonly string[], runtime: string): string | undefined;
 /** The protocol version whose runtimes serve a process's MCP endpoint. */
 export declare const MCP_SINCE: readonly [number, number];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20

package/dist/server/discovery.js

@@ -142,7 +142,7 @@ function startPositionRefusal(spec, sidecarProtocol) {
 export const STORAGE_SINCE = [1, 21];
 /** Every problem the sidecar has reported to this process, in order. */
 export const problems = [];
-export function discoveryRoutes(router, spec, log = console.error) {
+export function discoveryRoutes(router, spec, log = console.error, personal) {
     router.service(Discovery, {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
@@ -157,12 +157,14 @@ export function discoveryRoutes(router, spec, log = console.error) {
                 socketRefusal(answer, info.protocolVersion) ??
                 grantsRefusal(answer, info.protocolVersion) ??
                 // Last: an older runtime is told the oldest thing it lacks first.
-                mcpRefusal(answer, info.protocolVersion);
+                mcpRefusal(answer, info.protocolVersion) ??
+                personalRefusal(answer, personal?.users() ?? [], info.protocolVersion);
             if (why !== undefined) {
                 log(`ankka: ${why}`);
                 problems.push(why);
                 throw new ConnectError(why, Code.FailedPrecondition);
             }
+            personal?.discovered?.(info.protocolVersion);
             return answer;
         },
         async reportError(problem) {
@@ -211,6 +213,16 @@ export function grantsRefusal(spec, runtime) {
         return undefined;
     return `this runtime speaks protocol ${runtime || "unknown"}; granted callers and another project's topics need 1.15 (${endpoints.join(", ")})`;
 }
+/** The protocol version whose runtimes serve a subject's key, its notices and the erasure handler. */
+export const PERSONAL_SINCE = [1, 23];
+/** Why a service with personal fields (`users`) or an erasure handler cannot run on a runtime speaking
+ * `runtime`, or undefined. A runtime before 1.23 has no keyring to ask and would never call the handler. */
+export function personalRefusal(spec, users, runtime) {
+    const what = [...users, ...(spec.erasureHandler ? ["the erasure handler"] : [])];
+    if (what.length === 0 || !olderThan(runtime, PERSONAL_SINCE))
+        return undefined;
+    return `personal fields need protocol 1.23: this runtime speaks ${runtime || "unknown"}, and this SDK ${PROTOCOL_VERSION} (${what.join(", ")})`;
+}
 /** The protocol version whose runtimes serve a process's MCP endpoint. */
 export const MCP_SINCE = [1, 20];
 /** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.20

package/dist/server/erasure.d.ts

@@ -0,0 +1,7 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type ErasureCall, type ErasureReply } from "../_proto/ankka/protocol/v1/erasure_pb.ts";
+import { type ErasureHandler } from "../erasure.ts";
+import type { ServerContext } from "./server.ts";
+/** Runs the service's handler for one call; the Connect servicer and the unit tests both call it. */
+export declare function invokeErasure(handler: ErasureHandler | undefined, call: ErasureCall, ctx: ServerContext): Promise<ErasureReply>;
+export declare function erasureRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/erasure.js

@@ -0,0 +1,40 @@
+// The `Erasure` service (protocol 1.23, feature 042): the sidecar asks this process to run its erasure
+// handler for one erased data subject. A handler that throws answers an `Error`, which the platform
+// records as a failed run and runs again on the next pass; it is never a gRPC status.
+import { create } from "@bufbuild/protobuf";
+import { Erasure, ErasureReplySchema } from "../_proto/ankka/protocol/v1/erasure_pb.js";
+import { secretsFor } from "../client.js";
+import { metadataFromProto } from "../context.js";
+import { CommandError, ErrorCode } from "../effects/common.js";
+import { erasuresFor } from "../erasures.js";
+import { finalityToProto } from "../erasure.js";
+import { errorCodeToProto } from "../kinds.js";
+import { subjectProblem } from "../personal.js";
+import { processStorage } from "../storage.js";
+function failed(message, code = ErrorCode.Internal) {
+    return create(ErasureReplySchema, { objectsErased: 0n, finality: "", error: { message, code: errorCodeToProto(code) } });
+}
+/** Runs the service's handler for one call; the Connect servicer and the unit tests both call it. */
+export async function invokeErasure(handler, call, ctx) {
+    if (!handler)
+        return failed("this service declares no erasure handler", ErrorCode.NotFound);
+    const problem = subjectProblem(call.subject);
+    if (problem !== undefined)
+        return failed(problem, ErrorCode.BadRequest);
+    const metadata = metadataFromProto(call.metadata);
+    const client = ctx.client.withMetadata(metadata);
+    try {
+        const report = (await handler({ client, secrets: secretsFor(client), storage: ctx.storage ?? processStorage(), erasures: erasuresFor(client), erasureSeq: call.erasureSeq, rerun: call.rerun, metadata }, call.subject)) ?? {};
+        const count = report.objectsErased ?? 0;
+        return create(ErasureReplySchema, { objectsErased: BigInt(count), finality: finalityToProto(report.finality) });
+    }
+    catch (e) {
+        ctx.log(`ankka: the erasure handler failed for '${call.subject}': ${e instanceof Error ? e.message : String(e)}`);
+        return failed(e instanceof Error ? e.message : String(e), e instanceof CommandError ? e.code : ErrorCode.Internal);
+    }
+}
+export function erasureRoutes(router, ctx) {
+    router.service(Erasure, {
+        invoke: (call) => invokeErasure(ctx.registry.erasureHandler, call, ctx),
+    });
+}

package/dist/server/eventSourced.js

@@ -14,7 +14,8 @@ import { ErrorCode } from "../effects/common.js";
 import { binaryCodecs } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { materialiseEventSourced } from "../materialise.js";
-import { decodePayload, encodePayload } from "./payloads.js";
+import { PersonalError } from "../personal.js";
+import { decodePayload, encodePayload, prefetchPayload, prefetchPayloadAt, prefetchValue, prefetchValueAt } from "./payloads.js";
 /** A replicated entity's handover or change to its replication set, as the reply carries it (1.19). */
 export function replicationToProto(change) {
     if (!change)
@@ -53,11 +54,16 @@ export async function* handleEventSourced(requests, ctx) {
     let sequence = 0n;
     // This installation, for a replicated entity (1.19): null on a service that names none.
     let here = null;
+    // The entity's home as its records have named it so far (FR-032): Init.home, then each folded
+    // event's installation, then Command.home. Its personal fields' keys are that installation's.
+    let home = null;
+    const keysAt = () => (home === null || home === here ? "" : home);
     for await (const m of requests) {
         switch (m.message.case) {
             case "init": {
                 const init = m.message.value;
                 here = init.installation || null;
+                home = init.home || null;
                 const found = ctx.registry.component(init.componentId);
                 if (!found || found.kind !== "event-sourced") {
                     yield failure(0n, { message: `no event sourced entity ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound });
@@ -65,11 +71,12 @@ export async function* handleEventSourced(requests, ctx) {
                 }
                 registered = found;
                 entityId = init.entityId;
+                await prefetchPayloadAt(keysAt(), init.snapshot?.payload);
                 try {
                     entity = new registered.cls();
                     entity._bindInstance(entityId);
                     if (init.snapshot) {
-                        state = decodePayload(registered.stateCodec, init.snapshot.payload);
+                        state = decodePayload(registered.stateCodec, init.snapshot.payload, keysAt());
                         sequence = init.snapshot.sequence;
                     }
                     else {
@@ -90,9 +97,13 @@ export async function* handleEventSourced(requests, ctx) {
                     return;
                 }
                 const ev = m.message.value;
+                // A record from before replication names no installation, and reads as written at the home.
+                if (ev.installation)
+                    home = ev.installation;
+                await prefetchPayloadAt(keysAt(), ev.payload);
                 try {
                     const written = ev.installation || here;
-                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload), eventContext(written, written === here, ev.sequence, ev.attribution, ev.forwardedFrom));
+                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload, keysAt()), eventContext(written, written === here, ev.sequence, ev.attribution, ev.forwardedFrom));
                     sequence = ev.sequence;
                 }
                 catch (e) {
@@ -107,7 +118,9 @@ export async function* handleEventSourced(requests, ctx) {
                     yield failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal });
                     return;
                 }
-                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx, here);
+                if (m.message.value.home)
+                    home = m.message.value.home;
+                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx, here, keysAt());
                 yield result.out;
                 if (result.newState !== undefined) {
                     state = result.newState.state;
@@ -120,11 +133,12 @@ export async function* handleEventSourced(requests, ctx) {
         }
     }
 }
-async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx, here = null) {
+async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx, here = null, keys = "") {
     const handler = registered.handlers.get(cmd.name);
     if (!handler)
         return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
     let input;
+    await prefetchPayload(cmd.payload);
     try {
         input = handler.input ? decodePayload(codecFor(handler.input), cmd.payload) : undefined;
     }
@@ -154,8 +168,11 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
             applied += 1n;
             return entity.applyEvent(s, e, eventContext(here, true, applied, context.attribution, context.forwardedFrom));
         });
+        // What is persisted, and the snapshot, are the record's: sealed with its home's keys (FR-032).
+        await prefetchValueAt(keys, m.events, cmd.snapshotRequested ? m.newState : undefined);
+        await prefetchValue(m.reply);
         const replication = !m.error && effect.kind === "persist" ? replicationToProto(effect.replication) : undefined;
-        const events = m.events.map((e) => encodePayload(registered.eventCodec, e));
+        const events = m.events.map((e) => encodePayload(registered.eventCodec, e, keys));
         const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
         const outcome = m.error
             ? { outcome: { case: "error", value: { message: m.error.message, code: errorCodeToProto(m.error.code) } } }
@@ -170,7 +187,7 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
                     events,
                     retention: retentionToProto(m.retention),
                     outcome,
-                    snapshot: cmd.snapshotRequested ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                    snapshot: cmd.snapshotRequested ? encodePayload(registered.stateCodec, m.newState, keys) : undefined,
                     replication,
                 },
             },
@@ -181,6 +198,6 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
     }
     catch (e) {
         ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
-        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+        return { out: failure(cmd.id, { message: messageOf(e), code: e instanceof PersonalError ? e.code : ErrorCode.Internal }) };
     }
 }

package/dist/server/keyValue.js

@@ -8,7 +8,8 @@ import { ErrorCode } from "../effects/common.js";
 import { errorCodeToProto } from "../kinds.js";
 import { materialiseKeyValue } from "../materialise.js";
 import { retentionToProto } from "./eventSourced.js";
-import { decodePayload, encodePayload } from "./payloads.js";
+import { PersonalError } from "../personal.js";
+import { decodePayload, encodePayload, prefetchPayload, prefetchValue } from "./payloads.js";
 function failure(commandId, error) {
     return create(KeyValueOutSchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
 }
@@ -36,6 +37,7 @@ export async function* handleKeyValue(requests, ctx) {
                 }
                 registered = found;
                 entityId = init.entityId;
+                await prefetchPayload(init.state);
                 try {
                     entity = new registered.cls();
                     entity._bindInstance(entityId);
@@ -69,6 +71,7 @@ async function runCommand(registered, entity, entityId, state, cmd, ctx) {
     if (!handler)
         return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
     let input;
+    await prefetchPayload(cmd.payload);
     try {
         input = handler.input ? decodePayload(codecFor(handler.input), cmd.payload) : undefined;
     }
@@ -94,6 +97,7 @@ async function runCommand(registered, entity, entityId, state, cmd, ctx) {
     }
     try {
         const m = materialiseKeyValue(effect, state);
+        await prefetchValue(m.reply, m.changed ? m.newState : undefined);
         const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
         const outcome = m.error
             ? { outcome: { case: "error", value: { message: m.error.message, code: errorCodeToProto(m.error.code) } } }
@@ -117,6 +121,6 @@ async function runCommand(registered, entity, entityId, state, cmd, ctx) {
     }
     catch (e) {
         ctx.log(`ankka: ${registered.id}/${entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
-        return { out: failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal }) };
+        return { out: failure(cmd.id, { message: messageOf(e), code: e instanceof PersonalError ? e.code : ErrorCode.Internal }) };
     }
 }

package/dist/server/payloads.d.ts

@@ -1,6 +1,14 @@
 import { type Payload } from "../_proto/ankka/protocol/v1/payload_pb.ts";
 import type { Codec } from "../codec.ts";
-export declare function encodePayload<T>(codec: Codec<T>, value: T): Payload;
+export declare function encodePayload<T>(codec: Codec<T>, value: T, home?: string): Payload;
 /** Decodes a payload with `codec`. An absent payload is the empty payload, which is what `unit` and `done` are. */
-export declare function decodePayload<T>(codec: Codec<T>, payload: Payload | undefined): T;
+export declare function decodePayload<T>(codec: Codec<T>, payload: Payload | undefined, home?: string): T;
+/** Fetches the keys every personal envelope in these payloads needs. Never throws. */
+export declare function prefetchPayload(...payloads: (Payload | undefined)[]): Promise<void>;
+/** Fetches, from `home`'s keyring, the keys every personal envelope in these payloads needs. Never throws. */
+export declare function prefetchPayloadAt(home: string, ...payloads: (Payload | undefined)[]): Promise<void>;
+/** Fetches the keys every personal field in these values needs to be written. Never throws. */
+export declare function prefetchValue(...values: unknown[]): Promise<void>;
+/** Fetches, from `home`'s keyring, the keys every personal field in these values needs to be written. Never throws. */
+export declare function prefetchValueAt(home: string, ...values: unknown[]): Promise<void>;
 export declare const EMPTY_PAYLOAD: Payload;