ankka 0.15.0 → 0.16.0

package/dist/consumer.js

@@ -3,6 +3,7 @@ import { secretsFor } from "./client.js";
 import { processStorage } from "./storage.js";
 import { ConsumerEffects } from "./effects/stateless.js";
 import { servicesFor } from "./services.js";
+import { erasuresFor } from "./erasures.js";
 /** The metadata entry a runtime sets on a consumer's request to say what it speaks: its protocol version. */
 export const PROTOCOL_KEY = "ankka.protocol";
 /** Thrown when a consumer answers with several messages, or a record key, to a runtime that would drop them. */
@@ -89,6 +90,15 @@ export class Consumer {
     set services(services) {
         this.#services = services;
     }
+    #erasures;
+    /** Asks for erasure requests as this service (1.23), which needs the project's `erasure` grant. */
+    get erasures() {
+        return this.#erasures ?? erasuresFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.erasures = new Erasures(client)`. */
+    set erasures(erasures) {
+        this.#erasures = erasures;
+    }
     /** @internal */
     get _kind() {
         return "consumer";

package/dist/endpoint.d.ts

@@ -4,6 +4,7 @@ import { type Buckets } from "./storage.ts";
 import { type RequestContext } from "./context.ts";
 import type { Acl, RouteTable } from "./routes.ts";
 import { type Services } from "./services.ts";
+import { type Erasures } from "./erasures.ts";
 export declare abstract class Endpoint {
     #private;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
@@ -22,6 +23,10 @@ export declare abstract class Endpoint {
     get services(): Services;
     /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
     set services(services: Services);
+    /** Asks for erasure requests as this service (1.23), which needs the project's `erasure` grant. */
+    get erasures(): Erasures;
+    /** A unit test's in place of the runtime's: `component.erasures = new Erasures(client)`. */
+    set erasures(erasures: Erasures);
     /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
     get clientKeys(): ClientKeys;
     /** A unit test's in place of the runtime's: `component.clientKeys = new InMemoryClientKeys()`. */

package/dist/endpoint.js

@@ -13,6 +13,7 @@ import { secretsFor } from "./client.js";
 import { processStorage } from "./storage.js";
 import { currentRequest, requestIfAny } from "./context.js";
 import { servicesFor } from "./services.js";
+import { erasuresFor } from "./erasures.js";
 export class Endpoint {
     #client;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
@@ -53,6 +54,15 @@ export class Endpoint {
     set services(services) {
         this.#services = services;
     }
+    #erasures;
+    /** Asks for erasure requests as this service (1.23), which needs the project's `erasure` grant. */
+    get erasures() {
+        return this.#erasures ?? erasuresFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.erasures = new Erasures(client)`. */
+    set erasures(erasures) {
+        this.#erasures = erasures;
+    }
     #clientKeys;
     /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
     get clientKeys() {

package/dist/erasure.d.ts

@@ -0,0 +1,35 @@
+import type { ComponentClient, Secrets } from "./client.ts";
+import type { Metadata } from "./effects/common.ts";
+import type { Erasures } from "./erasures.ts";
+import type { DataSubject } from "./personal.ts";
+import type { Buckets } from "./storage.ts";
+import type { Duration } from "./time.ts";
+/** What a handler is given beside the subject. */
+export interface ErasureContext {
+    readonly client: ComponentClient;
+    readonly secrets: Secrets;
+    /** The service's buckets. */
+    readonly storage: Buckets;
+    /** Asks for erasure requests as this service (1.23). */
+    readonly erasures: Erasures;
+    /** The erasure's sequence number in the keyring. */
+    readonly erasureSeq: bigint;
+    /** Whether this is a re-run of a handler that already ran for this subject. */
+    readonly rerun: boolean;
+    readonly metadata: Metadata;
+}
+/** When what the handler erased is gone: at once, or after the store's own retention. */
+export type Finality = {
+    readonly kind: "immediate";
+} | {
+    readonly kind: "after";
+    readonly after: Duration;
+};
+/** What a handler reports: how many objects it erased, and when they are gone. */
+export interface ErasureReport {
+    readonly objectsErased?: number | bigint;
+    readonly finality?: Finality;
+}
+export type ErasureHandler = (ctx: ErasureContext, subject: DataSubject) => Promise<ErasureReport | void> | ErasureReport | void;
+/** The finality as the protocol carries it: `immediate`, or `after:` and an ISO-8601 duration. */
+export declare function finalityToProto(finality: Finality | undefined): string;

package/dist/erasure.js

@@ -0,0 +1,10 @@
+// The erasure handler (feature 042): what the platform cannot erase for the service, such as objects in
+// a bucket. `service.erasureHandler(async (ctx, subject) => …)`; one per service. The sidecar calls it
+// for each erased data subject and again on each re-run within the window, so it must be idempotent. A
+// handler that throws is recorded as failed for that run and run again on the next.
+/** The finality as the protocol carries it: `immediate`, or `after:` and an ISO-8601 duration. */
+export function finalityToProto(finality) {
+    if (finality === undefined || finality.kind === "immediate")
+        return "immediate";
+    return `after:${finality.after.toString()}`;
+}

package/dist/erasures.d.ts

@@ -0,0 +1,32 @@
+import { type ComponentClient } from "./client.ts";
+import type { LocalDate } from "./time.ts";
+/** The first protocol whose sidecar asks for an erasure request; an older one answers `UNIMPLEMENTED`. */
+export declare const ERASURES_SINCE = "1.23";
+/** What to ask: whose personal data, where, and from when. */
+export interface AskErasure {
+    readonly subject: string;
+    /** The project to erase in; this service's own when absent. */
+    readonly project?: string;
+    /** Held until this date; sent as ISO-8601 (`2027-01-31`). */
+    readonly notBefore?: LocalDate;
+    readonly reason?: string;
+    readonly correlation?: string;
+}
+/** An erasure request as asked: its id in its project and its state (held, applying, applied). */
+export interface ErasureAsked {
+    readonly id: string;
+    readonly state: string;
+}
+/**
+ * Asks for erasure requests as this service. A refusal is a `CommandError` with the control plane's
+ * code: `FORBIDDEN` without the `erasure` grant, `CONFLICT` while erasure is off in the project,
+ * `BAD_REQUEST` for a subject outside the rule.
+ */
+export declare class Erasures {
+    #private;
+    /** Asked through `client`'s sidecar; with none, every ask throws. */
+    constructor(client?: ComponentClient);
+    ask(request: AskErasure): Promise<ErasureAsked>;
+}
+/** @internal The erasures reached through `client`'s sidecar. */
+export declare function erasuresFor(client: ComponentClient): Erasures;

package/dist/erasures.js

@@ -0,0 +1,65 @@
+// Asking for an erasure request from code (feature 042, protocol 1.23): `this.erasures.ask({ subject })`
+// in an endpoint or a consumer, `ctx.erasures.ask(...)` in the erasure handler. The request is asked of
+// the control plane as this service, through the sidecar's `Client.AskErasure`; the service needs the
+// `erasure` grant of the project it asks in, its own included, and is named as who asked.
+//
+//   const asked = await this.erasures.ask({ subject: "customer-42", notBefore: LocalDate.of(2027, 1, 31), reason: "aml-retention" })
+//   asked.id, asked.state   // "held", "applying" or "applied"
+import { Code, ConnectError } from "@connectrpc/connect";
+import { channelOf } from "./client.js";
+import { metadataToProto } from "./context.js";
+import { CommandError, ErrorCode } from "./effects/common.js";
+import { errorCodeFromProto } from "./kinds.js";
+import { PROTOCOL_VERSION } from "./spec.js";
+/** The first protocol whose sidecar asks for an erasure request; an older one answers `UNIMPLEMENTED`. */
+export const ERASURES_SINCE = "1.23";
+/**
+ * Asks for erasure requests as this service. A refusal is a `CommandError` with the control plane's
+ * code: `FORBIDDEN` without the `erasure` grant, `CONFLICT` while erasure is off in the project,
+ * `BAD_REQUEST` for a subject outside the rule.
+ */
+export class Erasures {
+    #client;
+    /** Asked through `client`'s sidecar; with none, every ask throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    async ask(request) {
+        const channel = this.#client ? channelOf(this.#client) : undefined;
+        if (!channel)
+            throw new Error("these erasures are not connected to a runtime; a unit test assigns its own");
+        const reply = await channel
+            .stub()
+            .askErasure({
+            project: request.project ?? "",
+            subject: request.subject,
+            ...(request.notBefore !== undefined ? { notBefore: request.notBefore.toString() } : {}),
+            ...(request.reason !== undefined ? { reason: request.reason } : {}),
+            ...(request.correlation !== undefined ? { correlation: request.correlation } : {}),
+            metadata: metadataToProto(channel.metadata),
+        })
+            .catch((failure) => {
+            if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+                throw new CommandError({
+                    message: `the runtime beside this process cannot ask for an erasure, which needs protocol ${ERASURES_SINCE}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+                    code: ErrorCode.Internal,
+                });
+            }
+            throw failure;
+        });
+        switch (reply.reply.case) {
+            case "ok":
+                return Object.freeze({ id: reply.reply.value.id, state: reply.reply.value.state });
+            case "error": {
+                const error = reply.reply.value;
+                throw new CommandError({ message: error.message, code: errorCodeFromProto(error.code), details: { ...(error.details ?? {}) } });
+            }
+            default:
+                throw new CommandError({ message: "the runtime answered an erasure request with nothing", code: ErrorCode.Internal });
+        }
+    }
+}
+/** @internal The erasures reached through `client`'s sidecar. */
+export function erasuresFor(client) {
+    return new Erasures(client);
+}

package/dist/graph.d.ts

@@ -4,6 +4,7 @@ import type { EffectLike, Metadata } from "./effects/common.ts";
 import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
 import { type Buckets } from "./storage.ts";
 import { type Services } from "./services.ts";
+import { type Erasures } from "./erasures.ts";
 import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** The contract's name: the manifest and the `ce-type` of every delta. */
@@ -155,6 +156,10 @@ export declare abstract class GraphConsumer<M> {
     get services(): Services;
     /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
     set services(services: Services);
+    /** Asks for erasure requests as this service (1.23), which needs the project's `erasure` grant. */
+    get erasures(): Erasures;
+    /** A unit test's in place of the runtime's: `component.erasures = new Erasures(client)`. */
+    set erasures(erasures: Erasures);
     /** @internal */
     get _kind(): "consumer";
     abstract onMessage(message: M): MaybePromise<GraphEffect>;

package/dist/graph.js

@@ -20,6 +20,7 @@ import { processStorage } from "./storage.js";
 import { sequenceNumberOf } from "./consumer.js";
 import { renderDouble, reviver } from "./json.js";
 import { servicesFor } from "./services.js";
+import { erasuresFor } from "./erasures.js";
 /** The contract's name: the manifest and the `ce-type` of every delta. */
 export const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
 /** The record key of every delta for the node `id`. */
@@ -445,6 +446,15 @@ export class GraphConsumer {
     set services(services) {
         this.#services = services;
     }
+    #erasures;
+    /** Asks for erasure requests as this service (1.23), which needs the project's `erasure` grant. */
+    get erasures() {
+        return this.#erasures ?? erasuresFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.erasures = new Erasures(client)`. */
+    set erasures(erasures) {
+        this.#erasures = erasures;
+    }
     /** @internal */
     get _kind() {
         return "consumer";

package/dist/index.d.ts

@@ -27,11 +27,12 @@ export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, reje
 export { Endpoint, type EndpointClass } from "./endpoint.ts";
 export { McpEndpoint, ToolTable, tools, MCP_ENDPOINTS_SINCE, type McpEndpointClass, type DeclaredTool, type ToolOptions, type ReferenceOptions, type RegisteredMcpEndpoint, type RegisteredMcpTool, type ToolRun, } from "./mcp-endpoint.ts";
 export { ClientKeys, InMemoryClientKeys, Expiry, CLIENT_KEYS_SINCE, type IssueClientKey, type IssuedClientKey, type ClientKeySummary, } from "./client-keys.ts";
+export { Erasures, ERASURES_SINCE, type AskErasure, type ErasureAsked } from "./erasures.ts";
 export { type Socket, SocketClosed } from "./socket.ts";
 export { Acl, Callers, type CallerMatcher, type CallersAcl, type AnyOfAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
 export { type CommandContext, type EventContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
 export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE, type AwaitPart, type WatchEvent, type WatchOptions, type Overflow, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
-export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, type Buckets, type Bucket, type BucketExposure, type SignedAccess, type StoredObject, type ObjectInfo, type ObjectEntry, type PutOptions, type InMemoryBucketsOptions, type DirectoryBucketsOptions, type DeclaredBuckets, type S3Settings, type S3Target, type NamedTarget, type StorageBackend, type ChosenStorage, type StorageChoiceOptions, } from "./storage.ts";
+export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, subjectPrefix, parseVersions, type ErasedObjects, type VersionsPage, type Buckets, type Bucket, type BucketExposure, type SignedAccess, type StoredObject, type ObjectInfo, type ObjectEntry, type PutOptions, type InMemoryBucketsOptions, type DirectoryBucketsOptions, type DeclaredBuckets, type S3Settings, type S3Target, type NamedTarget, type StorageBackend, type ChosenStorage, type StorageChoiceOptions, } from "./storage.ts";
 export { Credentials, SignedRequest, sign as signRequest, presign as presignUrl } from "./sigv4.ts";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, type ServiceResponse, type ServiceRequest, type ServiceHeaders, } from "./services.ts";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredKeyedView, type RegisteredKeyedSource, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
@@ -43,3 +44,6 @@ export { StartFrom } from "./startFrom.ts";
 export { isTerminal, isUnknown, type Standing, type StandingStatus } from "./standing.ts";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
 export type { ComponentKind } from "./kinds.ts";
+export { personal, subject, subjectProblem, isPersonal, Present, Erased, PersonalError, DATA_SUBJECT_RULE, type Personal, type DataSubject, type PersonalReason, } from "./personal.ts";
+export { Keyring, currentKeyring, keyringSettings, DEFAULT_KEYRING_SETTINGS, type KeyAnswer, type KeyFetch, type KeyReply, type KeyringOptions, type KeyringSettings } from "./keyring.ts";
+export { finalityToProto, type ErasureContext, type ErasureHandler, type ErasureReport, type Finality } from "./erasure.ts";

package/dist/index.js

@@ -38,11 +38,12 @@ export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, reje
 export { Endpoint } from "./endpoint.js";
 export { McpEndpoint, ToolTable, tools, MCP_ENDPOINTS_SINCE, } from "./mcp-endpoint.js";
 export { ClientKeys, InMemoryClientKeys, Expiry, CLIENT_KEYS_SINCE, } from "./client-keys.js";
+export { Erasures, ERASURES_SINCE } from "./erasures.js";
 export { SocketClosed } from "./socket.js";
 export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, socket } from "./routes.js";
 export { Query, Headers } from "./context.js";
 export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE } from "./client.js";
-export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, } from "./storage.js";
+export { ObjectRules, StorageRefusals, InMemoryBuckets, DirectoryBuckets, S3Buckets, S3Bucket, noStorage, chooseStorage, declaredBuckets, processStorage, s3Settings, bucketNameOf, bucketVariableSuffix, localAddress, STORAGE_PATH, subjectPrefix, parseVersions, } from "./storage.js";
 export { Credentials, SignedRequest, sign as signRequest, presign as presignUrl } from "./sigv4.js";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, } from "./services.js";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";
@@ -53,3 +54,6 @@ export { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
 export { StartFrom } from "./startFrom.js";
 export { isTerminal, isUnknown } from "./standing.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";
+export { personal, subject, subjectProblem, isPersonal, Present, Erased, PersonalError, DATA_SUBJECT_RULE, } from "./personal.js";
+export { Keyring, currentKeyring, keyringSettings, DEFAULT_KEYRING_SETTINGS } from "./keyring.js";
+export { finalityToProto } from "./erasure.js";

package/dist/json.js

@@ -7,6 +7,8 @@
 // schema-directed decode that converts, checks and names the path of anything it refuses.
 import { Duration, Instant, LocalDate, LocalDateTime } from "./time.js";
 import { done, resolve, describe } from "./schema.js";
+import { associatedData, currentScope, Erased, ENVELOPE_VERSION, open, originOf, PersonalError, Present, readFrom, seal, subjectProblem } from "./personal.js";
+import { requireKeyring } from "./keyring.js";
 export class EncodingError extends Error {
     constructor(message) {
         super(message);
@@ -188,8 +190,69 @@ function write(schema, value, out, path) {
             out.push(`{"type":${JSON.stringify(value)}}`);
             return;
         }
+        case "personal": {
+            if (!(value instanceof Present) && !(value instanceof Erased)) {
+                throw new EncodingError(`${at(path)}expected a personal field (personal(subject, value)), got ${kindOf(value)}`);
+            }
+            const problem = subjectProblem(value.subject);
+            if (problem !== undefined)
+                throw new EncodingError(`${at(path)}${problem}`);
+            const scope = currentScope();
+            if (scope === undefined) {
+                // The edge: the value with its subject beside it.
+                out.push(`{"subject":${JSON.stringify(value.subject)}`);
+                if (value instanceof Present) {
+                    out.push(`,"value":`);
+                    write(r.inner, value.value, out, path ? `${path}.value` : "value");
+                }
+                out.push("}");
+            }
+            else
+                writeEnvelope(r.inner, value, scope, out, path);
+            return;
+        }
+    }
+}
+function writeEnvelope(inner, value, scope, out, path) {
+    let project;
+    let c;
+    const origin = originOf(value);
+    if (origin !== undefined && origin !== requireKeyring().project) {
+        // Read from another project's envelope: kept under that project's key (FR-027), so an erasure
+        // there reaches what this service keeps of it, with no notice of its own. A key it can no longer
+        // have writes the field erased, as it would now be read.
+        project = origin;
+        if (value instanceof Present) {
+            const answer = requireKeyring().keyForRead(origin, value.subject);
+            if (answer.kind === "key") {
+                const plaintext = [];
+                write(inner, value.value, plaintext, path);
+                c = base64Encode(seal(answer.key, utf8.encode(plaintext.join("")), associatedData(value.subject, origin, scope.manifest), scope.nonce));
+            }
+        }
+    }
+    else if (value instanceof Present) {
+        const { project: own, key } = requireKeyring().keyForWrite(value.subject);
+        project = own;
+        const plaintext = [];
+        write(inner, value.value, plaintext, path);
+        const sealed = seal(key, utf8.encode(plaintext.join("")), associatedData(value.subject, project, scope.manifest), scope.nonce);
+        c = base64Encode(sealed);
+    }
+    else {
+        // Written again after a redaction: the subject alone, under the service's own project.
+        const keyring = requireKeyring();
+        if (keyring.project === undefined)
+            throw PersonalError.unavailable("this process does not know its project yet: no key answer from the sidecar has named it");
+        project = keyring.project;
     }
+    out.push(`{"$personal":${ENVELOPE_VERSION},"project":${JSON.stringify(project)},"subject":${JSON.stringify(value.subject)}`);
+    if (c !== undefined)
+        out.push(`,"c":${JSON.stringify(c)}`);
+    out.push("}");
 }
+const utf8 = new TextEncoder();
+const utf8Strict = new TextDecoder("utf-8", { fatal: true });
 function writeFields(fields, value, out, path, continuing) {
     let first = !continuing;
     for (const [name, field] of Object.entries(fields)) {
@@ -314,7 +377,54 @@ function decode(schema, raw, path) {
             }
             return name;
         }
+        case "personal":
+            return currentScope() === undefined ? decodeEdge(r.inner, raw, path) : decodeEnvelope(r.inner, raw, currentScope(), path);
+    }
+}
+function decodeEdge(inner, raw, path) {
+    if (!isPlainObject(raw))
+        throw new DecodingError(`expected a personal field {"subject", "value"}, got ${kindOf(raw)}`, path);
+    const about = raw["subject"];
+    if (about === undefined)
+        throw new DecodingError("a personal field names its data subject", path);
+    const problem = subjectProblem(about);
+    if (problem !== undefined)
+        throw new DecodingError(problem, path ? `${path}.subject` : "subject");
+    if (!("value" in raw))
+        return new Erased(about);
+    return new Present(about, decode(inner, raw["value"], path ? `${path}.value` : "value"));
+}
+function decodeEnvelope(inner, raw, scope, path) {
+    if (!isPlainObject(raw))
+        throw new DecodingError(`expected a personal envelope, got ${kindOf(raw)}`, path);
+    const { project, subject: about, c } = raw;
+    if (typeof about !== "string" || typeof project !== "string")
+        throw new DecodingError("a personal envelope names its project and its data subject", path);
+    const problem = subjectProblem(about);
+    if (problem !== undefined)
+        throw new DecodingError(problem, path ? `${path}.subject` : "subject");
+    const s = about;
+    if (raw["$personal"] !== ENVELOPE_VERSION) {
+        throw PersonalError.corrupt(about, `its version is ${String(raw["$personal"])}, and this reader knows ${ENVELOPE_VERSION}`);
+    }
+    if (c === undefined)
+        return readFrom(new Erased(s), project);
+    const answer = requireKeyring().keyForRead(project, about);
+    if (answer.kind === "erased")
+        return readFrom(new Erased(s), project);
+    if (typeof c !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(c))
+        throw PersonalError.corrupt(about, "it is not base64");
+    const plaintext = open(answer.key, base64Decode(c), associatedData(about, project, scope.manifest));
+    if (plaintext === undefined)
+        throw PersonalError.corrupt(about, "it failed authentication");
+    let parsed;
+    try {
+        parsed = JSON.parse(utf8Strict.decode(plaintext), reviver);
+    }
+    catch {
+        throw PersonalError.corrupt(about, "its plaintext is not JSON");
     }
+    return readFrom(new Present(s, decode(inner, parsed, path)), project);
 }
 function decodeFields(fields, raw, path) {
     const out = {};

package/dist/keyring.d.ts

@@ -0,0 +1,119 @@
+/** What the keyring answered for one data subject. */
+export type KeyAnswer = {
+    readonly kind: "key";
+    readonly key: Uint8Array;
+} | {
+    readonly kind: "erased";
+};
+/** A key answer and the project it is for: the service's own when the request left `project` empty. */
+export interface KeyReply {
+    readonly project: string;
+    readonly answer: KeyAnswer;
+}
+/**
+ * How a key is fetched: `project` empty is the service's own, and `create` makes one for a write.
+ * `home`, when given, is the installation whose keyring keeps the key: a replicated entity's home
+ * elsewhere (FR-032), asked through the sidecar's relay and never with `create`.
+ */
+export type KeyFetch = (project: string, subject: string, create: boolean, home?: string) => Promise<KeyReply>;
+/**
+ * How a process holds the keys it fetched: the runtime's `ankka.keyring` settings, by the same names
+ * and defaults, in milliseconds. `keyringSettings` refuses one that breaks a rule, naming it.
+ */
+export interface KeyringSettings {
+    /** `ankka.keyring.cache.max-keys`: how many keys are held at once; the least recently used goes first. */
+    readonly maxKeys: number;
+    /** `ankka.keyring.cache.ttl`: how long a key of the own project is held before it is asked for again. */
+    readonly ttlMillis: number;
+    /** `ankka.keyring.cache.foreign-ttl`: how long a key of another project, or a read's erased answer, is held. */
+    readonly foreignTtlMillis: number;
+    /** `ankka.keyring.cache.outage-bound`: how long after its fetch a held own key serves while the keyring cannot be reached. */
+    readonly outageBoundMillis: number;
+    /** `ankka.keyring.notice-bound`: the bound on an erasure reaching a read, which the outage bound may not exceed. */
+    readonly noticeBoundMillis: number;
+}
+export declare const DEFAULT_KEYRING_SETTINGS: KeyringSettings;
+/** The defaults with `given` over them; throws a `RangeError` naming the setting a value breaks. */
+export declare function keyringSettings(given?: Partial<KeyringSettings>): KeyringSettings;
+export interface KeyringOptions {
+    readonly fetch: KeyFetch;
+    readonly settings?: Partial<KeyringSettings>;
+    /** Milliseconds now; a test moves it. */
+    readonly clock?: () => number;
+}
+/**
+ * The process's key cache, under the runtime's rules: at most `maxKeys`, the least recently used going
+ * first; a key of the own project fresh for `ttl`, and still served while the keyring cannot be reached
+ * until `outageBound` after it was fetched; a key of another project, which no notice of that project
+ * reaches, and a read's erased answer, for `foreignTtl` and no longer. A write's erased answer is a
+ * destroyed key, which never changes. An answer whose fetch was in flight when a notice dropped its
+ * subject may be the destroyed key: it is never cached, and the key is asked for again.
+ */
+export declare class Keyring {
+    #private;
+    constructor(options: KeyringOptions);
+    /** The service's own project, as the first key answer for it named it; `undefined` until then. */
+    get project(): string | undefined;
+    get settings(): KeyringSettings;
+    /** How many answers are held. */
+    get size(): number;
+    /**
+     * `work`, run with the keys of `home`'s keyring: a replicated entity's home as its records name it
+     * (FR-032), "" for this installation's. `work` is a synchronous codec call, so nothing else runs
+     * while the home is set.
+     */
+    within<T>(home: string, work: () => T): T;
+    /**
+     * Fetches, unless held fresh, the key of every subject the envelopes in `json` name, from `home`'s
+     * keyring ("" for this installation's). Never throws.
+     */
+    prefetchJson(json: Uint8Array | string, home?: string): Promise<void>;
+    /**
+     * Fetches, unless held fresh, the key of every present personal field in `value`, for a write. An
+     * erased field needs no key, but its envelope names the own project: until an answer has named it, one
+     * is asked for, without `create`. A field read from another project's envelope is sealed again under
+     * that project's key (FR-027): its key is fetched, never made. `home` is whose keyring keeps the
+     * keys, "" for this installation's; another home's keys are never made. Never throws.
+     */
+    prefetchValue(value: unknown, home?: string): Promise<void>;
+    /** The key a write seals `subject`'s field with. Throws `Erased` or `Unavailable`; never fetches. */
+    keyForWrite(subject: string): {
+        project: string;
+        key: Uint8Array;
+    };
+    /** The key a read opens `subject`'s field of `project` with, or `erased`. Throws `Unavailable`; never fetches. */
+    keyForRead(project: string, subject: string): KeyAnswer;
+    /**
+     * Forgets every key: what the process does when its notice stream ends or opens again, since the
+     * sidecar counts a closed stream as acked and hands a notice sent while none was held never again.
+     */
+    dropAll(): void;
+    /** Forgets `subject`'s key, from whichever home it was fetched: what a notice from the sidecar does. */
+    drop(project: string, subject: string): void;
+    /** Whether a key, or an erased answer, is held for `subject` and may be used. */
+    holds(project: string, subject: string, home?: string): boolean;
+}
+/** @internal Installs the keyring every codec in this process reads; `undefined` removes it. */
+export declare function installKeyring(keyring: Keyring | undefined): void;
+/** The keyring installed in this process, if any. */
+export declare function currentKeyring(): Keyring | undefined;
+/** The installed keyring; `Unavailable` when there is none. */
+export declare function requireKeyring(): Keyring;
+/** Prefetches for decoding `json` from `home`'s keyring, when a keyring is installed. Never throws. */
+export declare function prefetchForDecode(json: Uint8Array | string | undefined, home?: string): Promise<void>;
+/** Prefetches for encoding `value` with `home`'s keys, when a keyring is installed. Never throws. */
+export declare function prefetchForEncode(value: unknown, home?: string): Promise<void>;
+/** `work` with the keys of `home`'s keyring ("" for this installation's), when a keyring is installed. */
+export declare function withKeysAt<T>(home: string, work: () => T): T;
+/** A notice as the sidecar relays it. */
+export interface SubjectNotice {
+    readonly seq: bigint;
+    readonly project: string;
+    readonly subject: string;
+    readonly rerun: boolean;
+}
+/**
+ * Holds `open()`'s notice stream for as long as `signal` is not aborted: each notice drops the subject's
+ * key and is then acked. A stream that ends or fails is opened again after `retryMillis`.
+ */
+export declare function followNotices(keyring: Keyring, open: (signal: AbortSignal) => AsyncIterable<SubjectNotice>, ack: (seq: bigint) => Promise<void>, signal: AbortSignal, log?: (message: string) => void, retryMillis?: number): Promise<void>;