@voltro/plugin-storage 0.84.0 → 0.86.0

package/dist/index.d.ts

@@ -9,11 +9,14 @@ import { mixin } from '@voltro/database';
 import { PluginEgressDeclaration } from '@voltro/protocol';
 import { Readable } from 'node:stream';
 import { Schema } from 'effect';
+import { StorageAccessPolicy } from '@voltro/protocol';
+import { StorageAccessRule } from '@voltro/protocol';
 import { Stream } from 'effect';
 import { Subject } from '@voltro/protocol';
 import { Table } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
 
 export declare interface AccessOptions {
     /** Resolve a subject's group ids. Default: `subject.metadata.groups`. */
@@ -22,7 +25,7 @@ export declare interface AccessOptions {
     readonly guards?: Record<string, StorageGuard>;
 }
 
-export declare type AccessPolicy = ReadonlyArray<AccessRule>;
+export declare type AccessPolicy = StorageAccessPolicy;
 
 /**
  * One access rule. A rule GRANTS when EVERY present condition is satisfied
@@ -30,24 +33,7 @@ export declare type AccessPolicy = ReadonlyArray<AccessRule>;
  * grants (OR). An empty policy on a private object means owner-only (the
  * implicit owner check always applies).
  */
-export declare interface AccessRule {
-    /** `subject.id === ref.ownerId`. */
-    readonly owner?: boolean;
-    /** `subject.metadata.roles` intersects these. */
-    readonly roles?: ReadonlyArray<string>;
-    /** resolved groups (default `subject.metadata.groups`) intersect these. */
-    readonly groups?: ReadonlyArray<string>;
-    /** `subject.scopes` intersects these. */
-    readonly scopes?: ReadonlyArray<string>;
-    /** `subject.tenantId === ref.tenantId`. */
-    readonly tenant?: boolean;
-    /** subject is any authenticated api-key. */
-    readonly apiKey?: boolean;
-    /** a correct password was supplied (checked at mint, against passwordHash). */
-    readonly password?: boolean;
-    /** a named custom guard (`options.guards[name]`) returns true. */
-    readonly guard?: string;
-}
+export declare type AccessRule = StorageAccessRule;
 
 /**
  * The provider the APP configured, falling back to the env-derived default when no
@@ -72,6 +58,20 @@ export declare interface AssetRefOptions {
     readonly nullable?: boolean;
 }
 
+/** The caller owns the after-schema transaction, with serving replicas stopped.
+ * Assignments preserve reference IDs, keys, grants, raw put identities, claims
+ * and quota. No provider I/O or nested transaction occurs. Returned cleanup
+ * targets run through their matching service after boot. */
+export declare const assignStorageObjectNamespacesInTransaction: (store: DataStore, scopes: readonly StorageReferenceScope[], assignments: readonly StorageObjectNamespaceAssignment[]) => Promise<StorageObjectNamespaceMigrationResult>;
+
+/** Run in an after-schema migration with serving replicas stopped. The mapping
+ * comes from the operator, never from provider failures or the default name.
+ * The supplied store belongs to the caller’s transaction. No nested transaction
+ * is opened. Only ownership columns change: IDs, bytes, claims, quota and replay stay put. */
+export declare const assignStorageReferenceInstancesInTransaction: (store: DataStore, instances: readonly string[], assignments: readonly StorageReferenceInstanceAssignment[]) => Promise<{
+    readonly assigned: number;
+}>;
+
 export declare const azureProvider: (options: AzureProviderOptions) => StorageProvider;
 
 export declare interface AzureProviderOptions {
@@ -173,10 +173,10 @@ export declare const databaseProvider: () => StorageProvider & {
     bindDataStore: (store: unknown) => void;
 };
 
-export declare const dataStoreGrantStore: (store: DataStore) => GrantStore;
+export declare const dataStoreGrantStore: (store: DataStore, configuredScope: StorageReferenceScope) => GrantStore;
 
 /** Ref store backed by the app's `DataStore` (`_voltro_storage_refs`). */
-export declare const dataStoreRefStore: (store: DataStore) => RefStore;
+export declare const dataStoreRefStore: (store: DataStore, configuredScope: StorageReferenceScope) => RefStore;
 
 /** Decode a `data:<mime>;base64,<data>` URI to bytes + content type. */
 export declare const decodeDataUri: (dataUri: string) => {
@@ -193,10 +193,22 @@ export declare const decodeDataUri: (dataUri: string) => {
  */
 export declare const durabilityNotice: (path: string) => string | undefined;
 
+/**
+ * Apply a creative edit; null when the input is not an image, `sharp` is not
+ * installed, the edit is empty or fails. The format stays the input's.
+ */
+export declare const editImage: (bytes: Uint8Array, contentType: string, edit: ImageEdit) => Promise<Transformed | null>;
+
 /** Frame bytes for clamd `INSTREAM`: `zINSTREAM\0` then `<u32 len><data>`
  *  chunks, terminated by a zero-length chunk. Exposed for testing. */
 export declare const encodeInstream: (bytes: Uint8Array, chunkSize?: number) => Buffer;
 
+/** Boot-time initialization after normal schema reconciliation. This identity
+ * describes the persisted reference catalogue, not its provider bytes or host. */
+export declare const ensureStorageReferenceCatalogue: (store: DataStore) => Promise<void>;
+
+export declare const fetchIngestBody: (url: string, configuredMaxBytes?: number, policy?: IngestPolicy) => Effect.Effect<StoredObject, StorageError | StorageRejected>;
+
 export declare interface FfmpegRenditionSpec {
     /** Derivative class stored on the rendition ref — `'rendition'` / `'poster'`. */
     readonly kind: string;
@@ -286,6 +298,19 @@ export declare interface GrantTokenPayload {
 /** Hash a file password as `salt:scryptHash` (hex). */
 export declare const hashPassword: (password: string) => string;
 
+/** A creative edit: the result is new bytes, stored as a new version — unlike a delivery transform. */
+export declare interface ImageEdit {
+    /** Clockwise, in degrees. */
+    readonly rotate?: 90 | 180 | 270;
+    /** Mirror top to bottom. */
+    readonly flip?: boolean;
+    /** Mirror left to right. */
+    readonly flop?: boolean;
+    readonly grayscale?: boolean;
+    /** Cut this region out, in pixels of the original. */
+    readonly crop?: Region;
+}
+
 /** Where `ingestUrl` may fetch from — see `ssrfReason` in `@voltro/runtime`. */
 export declare interface IngestPolicy {
     /** Hosts (or `host:port`, or `*.suffix`) reachable although internal — a
@@ -333,15 +358,21 @@ export declare interface ListRefsResult {
 
 /** DataStore-backed metadata boundary, intentionally no provider access. The
  * service must use reserve -> provider.put -> confirm and retain failed intents. */
-export declare const makeStorageObjectMetadata: (store: DataStore) => {
+export declare const makeStorageObjectMetadata: (store: DataStore, configuredScope: StorageReferenceScope) => {
+    scope: Readonly<{
+        storageInstance: string;
+        objectNamespace: string;
+    }>;
     /** The put intent a reference was written under, if it was written through an operation at all. */
     intent: (refId: string) => Promise<{
         identity: {
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
         ref: StorageRef;
@@ -361,32 +392,38 @@ export declare const makeStorageObjectMetadata: (store: DataStore) => {
     beginDelete: (refId: string, tenantId?: string | null, claim?: string) => Promise<{
         released: true;
         identity: {
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
         operation?: never;
     } | {
         released: true;
         operation: {
-            readonly key: string;
             readonly id: string;
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
+            readonly objectId: string;
             readonly fingerprint: string;
             readonly generation: string;
-            readonly state: "ready" | "reserved" | "deleted" | "deleting";
+            readonly key: string;
             readonly refId: string;
-            readonly objectId: string;
+            readonly state: "ready" | "reserved" | "deleting" | "deleted";
             readonly deleteKey: string | null;
         };
         identity: {
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
     }>;
@@ -541,6 +578,9 @@ export declare interface RefStatistics {
 }
 
 export declare interface RefStore {
+    /** Stable identity of this actual reference view. Shared catalogues expose
+     * the same identity; independent/process-local stores must expose their own. */
+    readonly catalogueId: Effect.Effect<string, StorageError>;
     /** Aggregate the complete reference index without a recent-object limit. */
     readonly statistics: () => Effect.Effect<RefStatistics, StorageError>;
     readonly insert: (ref: StorageRef) => Effect.Effect<void, StorageError>;
@@ -593,6 +633,14 @@ export declare interface RefStore {
     readonly countPublicByKey?: ((bucket: string, key: string) => Effect.Effect<number, StorageError>) | undefined;
 }
 
+/** A region of an image in pixels. */
+declare interface Region {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+
 /** One derived output a `Transcoder` produces from a source asset. Each becomes
  *  a normal storage ref linked back to the original via `derivedFrom`. */
 export declare interface Rendition {
@@ -604,6 +652,9 @@ export declare interface Rendition {
     readonly label?: string;
 }
 
+/** Nullable additions deliberately fail closed until the explicit upgrade. */
+export declare const requireStorageObjectNamespaces: (store: DataStore) => Promise<void>;
+
 /** A `ListRefsInput` after the service normalizes its defaults / clamps — what
  *  a `RefStore.listRefs` impl receives. `limit` is already the `+1` probe. */
 export declare interface ResolvedListQuery {
@@ -655,23 +706,25 @@ export declare interface S3ProviderOptions {
     readonly publicAcl?: boolean;
 }
 
+declare type ScopedStorageObjectIdentity = StorageObjectIdentity & StorageReferenceScope;
+
 /** Register the app's storage provider (or clear with `undefined`). */
 export declare const setActiveStorageProvider: (provider: StorageProvider | undefined) => void;
 
 /** Sign a finalize token valid for `ttlSeconds`. */
-export declare const signFinalizeTicket: (fields: Omit<FinalizeTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signFinalizeTicket: (fields: Omit<FinalizeTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Mint a token granting read access to `refId` for `ttlSeconds`. */
 export declare const signGrant: (refId: string, ttlSeconds: number, secret?: string, audience?: string) => string;
 
 /** Sign a multipart ticket valid for `ttlSeconds`. */
-export declare const signMultipartTicket: (fields: Omit<MultipartTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signMultipartTicket: (fields: Omit<MultipartTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Sign a resumable ticket valid for `ttlSeconds`. */
-export declare const signResumableTicket: (fields: Omit<ResumableTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signResumableTicket: (fields: Omit<ResumableTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Sign an upload ticket valid for `ttlSeconds`. */
-export declare const signUploadTicket: (fields: Omit<UploadTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signUploadTicket: (fields: Omit<UploadTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** True if the bytes match the declared content type's magic number, OR we
  *  have no signature for that type (can't verify → don't block). */
@@ -681,6 +734,8 @@ export declare const STORAGE_BLOBS_TABLE = "_voltro_storage_blobs";
 
 export declare const STORAGE_GRANTS_TABLE = "_voltro_storage_grants";
 
+export declare const STORAGE_REFERENCE_CATALOGUE_TABLE = "_voltro_storage_reference_catalogue";
+
 export declare const STORAGE_REFS_TABLE = "_voltro_storage_refs";
 
 export declare const STORAGE_USAGE_TABLE = "_voltro_storage_usage";
@@ -693,12 +748,10 @@ export declare const STORAGE_USAGE_TABLE = "_voltro_storage_usage";
 export declare class StorageAccessDenied extends StorageAccessDenied_base {
 }
 
-declare const StorageAccessDenied_base: Schema.TaggedErrorClass<StorageAccessDenied, "StorageAccessDenied", {
-    readonly _tag: Schema.tag<"StorageAccessDenied">;
-} & {
-    refId: typeof Schema.String;
-    reason: typeof Schema.String;
-}>;
+declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema.TaggedStruct<"StorageAccessDenied", {
+    readonly refId: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
 
 /**
  * Where the bytes go, read from the same options and env `resolveProvider`
@@ -715,14 +768,12 @@ export declare const storageEgressOf: (options: StoragePluginOptions) => Readonl
 export declare class StorageError extends StorageError_base {
 }
 
-declare const StorageError_base: Schema.TaggedErrorClass<StorageError, "StorageError", {
-    readonly _tag: Schema.tag<"StorageError">;
-} & {
-    provider: typeof Schema.String;
-    message: typeof Schema.String;
-    transient: typeof Schema.Boolean;
-    status: Schema.optional<typeof Schema.Number>;
-}>;
+declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
+    readonly provider: Schema.String;
+    readonly message: Schema.String;
+    readonly transient: Schema.Boolean;
+    readonly status: Schema.optional<Schema.Number>;
+}>, YieldableError>;
 
 /** A persisted, explicit share of one object with one principal. */
 export declare interface StorageGrant {
@@ -752,8 +803,9 @@ export declare type StorageGuard = (ctx: {
  * and `BASE_NAME` is not exported, so a caller minting a ticket outside the
  * plugin had to guess it. Guessing is exactly what a `string` parameter invites.
  *
+ *     const writeScope = await Effect.runPromise(service.uploadTicketScope())
  *     const ticket = signUploadTicket(
- *       { instance: storageInstanceName(), key, contentType },
+ *       { writeScope, instance: storageInstanceName(options), key, ct: contentType, sub: ownerId, tenant: tenantId, vis: 'private' },
  *       300,
  *     )
  *
@@ -782,11 +834,14 @@ export declare const storageObjectLifecycleTables: ( Table<"_voltro_storage_oper
     readonly nonce: ColumnBuilder<string, "text", boolean>;
 }>, false, never> | Table<"_voltro_storage_object_heads", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
     readonly generation: ColumnBuilder<string, "text", boolean>;
     readonly key: ColumnBuilder<string, "text", boolean>;
     readonly reservations: ColumnBuilder<string, "bigint", boolean>;
 }>, false, never> | Table<"_voltro_storage_operations", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly storageInstance: ColumnBuilder<string | null, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
     readonly objectId: ColumnBuilder<string, "text", boolean>;
     readonly fingerprint: ColumnBuilder<string, "text", boolean>;
     readonly generation: ColumnBuilder<string, "text", boolean>;
@@ -802,6 +857,19 @@ export declare const storageObjectLifecycleTables: ( Table<"_voltro_storage_oper
 
 export declare type StorageObjectMetadata = ReturnType<typeof makeStorageObjectMetadata>;
 
+/** Credential-independent identity of a physical object-key namespace.
+ * Equal identities mean an equal key addresses the same provider bytes. */
+export declare const storageObjectNamespace: (parts: readonly string[]) => string;
+
+export declare interface StorageObjectNamespaceAssignment extends StorageReferenceScope {
+    readonly refId: string;
+}
+
+export declare interface StorageObjectNamespaceMigrationResult {
+    readonly assigned: number;
+    readonly pendingDeletes: readonly StorageObjectNamespaceAssignment[];
+}
+
 export declare const storagePlugin: (options?: StoragePluginOptions) => VoltroPlugin;
 
 export declare interface StoragePluginOptions {
@@ -866,12 +934,25 @@ export declare interface StoragePluginOptions {
     /** Access engine config — a group resolver + named custom guards. */
     readonly access?: AccessOptions;
     /**
-     * The access policy every PRIVATE client upload (an upload ticket) is
-     * stored with — declared by the app, never chosen by the client. Without
+     * The default policy for PRIVATE client uploads, or an Effect function
+     * authorizing self-service upload visibility and requested policies before the server signs a ticket. Without
      * it only the uploader (the implicit owner rule) can read a private upload;
      * `[{ tenant: true }]` lets everyone in the uploader's tenant read it.
      */
-    readonly uploadAccess?: AccessPolicy;
+    readonly uploadAccess?: AccessPolicy | ((request: {
+        readonly subject: Subject;
+        readonly requested: AccessPolicy | undefined;
+        readonly visibility: 'public' | 'private';
+        readonly contentType: string;
+    }) => Effect.Effect<AccessPolicy, StorageError>);
+    /**
+     * How long a browser or shared cache may keep a PUBLIC object the serve
+     * route delivers itself (and each transform of it). Default: a year,
+     * `immutable`. An object can turn private later; a copy cached before then
+     * keeps opening until this runs out — set it to bound that window (the
+     * bucket's own caching, behind a direct URL, is the provider's).
+     */
+    readonly publicCacheSeconds?: number;
     /** Upload constraints — size cap, content-type allow-list, magic-byte sniff. */
     readonly limits?: UploadLimits;
     /**
@@ -943,6 +1024,8 @@ export declare interface StoragePluginOptions {
  * access policy.
  */
 export declare interface StorageProvider {
+    /** Stable physical object-key namespace; exclude credentials and plugin aliases. */
+    readonly objectNamespace: Effect.Effect<string, StorageError>;
     /**
      * Where a FILESYSTEM provider writes. Absent for every other provider.
      *
@@ -1033,7 +1116,9 @@ export declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem
 export declare const storagePutIntentsTable: Table<"_voltro_storage_put_intents", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
     readonly refId: ColumnBuilder<string, "text", boolean>;
-    readonly identity: ColumnBuilder<StorageObjectIdentity, "json", boolean>;
+    readonly storageInstance: ColumnBuilder<string | null, "text", boolean>;
+    readonly objectNamespace: ColumnBuilder<string | null, "text", boolean>;
+    readonly identity: ColumnBuilder<ScopedStorageObjectIdentity, "json", boolean>;
     readonly ref: ColumnBuilder<StorageRef, "json", boolean>;
 }>, false, never>;
 
@@ -1083,18 +1168,32 @@ export declare interface StorageRef {
     readonly kind?: string | null;
 }
 
+export declare const storageReferenceCatalogueTable: Table<"_voltro_storage_reference_catalogue", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "text", boolean>;
+    readonly namespace: ColumnBuilder<string, "text", boolean>;
+}>, false, never>;
+
+export declare interface StorageReferenceInstanceAssignment {
+    readonly refId: string;
+    readonly storageInstance: string;
+}
+
+export declare interface StorageReferenceScope {
+    readonly storageInstance: string;
+    readonly objectNamespace: string;
+}
+
 /** An upload was rejected by a constraint (size / content-type / magic-byte
  *  mismatch). `reason` is a stable code; `detail` is human-readable. */
 export declare class StorageRejected extends StorageRejected_base {
+    get message(): string;
 }
 
-declare const StorageRejected_base: Schema.TaggedErrorClass<StorageRejected, "StorageRejected", {
-    readonly _tag: Schema.tag<"StorageRejected">;
-} & {
+declare const StorageRejected_base: Schema.Class<StorageRejected, Schema.TaggedStruct<"StorageRejected", {
     /** `'too-large' | 'content-type-not-allowed' | 'content-mismatch'` */
-    reason: typeof Schema.String;
-    detail: typeof Schema.String;
-}>;
+    readonly reason: Schema.String;
+    readonly detail: Schema.String;
+}>, YieldableError>;
 
 /** Scans bytes before they're stored. Return `{ clean:false, threat }` to
  *  reject the upload (fails with `StorageScanRejected`, nothing is stored). */
@@ -1108,11 +1207,9 @@ export declare type StorageScanner = (input: {
 export declare class StorageScanRejected extends StorageScanRejected_base {
 }
 
-declare const StorageScanRejected_base: Schema.TaggedErrorClass<StorageScanRejected, "StorageScanRejected", {
-    readonly _tag: Schema.tag<"StorageScanRejected">;
-} & {
-    threat: typeof Schema.String;
-}>;
+declare const StorageScanRejected_base: Schema.Class<StorageScanRejected, Schema.TaggedStruct<"StorageScanRejected", {
+    readonly threat: Schema.String;
+}>, YieldableError>;
 
 export declare interface StorageScanResult {
     readonly clean: boolean;
@@ -1123,7 +1220,7 @@ export declare interface StorageScanResult {
 export declare class StorageService extends StorageService_base {
 }
 
-declare const StorageService_base: Context.TagClass<StorageService, "@voltro/plugin-storage/StorageService", StorageServiceShape>;
+declare const StorageService_base: Context.ServiceClass<StorageService, "@voltro/plugin-storage/StorageService", StorageServiceShape>;
 
 export declare const storageServiceLayer: (options: StorageServiceOptions) => Layer.Layer<StorageService>;
 
@@ -1132,6 +1229,8 @@ export declare interface StorageServiceOptions {
     readonly refStore: RefStore;
     readonly grantStore: GrantStore;
     readonly bucket: string;
+    /** Canonical plugin instance; separates new plain keys on a shared provider. */
+    readonly storageInstance?: string;
     /** Static prefix prepended to every key (e.g. an app/env namespace). */
     readonly tenantPrefix?: string;
     /** Transient-failure retries (429 / 5xx / network). Default 3. */
@@ -1184,6 +1283,8 @@ export declare interface StorageServiceOptions {
 
 /** The service handlers consume: `const storage = yield* StorageService`. */
 export declare interface StorageServiceShape {
+    /** Opaque destination binding for manually signed upload-family credentials. */
+    readonly uploadTicketScope: () => Effect.Effect<string, StorageError>;
     /** Store bytes. The result is the ref plus this call's `outcome`. */
     readonly put: (input: PutInput) => Effect.Effect<StoredRef, StorageError | StorageRejected | StorageScanRejected>;
     /** Fetch an object's bytes by id. Enforces the tenant guard ONLY — it does
@@ -1370,6 +1471,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1403,6 +1505,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1452,6 +1555,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1564,10 +1668,14 @@ export declare interface UploadLimits {
 /** What an upload ticket authorizes: a single through-app upload bound to an
  *  owner/tenant/content-type/visibility, until `exp`. */
 export declare interface UploadTicketPayload {
+    /** Frozen-policy ticket contract. Previous tickets must be minted again. */
+    readonly version: 2;
     /** Optional durable write identity, preserved across ticket renewal. */
     readonly operationId?: string;
-    /** Inspect uploads may be pinned to their issuing process. */
-    readonly replicaId?: string;
+    /** Exact reference catalogue and physical byte destination authorized by the issuer. */
+    readonly writeScope: string;
+    /** Optional signed routing hint for the binary relay; destination authorization still uses writeScope. */
+    readonly issuerReplicaId?: string;
     /** Exact storage plugin instance authorized to accept the bytes. */
     readonly instance: string;
     /** ownerId (subject id) the stored object is attributed to. */
@@ -1577,6 +1685,8 @@ export declare interface UploadTicketPayload {
     /** Authorized content-type — the stored object uses this. */
     readonly ct: string;
     readonly vis: 'public' | 'private';
+    /** Server-authorized policy, frozen into the signed ticket. */
+    readonly access?: AccessPolicy;
     /** Optional fixed logical key (else content-addressed). */
     readonly key?: string;
     /** Max bytes the route will accept for this ticket (0/undefined = no cap). */