@vibesdotdev/storage 0.0.2 → 1.0.0-rc.4

package/dist/manifest/base.js

@@ -1,3 +1,5 @@
+import { pushManifestToCloudAfterLocalSave } from "./cloud-sync.js";
+import { StorageAdapterConfigSchema as ManifestAdapterConfigSchema } from "../schemas/adapter-config.js";
 /**
  * Storage Manifest Base Class
  *
@@ -6,21 +8,54 @@
  *
  * Uses runtime query API to resolve the appropriate adapter.
  */
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
+import * as z from 'zod/v4';
+import { ZodSchemaValueSchema } from "../schemas/zod-schema-value.js";
 import { getLogger } from '@vibesdotdev/logging';
-import { getVibesRuntime } from '@vibesdotdev/runtime/api/runtime';
-import { createTracer } from '@vibesdotdev/runtime/debug';
-import { isBuildingEnvironment } from '@vibesdotdev/runtime';
-import { resolveHomePath, resolveScopePathTemplate, resolveWorkspacePath } from '../paths.js';
-import { toErrorContext } from '../utils/error-context.js';
-const logger = getLogger('storage:manifest');
+import { CapabilityError, CaughtFailureSchema, isCapabilityError, settle, settleNow, valueFreeFailure } from '@vibesdotdev/kernel';
+import { SelectedDocumentIdentitySchema } from "../schemas/document-identity.js";
+export { FilesystemDocumentIdentitySchema, LogicalDocumentIdentitySchema, SelectedDocumentIdentitySchema } from "../schemas/document-identity.js";
+import { StorageManifestDescriptorSchema } from "../schemas/manifest-descriptor.js";
+import { createTracer } from '@vibesdotdev/kernel/debug';
+import { getPathRoots } from '@vibesdotdev/paths';
+import { resolveGlobalStorageBasePath, readHostWorkspace, resolveScopePathTemplate, resolveWorkspacePathWithPolicy as resolveWorkspacePath } from "../path-policy.js";
+import { resolveStoragePolicyOverridesFromContext } from "../policy/overrides.js";
+import { selectStorageAdapter } from "../adapters/select-adapter.js";
+/** Refuse `CANCELLED storage-load-cancelled` when the caller's signal has aborted. */
+function throwIfLoadCancelled(options, manifestId) {
+    if (!options?.signal?.aborted)
+        return;
+    throw new CapabilityError('The storage read was cancelled by its caller.', 'CANCELLED', {
+        reason: 'storage-load-cancelled',
+        retryable: false,
+        details: { manifestId }
+    });
+}
+/** The adapter id a pending (not yet resolved) manifest's placeholder names. */
+const PENDING_MANIFEST_ADAPTER = 'storage.pending-resolution';
+/** A manifest id handed instead of a descriptor (resolved on first use). */
+const ManifestIdSchema = z.string().min(1);
+import { CloudEndpointsSchema, EndpointRegistrarSchema, extractCloudEndpoint, registerCloudEndpointIfSupported } from "../schemas/cloud-endpoints.js";
+/**
+ * Whether a descriptor's schema is a zod schema. The manifest's document type
+ * `T` is the one its registered descriptor declares: the schema it carries
+ * produces it.
+ */
+function isDocumentSchema(schema) {
+    return ZodSchemaValueSchema.safeParse(schema).success;
+}
+/** Notify one subscriber; a subscriber that throws is reported once, never thrown into the notifier. */
+function notifySubscriber(runtime, callback, data) {
+    const logger = getLogger('storage:manifest', runtime);
+    try {
+        callback(data);
+    }
+    catch (error) {
+        logger.error('Error in manifest subscriber', { error: valueFreeFailure(CaughtFailureSchema.parse(error)) });
+    }
+}
+/** The longest a cloud push after a save may run before the runtime stops waiting for it. */
+export const CLOUD_SYNC_PUSH_TIMEOUT_MS = 60_000;
+const CLOUD_SYNC_PUSH_INCOMPLETE = 'Cloud sync push after save did not complete';
 /**
  * Base class for storage manifests.
  *
@@ -37,7 +72,7 @@ const logger = getLogger('storage:manifest');
  * // The runtime will instantiate this with the descriptor
  *
  * // Manual instantiation by ID
- * const storage = StorageManifest.fromId<AIProvider[]>('ai.providers');
+ * const storage = StorageManifest.fromId<AIProvider[]>('ai.providers', runtime);
  * const providers = await storage.load();
  *
  * // Extended class with custom methods
@@ -53,6 +88,8 @@ export class StorageManifest {
     descriptor;
     context;
     adapterCache = null;
+    adapterCacheId = null;
+    adapterBasePathSemantics = 'unused';
     // Lazy resolution
     pendingId = null;
     pendingContext;
@@ -64,34 +101,45 @@ export class StorageManifest {
     subscribers = new Set();
     storeUnsubscribe = null;
     subscriptionStarted = false;
+    /** The runtime this manifest was handed; there is no ambient default. */
     getRuntime() {
-        return this.context.runtime ?? getVibesRuntime();
+        const runtime = this.context.runtime;
+        if (!runtime) {
+            throw new CapabilityError(`Storage manifest '${this.descriptor.id}' was built without a runtime.`, 'INVALID_INPUT', { reason: 'storage-runtime-missing', retryable: false });
+        }
+        return runtime;
     }
     /**
      * Create a storage manifest instance.
      *
      * @param descriptorOrId - Either the full descriptor (for runtime instantiation)
      *                         or the manifest ID string (for manual instantiation)
-     * @param context - Runtime context (optional for manual instantiation, required for runtime)
+     * @param context - The runtime context the manifest reads and writes through
+     *                  (`{ runtime }`); required, there is no ambient runtime.
      */
     constructor(descriptorOrId, context) {
-        if (typeof descriptorOrId === 'string') {
+        if (!(descriptorOrId instanceof Object)) {
+            const pending = { data: ManifestIdSchema.parse(descriptorOrId) };
             // Defer descriptor resolution so module-level singletons don't crash
             // when imported before the runtime is bootstrapped (e.g. SSR imports).
-            this.pendingId = descriptorOrId;
+            this.pendingId = pending.data;
             this.pendingContext = context;
             // Set stub descriptor so property accesses before resolve don't throw
-            this.descriptor = {
-                id: descriptorOrId,
+            // A pending placeholder: its schema refuses everything and its adapter
+            // is a marker; ensureResolved() replaces it before any read uses either.
+            this.descriptor = StorageManifestDescriptorSchema.parse({
+                id: pending.data,
                 kind: 'storage/manifest',
-                namespace: descriptorOrId
-            };
-            this.context = context ?? { runtime: getVibesRuntime() };
+                namespace: pending.data,
+                allowedAdapters: [PENDING_MANIFEST_ADAPTER],
+                schema: z.never()
+            });
+            this.context = context;
         }
         else {
             // Direct descriptor (runtime instantiation)
             this.descriptor = descriptorOrId;
-            this.context = context ?? { runtime: getVibesRuntime() };
+            this.context = context;
             this.resolved = true;
         }
     }
@@ -102,23 +150,16 @@ export class StorageManifest {
     ensureResolved() {
         if (this.resolved || !this.pendingId)
             return;
-        const runtime = this.pendingContext?.runtime ??
-            this.context.runtime ??
-            getVibesRuntime();
-        const hasKind = runtime.hasKind('storage/manifest');
-        if (!hasKind) {
-            // Runtime not yet bootstrapped — keep the stub descriptor.
-            // It will be re-resolved on next access after bootstrap.
-            return;
+        const runtime = this.getRuntime();
+        if (!runtime.hasKind('storage/manifest')) {
+            throw new CapabilityError(`Storage manifest '${this.pendingId}' cannot resolve: the handed runtime composes no storage/manifest kind.`, 'UNAVAILABLE', { reason: 'storage-manifest-kind-unavailable', retryable: false });
         }
-        const descriptor = runtime
-            .query('storage/manifest')
-            .filter((d) => d.id === this.pendingId)
-            .firstDescriptor();
+        const descriptor = runtime.query('storage/manifest').withId(this.pendingId).descriptors()[0];
         if (!descriptor) {
-            if (isBuildingEnvironment())
-                return;
-            throw new Error(`Storage manifest '${this.pendingId}' not found. Is it registered?`);
+            throw new CapabilityError(`Storage manifest '${this.pendingId}' is not registered.`, 'NOT_FOUND', {
+                reason: 'storage-manifest-not-registered',
+                retryable: false
+            });
         }
         this.descriptor = descriptor;
         this.context = this.pendingContext ?? { runtime };
@@ -128,17 +169,26 @@ export class StorageManifest {
     }
     /**
      * Create a storage manifest by looking up its ID.
-     * Convenience static method for manual instantiation.
+     * Convenience static method for manual instantiation, bound to the runtime
+     * the caller holds (there is no ambient runtime).
      */
-    static fromId(manifestId) {
-        return new StorageManifest(manifestId);
+    static fromId(manifestId, runtime) {
+        return new StorageManifest(manifestId, { runtime });
     }
     /**
      * Get the schema for this manifest.
      */
     get schema() {
         this.ensureResolved();
-        return this.descriptor.schema;
+        const schema = this.descriptor.schema;
+        if (!isDocumentSchema(schema)) {
+            throw new CapabilityError(`Storage manifest '${this.descriptor.id}' declares no zod schema.`, 'INVALID_INPUT', {
+                reason: 'storage-manifest-schema-missing',
+                retryable: false,
+                details: { manifestId: this.descriptor.id }
+            });
+        }
+        return schema;
     }
     /**
      * Get the namespace for this manifest.
@@ -147,6 +197,89 @@ export class StorageManifest {
         this.ensureResolved();
         return this.descriptor.namespace;
     }
+    /**
+     * Create an isolated document partition while retaining this manifest's
+     * schema, adapter policy, and runtime context. The partition is a distinct
+     * adapter namespace, not a field inside a shared document, so deleting or
+     * recovering one principal cannot erase another principal's value.
+     */
+    partition(partitionId) {
+        this.ensureResolved();
+        if (!this.resolved) {
+            throw new Error(`Storage manifest '${this.descriptor.id}' must resolve before it can be partitioned.`);
+        }
+        const normalized = partitionId.trim();
+        if (!normalized)
+            throw new Error('Storage manifest partition id must not be empty.');
+        this.assertNamespaceAddressedPartition();
+        const namespace = `${this.descriptor.namespace}/${encodeURIComponent(normalized)}`;
+        return new StorageManifest({ ...this.descriptor, namespace }, this.context);
+    }
+    /** Discover persisted immediate partitions without reading their documents. */
+    async listPartitions() {
+        this.ensureResolved();
+        if (!this.resolved) {
+            throw new Error(`Storage manifest '${this.descriptor.id}' must resolve before listing partitions.`);
+        }
+        this.assertNamespaceAddressedPartition();
+        const { store } = await this.openStore();
+        if (!store.listChildNamespaces) {
+            throw new CapabilityError(`Storage manifest '${this.descriptor.id}' adapter does not support partition discovery.`, 'UNAVAILABLE', {
+                reason: 'storage-partition-discovery-unsupported',
+                retryable: false,
+                details: { manifestId: this.descriptor.id }
+            });
+        }
+        const prefix = `${this.descriptor.namespace}/`;
+        const partitions = (await store.listChildNamespaces()).map((namespace) => {
+            const encoded = namespace.startsWith(prefix) ? namespace.slice(prefix.length) : '';
+            let partitionId;
+            try {
+                partitionId = decodeURIComponent(encoded);
+            }
+            catch (error) {
+                throw new CapabilityError(`Storage manifest '${this.descriptor.id}' returned an invalid partition namespace.`, 'INTERNAL', {
+                    reason: 'storage-partition-namespace-invalid',
+                    retryable: false,
+                    details: { manifestId: this.descriptor.id },
+                    cause: CaughtFailureSchema.parse(error)
+                });
+            }
+            if (!partitionId ||
+                partitionId.trim() !== partitionId ||
+                encodeURIComponent(partitionId) !== encoded) {
+                throw new Error(`Storage manifest '${this.descriptor.id}' returned an invalid partition namespace.`);
+            }
+            return partitionId;
+        });
+        return [...new Set(partitions)].sort();
+    }
+    /**
+     * A partition can only be honest when the adapter's document address is the
+     * namespace passed to `documentStore()`. Adapter-specific configuration is
+     * opaque to storage core: an explicit filename, HTTP endpoint, table, object
+     * key, or a future adapter locator can alias every derived namespace back to
+     * the same physical document. Refuse all non-empty config for allowed
+     * adapters rather than maintaining an inevitably incomplete key blacklist.
+     */
+    assertNamespaceAddressedPartition() {
+        if (this.descriptor.customTables) {
+            throw new Error(`Storage manifest '${this.descriptor.id}' cannot be partitioned safely: customTables=true does not use the document namespace as the storage address.`);
+        }
+        for (const adapterId of this.descriptor.allowedAdapters) {
+            const config = this.descriptor.adapterConfig?.[adapterId];
+            if (config === undefined)
+                continue;
+            const parsedConfig = ManifestAdapterConfigSchema.safeParse(config);
+            if (!parsedConfig.success) {
+                throw new Error(`Storage manifest '${this.descriptor.id}' cannot be partitioned safely: adapterConfig['${adapterId}'] is not an empty configuration object.`);
+            }
+            const explicitOptions = Object.keys(parsedConfig.data);
+            if (explicitOptions.length > 0) {
+                throw new Error(`Storage manifest '${this.descriptor.id}' cannot be partitioned safely: adapterConfig['${adapterId}'] declares explicit option(s): ${explicitOptions.join(', ')}. StorageManifest.partition() only supports namespace-addressed document manifests with empty per-adapter configuration.`);
+            }
+        }
+    }
     /**
      * Resolve the adapter for this manifest using runtime query API.
      *
@@ -162,67 +295,60 @@ export class StorageManifest {
         // Adapters are runtime singletons, so manifest-specific configuration
         // must be re-applied on every access before reuse.
         if (this.adapterCache) {
-            this.adapterCache.configure(this.getAdapterConfig());
+            this.adapterCache.configure(this.getAdapterConfig(this.adapterCacheId ?? this.adapterCache.id, this.adapterBasePathSemantics));
             return this.adapterCache;
         }
         const adapterTracer = createTracer(`adapter:${this.descriptor.id}`);
         adapterTracer.start();
         const runtime = this.getRuntime();
-        let adapter = null;
-        let adapterId = '';
-        // Prefer explicit default adapter when available for current hardware.
-        if (this.descriptor.defaultAdapter &&
-            this.descriptor.allowedAdapters.includes(this.descriptor.defaultAdapter)) {
-            adapterId = this.descriptor.defaultAdapter;
-            try {
-                adapter = await runtime
-                    .query('storage/adapter')
-                    .withId(adapterId)
-                    .enabled()
-                    .resolve();
-            }
-            catch {
-                // Default adapter not registered or unavailable — fall through to allowed adapters
-                adapter = null;
-                adapterId = '';
-            }
-        }
-        // Fallback to first available adapter
-        if (!adapter) {
-            for (const allowedId of this.descriptor.allowedAdapters) {
-                try {
-                    adapter = await runtime
-                        .query('storage/adapter')
-                        .withId(allowedId)
-                        .enabled()
-                        .resolve();
-                    adapterId = allowedId;
-                    break;
-                }
-                catch {
-                    continue;
-                }
-            }
-        }
-        if (!adapter || !adapterId) {
-            throw new Error(`No available adapter for manifest '${this.descriptor.id}'. Checked: ${this.descriptor.allowedAdapters.join(', ')}`);
-        }
+        // A runtime-provided storage policy can override this manifest's default
+        // adapter by id — this is how an authenticated consumer flips a
+        // cloud-syncable manifest (e.g. agents) from the local `storage.json`
+        // default to `storage.cloud-api`, while an offline/unauthenticated
+        // consumer keeps the local default. The policy is provided as the
+        // resolved `storage/policy` context value and gated by the consumer that
+        // registers it (that consumer, not storage core, knows auth state).
+        //
+        // Fully backward compatible: no policy, an unparseable policy, or an
+        // override naming an adapter this manifest does not allow all fall
+        // through to `descriptor.defaultAdapter` — the exact prior behavior.
+        const policyOverride = resolveStoragePolicyOverridesFromContext(this.context['storage/policy'], this.descriptor.id);
+        const overrideAdapterId = policyOverride?.defaultAdapter &&
+            this.descriptor.allowedAdapters.includes(policyOverride.defaultAdapter)
+            ? policyOverride.defaultAdapter
+            : undefined;
+        // Prefer the policy override (if any), else the descriptor default. A
+        // preferred adapter that is offered but fails, or a policy adapter this
+        // runtime does not offer, is an error — never a silent reroute (RC06 U6).
+        const { adapter, adapterId, descriptor: adapterDescriptor } = await selectStorageAdapter(runtime, {
+            ownerKind: 'manifest',
+            ownerId: this.descriptor.id,
+            allowedAdapters: this.descriptor.allowedAdapters,
+            ...(overrideAdapterId
+                ? { preferred: { adapterId: overrideAdapterId, source: 'policy' } }
+                : this.descriptor.defaultAdapter
+                    ? { preferred: { adapterId: this.descriptor.defaultAdapter, source: 'descriptor' } }
+                    : {})
+        });
         // Adapters are shared across manifests. Always apply this manifest's
         // configuration before use so filename/basePath overrides stay isolated.
-        const config = this.getAdapterConfig(adapterId);
+        const basePathSemantics = adapterDescriptor.basePathSemantics ?? 'unused';
+        const config = this.getAdapterConfig(adapterId, basePathSemantics);
         adapter.configure(config);
         // Register per-manifest cloud endpoint overrides so cloud-api uses
         // descriptor endpoints (e.g. /api/storage/chat/rooms) instead of the
         // namespace fallback (/api/storage/chat.rooms).
         if (adapterId === 'storage.cloud-api') {
             const cloudEndpoint = this.getCloudApiEndpoint();
-            if (cloudEndpoint && this.hasCloudEndpointRegistrar(adapter)) {
-                adapter.registerEndpoint(this.descriptor.namespace, cloudEndpoint);
+            if (cloudEndpoint) {
+                registerCloudEndpointIfSupported(adapter, this.descriptor.namespace, cloudEndpoint);
             }
         }
         // Cache adapter but don't initialize yet
         // Initialization will happen on first data access
         this.adapterCache = adapter;
+        this.adapterCacheId = adapterId;
+        this.adapterBasePathSemantics = basePathSemantics;
         adapterTracer.end('resolved');
         return adapter;
     }
@@ -230,12 +356,26 @@ export class StorageManifest {
      * Get adapter configuration based on manifest scope.
      * Override in subclasses for custom configuration.
      */
-    getAdapterConfig(adapterId) {
-        const workspacePath = resolveWorkspacePath(this.context);
-        const config = {
-            basePath: this.getBasePath(workspacePath),
-            workspacePath
-        };
+    getAdapterConfig(adapterId, basePathSemantics = this.adapterBasePathSemantics) {
+        // Every adapter call runs on this manifest's runtime: an adapter that
+        // resolves origins or credentials (cloud-api) uses it, never an ambient one.
+        const config = { runtime: this.getRuntime() };
+        if (basePathSemantics === 'filesystem') {
+            // Hand the adapter THIS manifest's runtime path roots. A runtime that
+            // cannot answer for paths fails here, naming itself; there is no
+            // ambient fallback.
+            const roots = getPathRoots(this.getRuntime());
+            // The runtime-owned roots are also the sync fallback for manually-created
+            // consumer manifests. This preserves repo-root identity without admitting
+            // the consumer-only filesystem/worktree probe into universal core.
+            const workspacePath = resolveWorkspacePath(this.context, undefined, roots, undefined, undefined, readHostWorkspace(this.getRuntime()));
+            config.basePath = this.getBasePath(roots, workspacePath);
+            config.workspacePath = workspacePath;
+            config.roots = roots;
+            // Filesystem adapters wait (e.g. the JSON document lock) on the
+            // manifest's own runtime lifecycle (RC07).
+            config.lifecycle = this.getRuntime().lifecycle;
+        }
         // Pass through descriptor-level flags that adapters need
         if (this.descriptor.customTables) {
             config.customTables = true;
@@ -246,49 +386,43 @@ export class StorageManifest {
         // Pass through adapter-specific config from descriptor
         if (this.descriptor.adapterConfig) {
             const selectedAdapterId = adapterId || this.descriptor.defaultAdapter || this.descriptor.allowedAdapters[0];
-            const adapterSpecificConfig = this.descriptor.adapterConfig[selectedAdapterId];
-            if (adapterSpecificConfig && typeof adapterSpecificConfig === 'object') {
-                Object.assign(config, adapterSpecificConfig);
-            }
+            const adapterSpecificConfig = ManifestAdapterConfigSchema.safeParse(this.descriptor.adapterConfig[selectedAdapterId]);
+            if (adapterSpecificConfig.success)
+                Object.assign(config, adapterSpecificConfig.data);
             // Backward-compatible normalization for cloud adapter manifests.
             // Only promote endpoint -> apiEndpoint when endpoint is a full URL.
-            if (selectedAdapterId === 'storage.cloud-api' &&
-                typeof config.endpoint === 'string' &&
-                typeof config.apiEndpoint !== 'string' &&
-                config.endpoint.startsWith('http')) {
-                config.apiEndpoint = config.endpoint;
+            const endpoints = CloudEndpointsSchema.parse(config);
+            if (selectedAdapterId === 'storage.cloud-api' && endpoints.endpoint?.startsWith('http') && endpoints.apiEndpoint === undefined) {
+                config.apiEndpoint = endpoints.endpoint;
             }
         }
         return config;
     }
     getCloudApiEndpoint() {
-        const raw = this.descriptor.adapterConfig?.['storage.cloud-api'];
-        if (!raw || typeof raw !== 'object')
-            return null;
-        const endpoint = raw.endpoint;
-        return typeof endpoint === 'string' && endpoint.length > 0 ? endpoint : null;
+        const endpoint = extractCloudEndpoint(this.descriptor.adapterConfig);
+        return endpoint && endpoint.length > 0 ? endpoint : null;
     }
     hasCloudEndpointRegistrar(adapter) {
-        return typeof adapter.registerEndpoint === 'function';
+        return EndpointRegistrarSchema.safeParse(adapter).success;
     }
     /**
      * Get base path for storage based on scope.
      * Uses descriptor's scopePaths if provided, otherwise defaults.
      */
-    getBasePath(workspacePath = resolveWorkspacePath(this.context)) {
-        const home = resolveHomePath();
+    getBasePath(roots = getPathRoots(this.getRuntime()), workspacePath = resolveWorkspacePath(this.context, undefined, roots, undefined, undefined, readHostWorkspace(this.getRuntime()))) {
         const scope = this.descriptor.scope;
         // Use custom scope paths if provided
         if (this.descriptor.scopePaths) {
-            const customPath = this.descriptor.scopePaths[scope];
+            const customPath = scope === 'auto' ? undefined : this.descriptor.scopePaths[scope];
             if (customPath) {
-                return resolveScopePathTemplate(customPath, workspacePath);
+                return resolveScopePathTemplate(customPath, workspacePath, roots);
             }
         }
         // Default path resolution
         switch (scope) {
             case 'global':
-                return `${home}/.vibes/storage`;
+                // Profile-aware + dev/prod base-split (see resolveGlobalStorageBasePath).
+                return resolveGlobalStorageBasePath(roots);
             case 'project':
             case 'local':
                 return `${workspacePath}/.vibes/storage`;
@@ -322,19 +456,82 @@ export class StorageManifest {
         return this.cacheValid;
     }
     // Document Operations
+    /**
+     * Resolve the adapter and open a document store for it **atomically**.
+     *
+     * Adapters are runtime singletons carrying mutable per-manifest config — most
+     * importantly the JSON adapter's `basePath`/`filename`. `getAdapter()` applies
+     * this manifest's config, but the `await` boundary before a store is created
+     * lets a sibling manifest loading concurrently call `configure()` on the same
+     * singleton first, redirecting this store's reads to the wrong file. (That race
+     * silently dropped whole config manifests — e.g. `ai.providers` — to `null`
+     * whenever several were loaded in one `Promise.all`.)
+     *
+     * We close the window on both sides: re-apply this manifest's config
+     * **synchronously, immediately before** creating the store (no `await` between,
+     * so no sibling can interleave), and the JSON adapter snapshots its resolved
+     * path at `documentStore()` time so the store is immune to later reconfigures.
+     * Together these make concurrent multi-manifest reads correct.
+     */
+    async openStore() {
+        const adapter = await this.getAdapter();
+        adapter.configure(this.getAdapterConfig(this.adapterCacheId ?? adapter.id, this.adapterBasePathSemantics));
+        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        return { adapter, store };
+    }
+    /**
+     * The selected document owner's coordination identity: includes `basePath`
+     * only when the selected adapter descriptor declares `basePathSemantics: 'filesystem'`,
+     * so memory and remote adapters never require `paths/roots`.
+     */
+    async documentIdentity() {
+        const adapter = await this.getAdapter();
+        const adapterId = this.adapterCacheId ?? adapter.id;
+        const config = this.getAdapterConfig(adapterId, this.adapterBasePathSemantics);
+        adapter.configure(config);
+        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        if (this.adapterBasePathSemantics === 'filesystem') {
+            return SelectedDocumentIdentitySchema.parse({
+                kind: 'filesystem',
+                basePathSemantics: 'filesystem',
+                adapterId,
+                namespace: this.descriptor.namespace,
+                basePath: config.basePath,
+                documentPath: store.getPath()
+            });
+        }
+        return SelectedDocumentIdentitySchema.parse({
+            kind: 'logical',
+            basePathSemantics: this.adapterBasePathSemantics,
+            adapterId,
+            namespace: this.descriptor.namespace,
+            documentPath: store.getPath()
+        });
+    }
+    /** Fresh selected-owner metadata and conditional reads bypass this manifest's body cache. */
+    async documentRevisions() {
+        const { store } = await this.openStore();
+        if (!store.revisions)
+            throw new CapabilityError('The selected document adapter exposes no authoritative revision protocol.', 'UNAVAILABLE', {
+                reason: 'document-revision-unavailable', retryable: false, details: { manifestId: this.descriptor.id }
+            });
+        return store.revisions;
+    }
     /**
      * Load data from storage.
      *
      * @returns The stored data, or null if not found
      */
-    async load() {
+    async load(options) {
+        throwIfLoadCancelled(options, this.descriptor.id);
         // Return cached data if valid
         if (this.cacheValid) {
             return this.cachedData;
         }
-        const adapter = await this.getAdapter();
-        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
-        const data = await store.load();
+        const { store } = await this.openStore();
+        const data = await store.load(options);
+        // A read the caller cancelled is refused, never cached.
+        throwIfLoadCancelled(options, this.descriptor.id);
         // Update cache
         this.cachedData = data;
         this.cacheValid = true;
@@ -350,8 +547,7 @@ export class StorageManifest {
      * @param data - The data to save
      */
     async save(data) {
-        const adapter = await this.getAdapter();
-        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        const { adapter, store } = await this.openStore();
         await store.save(data);
         // Update cache
         this.cachedData = data;
@@ -361,14 +557,7 @@ export class StorageManifest {
         // Non-blocking cloud push when a consumer-local save needs to mirror to cloud.
         this.triggerCloudSync(adapter.id, data);
     }
-    /**
-     * Trigger a non-blocking cloud push after save.
-     * Only fires if the manifest has cloud-api in allowedAdapters.
-     *
-     * Consumer modules are loaded via opaque dynamic import to prevent Vite
-     * from tracing them into the client bundle — they contain Node.js APIs
-     * and must only run server-side.
-     */
+    /** Start the runtime-resolved cloud push after a local save. */
     triggerCloudSync(activeAdapterId, data) {
         if (!this.descriptor.allowedAdapters.includes('storage.cloud-api'))
             return;
@@ -376,31 +565,52 @@ export class StorageManifest {
             return;
         if (this.getRuntime().scope.hardware === 'cloud')
             return;
-        const consumerSyncModule = './cloud-sync.consumer';
-        void import(__rewriteRelativeImportExtension(/* @vite-ignore */ consumerSyncModule))
-            .then(({ pushManifestToCloudAfterLocalSave }) => pushManifestToCloudAfterLocalSave({
-            descriptor: this.descriptor,
-            data,
-            activeAdapterId
-        }))
-            .catch(() => {
-            // Non-blocking: don't fail the save operation on sync errors.
+        // Started, not awaited: the save never waits for the cloud. The push is
+        // work the runtime's lifecycle owns (see pushToCloudAfterSave).
+        void this.pushToCloudAfterSave(activeAdapterId, data);
+    }
+    /**
+     * The cloud push after a save, as lifecycle-owned work: bounded by
+     * {@link CLOUD_SYNC_PUSH_TIMEOUT_MS}, aborted when disposal begins, and a
+     * still-running push is joined by disposal within the finalization budget.
+     * The push records its own outcome in sync state; anything that escapes it
+     * (a module that fails to load, an unreadable sync state) is reported once
+     * on the manifest's logger with its value-free facts, never thrown into
+     * the save that already succeeded. The push is started unawaited, so the
+     * report itself never throws: when Logging refuses it (unprepared, or the
+     * runtime is disposing) the failure goes to the kernel diagnostics port.
+     */
+    async pushToCloudAfterSave(activeAdapterId, data) {
+        const runtime = this.getRuntime();
+        const args = { runtime, descriptor: this.descriptor, data, activeAdapterId };
+        const pushed = await settle(() => runtime.lifecycle.wait((signal) => pushManifestToCloudAfterLocalSave({ ...args, signal }), { timeoutMs: CLOUD_SYNC_PUSH_TIMEOUT_MS, reason: 'storage-cloud-sync-push' }));
+        if (pushed.ok)
+            return;
+        const reported = settleNow(() => getLogger('storage:cloud-sync', runtime).warn(CLOUD_SYNC_PUSH_INCOMPLETE, {
+            manifestId: this.descriptor.id,
+            error: valueFreeFailure(pushed.cause)
+        }));
+        if (reported.ok)
+            return;
+        // The diagnostics port renders only each failure's class, never its message.
+        runtime.diagnostics.error(CLOUD_SYNC_PUSH_INCOMPLETE, {
+            scope: 'storage',
+            plugin: 'storage:cloud-sync',
+            error: new AggregateError([pushed.cause, reported.cause], 'Logging refused the cloud sync failure report.')
         });
     }
     /**
      * Check if data exists in storage.
      */
     async exists() {
-        const adapter = await this.getAdapter();
-        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        const { store } = await this.openStore();
         return store.exists();
     }
     /**
      * Delete data from storage.
      */
     async delete() {
-        const adapter = await this.getAdapter();
-        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        const { store } = await this.openStore();
         await store.delete();
         // Clear cache
         this.cachedData = null;
@@ -417,14 +627,53 @@ export class StorageManifest {
         const data = await this.load();
         return data ?? defaultValue;
     }
+    /**
+     * The stored layer as written: validated, with no schema default filled
+     * (`null` when nothing is stored). Layered readers (config composition)
+     * merge this with the layers above it and parse once; ordinary callers use
+     * `load()`. An adapter path without `loadStored` is refused, never
+     * answered with the parsed document (which would carry defaults).
+     */
+    async loadStored(options) {
+        throwIfLoadCancelled(options, this.descriptor.id);
+        const { adapter, store } = await this.openStore();
+        if (!store.loadStored) {
+            throw new CapabilityError(`Storage adapter '${adapter.id}' cannot read the raw stored layer of manifest '${this.descriptor.id}'.`, 'UNAVAILABLE', { reason: 'storage-load-stored-unsupported', details: { manifestId: this.descriptor.id, adapterId: adapter.id } });
+        }
+        const loadStored = store.loadStored.bind(store);
+        const read = await settle(() => loadStored(options));
+        if (!read.ok) {
+            // A stored layer that breaks its schema names the manifest and adapter it belongs to.
+            if (isCapabilityError(read.cause) && read.cause.reason === 'stored-layer-invalid') {
+                throw new CapabilityError(`The stored layer of manifest '${this.descriptor.id}' (${adapter.id}) is invalid: ${read.cause.message}`, 'INVALID_INPUT', {
+                    reason: 'stored-layer-invalid',
+                    retryable: false,
+                    details: { ...read.cause.details, manifestId: this.descriptor.id, adapterId: adapter.id },
+                    cause: read.cause
+                });
+            }
+            throw read.cause;
+        }
+        throwIfLoadCancelled(options, this.descriptor.id);
+        return read.value;
+    }
     /**
      * Update data using a transform function.
      *
      * @param transform - Function that receives current data and returns updated data
      */
     async update(transform) {
+        const { adapter, store } = await this.openStore();
+        if (store.update) {
+            const updated = await store.update(transform);
+            this.cachedData = updated;
+            this.cacheValid = true;
+            this.notifySubscribers(updated);
+            this.triggerCloudSync(adapter.id, updated);
+            return;
+        }
         const current = await this.load();
-        const updated = transform(current);
+        const updated = await transform(current);
         await this.save(updated);
     }
     /**
@@ -462,8 +711,7 @@ export class StorageManifest {
     async initSubscription() {
         if (this.subscriptionStarted)
             return;
-        const adapter = await this.getAdapter();
-        const store = adapter.documentStore(this.descriptor.namespace, this.schema, this.descriptor);
+        const { store } = await this.openStore();
         if (store.subscribe) {
             this.startSubscription(store.subscribe.bind(store));
         }
@@ -497,14 +745,8 @@ export class StorageManifest {
      * Notify all subscribers of a change.
      */
     notifySubscribers(data) {
-        for (const callback of this.subscribers) {
-            try {
-                callback(data);
-            }
-            catch (error) {
-                logger.error('Error in manifest subscriber:', toErrorContext(error));
-            }
-        }
+        for (const callback of this.subscribers)
+            notifySubscriber(this.getRuntime(), callback, data);
     }
     /**
      * Get the number of active subscribers.