@voltro/plugin-storage 0.85.0 → 0.86.0

package/dist/index.d.ts

@@ -58,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 {
@@ -159,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) => {
@@ -189,6 +203,12 @@ export declare const editImage: (bytes: Uint8Array, contentType: string, edit: I
  *  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;
@@ -338,10 +358,16 @@ 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;
@@ -366,6 +392,8 @@ 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;
@@ -378,15 +406,19 @@ export declare const makeStorageObjectMetadata: (store: DataStore) => {
         released: true;
         operation: {
             readonly id: string;
+            readonly storageInstance: string;
+            readonly objectNamespace: string;
             readonly objectId: string;
             readonly fingerprint: string;
             readonly generation: string;
             readonly key: string;
             readonly refId: string;
-            readonly state: "ready" | "reserved" | "deleted" | "deleting";
+            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;
@@ -546,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>;
@@ -617,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 {
@@ -668,6 +706,8 @@ 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;
 
@@ -694,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";
@@ -761,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,
  *     )
  *
@@ -791,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>;
@@ -811,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 {
@@ -965,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.
      *
@@ -1055,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>;
 
@@ -1105,6 +1168,21 @@ 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 {
@@ -1151,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. */
@@ -1203,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
@@ -1587,11 +1669,13 @@ export declare interface UploadLimits {
  *  owner/tenant/content-type/visibility, until `exp`. */
 export declare interface UploadTicketPayload {
     /** Frozen-policy ticket contract. Previous tickets must be minted again. */
-    readonly version: 1;
+    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. */