ankka 0.15.0 → 0.16.0

package/dist/server/payloads.js

@@ -1,11 +1,43 @@
 // The bridge between a codec and the protocol's `Payload`: `{ content_type, manifest, data }`.
+//
+// A payload is what a serializer writes, so a personal field in it is the personal envelope, bound to
+// the payload's manifest (feature 042): both directions run under that scope. The codec is synchronous,
+// so the keys it needs are fetched first: `prefetchPayload` before a decode, `prefetchValue` before an
+// encode. Each is a no-op when the process has no keyring or nothing personal is in sight.
+//
+// A replicated entity's keys are its home's (FR-032): the `…At` forms name the installation whose
+// keyring keeps them, "" for this one, for both the fetch and the codec call that reads it.
 import { create } from "@bufbuild/protobuf";
 import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
-export function encodePayload(codec, value) {
-    return create(PayloadSchema, { contentType: codec.contentType, manifest: codec.manifest, data: codec.encode(value) });
+import { withinScope } from "../personal.js";
+import { prefetchForDecode, prefetchForEncode, withKeysAt } from "../keyring.js";
+export function encodePayload(codec, value, home = "") {
+    return create(PayloadSchema, {
+        contentType: codec.contentType,
+        manifest: codec.manifest,
+        data: withKeysAt(home, () => withinScope(codec.manifest, () => codec.encode(value))),
+    });
 }
 /** Decodes a payload with `codec`. An absent payload is the empty payload, which is what `unit` and `done` are. */
-export function decodePayload(codec, payload) {
-    return codec.decode(payload?.data ?? new Uint8Array());
+export function decodePayload(codec, payload, home = "") {
+    return withKeysAt(home, () => withinScope(codec.manifest, () => codec.decode(payload?.data ?? new Uint8Array())));
+}
+/** Fetches the keys every personal envelope in these payloads needs. Never throws. */
+export async function prefetchPayload(...payloads) {
+    await prefetchPayloadAt("", ...payloads);
+}
+/** Fetches, from `home`'s keyring, the keys every personal envelope in these payloads needs. Never throws. */
+export async function prefetchPayloadAt(home, ...payloads) {
+    for (const p of payloads)
+        await prefetchForDecode(p?.data, home);
+}
+/** Fetches the keys every personal field in these values needs to be written. Never throws. */
+export async function prefetchValue(...values) {
+    await prefetchValueAt("", ...values);
+}
+/** Fetches, from `home`'s keyring, the keys every personal field in these values needs to be written. Never throws. */
+export async function prefetchValueAt(home, ...values) {
+    for (const v of values)
+        await prefetchForEncode(v, home);
 }
 export const EMPTY_PAYLOAD = create(PayloadSchema, { contentType: "application/octet-stream", manifest: "unit", data: new Uint8Array() });

package/dist/server/server.d.ts

@@ -16,6 +16,8 @@ export interface ServerOptions {
     readonly storage?: Buckets;
     /** Where `service.json` is read from for the buckets it declares; the working directory by default. */
     readonly serviceDirectory?: string;
+    /** How long a subject key is waited for from the sidecar; 10 seconds by default. */
+    readonly keyTimeoutMillis?: number;
 }
 /** What every servicer needs. */
 export interface ServerContext {

package/dist/server/server.js

@@ -16,11 +16,17 @@ import { statelessRoutes } from "./stateless.js";
 import { agentRoutes } from "./agent.js";
 import { httpRoutes } from "./http.js";
 import { mcpRoutes } from "./mcp.js";
+import { erasureRoutes } from "./erasure.js";
+import { randomUUID } from "node:crypto";
+import { channelOf } from "../client.js";
+import { currentKeyring, followNotices, installKeyring, Keyring } from "../keyring.js";
+import { olderThan } from "../startFrom.js";
+import { PERSONAL_SINCE } from "./discovery.js";
 /** The registry with the directory store's endpoint, which serves the URLs that store signs. */
 function withStorageEndpoint(registry) {
     const cls = DirectoryStorageEndpoint;
     const endpoint = Object.freeze({ id: cls.name, cls, prefix: cls.prefix, acl: cls.acl, routes: new Map(Object.entries(cls.routes)) });
-    return new Registry(registry.components, new Map([...registry.endpoints, [endpoint.id, endpoint]]));
+    return new Registry(registry.components, new Map([...registry.endpoints, [endpoint.id, endpoint]]), registry.mcpEndpoints, registry.erasureHandler);
 }
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0", "::"]);
 export class Server {
@@ -30,6 +36,8 @@ export class Server {
     #sessions = new Set();
     #http2;
     #address;
+    #keyring;
+    #following = false;
     #resolveClosed;
     closed = new Promise((resolve) => {
         this.#resolveClosed = resolve;
@@ -56,10 +64,14 @@ export class Server {
         _setProcessStorage(chosen.buckets);
         const registry = chosen.buckets instanceof DirectoryBuckets ? withStorageEndpoint(this.#context.registry) : this.#context.registry;
         this.#context = { ...this.#context, registry, storage: chosen.buckets };
+        this.#installKeyring();
         this.#context.log(`ankka: object storage is ${chosen.backend}${chosen.buckets instanceof DirectoryBuckets ? ` at ${chosen.buckets.root}` : ""}`);
         const handler = connectNodeAdapter({
             routes: (router) => {
-                discoveryRoutes(router, () => renderSpec(this.#context.registry), this.#context.log);
+                discoveryRoutes(router, () => renderSpec(this.#context.registry), this.#context.log, {
+                    users: () => this.#context.registry.personalUsers,
+                    discovered: (protocol) => this.#followNotices(protocol),
+                });
                 eventSourcedRoutes(router, this.#context);
                 keyValueRoutes(router, this.#context);
                 workflowRoutes(router, this.#context);
@@ -67,6 +79,7 @@ export class Server {
                 agentRoutes(router, this.#context);
                 httpRoutes(router, this.#context);
                 mcpRoutes(router, this.#context);
+                erasureRoutes(router, this.#context);
             },
             shutdownSignal: this.#shutdown.signal,
             readMaxBytes: this.#options.readMaxBytes ?? 64 * 1024 * 1024,
@@ -93,6 +106,48 @@ export class Server {
         server.on("close", () => this.#resolveClosed());
         return this.#address;
     }
+    /** The process's keyring: subject keys asked of the sidecar this server's client dials (feature 042). */
+    #installKeyring() {
+        const channel = channelOf(this.#context.client);
+        if (!channel)
+            return;
+        const timeoutMs = this.#options.keyTimeoutMillis ?? 10_000;
+        // The project is learned from the sidecar's answers (`SubjectKeyReply.project`), never configured.
+        this.#keyring = new Keyring({
+            fetch: async (project, subject, create, home = "") => {
+                const reply = await channel.stub().getSubjectKey({ subject, create, project, home }, { timeoutMs });
+                switch (reply.reply.case) {
+                    case "key":
+                        return { project: reply.project, answer: { kind: "key", key: reply.reply.value } };
+                    case "erased":
+                        return { project: reply.project, answer: { kind: "erased" } };
+                    case "error":
+                        throw new Error(reply.reply.value.message);
+                    default:
+                        throw new Error("the sidecar answered a subject key request with nothing");
+                }
+            },
+        });
+        installKeyring(this.#keyring);
+    }
+    /** Holds the sidecar's subject notices once a runtime speaking 1.23 has discovered a service with personal fields. */
+    #followNotices(protocol) {
+        const keyring = this.#keyring;
+        // Discovered, by a sidecar that may be new: one that stopped before it handed on a notice hands
+        // it never again, and this process may not yet have seen the old notice stream end. Every key
+        // held is forgotten, so an erased subject is asked for again and reads as erased.
+        keyring?.dropAll();
+        const channel = channelOf(this.#context.client);
+        if (this.#following || !keyring || !channel || olderThan(protocol, PERSONAL_SINCE) || this.#context.registry.personalUsers.length === 0)
+            return;
+        this.#following = true;
+        const instance = randomUUID();
+        void followNotices(keyring, (signal) => channel.stub().subjectNotices({ instance }, { signal }), async (seq) => {
+            const reply = await channel.stub().ackSubjectNotice({ seq, instance });
+            if (reply.error)
+                this.#context.log(`ankka: the sidecar refused the ack of subject notice ${seq}: ${reply.error.message}`);
+        }, this.#shutdown.signal, this.#context.log);
+    }
     /** The bound address; throws before `start`. */
     get address() {
         if (!this.#address)
@@ -105,6 +160,8 @@ export class Server {
         if (!server)
             return;
         this.#shutdown.abort();
+        if (this.#keyring && currentKeyring() === this.#keyring)
+            installKeyring(undefined);
         const closing = new Promise((resolve) => server.close(() => resolve()));
         for (const session of this.#sessions)
             session.close();

package/dist/server/stateless.js

@@ -13,7 +13,7 @@ import { ProtocolVersionError, requireSeveralMessages } from "../consumer.js";
 import { GRAPH_DELTA_SCHEMA, deltaRecords } from "../graph.js";
 import { JSON_CONTENT } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
-import { decodePayload, encodePayload } from "./payloads.js";
+import { decodePayload, encodePayload, prefetchPayload, prefetchValue } from "./payloads.js";
 import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 import { standingFromProto } from "../standing.js";
 function messageOf(e) {
@@ -34,12 +34,14 @@ async function handleKeyedView(req, sourceId, ctx) {
     const view = new registered.cls();
     try {
         const client = ctx.client.withMetadata(metadata);
+        await prefetchPayload(req.event);
         view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec), standingFromProto(req.standing));
         const effect = (req.deleted
             ? source.deleted
                 ? await source.deleted(view)
                 : undefined
             : await source.onChange(view, decodePayload(source.eventCodec, req.event)));
+        await prefetchValue(effect);
         if (effect !== undefined && effect?.kind !== "rows")
             throw new TypeError(`${registered.id}'s handler for ${sourceId} returned something that is not a keyed view effect`);
         const changes = (effect?.changes ?? []).map((c) => "deleted" in c
@@ -63,9 +65,11 @@ export async function handleView(req, ctx) {
     const metadata = metadataFromProto(req.metadata);
     const view = new registered.cls();
     try {
+        await prefetchPayload(req.row, req.event);
         const row = req.row ? decodePayload(registered.rowCodec, req.row) : null;
         view._bind(row, metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
         const effect = req.deleted ? await view.onDelete() : await view.onChange(decodePayload(registered.eventCodec, req.event));
+        await prefetchValue(effect);
         switch (effect.kind) {
             case "update-row":
                 return create(ViewEffectSchema, { effect: { case: "updateRow", value: encodePayload(registered.rowCodec, effect.row) } });
@@ -104,7 +108,9 @@ function produceAll(request, messages) {
 async function graphEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
     consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
+    await prefetchPayload(req.message);
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+    await prefetchValue(effect);
     switch (effect.kind) {
         case "publish":
             return produceAll(metadata, deltaRecords(effect, metadata).map((r) => ({
@@ -123,7 +129,9 @@ async function graphEffect(registered, req, metadata, ctx) {
 async function consumerEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
     consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
+    await prefetchPayload(req.message);
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+    await prefetchValue(effect);
     const outCodec = () => {
         if (!registered.outCodec)
             throw new Error(`${registered.id} produced a message but declares no out shape`);
@@ -171,6 +179,7 @@ export async function handleTimedAction(req, ctx) {
     const metadata = metadataFromProto(req.metadata);
     const instance = new registered.cls();
     try {
+        await prefetchPayload(req.payload);
         const input = action.input ? decodePayload(codecFor(action.input), req.payload) : undefined;
         instance._bind(metadata, ctx.client.withMetadata(metadata));
         const effect = await action.run(instance, input);

package/dist/server/workflow.js

@@ -10,7 +10,8 @@ import { commandContext, metadataFromProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
 import { errorCodeToProto } from "../kinds.js";
 import { materialiseStep, materialiseWorkflowCommand } from "../materialise.js";
-import { decodePayload, encodePayload } from "./payloads.js";
+import { PersonalError } from "../personal.js";
+import { decodePayload, encodePayload, prefetchPayload, prefetchValue } from "./payloads.js";
 import { AsyncQueue } from "./queue.js";
 function failure(commandId, error) {
     return create(WorkflowOutSchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
@@ -48,6 +49,7 @@ class WorkflowStream {
         if (!handler)
             return 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;
         }
@@ -72,6 +74,7 @@ class WorkflowStream {
         }
         try {
             const m = materialiseWorkflowCommand(effect, this.state);
+            await prefetchValue(m);
             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) } } }
@@ -95,7 +98,7 @@ class WorkflowStream {
         }
         catch (e) {
             ctx.log(`ankka: ${registered.id}/${this.entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
-            return failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal });
+            return failure(cmd.id, { message: messageOf(e), code: e instanceof PersonalError ? e.code : ErrorCode.Internal });
         }
     }
     /** Runs a step on a fresh instance, as the sidecar's engine does: commands keep arriving on the stream's instance meanwhile. */
@@ -107,6 +110,7 @@ class WorkflowStream {
         const fresh = new registered.cls();
         fresh._bindInstance(this.entityId);
         let input;
+        await prefetchPayload(run.input);
         try {
             input = step.input ? decodePayload(codecFor(step.input), run.input) : undefined;
         }
@@ -132,6 +136,7 @@ class WorkflowStream {
         }
         try {
             const m = materialiseStep(effect, this.state);
+            await prefetchValue(m);
             let next;
             switch (m.next.kind) {
                 case "transition":
@@ -181,6 +186,7 @@ export async function* handleWorkflow(requests, ctx) {
                             out.push(failure(0n, { message: `no workflow ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound }));
                             return;
                         }
+                        await prefetchPayload(init.state);
                         try {
                             const instance = new found.cls();
                             instance._bindInstance(init.entityId);

package/dist/service.d.ts

@@ -1,6 +1,7 @@
 import { type StartFrom } from "./startFrom.ts";
 import { Contract, type Publication } from "./contract.ts";
 import { type Codec } from "./codec.ts";
+import type { ErasureHandler } from "./erasure.ts";
 import { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
 import { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 import { Workflow, type WorkflowClass } from "./workflow.ts";
@@ -153,7 +154,11 @@ export declare class Registry {
     readonly endpoints: ReadonlyMap<string, RegisteredEndpoint>;
     /** The MCP endpoints (1.20), by id, their references resolved. */
     readonly mcpEndpoints: ReadonlyMap<string, RegisteredMcpEndpoint>;
-    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>, mcpEndpoints?: ReadonlyMap<string, RegisteredMcpEndpoint>);
+    /** The service's erasure handler (1.23), if it declares one. */
+    readonly erasureHandler: ErasureHandler | undefined;
+    /** The components and endpoints whose shapes hold a personal field (1.23). */
+    readonly personalUsers: readonly string[];
+    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>, mcpEndpoints?: ReadonlyMap<string, RegisteredMcpEndpoint>, erasureHandler?: ErasureHandler);
     mcpEndpoint(id: string): RegisteredMcpEndpoint | undefined;
     component(id: string): RegisteredComponent | undefined;
     /** The component `id` when it is of `kind`. */
@@ -191,6 +196,12 @@ export declare class ServiceBuilder {
     register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;
     register<C extends McpEndpoint>(cls: McpEndpointClass<C>): this;
     register<C extends Endpoint>(cls: EndpointClass<C>): this;
+    /**
+     * The service's erasure handler (feature 042, protocol 1.23): run for each erased data subject, and again
+     * on each re-run, so it must be idempotent. One per service. A handler that throws is recorded as failed
+     * for that run and run again on the next.
+     */
+    erasureHandler(handler: ErasureHandler): this;
     /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
     validate(): Registry;
     /** The discovery `Spec` for what is registered, without listening. */

package/dist/service.js

@@ -5,7 +5,8 @@
 //   await Ankka.service().register(ShoppingCartEntity).register(ShoppingCartEndpoint).listen()
 import { isStartFrom } from "./startFrom.js";
 import { Contract } from "./contract.js";
-import { codecFor, isCodec } from "./codec.js";
+import { codecFor, isCodec, schemaOf } from "./codec.js";
+import { holdsPersonal } from "./schema.js";
 import { EventSourcedEntity } from "./eventSourcedEntity.js";
 import { KeyValueEntity } from "./keyValueEntity.js";
 import { Workflow } from "./workflow.js";
@@ -29,10 +30,19 @@ export class Registry {
     endpoints;
     /** The MCP endpoints (1.20), by id, their references resolved. */
     mcpEndpoints;
-    constructor(components, endpoints, mcpEndpoints = new Map()) {
+    /** The service's erasure handler (1.23), if it declares one. */
+    erasureHandler;
+    /** The components and endpoints whose shapes hold a personal field (1.23). */
+    personalUsers;
+    constructor(components, endpoints, mcpEndpoints = new Map(), erasureHandler) {
         this.components = components;
         this.endpoints = endpoints;
         this.mcpEndpoints = mcpEndpoints;
+        this.erasureHandler = erasureHandler;
+        this.personalUsers = Object.freeze([
+            ...[...components.values()].filter((c) => mentionsPersonal(c)).map((c) => c.id),
+            ...[...endpoints.values()].filter((e) => mentionsPersonal(e.routes)).map((e) => e.id),
+        ]);
         Object.freeze(this);
     }
     mcpEndpoint(id) {
@@ -50,6 +60,39 @@ export class Registry {
         return this.endpoints.get(id);
     }
 }
+/**
+ * Whether a registered component or endpoint holds a schema with a personal field anywhere among its
+ * codecs and handler shapes. Its class is not searched: everything it declares was resolved into the entry.
+ */
+function mentionsPersonal(entry) {
+    const seen = new Set();
+    const go = (v, depth) => {
+        if (depth > 8 || v === null || (typeof v !== "object" && typeof v !== "function") || seen.has(v))
+            return false;
+        seen.add(v);
+        if (typeof v === "function")
+            return false;
+        if (isCodec(v)) {
+            const schema = schemaOf(v);
+            return schema !== undefined && holdsPersonal(schema);
+        }
+        if (typeof v.kind === "string" && isSchemaKind(v.kind))
+            return holdsPersonal(v);
+        if (v instanceof Map)
+            return [...v.values()].some((x) => go(x, depth + 1));
+        if (Array.isArray(v))
+            return v.some((x) => go(x, depth + 1));
+        return Object.entries(v).some(([k, x]) => k !== "cls" && go(x, depth + 1));
+    };
+    return go(entry, 0);
+}
+const SCHEMA_KINDS = new Set([
+    "string", "int", "long", "double", "boolean", "instant", "duration", "localDate", "localDateTime", "bytes", "unit", "done",
+    "option", "list", "stringMap", "record", "sumType", "enumeration", "lazy", "personal",
+]);
+function isSchemaKind(kind) {
+    return SCHEMA_KINDS.has(kind);
+}
 /** Thrown by `validate`, `spec`, `server` and `listen` with every problem the registration has. */
 export class RegistrationError extends Error {
     problems;
@@ -71,6 +114,7 @@ function nameOf(cls) {
 export class ServiceBuilder {
     #classes = [];
     #client;
+    #erasureHandlers = [];
     #log;
     constructor(options = {}) {
         this.#client = options.client ?? new ComponentClient();
@@ -84,6 +128,15 @@ export class ServiceBuilder {
         this.#classes.push(cls);
         return this;
     }
+    /**
+     * The service's erasure handler (feature 042, protocol 1.23): run for each erased data subject, and again
+     * on each re-run, so it must be idempotent. One per service. A handler that throws is recorded as failed
+     * for that run and run again on the next.
+     */
+    erasureHandler(handler) {
+        this.#erasureHandlers.push(handler);
+        return this;
+    }
     /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
     validate() {
         const problems = [];
@@ -166,9 +219,13 @@ export class ServiceBuilder {
             else
                 mcpEndpoints.set(r.id, r);
         }
+        if (this.#erasureHandlers.some((h) => typeof h !== "function"))
+            problems.push("the erasure handler is not a function");
+        if (this.#erasureHandlers.length > 1)
+            problems.push(`a service has one erasure handler, and ${this.#erasureHandlers.length} were given`);
         if (problems.length > 0)
             throw new RegistrationError(problems);
-        return new Registry(components, endpoints, mcpEndpoints);
+        return new Registry(components, endpoints, mcpEndpoints, this.#erasureHandlers[0]);
     }
     /** The discovery `Spec` for what is registered, without listening. */
     spec() {

package/dist/spec.d.ts

@@ -2,7 +2,7 @@ import { type MessageInitShape } from "@bufbuild/protobuf";
 import { Endpoint_Acl, type McpAclSchema, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import type { Registry } from "./service.ts";
 import type { Acl } from "./routes.ts";
-export declare const PROTOCOL_VERSION = "1.22";
+export declare const PROTOCOL_VERSION = "1.23";
 export declare const SDK_NAME = "ankka-typescript";
 /** An HTTP endpoint's rule; client keys and `anyOf` are refused for one at registration, so they deny here. */
 export declare function aclToProto(acl: Acl): Endpoint_Acl;

package/dist/spec.js

@@ -17,7 +17,7 @@ function toolInit(t) {
         ...(approval !== undefined ? { approval } : {}),
     };
 }
-export const PROTOCOL_VERSION = "1.22";
+export const PROTOCOL_VERSION = "1.23";
 export const SDK_NAME = "ankka-typescript";
 /** An HTTP endpoint's rule; client keys and `anyOf` are refused for one at registration, so they deny here. */
 export function aclToProto(acl) {
@@ -287,5 +287,6 @@ export function renderSpec(registry) {
         components,
         endpoints,
         mcpEndpoints,
+        erasureHandler: registry.erasureHandler !== undefined,
     });
 }

package/dist/storage.d.ts

@@ -1,6 +1,8 @@
 import { CommandError } from "./effects/common.ts";
+import type { Finality } from "./erasure.ts";
+import { type DataSubject } from "./personal.ts";
 import { Credentials } from "./sigv4.ts";
-import { Instant } from "./time.ts";
+import { Duration, Instant } from "./time.ts";
 /** How a bucket is reached from outside the installation. */
 export type BucketExposure = "private" | "signed" | "public" | "supplied";
 /** What a signed URL lets its holder do with one object. */
@@ -61,7 +63,25 @@ export interface Bucket {
     signedUrl(name: string, access: SignedAccess, spanSeconds?: number): string;
     /** The address a browser reads the object under `name` at, with no signature: a public bucket's only. */
     url(name: string): string;
+    /**
+     * Removes every object of `subject` (feature 042): those under its prefix (`subjectPrefix`), and on a
+     * store that keeps versions every version of each. Objects outside it are kept, those of another data
+     * subject included. Run again, it erases what was kept since, and answers 0 when nothing was.
+     */
+    erase(subject: DataSubject | string): Promise<ErasedObjects>;
+}
+/** What `Bucket.erase` removed: how many objects, and when they are gone for good (an `ErasureReport`'s `finality`). */
+export interface ErasedObjects {
+    readonly count: number;
+    readonly finality: Finality;
 }
+/**
+ * Where a service keeps the objects of `subject` (feature 042): `subjects/`, the data subject with every
+ * `/` written `%2F`, and `/`. A data subject cannot hold `%`, so no subject prefix holds another's:
+ * `player`'s is `subjects/player/` and `player/8c1f`'s `subjects/player%2F8c1f/`. A string that is no
+ * data subject is refused (`BAD_REQUEST`).
+ */
+export declare function subjectPrefix(subject: DataSubject | string): string;
 /** A service's buckets: `default`, the unnamed one, and the named ones by name. */
 export interface Buckets {
     /** The unnamed bucket. Refuses, naming `provisionObjectStorage`, when the service has none. */
@@ -94,6 +114,8 @@ export declare const ObjectRules: Readonly<{
     checkName(name: string): void;
     checkPrefix(prefix: string): void;
     checkSpan(spanSeconds: number): void;
+    /** Where a service keeps the objects of `subject`: `subjectPrefix`. */
+    subjectPrefix(subject: DataSubject | string): string;
 }>;
 /** What the storage client says when it refuses: the runtime's words (`StorageRefusals` in the Scala SDK). */
 export declare const StorageRefusals: Readonly<{
@@ -220,6 +242,11 @@ export interface S3Settings {
     readonly named: readonly NamedTarget[];
     /** How long one request waits for an answer: 30 seconds. */
     readonly timeoutMs: number;
+    /**
+     * How long the store keeps a deleted object (feature 042), from `ANKKA_S3_SOFT_DELETE_DAYS`: a whole
+     * number of days from 1, or `undefined` for at once.
+     */
+    readonly softDelete?: Duration | undefined;
 }
 type Env = Readonly<Record<string, string | undefined>>;
 /** The bucket a variable's `<NAME>` names: lower case, `_` as `-`. */
@@ -239,17 +266,36 @@ export declare function parseListing(xml: string): {
     readonly entries: ObjectEntry[];
     readonly next: string | undefined;
 };
+/** One page of a `ListObjectVersions` answer: each version and delete marker as its key and version id. */
+export interface VersionsPage {
+    /** `[key, versionId]`; the id is `null` for a version written before versioning was on. */
+    readonly versions: readonly (readonly [string, string])[];
+    readonly truncated: boolean;
+    readonly nextKey: string | undefined;
+    readonly nextVersion: string | undefined;
+    /** The answer named versions as Google Cloud Storage does (`Generation`, `NextGenerationMarker`); its next page is asked for by `generation-marker`. */
+    readonly generations: boolean;
+}
+/** A `ListObjectVersions` answer: its versions and delete markers, and where the next page starts while it is truncated. */
+export declare function parseVersions(xml: string): VersionsPage;
 /** One bucket in an S3 store: path-style requests, a put streamed once with an unsigned payload, a listing paged as it is walked. */
 export declare class S3Bucket implements Bucket {
     #private;
     readonly name: string | undefined;
     readonly exposure: BucketExposure;
-    constructor(target: S3Target, name: string | undefined, exposure: BucketExposure, publicUrl: string | undefined, timeoutMs?: number);
+    constructor(target: S3Target, name: string | undefined, exposure: BucketExposure, publicUrl: string | undefined, timeoutMs?: number, softDelete?: Duration);
     put(objectName: string, body: ReadableStream<Uint8Array> | Uint8Array, options: PutOptions): Promise<void>;
     get(objectName: string): Promise<StoredObject | undefined>;
     stat(objectName: string): Promise<ObjectInfo | undefined>;
     delete(objectName: string): Promise<void>;
     list(prefix: string): AsyncIterable<ObjectEntry>;
+    /**
+     * Lists every version and delete marker under the subject's prefix (`ListObjectVersions`) and deletes
+     * each by its version id; the count is the objects with a version. A store that lists no versions
+     * (Garage answers `NotImplemented`) is listed plainly and each object deleted. The finality is
+     * `ANKKA_S3_SOFT_DELETE_DAYS`'s, or immediate.
+     */
+    erase(subject: DataSubject | string): Promise<ErasedObjects>;
     signedUrl(objectName: string, access: SignedAccess, spanSeconds?: number): string;
     url(objectName: string): string;
 }