ankka 0.11.0 → 0.13.0

package/dist/spec.d.ts

@@ -1,10 +1,16 @@
 import { type MessageInitShape } from "@bufbuild/protobuf";
-import { Endpoint_Acl, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
+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.14";
+export declare const PROTOCOL_VERSION = "1.21";
 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;
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */
 export declare function callersToProto(acl: Acl): MessageInitShape<typeof CallerMatcherSchema>[];
+/**
+ * An MCP endpoint's or tool's rule as discovery carries it (1.20): each member of an `anyOf` sets its
+ * own field, so `anyOf(clientKeys, authenticated)` is `client_keys` and `tokens`.
+ */
+export declare function mcpAclToProto(acl: Acl): MessageInitShape<typeof McpAclSchema>;
 export declare function renderSpec(registry: Registry): Spec;

package/dist/spec.js

@@ -17,11 +17,12 @@ function toolInit(t) {
         ...(approval !== undefined ? { approval } : {}),
     };
 }
-export const PROTOCOL_VERSION = "1.14";
+export const PROTOCOL_VERSION = "1.21";
 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) {
     if (typeof acl === "object")
-        return Endpoint_Acl.CALLERS;
+        return acl.kind === "callers" ? Endpoint_Acl.CALLERS : Endpoint_Acl.DENY_ALL;
     switch (acl) {
         case "allow-all":
             return Endpoint_Acl.ALLOW_ALL;
@@ -29,11 +30,13 @@ export function aclToProto(acl) {
             return Endpoint_Acl.DENY_ALL;
         case "authenticated":
             return Endpoint_Acl.AUTHENTICATED;
+        case "client-keys":
+            return Endpoint_Acl.DENY_ALL;
     }
 }
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */
 export function callersToProto(acl) {
-    if (typeof acl !== "object")
+    if (typeof acl !== "object" || acl.kind !== "callers")
         return [];
     return acl.callers.map((m) => {
         switch (m.kind) {
@@ -43,11 +46,45 @@ export function callersToProto(acl) {
                 return { kind: { case: "anyInProject", value: {} } };
             case "self":
                 return { kind: { case: "self", value: {} } };
+            case "granted":
+                return { kind: { case: "granted", value: {} } };
             case "service":
                 return { kind: { case: "service", value: m.project !== undefined ? { name: m.name, project: m.project } : { name: m.name } } };
         }
     });
 }
+/**
+ * An MCP endpoint's or tool's rule as discovery carries it (1.20): each member of an `anyOf` sets its
+ * own field, so `anyOf(clientKeys, authenticated)` is `client_keys` and `tokens`.
+ */
+export function mcpAclToProto(acl) {
+    const out = { allowAll: false, denyAll: false, tokens: false, clientKeys: false, callers: [] };
+    const add = (rule) => {
+        if (typeof rule === "object") {
+            if (rule.kind === "anyOf")
+                rule.acls.forEach(add);
+            else
+                out.callers.push(...callersToProto(rule));
+            return;
+        }
+        switch (rule) {
+            case "allow-all":
+                out.allowAll = true;
+                break;
+            case "deny-all":
+                out.denyAll = true;
+                break;
+            case "authenticated":
+                out.tokens = true;
+                break;
+            case "client-keys":
+                out.clientKeys = true;
+                break;
+        }
+    };
+    add(acl);
+    return out;
+}
 function handlerInits(handlers) {
     return [...handlers.values()]
         .map((h) => ({ name: h.name, readOnly: h.readOnly, streaming: h.streaming }))
@@ -62,6 +99,8 @@ function sourceInit(source) {
         ...(source.contract !== undefined ? { contract: { name: source.contract.name, fingerprint: source.contract.fingerprint } } : {}),
         ...(source.broker !== undefined ? { broker: source.broker } : {}),
         ...(source.parallel === true ? { parallel: true } : {}),
+        // 1.15: another project's topic.
+        ...(source.project !== undefined ? { project: source.project } : {}),
     };
     if (start === undefined)
         return { source: { case: "topic", value: source.topic }, ...options };
@@ -93,7 +132,7 @@ function componentInit(c) {
         case "autonomous-agent":
             return autonomousInit(c);
         case "event-sourced":
-            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery } } };
+            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery, replicated: c.replicated } } };
         case "key-value":
             return { ...base, handlers: handlerInits(c.handlers), detail: { case: "keyValue", value: {} } };
         case "workflow":
@@ -113,7 +152,7 @@ function componentInit(c) {
                         rowManifest: c.rowCodec.manifest,
                         queries: [...c.queries],
                         ...(c.version !== undefined ? { version: c.version } : {}),
-                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement })),
+                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement, watched: q.watched ?? false })),
                     },
                 },
             };
@@ -128,7 +167,7 @@ function componentInit(c) {
                         queries: [],
                         ...(c.version !== undefined ? { version: c.version } : {}),
                         sources: [...c.sources.values()].map((s) => sourceInit({ component: { kind: s.kind, id: s.id } })),
-                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement })),
+                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement, watched: q.watched ?? false })),
                     },
                 },
             };
@@ -142,6 +181,7 @@ function componentInit(c) {
                         source: sourceInit(c.source),
                         ...(c.producesTo !== undefined ? { producesTo: c.producesTo } : {}),
                         ...(c.version !== undefined ? { version: c.version } : {}),
+                        mirroredChanges: c.mirroredChanges,
                         // 1.14: the publication with its contract and broker; `producesTo` stays for an older sidecar.
                         ...(c.produces !== undefined
                             ? {
@@ -149,6 +189,7 @@ function componentInit(c) {
                                     topic: c.produces.topic,
                                     ...(c.produces.contract !== undefined ? { contract: { name: c.produces.contract.name, fingerprint: c.produces.contract.fingerprint } } : {}),
                                     ...(c.produces.broker !== undefined ? { broker: c.produces.broker } : {}),
+                                    ...(c.produces.project !== undefined ? { project: c.produces.project } : {}),
                                 },
                             }
                             : {}),
@@ -226,10 +267,25 @@ export function renderSpec(registry) {
             ...(r.acl !== undefined ? { acl: aclToProto(r.acl), allowCallers: callersToProto(r.acl) } : {}),
         })),
     }));
+    const mcpEndpoints = [...registry.mcpEndpoints.values()].map((e) => ({
+        id: e.id,
+        path: e.path,
+        ...(e.serverName !== undefined ? { name: e.serverName } : {}),
+        ...(e.serverVersion !== undefined ? { version: e.serverVersion } : {}),
+        acl: mcpAclToProto(e.acl),
+        tools: e.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchemaJson: JSON.stringify(t.inputSchema),
+            ...(t.acl !== undefined ? { acl: mcpAclToProto(t.acl) } : {}),
+        })),
+        brokered: e.brokered,
+    }));
     return create(SpecSchema, {
         protocolVersion: PROTOCOL_VERSION,
         sdk: { name: SDK_NAME, version: VERSION },
         components,
         endpoints,
+        mcpEndpoints,
     });
 }

package/dist/standing.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowStanding } from "./_proto/ankka/protocol/v1/payload_pb.ts";
+export type StandingStatus = "NotStarted" | "Running" | "Paused" | "Completed" | "Failed" | "Unknown";
+export interface Standing {
+    readonly status: StandingStatus;
+    /** The step the workflow is on, or the step a pause names or follows. */
+    readonly step?: string;
+    /** Retries so far, per step. */
+    readonly retries: Readonly<Record<string, number>>;
+    /** Why it failed, when it did. */
+    readonly failure?: string;
+}
+export declare function isTerminal(standing: Standing): boolean;
+/** The state was recorded before the platform stamped standings. */
+export declare function isUnknown(standing: Standing): boolean;
+/** @internal The standing a request carries, or `undefined` for a change from an entity or a topic. */
+export declare function standingFromProto(standing: WorkflowStanding | undefined): Standing | undefined;
+/** @internal The version whose runtimes read a workflow as a source. */
+export declare const WORKFLOW_SOURCE_PROTOCOL: readonly [number, number];

package/dist/standing.js

@@ -0,0 +1,26 @@
+// Where a workflow stood once the effect that recorded a state was applied (protocol 1.16).
+//
+// A view or a consumer whose source is a workflow is handed, with each state the workflow records,
+// its standing: running, paused, completed or failed, the step it is on or waits after, the retries
+// of each step and, when it failed, why. `Unknown` is the standing of a state recorded before the
+// platform stamped standings. A change from an entity or a topic has none.
+export function isTerminal(standing) {
+    return standing.status === "Completed" || standing.status === "Failed";
+}
+/** The state was recorded before the platform stamped standings. */
+export function isUnknown(standing) {
+    return standing.status === "Unknown";
+}
+/** @internal The standing a request carries, or `undefined` for a change from an entity or a topic. */
+export function standingFromProto(standing) {
+    if (standing === undefined)
+        return undefined;
+    return Object.freeze({
+        status: standing.status,
+        ...(standing.step ? { step: standing.step } : {}),
+        retries: Object.freeze({ ...standing.retries }),
+        ...(standing.failure ? { failure: standing.failure } : {}),
+    });
+}
+/** @internal The version whose runtimes read a workflow as a source. */
+export const WORKFLOW_SOURCE_PROTOCOL = [1, 16];

package/dist/startFrom.d.ts

@@ -24,9 +24,13 @@ export declare const START_POSITION_PROTOCOL: readonly [number, number];
 export declare function isStartFrom(value: unknown): value is StartFrom;
 /** The first protocol in which a process can declare a view's queries. */
 export declare const DECLARED_QUERY_PROTOCOL: readonly [number, number];
+export declare function olderThan(protocolVersion: string, [wantMajor, wantMinor]: readonly [number, number]): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a start position and a version. */
 export declare function olderThanStartPositions(protocolVersion: string): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a view's declared queries. */
 export declare function olderThanDeclaredQueries(protocolVersion: string): boolean;
+/** Whether a sidecar speaking `protocolVersion` would not know a watched query. */
+export declare function olderThanViewStreams(protocolVersion: string): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a topic's contract, broker and parallel reading. */
+export declare function olderThanWorkflowSources(protocolVersion: string): boolean;
 export declare function olderThanContracts(protocolVersion: string): boolean;

package/dist/startFrom.js

@@ -24,7 +24,7 @@ export function isStartFrom(value) {
 }
 /** The first protocol in which a process can declare a view's queries. */
 export const DECLARED_QUERY_PROTOCOL = [1, 13];
-function olderThan(protocolVersion, [wantMajor, wantMinor]) {
+export function olderThan(protocolVersion, [wantMajor, wantMinor]) {
     const [major, minor] = protocolVersion.split(".").map((part) => Number.parseInt(part, 10));
     if (!Number.isFinite(major) || !Number.isFinite(minor))
         return false;
@@ -38,7 +38,14 @@ export function olderThanStartPositions(protocolVersion) {
 export function olderThanDeclaredQueries(protocolVersion) {
     return olderThan(protocolVersion, DECLARED_QUERY_PROTOCOL);
 }
+/** Whether a sidecar speaking `protocolVersion` would not know a watched query. */
+export function olderThanViewStreams(protocolVersion) {
+    return olderThan(protocolVersion, [1, 17]);
+}
 /** Whether a sidecar speaking `protocolVersion` would ignore a topic's contract, broker and parallel reading. */
+export function olderThanWorkflowSources(protocolVersion) {
+    return olderThan(protocolVersion, [1, 16]);
+}
 export function olderThanContracts(protocolVersion) {
     return olderThan(protocolVersion, [1, 14]);
 }

package/dist/storage.d.ts

@@ -0,0 +1,288 @@
+import { CommandError } from "./effects/common.ts";
+import { Credentials } from "./sigv4.ts";
+import { 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. */
+export type SignedAccess = "read" | "keep";
+/** An object read from a bucket. Read its `body` once, or call `bytes()`. */
+export interface StoredObject {
+    readonly contentType: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+    readonly body: ReadableStream<Uint8Array>;
+    /** The whole body, read from `body`. */
+    bytes(): Promise<Uint8Array>;
+}
+/** What a bucket keeps under a name, without the bytes. */
+export interface ObjectInfo {
+    readonly name: string;
+    readonly contentType: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+}
+/** One object in a listing. */
+export interface ObjectEntry {
+    readonly name: string;
+    readonly length: number;
+    readonly lastKept: Instant;
+}
+/** How a put keeps its body: its content type, and its length, which a stream must declare. */
+export interface PutOptions {
+    readonly contentType: string;
+    readonly length?: number;
+}
+/**
+ * One bucket. Its objects are named with `/` between segments, so a listing by prefix reads like a
+ * directory; it is not one. A put replaces the whole object or leaves the old one.
+ */
+export interface Bucket {
+    /** The descriptor's name for it; `undefined` for the unnamed bucket. */
+    readonly name: string | undefined;
+    readonly exposure: BucketExposure;
+    /**
+     * Keeps `body` under `name`, replacing what was there. A stream declares its `length`; one that ends
+     * before it fails and keeps nothing, and the old object, if any, stays.
+     */
+    put(name: string, body: ReadableStream<Uint8Array> | Uint8Array, options: PutOptions): Promise<void>;
+    /** The object kept under `name`, or `undefined` when there is none. */
+    get(name: string): Promise<StoredObject | undefined>;
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    delete(name: string): Promise<void>;
+    /** Every object whose name begins with `prefix`, in name order; pages are read as it is walked. */
+    list(prefix: string): AsyncIterable<ObjectEntry>;
+    /** What is kept under `name`, without its bytes, or `undefined`. */
+    stat(name: string): Promise<ObjectInfo | undefined>;
+    /**
+     * A URL a browser may use, until `spanSeconds` (15 minutes by default, at most seven days) have
+     * passed, to read or keep the object under `name`. Computed: no request reaches the store. A signed
+     * bucket's, or the unnamed bucket's when the service sets `exposeObjectStorage`.
+     */
+    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;
+}
+/** 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. */
+    readonly default: Bucket;
+    /** A bucket the descriptor's `buckets` list names; refused, naming the ones it does name, otherwise. */
+    bucket(name: string): Bucket;
+    /** Every named bucket, in no particular order. */
+    readonly buckets: Bucket[];
+}
+/**
+ * What an object's name, a prefix, a bucket's name and a signed URL's span may be. Every store and every
+ * test double applies these, and `protocol/fixtures/storage/rules.json` holds them to the other SDKs.
+ */
+export declare const ObjectRules: Readonly<{
+    MAX_NAME_BYTES: 1024;
+    MAX_BUCKET_NAME: 32;
+    /** Seven days. */
+    MAX_SIGNED_URL_SECONDS: 604800;
+    /** Fifteen minutes. */
+    DEFAULT_SIGNED_URL_SECONDS: 900;
+    BUCKET_NAME_RULE: "lower-case letters, digits and '-', 1 to 32 characters";
+    /** What is wrong with an object's `name`, if anything. */
+    nameProblem(name: string): string | undefined;
+    /** What is wrong with a listing's `prefix`, if anything. Empty is everything. */
+    prefixProblem(prefix: string): string | undefined;
+    /** What is wrong with a bucket's name, if anything, in the descriptor's words. */
+    bucketNameProblem(name: string): string | undefined;
+    /** What is wrong with a signed URL's span, in seconds, if anything. */
+    spanProblem(spanSeconds: number): string | undefined;
+    checkName(name: string): void;
+    checkPrefix(prefix: string): void;
+    checkSpan(spanSeconds: number): void;
+}>;
+/** What the storage client says when it refuses: the runtime's words (`StorageRefusals` in the Scala SDK). */
+export declare const StorageRefusals: Readonly<{
+    noBucket(): CommandError;
+    unknown(name: string, known: Iterable<string>): CommandError;
+    noCredential(): CommandError;
+    notExposed(): CommandError;
+    notSigned(bucket: string, exposure: BucketExposure): CommandError;
+    notPublic(bucket: string | undefined, exposure: BucketExposure): CommandError;
+    unreachable(endpoint: string, cause: string): CommandError;
+    refusedByStore(endpoint: string, status: number, detail: string): CommandError;
+    unreadable(endpoint: string, cause: string): CommandError;
+    shortBody(declared: number, read: number): CommandError;
+    negativeLength(length: number): CommandError;
+    /** TypeScript's own: a stream's length cannot be known before it is read, and S3 is told it first. */
+    undeclaredLength(): CommandError;
+    stepsOnly(): CommandError;
+}>;
+/** Buckets that refuse every call, naming `provisionObjectStorage`: a deployed service with no bucket. */
+export declare const noStorage: Buckets;
+export interface InMemoryBucketsOptions {
+    /** The named buckets and their exposure; more may be declared later with `declare`. */
+    readonly buckets?: Readonly<Record<string, BucketExposure>>;
+    /** Whether the service has the unnamed bucket; `true` by default. */
+    readonly unnamed?: boolean;
+    /** The unnamed bucket's exposure: `signed` by default, so a test may sign a URL for it. */
+    readonly unnamedExposure?: BucketExposure;
+    /** Where a public bucket's objects are read: `http://memory/public/<bucket>` by default, reaching nothing. */
+    readonly publicBase?: (bucket: string) => string;
+}
+/**
+ * A service's buckets in memory: the test kits' store, so a test of a handler that keeps or reads an
+ * object needs no object store and no Docker. It applies every rule the other stores apply, in the
+ * same words. A signed URL is computed (`http://memory/...`) and reaches nothing.
+ */
+export declare class InMemoryBuckets implements Buckets {
+    #private;
+    constructor(options?: InMemoryBucketsOptions);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+    /** Declares a named bucket, before or after the service starts. */
+    declare(name: string, exposure: BucketExposure): void;
+    /** Forgets every object; the declared buckets stay. */
+    clear(): void;
+}
+/** What a descriptor declares: whether the unnamed bucket is asked for, and each named one. */
+export interface DeclaredBuckets {
+    readonly unnamed: boolean;
+    readonly buckets: Readonly<Record<string, BucketExposure>>;
+}
+/**
+ * The buckets `service.json` in `directory` declares, read where a service runs on a developer's machine
+ * and in a test, so the directory and memory stores refuse the names a deployed service would; `undefined`
+ * when there is no such file. Only the two fields that say which buckets there are.
+ */
+export declare function declaredBuckets(directory?: string): DeclaredBuckets | undefined;
+/** Where a service serves its directory store's objects. */
+export declare const STORAGE_PATH = "/_ankka/storage";
+/** The unnamed bucket's directory and URL segment: no bucket name begins with `_`. */
+export declare const DEFAULT_SEGMENT = "_default";
+export interface DirectoryBucketsOptions {
+    /** The buckets `service.json` declares; with none, the unnamed bucket and any name asked for, as private. */
+    readonly declared?: DeclaredBuckets;
+    /** The service's own address, where its URLs point: `http://<ANKKA_HTTP_INTERFACE or 127.0.0.1>:<ANKKA_HTTP_PORT or 9000>`. */
+    readonly addressBase?: () => string;
+}
+/** The address a local service's HTTP port answers at, as the sidecar beside it binds it. */
+export declare function localAddress(env?: Readonly<Record<string, string | undefined>>): string;
+/**
+ * A service's buckets in a directory on a developer's machine: what a service keeps when it runs with no
+ * variable of an object store. The runtime's layout exactly, so a Scala service and a TypeScript one read
+ * each other's: one directory per bucket under `root` (`_default` for the unnamed one), an object's name
+ * encoded into one file name under `objects/` (its hash when too long), and beside it under `meta/` its
+ * name, content type, length and when it was kept. A put writes a temporary file and moves it into place,
+ * so a stream that ends short leaves the old object.
+ *
+ * A signed URL and a public address point at the service's own HTTP port, under `/_ankka/storage`, which
+ * the SDK serves through the sidecar while this is the service's store.
+ */
+export declare class DirectoryBuckets implements Buckets {
+    #private;
+    readonly root: string;
+    constructor(root: string, options?: DirectoryBucketsOptions);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+    /** The bucket a URL's segment names, `_default` or a bucket's name, as this store would answer it. */
+    bySegment(segment: string): {
+        readonly bucket: Bucket;
+        readonly segment: string;
+    } | undefined;
+    /** `HMAC-SHA256(key, "<segment>/<name>|<access>|<expires>")` in hex, over the key kept in the root. */
+    token(segment: string, objectName: string, access: string, expires: number): string;
+    /** Whether `token` signs this access until `expires`, and `expires` is still to come. */
+    admits(segment: string, objectName: string, access: string, expires: number, token: string): boolean;
+}
+/**
+ * The deepest object name whose address keeps its slashes. The sidecar matches a process's route by
+ * whole segments, so the storage endpoint declares one route per depth up to this; a deeper name's
+ * slashes are encoded and it travels as one segment.
+ */
+export declare const MAX_ADDRESS_SEGMENTS = 16;
+/** An object's name in a directory store's address: as the runtime writes it, while the sidecar can route it. */
+export declare function addressOf(objectName: string): string;
+/** One S3 bucket and how to reach it. */
+export interface S3Target {
+    readonly endpoint: URL;
+    readonly region: string;
+    readonly bucket: string;
+    readonly credentials: Credentials | undefined;
+    readonly publicEndpoint: URL | undefined;
+}
+/** A bucket the descriptor names: its exposure, where it is, and for a public one the base it is read at. */
+export interface NamedTarget {
+    readonly name: string;
+    readonly exposure: BucketExposure;
+    readonly target: S3Target;
+    readonly publicUrl: string | undefined;
+}
+/** The S3 store's settings, read from the `ANKKA_S3_*` variables as the runtime's `StorageSettings` reads them. */
+export interface S3Settings {
+    readonly unnamed: S3Target | undefined;
+    readonly named: readonly NamedTarget[];
+    /** How long one request waits for an answer: 30 seconds. */
+    readonly timeoutMs: number;
+}
+type Env = Readonly<Record<string, string | undefined>>;
+/** The bucket a variable's `<NAME>` names: lower case, `_` as `-`. */
+export declare function bucketNameOf(suffix: string): string;
+/** The `<NAME>` of a bucket's variables: upper case, `-` as `_`. */
+export declare function bucketVariableSuffix(bucket: string): string;
+/**
+ * The S3 settings in `env`: the unnamed family `ANKKA_S3_{ENDPOINT,REGION,BUCKET,ACCESS_KEY,SECRET_KEY,PUBLIC_ENDPOINT}`;
+ * a named bucket the platform made, `ANKKA_S3_BUCKET_<NAME>`, `ANKKA_S3_EXPOSURE_<NAME>` and, for a public
+ * one, `ANKKA_S3_PUBLIC_URL_<NAME>`, sharing the unnamed family's endpoint, region and key; a supplied
+ * bucket, the five `ANKKA_S3_{ENDPOINT,REGION,BUCKET,ACCESS_KEY,SECRET_KEY}_<NAME>` of its own. Throws,
+ * naming the variable, on a family that cannot be read.
+ */
+export declare function s3Settings(env?: Env, timeoutMs?: number): S3Settings;
+/** A `ListObjectsV2` answer: its entries, and the token for the next page while it is truncated. */
+export declare function parseListing(xml: string): {
+    readonly entries: ObjectEntry[];
+    readonly next: string | undefined;
+};
+/** 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);
+    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>;
+    signedUrl(objectName: string, access: SignedAccess, spanSeconds?: number): string;
+    url(objectName: string): string;
+}
+/** The S3 store's buckets, by name, from `s3Settings`. */
+export declare class S3Buckets implements Buckets {
+    #private;
+    constructor(settings?: S3Settings);
+    get default(): Bucket;
+    bucket(name: string): Bucket;
+    get buckets(): Bucket[];
+}
+/** What stands behind every bucket of a service. */
+export type StorageBackend = "s3" | "directory" | "memory" | "unavailable";
+export interface ChosenStorage {
+    readonly backend: StorageBackend;
+    readonly buckets: Buckets;
+}
+export interface StorageChoiceOptions {
+    /** Where `service.json` is read from, for the buckets it declares: the working directory by default. */
+    readonly serviceDirectory?: string;
+    /** The service's own address, for the directory store's URLs. */
+    readonly addressBase?: () => string;
+}
+/**
+ * The one place a process's store is chosen, as the runtime chooses its own: `ANKKA_STORAGE_BACKEND` when
+ * set (`s3`, `directory` or `memory`); otherwise S3 when any `ANKKA_S3_*` bucket is given, the directory
+ * store (`ANKKA_STORAGE_DIR`, default `.ankka/storage`) on a developer's machine — anywhere Kubernetes did
+ * not start the process — and no store at all on the platform. Throws, naming the variable, when the
+ * settings cannot be read: a service that cannot reach its buckets does not start.
+ */
+export declare function chooseStorage(env?: Env, options?: StorageChoiceOptions): ChosenStorage;
+/** The store the server chose for this process, which every component's `storage` answers unless a test gave it one. */
+export declare function processStorage(): Buckets;
+/** @internal The server's: the store this process was given. */
+export declare function _setProcessStorage(buckets: Buckets): void;
+export {};