@sema-agent/server 7.150.0 → 7.152.0

package/dist/object-store-buckets.d.ts

@@ -1,13 +1,647 @@
 /**
- * The two object-store buckets this server reads from and never creates (`docs/DEPLOY-PREREQS.md` "对象存储桶"), and the name each takes when its
- * knob is unset — ONE spelling of each default. The config loader (`config.ts`), the config catalog's default notes, the boot presence check's role
- * table (`plugins/snapshot-bucket-presence.ts`) and the k8s adapter's refusal sentence all read these constants; a literal copied into any of them is
- * a second source that drifts the day a default changes (the refusal would then name a bucket the loader no longer defaults to).
+ * Every object-store request this server signs or hands out — ONE closed table ({@link OBJECT_STORE_ACTIONS}), the one source of what the engine
+ * does to S3 / MinIO: which bucket (by the knob that names it), which key form, which S3 action, who sends the request, how long the signed URL
+ * lives, and for which feature. The server uses no S3 SDK: every request is a SigV4 presigned URL from one signing seat
+ * (`plugins/s3-presign.ts`), and that seat refuses to sign a request whose call does not name a row of this table (the row's id, {@link ObjectStoreOp},
+ * is a required argument and the row's action must be the verb signed). A row no code signs, or a request no row names, is red at the gates
+ * (the source gate and the recorded-wire gate). The names the rows use — bucket defaults, key prefixes — have their one spelling here too, and the
+ * config loader, the boot bucket check and the call sites read them from here.
  *
- * Pure leaf: no imports.
+ * Who reads it outside this process: a deployment tool that issues least-privilege object-store credentials per engine
+ * (`@sema-agent/server/object-store-buckets`) — the S3 permissions of a row are {@link OBJECT_STORE_ACTION_PERMISSIONS}, its resource is
+ * {@link objectKeyGlob} of its key form. Every row except the anonymous read is signed with the engine's one key (`MINIO_ACCESS_KEY`), so
+ * the engine's policy is the union of those rows; the anonymous row is the public bucket's own GetObject-only policy.
+ *
+ * Key forms: `{slot}` = a deployment value (a knob, {@link OBJECT_KEY_KNOB_SLOTS}: its value, or what an unset knob reads as); `<segment>` = a
+ * value minted per request ({@link OBJECT_KEY_SEGMENTS}); everything else is literal. A LIST row's key form is the listed prefix.
+ *
+ * Pure leaf: no imports (so the config loader, the boot check, the adapters and an outside deployment tool can all import it).
  */
-/** `SESSION_SNAPSHOT_BUCKET` unset ⇒ this bucket: snapshot-BLOB offload, and the SendUserFile private presigned track / sandbox staging. */
+/** `SESSION_SNAPSHOT_BUCKET` unset ⇒ this bucket: the session blob domains (file history, attachments, the retired snapshot epoch), and the SendUserFile private track / sandbox staging. */
 export declare const SESSION_SNAPSHOT_BUCKET_DEFAULT = "session-snapshots";
 /** `WORKSPACE_SNAPSHOT_BUCKET` unset ⇒ this bucket: the k8s lane's workspace snapshots (cross-run space snapshots and parked-run archives). */
 export declare const WORKSPACE_SNAPSHOT_BUCKET_DEFAULT = "workspaces";
+/** `S3_PUBLIC_BUCKET` unset ⇒ this bucket: the SendUserFile permanent track (anonymous GetObject-only policy, set by the operator). */
+export declare const S3_PUBLIC_BUCKET_DEFAULT = "sema-public";
+/** `WORKSPACE_SNAPSHOT_PREFIX` unset ⇒ this prefix (the first segment of every snapshot object key of both k8s lanes). */
+export declare const WORKSPACE_SNAPSHOT_PREFIX_DEFAULT = "kata";
+/** `SESSION_SNAPSHOT_PREFIX` unset ⇒ the retired snapshot epoch's blob root (its objects were written under it; the file-history and attachment domains read an unset prefix as empty). */
+export declare const LEGACY_BLOB_ROOT_DEFAULT = "blobs/";
+/** The file-history blob domain's segment under `SESSION_SNAPSHOT_PREFIX` (domain isolation: its sweep never sees another domain's objects). */
+export declare const FILE_HISTORY_BLOB_SEGMENT = "file-history/";
+/** The attachment blob domain's segment under `SESSION_SNAPSHOT_PREFIX` (same sha256 keys as file history, a different lifetime — never one namespace). */
+export declare const ATTACHMENT_BLOB_SEGMENT = "attachments/";
+/** The session blob namespace's claim object under `SESSION_SNAPSHOT_PREFIX` (the bucket × prefix the three blob domains share): its body names the one
+ *  database the namespace belongs to. Every key in those domains is a content address and every delete is judged by one database's references, so the
+ *  namespace is one database's; the first database to write the claim holds it (a create-only write), and a store whose database is not the one named
+ *  refuses to open. */
+export declare const SESSION_BLOB_CLAIM_KEY = "blob-namespace-claim";
+/** Why a `SESSION_SNAPSHOT_PREFIX` value is refused when the configuration loads (`undefined` = accepted). The retired epoch's root is the prefix itself, so a
+ *  prefix that ends in a live domain's segment (`…file-history/`, `…attachments/`) makes the domain of another engine — the one whose prefix is the rest of
+ *  the value — this engine's retired root, and this engine's retired-epoch sweep would delete that engine's live bytes (two namespaces whose keys meet). */
+export declare function sessionSnapshotPrefixProblem(prefix: string): string | undefined;
+/** The SendUserFile private track's prefix in the session snapshot bucket (keeps its objects apart from the blob domains). */
+export declare const SENDFILE_PRIVATE_PREFIX = "sendfile/";
+/** The SendUserFile staging segment under {@link SENDFILE_PRIVATE_PREFIX}: the only key a sandbox ever gets a write URL for. */
+export declare const SENDFILE_STAGING_SEGMENT = "staging/";
+/** The leader's diff-out key prefix in the `MINIO_BUCKET` bucket. */
+export declare const LEADER_DIFF_PREFIX = "leader-diff";
+/** The bucket knobs (closed set) → the bucket name when the knob is unset. `MINIO_BUCKET` shares the workspace bucket's default NAME (not its explicit value: the two knobs are independent). */
+export declare const OBJECT_STORE_BUCKET_KNOBS: {
+    readonly SESSION_SNAPSHOT_BUCKET: "session-snapshots";
+    readonly WORKSPACE_SNAPSHOT_BUCKET: "workspaces";
+    readonly MINIO_BUCKET: "workspaces";
+    readonly S3_PUBLIC_BUCKET: "sema-public";
+};
+export type ObjectStoreBucketKnob = keyof typeof OBJECT_STORE_BUCKET_KNOBS;
+/** The `{slot}`s of a key form (closed set): the knob each one is read from and what it reads as when the knob is unset. One knob can feed two slots that read its absence differently. */
+export declare const OBJECT_KEY_KNOB_SLOTS: {
+    readonly workspacePrefix: {
+        readonly knob: "WORKSPACE_SNAPSHOT_PREFIX";
+        readonly unset: "kata";
+    };
+    readonly sessionPrefix: {
+        readonly knob: "SESSION_SNAPSHOT_PREFIX";
+        readonly unset: "";
+    };
+    readonly legacyBlobRoot: {
+        readonly knob: "SESSION_SNAPSHOT_PREFIX";
+        readonly unset: "blobs/";
+    };
+};
+export type ObjectKeyKnobSlot = keyof typeof OBJECT_KEY_KNOB_SLOTS;
+/** The `<segment>`s of a key form (closed set) → what each one holds. Each is one key segment (no `/`). */
+export declare const OBJECT_KEY_SEGMENTS: {
+    readonly sessionId: "the parked run's session id (an env without one cannot park: its `_` placeholder is outside the key segment shape, so nothing is signed)";
+    readonly incarnation: "the space occupant's incarnation (the session occupant's minted id)";
+    readonly snapshotId: "a snapshot id minted for one upload (carries the writer's ownership mark)";
+    readonly object: "an object name read from the partition's listing";
+    readonly sha256: "the blob's content address (hex sha256)";
+    readonly scope: "the hashed tenant segment (`_` for a single-user deployment)";
+    readonly uuid: "a uuidv7 minted per file (the capability part of a link)";
+    readonly name: "the sanitized file name";
+    readonly run: "the leader run's object tag (time + random)";
+    readonly workerId: "the leader sub-worker id";
+};
+export type ObjectKeySegment = keyof typeof OBJECT_KEY_SEGMENTS;
+/** The S3 actions (closed set). `LIST` = ListObjectsV2 under the row's prefix; `COPY` = a server-side CopyObject into the row's key from its `from`. */
+export declare const OBJECT_STORE_ACTION_VERBS: readonly ["GET", "PUT", "HEAD", "DELETE", "LIST", "COPY"];
+export type ObjectStoreActionVerb = (typeof OBJECT_STORE_ACTION_VERBS)[number];
+/** The S3 permissions each action needs on its row's resource (`COPY` also needs `s3:GetObject` on its `from`). */
+export declare const OBJECT_STORE_ACTION_PERMISSIONS: {
+    readonly GET: readonly ["s3:GetObject"];
+    readonly PUT: readonly ["s3:PutObject"];
+    readonly HEAD: readonly ["s3:GetObject"];
+    readonly DELETE: readonly ["s3:DeleteObject"];
+    readonly LIST: readonly ["s3:ListBucket"];
+    readonly COPY: readonly ["s3:PutObject"];
+};
+/** Who sends the request on the wire (closed set). Every signed URL is signed by the server with the engine's key; the executor is who holds it. */
+export declare const OBJECT_STORE_EXECUTORS: {
+    readonly server: "the server process sends it itself (from its replica's network)";
+    readonly sandbox: "the execution sandbox sends it (a k8s pod, an e2b / ssh sandbox, a leader worker env): it holds the presigned URL only, never the key";
+    readonly client: "the end user's client fetches the link the server handed out";
+};
+export type ObjectStoreExecutor = keyof typeof OBJECT_STORE_EXECUTORS;
+/** The feature each row belongs to (closed set). */
+export declare const OBJECT_STORE_DOMAINS: {
+    readonly "k8s-park": "k8s lane: a parked run's workspace archive (suspend / resume) and its reclaim";
+    readonly "k8s-space": "k8s lane: the workspace space (run-end snapshot, `latest` pointer, restore, prune) and its reclaim";
+    readonly "boot-probe": "boot: the one bucket-presence check per bucket";
+    readonly "file-history": "file-history blob bytes";
+    readonly attachments: "task attachment bytes and their orphan sweep";
+    readonly "blob-claim": "the session blob namespace's claim: one database per bucket × SESSION_SNAPSHOT_PREFIX (checked when the store opens)";
+    readonly "legacy-blobs": "the retired snapshot epoch's blob bytes (sweep only)";
+    readonly sendfile: "SendUserFile: the permanent and presigned tracks and the sandbox staging two-phase";
+    readonly "leader-diff": "the leader's diff-out: a worker uploads its patch, the leader fetches it";
+};
+export type ObjectStoreDomain = keyof typeof OBJECT_STORE_DOMAINS;
+/** The longest a SigV4 presigned URL may live (`X-Amz-Expires` ≤ 604800 s = 7 days) — the ONE ceiling of every signed row. The signing seat refuses a
+ *  requested lifetime over it for any row (judged before anything else, never clamped), and every knob a row's lifetime is read from is refused above it
+ *  when the configuration loads (the knob and this number named). A row's own `maxSec` is a lower per-row policy cap (the k8s lane's 3600 s) that the seat
+ *  clamps a within-ceiling request to — a different thing. */
+export declare const SIGV4_PRESIGN_MAX_SEC = 604800;
+/**
+ * How long a row's URL lives — the signing seat reads this column (`plugins/s3-presign.ts` `rowTtlSec`), so it is the number, not a description of one:
+ * no `knob` = a fixed TTL, `defaultSec` exactly (a call never brings its own); a `knob` = the configured value the call brings (the knob, or the call's
+ * own argument), `defaultSec` when it brings none (absent = it must bring one), clamped to `maxSec` (a row's policy cap, below the ceiling). Whatever the
+ * row says, a lifetime over {@link SIGV4_PRESIGN_MAX_SEC} is refused. `"unsigned"` = an anonymous read: no signature, no expiry.
+ */
+export type ObjectStoreTtl = {
+    readonly defaultSec?: number;
+    readonly knob?: string;
+    readonly maxSec?: number;
+} | "unsigned";
+interface ObjectStoreActionRowBase {
+    readonly domain: ObjectStoreDomain;
+    /** What the row's key names inside its domain (the id is `<domain>/<subject>:<action>`). */
+    readonly subject: string;
+    readonly bucketKnob: ObjectStoreBucketKnob;
+    /** The key form (see the module head); a LIST row's is the listed prefix. */
+    readonly key: string;
+    readonly executor: ObjectStoreExecutor;
+    readonly ttl: ObjectStoreTtl;
+}
+/** One row of {@link OBJECT_STORE_ACTIONS}. A `COPY` row names its source object (`from`); no other row has one. */
+export type ObjectStoreActionRow = (ObjectStoreActionRowBase & {
+    readonly action: Exclude<ObjectStoreActionVerb, "COPY">;
+    readonly from?: never;
+}) | (ObjectStoreActionRowBase & {
+    readonly action: "COPY";
+    readonly from: {
+        readonly bucketKnob: ObjectStoreBucketKnob;
+        readonly key: string;
+    };
+});
+/** The table. Each row is one request the code makes; its id ({@link ObjectStoreOp}) is what a signing call names. */
+export declare const OBJECT_STORE_ACTIONS: readonly [{
+    readonly domain: "k8s-park";
+    readonly subject: "archive";
+    readonly action: "PUT";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<sessionId>/<snapshotId>.tar.gz";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-park";
+    readonly subject: "archive";
+    readonly action: "HEAD";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<sessionId>/<snapshotId>.tar.gz";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-park";
+    readonly subject: "archive";
+    readonly action: "GET";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<sessionId>/<snapshotId>.tar.gz";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-park";
+    readonly subject: "prefix";
+    readonly action: "LIST";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<sessionId>/";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-park";
+    readonly subject: "object";
+    readonly action: "DELETE";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<sessionId>/<object>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "archive";
+    readonly action: "PUT";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/<snapshotId>.tar.gz";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "archive";
+    readonly action: "HEAD";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/<snapshotId>.tar.gz";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "archive";
+    readonly action: "GET";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/<snapshotId>.tar.gz";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "archive";
+    readonly action: "DELETE";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/<snapshotId>.tar.gz";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "latest";
+    readonly action: "GET";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/latest";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "latest";
+    readonly action: "PUT";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/latest";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "latest";
+    readonly action: "DELETE";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/latest";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "prefix";
+    readonly action: "LIST";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "k8s-space";
+    readonly subject: "object";
+    readonly action: "DELETE";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/<incarnation>/space/<object>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+        readonly knob: "WORKSPACE_SNAPSHOT_TTL_SEC";
+        readonly maxSec: 3600;
+    };
+}, {
+    readonly domain: "boot-probe";
+    readonly subject: "session";
+    readonly action: "LIST";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{legacyBlobRoot}";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+    };
+}, {
+    readonly domain: "boot-probe";
+    readonly subject: "workspace";
+    readonly action: "LIST";
+    readonly bucketKnob: "WORKSPACE_SNAPSHOT_BUCKET";
+    readonly key: "{workspacePrefix}/";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+    };
+}, {
+    readonly domain: "file-history";
+    readonly subject: "blob";
+    readonly action: "PUT";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}file-history/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "file-history";
+    readonly subject: "blob";
+    readonly action: "GET";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}file-history/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "file-history";
+    readonly subject: "blob";
+    readonly action: "DELETE";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}file-history/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "attachments";
+    readonly subject: "blob";
+    readonly action: "PUT";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}attachments/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "attachments";
+    readonly subject: "blob";
+    readonly action: "GET";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}attachments/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "attachments";
+    readonly subject: "blob";
+    readonly action: "HEAD";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}attachments/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "attachments";
+    readonly subject: "blob";
+    readonly action: "DELETE";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}attachments/<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "attachments";
+    readonly subject: "prefix";
+    readonly action: "LIST";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}attachments/";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "legacy-blobs";
+    readonly subject: "blob";
+    readonly action: "DELETE";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{legacyBlobRoot}<sha256>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 3600;
+        readonly knob: "SESSION_SNAPSHOT_TTL_SEC";
+    };
+}, {
+    readonly domain: "blob-claim";
+    readonly subject: "claim";
+    readonly action: "GET";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}blob-namespace-claim";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "blob-claim";
+    readonly subject: "claim";
+    readonly action: "PUT";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "{sessionPrefix}blob-namespace-claim";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "public";
+    readonly action: "PUT";
+    readonly bucketKnob: "S3_PUBLIC_BUCKET";
+    readonly key: "<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "public";
+    readonly action: "COPY";
+    readonly bucketKnob: "S3_PUBLIC_BUCKET";
+    readonly key: "<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+    readonly from: {
+        readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+        readonly key: "sendfile/staging/<scope>/<uuid>";
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "public";
+    readonly action: "HEAD";
+    readonly bucketKnob: "S3_PUBLIC_BUCKET";
+    readonly key: "<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "public";
+    readonly action: "DELETE";
+    readonly bucketKnob: "S3_PUBLIC_BUCKET";
+    readonly key: "<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "public";
+    readonly action: "GET";
+    readonly bucketKnob: "S3_PUBLIC_BUCKET";
+    readonly key: "<scope>/<uuid>/<name>";
+    readonly executor: "client";
+    readonly ttl: "unsigned";
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "private";
+    readonly action: "PUT";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 600;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "private";
+    readonly action: "COPY";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+    readonly from: {
+        readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+        readonly key: "sendfile/staging/<scope>/<uuid>";
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "private";
+    readonly action: "HEAD";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "private";
+    readonly action: "DELETE";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/<scope>/<uuid>/<name>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "private";
+    readonly action: "GET";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/<scope>/<uuid>/<name>";
+    readonly executor: "client";
+    readonly ttl: {
+        readonly knob: "SEND_USER_FILE_URL_TTL";
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "staging";
+    readonly action: "PUT";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/staging/<scope>/<uuid>";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly defaultSec: 120;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "staging";
+    readonly action: "HEAD";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/staging/<scope>/<uuid>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "sendfile";
+    readonly subject: "staging";
+    readonly action: "DELETE";
+    readonly bucketKnob: "SESSION_SNAPSHOT_BUCKET";
+    readonly key: "sendfile/staging/<scope>/<uuid>";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly defaultSec: 60;
+    };
+}, {
+    readonly domain: "leader-diff";
+    readonly subject: "patch";
+    readonly action: "PUT";
+    readonly bucketKnob: "MINIO_BUCKET";
+    readonly key: "leader-diff/<run>/<workerId>.patch";
+    readonly executor: "sandbox";
+    readonly ttl: {
+        readonly knob: "LEADER_TIMEOUT_MS";
+    };
+}, {
+    readonly domain: "leader-diff";
+    readonly subject: "patch";
+    readonly action: "GET";
+    readonly bucketKnob: "MINIO_BUCKET";
+    readonly key: "leader-diff/<run>/<workerId>.patch";
+    readonly executor: "server";
+    readonly ttl: {
+        readonly knob: "LEADER_TIMEOUT_MS";
+    };
+}];
+type OpOf<R> = R extends {
+    readonly domain: infer D extends string;
+    readonly subject: infer S extends string;
+    readonly action: infer A extends string;
+} ? `${D}/${S}:${A}` : never;
+/** A row's id — `<domain>/<subject>:<action>`, the closed set of the table's rows. A signing call names one. */
+export type ObjectStoreOp = OpOf<(typeof OBJECT_STORE_ACTIONS)[number]>;
+/** The id of a row (the one way it is spelled). */
+export declare function objectStoreOpOf(row: ObjectStoreActionRow): string;
+/** The row an id names. An id outside the table throws (a caller that is not typed against {@link ObjectStoreOp}, e.g. an outside tool reading a string). */
+export declare function objectStoreActionOf(op: ObjectStoreOp): ObjectStoreActionRow;
+/**
+ * The knob slot that confines a row to one engine, or `undefined` when nothing does — the table's "can this row be fenced per engine" reading, read off
+ * the key form (not a second hand-kept column): a row is confined per engine when its key form, and a COPY row's source too, starts with a `{slot}` each
+ * engine can be given its own value for (`WORKSPACE_SNAPSHOT_PREFIX` / `SESSION_SNAPSHOT_PREFIX`). A key form that starts with a literal (`sendfile/…`,
+ * `leader-diff/…`) or with a segment minted per request (the public bucket's `<scope>/…`) names the same objects for every engine on the bucket: a
+ * per-engine policy cannot fence those rows apart, and engines that share the bucket share them.
+ */
+export declare function objectStoreRowEngineSlot(row: ObjectStoreActionRow): ObjectKeyKnobSlot | undefined;
+/**
+ * A key form as a policy resource pattern: each `{slot}` replaced by the deployment's value (`slots`; absent ⇒ what the unset knob reads as), each
+ * `<segment>` by `*` (`{sessionPrefix}attachments/<sha256>` with the knob unset ⇒ `attachments/*`). The bucket is the row's `bucketKnob` value;
+ * a LIST row's pattern is the `s3:prefix` its listing asks for.
+ */
+export declare function objectKeyGlob(key: string, slots?: Partial<Record<ObjectKeyKnobSlot, string>>): string;
+export {};
 //# sourceMappingURL=object-store-buckets.d.ts.map