@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/host-files.js

@@ -0,0 +1,60 @@
+/**
+ * Storage's consumer-only features (backup, retention, sync state) read and
+ * write host files at absolute paths: the Vibes home, a workspace's `.vibes`,
+ * the backups directory. They reach the host only through the runtime's
+ * `filesystem/adapter` kind (unbound: absolute host paths, never a workspace
+ * binding), whose path mechanics (join, dirname, basename) they use too.
+ * Nothing here holds a host API.
+ */
+import { CapabilityError, CaughtFailureSchema } from '@vibesdotdev/kernel';
+import { resolveFileSystemAdapter } from '@vibesdotdev/filesystem/client/resolve-adapter';
+/**
+ * The unbound host filesystem adapter of `runtime`. A runtime without the kind
+ * refuses `UNAVAILABLE <reason>`; one without an adapter for its scope refuses
+ * with the filesystem's own `filesystem-adapter-*`.
+ */
+export async function hostFileSystemOf(runtime, reason) {
+    if (!runtime.hasKind('filesystem/adapter')) {
+        throw new CapabilityError('This runtime offers no filesystem (filesystem/adapter).', 'UNAVAILABLE', {
+            reason,
+            retryable: false,
+            recoveryHint: 'Compose a host environment that registers the filesystem/adapter kind (the Bun or Node host).'
+        });
+    }
+    return resolveFileSystemAdapter(runtime, { binding: false });
+}
+/**
+ * `stat` without following a link, or `undefined` when the path is absent.
+ * Only the host's `ENOENT` is absence; any other failure reaches the caller.
+ */
+export async function hostStat(fs, path) {
+    try {
+        return await fs.stat(path);
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        // Only the host's "no such entry" is absence; any other failure reaches the caller.
+        if (failure instanceof Error && 'code' in failure && failure.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** A file's UTF-8 text, or `undefined` when it is absent; any other failure reaches the caller. */
+export async function hostReadTextIfPresent(fs, path) {
+    try {
+        const content = await fs.readFile(path, 'utf-8');
+        return content instanceof Uint8Array ? new TextDecoder().decode(content) : content;
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        // Only the host's "no such entry" is absence; any other failure reaches the caller.
+        if (failure instanceof Error && 'code' in failure && failure.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Classify `path` without following a link. */
+export async function hostEntryKind(fs, path) {
+    return (await hostStat(fs, path))?.kind ?? 'missing';
+}
+//# sourceMappingURL=host-files.js.map

package/dist/host-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-files.js","sourceRoot":"","sources":["../src/host-files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAmB,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,gDAAgD,CAAC;AAQ1F;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAmB,EAAE,MAAc;IACzE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CAAC,yDAAyD,EAAE,aAAa,EAAE;YACnG,MAAM;YACN,SAAS,EAAE,KAAK;YAChB,YAAY,EAAE,+FAA+F;SAC7G,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,wBAAwB,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9D,CAAC;AAWD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,EAAkB,EAAE,IAAY;IAC9D,IAAI,CAAC;QACJ,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjD,oFAAoF;QACpF,IAAI,OAAO,YAAY,KAAK,IAAI,MAAM,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACjG,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC;AAED,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,EAAkB,EAAE,IAAY;IAC3E,IAAI,CAAC;QACJ,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,OAAO,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IACpF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjD,oFAAoF;QACpF,IAAI,OAAO,YAAY,KAAK,IAAI,MAAM,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACjG,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAkB,EAAE,IAAY;IACnE,OAAO,CAAC,MAAM,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,IAAI,SAAS,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -5,23 +5,25 @@
  *
  * @example
  * ```typescript
- * import { getVibesRuntime } from '@vibesdotdev/runtime';
  * import storagePlugin, { StorageManifest } from '@vibesdotdev/storage';
  *
- * // Register the storage plugin
- * await getVibesRuntime().registerPlugin(storagePlugin);
+ * // Register the storage plugin on the runtime you were handed
+ * await runtime.registerPlugin(storagePlugin);
  *
- * // Use storage manifest
- * const storage = new StorageManifest<MyData>('my.data');
+ * // Use storage manifest, bound to that runtime
+ * const storage = new StorageManifest<MyData>('my.data', { runtime });
  * const data = await storage.load();
  * ```
  */
-export { default as storagePlugin } from './storage.plugin';
-export { StorageProtocolSchema, StorageCapabilitySchema, StorageAdapterDescriptorSchema, StorageDriveSchema, StorageEntrySchema, StorageScopeSchema, StorageDataTypeSchema, StorageCloudApiAdapterConfigSchema, StorageManifestDescriptorSchema, StorageRecordDescriptorSchema, StorageSyncConfigSchema, StorageRemoteCrudSchema, StorageRemoteConfigSchema, StoragePersistenceModeSchema, StoragePersistencePolicySchema, StorageOwnershipFilterSchema } from './schemas';
-export type { StorageProtocol, StorageCapability, StorageAdapterDescriptor, StorageDrive, StorageEntry, StorageScope, StorageDataType, StorageCloudApiAdapterConfig, StorageManifestDescriptor, StorageRecordDescriptor, StorageRecordDescriptorInput, StorageSyncConfig, StorageRemoteCrud, StorageRemoteConfig, StoragePersistenceMode, StoragePersistencePolicy, StorageOwnershipFilter, StorageSyncContext, StorageRecordLocalSyncContext, StorageRecordRemoteSyncContext, StorageRecordSyncHooks } from './schemas';
-export { StorageManifest } from './manifest/base';
-export type { StorageAdapterInterface, StorageAdapterCapabilities, StorageHealthStatus, StorageDocumentStoreInterface, KeyValueSetOptions, StorageRepositoryInterface, RepositoryOptions, RepositoryCreateInput, RepositoryUpdateInput, RepositoryQuery, RepositoryListOptions, RepositoryFindOptions, RepositoryOrderBy, RepositoryPage, RepositoryMeta, StorageRecordInterface, FileBasedAdapterConfig, LocalDBAdapterConfig, JSONAdapterConfig, MemoryAdapterConfig, CloudAPIAdapterConfig, QueryBuilderDatabase } from './interfaces';
-export { bridgeStorageKinds } from './bridge';
-export type { StorageKindBridgeConfig } from './bridge';
-export { listBrowsableStorageAdapters } from './client';
+export { default as storagePlugin } from './storage.plugin.ts';
+export { StorageProtocolSchema, StorageCapabilitySchema, StorageBasePathSemanticsSchema, StorageAdapterDescriptorSchema, StorageAdapterConfigurationDiagnosticInputSchema, StorageAdapterConfigurationDiagnosticIssueSchema, StorageAdapterConfigurationDiagnosticSchema, StorageDriveSchema, StorageEntrySchema, StorageScopeSchema, StorageDataTypeSchema, StorageCloudApiAdapterConfigSchema, StorageManifestDescriptorSchema, StorageRecordDescriptorSchema, StorageSyncConfigSchema, StorageRemoteCrudSchema, StorageRemoteConfigSchema, StoragePersistenceModeSchema, StoragePersistencePolicySchema, StorageOwnershipFilterSchema } from './schemas/index.ts';
+export type { StorageProtocol, StorageCapability, StorageBasePathSemantics, StorageAdapterDescriptor, StorageAdapterConfigurationDiagnosticInput, StorageAdapterConfigurationDiagnosticIssue, StorageAdapterConfigurationDiagnostic, StorageDrive, StorageEntry, StorageScope, StorageDataType, StorageCloudApiAdapterConfig, StorageManifestDescriptor, StorageRecordDescriptor, StorageRecordDescriptorInput, StorageSyncConfig, StorageRemoteCrud, StorageRemoteConfig, StoragePersistenceMode, StoragePersistencePolicy, StorageOwnershipFilter, StorageSyncContext, StorageRecordLocalSyncContext, StorageRecordRemoteSyncContext, StorageRecordSyncHooks } from './schemas/index.ts';
+export { StoragePolicyContextSchema, StoragePolicyOverrideSchema, resolveStoragePolicyOverridesFromContext } from './policy/overrides.ts';
+export type { StoragePolicyContextValue } from './policy/overrides.ts';
+export { FilesystemDocumentIdentitySchema, LogicalDocumentIdentitySchema, SelectedDocumentIdentitySchema, StorageManifest, type FilesystemDocumentIdentity, type LogicalDocumentIdentity, type SelectedDocumentIdentity } from './manifest/base.ts';
+export type { StorageAdapterInterface, StorageAdapterCapabilities, StorageHealthStatus, StorageDocumentStoreInterface, KeyValueSetOptions, StorageRepositoryInterface, RepositoryOptions, RepositoryCreateInput, RepositoryUpdateInput, RepositoryQuery, RepositoryListOptions, RepositoryFindOptions, RepositoryOrderBy, RepositoryPage, RepositoryMeta, StorageRecordInterface, FileBasedAdapterConfig, LocalDBAdapterConfig, JSONAdapterConfig, MemoryAdapterConfig, CloudAPIAdapterConfig, QueryBuilderDatabase } from './interfaces/index.ts';
+export { bridgeStorageKinds } from './bridge/index.ts';
+export type { StorageKindBridgeConfig } from './bridge/index.ts';
+export { STORAGE_EXPLORER_CAPABILITY_ID, RendererStorageTargetSchema, StorageExplorerScopeSchema, StorageExplorerStatusSchema, listBrowsableStorageAdapters, projectStorageTargetForRenderer, storageExplorerCapabilityDescriptor, storageExplorerCapabilityExposure, storageExplorerCapabilityKind } from './client/index.ts';
+export type { RendererStorageTarget, StorageExplorerCapability, StorageExplorerScope, StorageExplorerStatus } from './client/index.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI5D,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,WAAW,CAAC;AAEnB,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIlD,YAAY,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,6BAA6B,EAC7B,kBAAkB,EAClB,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,sBAAsB,EAEtB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EAErB,oBAAoB,EACpB,MAAM,cAAc,CAAC;AAItB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAIxD,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAI/D,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,8BAA8B,EAC9B,gDAAgD,EAChD,gDAAgD,EAChD,2CAA2C,EAC3C,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACX,eAAe,EACf,iBAAiB,EACjB,wBAAwB,EACxB,wBAAwB,EACxB,0CAA0C,EAC1C,0CAA0C,EAC1C,qCAAqC,EACrC,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,4BAA4B,EAC5B,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,6BAA6B,EAC7B,8BAA8B,EAC9B,sBAAsB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,0BAA0B,EAC1B,2BAA2B,EAC3B,wCAAwC,EACxC,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAIvE,OAAO,EACN,gCAAgC,EAChC,6BAA6B,EAC7B,8BAA8B,EAC9B,eAAe,EACf,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,MAAM,oBAAoB,CAAC;AAI5B,YAAY,EACX,uBAAuB,EACvB,0BAA0B,EAC1B,mBAAmB,EACnB,6BAA6B,EAC7B,kBAAkB,EAClB,0BAA0B,EAC1B,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,sBAAsB,EAEtB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EAErB,oBAAoB,EACpB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAIjE,OAAO,EACN,8BAA8B,EAC9B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,mCAAmC,EACnC,iCAAiC,EACjC,6BAA6B,EAC7B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACX,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -5,25 +5,25 @@
  *
  * @example
  * ```typescript
- * import { getVibesRuntime } from '@vibesdotdev/runtime';
  * import storagePlugin, { StorageManifest } from '@vibesdotdev/storage';
  *
- * // Register the storage plugin
- * await getVibesRuntime().registerPlugin(storagePlugin);
+ * // Register the storage plugin on the runtime you were handed
+ * await runtime.registerPlugin(storagePlugin);
  *
- * // Use storage manifest
- * const storage = new StorageManifest<MyData>('my.data');
+ * // Use storage manifest, bound to that runtime
+ * const storage = new StorageManifest<MyData>('my.data', { runtime });
  * const data = await storage.load();
  * ```
  */
 // Plugin
-export { default as storagePlugin } from './storage.plugin.js';
+export { default as storagePlugin } from "./storage.plugin.js";
 // Schemas
-export { StorageProtocolSchema, StorageCapabilitySchema, StorageAdapterDescriptorSchema, StorageDriveSchema, StorageEntrySchema, StorageScopeSchema, StorageDataTypeSchema, StorageCloudApiAdapterConfigSchema, StorageManifestDescriptorSchema, StorageRecordDescriptorSchema, StorageSyncConfigSchema, StorageRemoteCrudSchema, StorageRemoteConfigSchema, StoragePersistenceModeSchema, StoragePersistencePolicySchema, StorageOwnershipFilterSchema } from './schemas';
+export { StorageProtocolSchema, StorageCapabilitySchema, StorageBasePathSemanticsSchema, StorageAdapterDescriptorSchema, StorageAdapterConfigurationDiagnosticInputSchema, StorageAdapterConfigurationDiagnosticIssueSchema, StorageAdapterConfigurationDiagnosticSchema, StorageDriveSchema, StorageEntrySchema, StorageScopeSchema, StorageDataTypeSchema, StorageCloudApiAdapterConfigSchema, StorageManifestDescriptorSchema, StorageRecordDescriptorSchema, StorageSyncConfigSchema, StorageRemoteCrudSchema, StorageRemoteConfigSchema, StoragePersistenceModeSchema, StoragePersistencePolicySchema, StorageOwnershipFilterSchema } from "./schemas/index.js";
+export { StoragePolicyContextSchema, StoragePolicyOverrideSchema, resolveStoragePolicyOverridesFromContext } from "./policy/overrides.js";
 // Base Classes
-export { StorageManifest } from './manifest/base.js';
+export { FilesystemDocumentIdentitySchema, LogicalDocumentIdentitySchema, SelectedDocumentIdentitySchema, StorageManifest } from "./manifest/base.js";
 // Bridge (storage → runtime kind hydration)
-export { bridgeStorageKinds } from './bridge';
+export { bridgeStorageKinds } from "./bridge/index.js";
 // Client surface (consumer-facing query helpers)
-export { listBrowsableStorageAdapters } from './client';
+export { STORAGE_EXPLORER_CAPABILITY_ID, RendererStorageTargetSchema, StorageExplorerScopeSchema, StorageExplorerStatusSchema, listBrowsableStorageAdapters, projectStorageTargetForRenderer, storageExplorerCapabilityDescriptor, storageExplorerCapabilityExposure, storageExplorerCapabilityKind } from "./client/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,SAAS;AAET,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE5D,UAAU;AAEV,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,WAAW,CAAC;AA0BnB,eAAe;AAEf,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AA+BlD,4CAA4C;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,iDAAiD;AAEjD,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,SAAS;AAET,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE/D,UAAU;AAEV,OAAO,EACN,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,8BAA8B,EAC9B,gDAAgD,EAChD,gDAAgD,EAChD,2CAA2C,EAC3C,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kCAAkC,EAClC,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,8BAA8B,EAC9B,4BAA4B,EAC5B,MAAM,oBAAoB,CAAC;AA8B5B,OAAO,EACN,0BAA0B,EAC1B,2BAA2B,EAC3B,wCAAwC,EACxC,MAAM,uBAAuB,CAAC;AAG/B,eAAe;AAEf,OAAO,EACN,gCAAgC,EAChC,6BAA6B,EAC7B,8BAA8B,EAC9B,eAAe,EAIf,MAAM,oBAAoB,CAAC;AA+B5B,4CAA4C;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGvD,iDAAiD;AAEjD,OAAO,EACN,8BAA8B,EAC9B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,4BAA4B,EAC5B,+BAA+B,EAC/B,mCAAmC,EACnC,iCAAiC,EACjC,6BAA6B,EAC7B,MAAM,mBAAmB,CAAC"}

package/dist/interfaces/adapter.d.ts

@@ -7,37 +7,51 @@
  * Each adapter can specify its own config type and declare which
  * storage protocols and features it supports.
  */
+import type { KindContext } from '@vibesdotdev/kernel/schemas/kind';
+import type { RuntimeRef } from '@vibesdotdev/kernel';
 import type { z } from 'zod/v4';
-import type { StorageDocumentStoreInterface } from './document-store';
-import type { StorageKeyValueInterface } from './key-value';
-import type { StorageRepositoryInterface, RepositoryOptions } from './repository';
-import type { StorageRecordInterface } from './record';
-import type { StorageRecordDescriptor } from '../schemas/record';
-import type { StorageCapability, StorageDrive, StorageEntry } from '../schemas/adapter-descriptor';
+import type { StorageDocumentStoreInterface } from './document-store.ts';
+import type { StorageKeyValueInterface } from './key-value.ts';
+import type { StorageRepositoryInterface, RepositoryOptions } from './repository.ts';
+import type { StorageRecordInterface } from './record/index.ts';
+import type { StorageObjectStoreInterface } from './object-store.ts';
+import type { StorageRecordDescriptor } from '../schemas/record/index.ts';
+import type { StorageCapability, StorageDrive, StorageEntry } from '../schemas/adapter-descriptor.ts';
+import type { StorageManifestDescriptor } from '../schemas/manifest-descriptor.ts';
+import type { StorageAdapterConfigurationDiagnostic, StorageAdapterConfigurationDiagnosticInput } from '../schemas/adapter-configuration-diagnostic.ts';
+import type { CloudRecordCollection, StorageAdapterConfig, StorageDatabaseConnection, StorageHealthDetails } from '../schemas/adapter-config.ts';
 /**
  * Universal SQL database handle interface.
  *
- * Abstracts the underlying SQL driver (bun:sqlite, better-sqlite3, postgres, etc.)
+ * Abstracts the underlying SQL driver (LocalDB's host SQLite driver, postgres, etc.)
  * to keep storage core universal (no Node/Bun/SQL imports in core).
  *
  * Exposes only the surface area that storage core actually uses.
  */
 export interface SqlDatabaseHandle {
+    /** Optional native synchronous transaction; prepared commits never join an existing transaction. */
+    readonly inTransaction?: boolean;
+    transaction?<T>(run: () => T): T;
+    /** The file the handle has open (`:memory:` for an in-memory database), when the driver reports one. */
+    readonly path?: string;
     exec(sql: string): void;
-    query<T, P extends any[] = unknown[]>(sql: string): SqlStatement<T, P>;
+    /** A typed query: `T` is the row type the statement's SQL selects. */
+    prepare<T>(sql: string): SqlStatement<T>;
 }
 /**
- * Prepared SQL statement returned by SqlDatabaseHandle.query()
+ * Prepared SQL statement returned by SqlDatabaseHandle.prepare()
  */
-export interface SqlStatement<T, P extends any[] = unknown[]> {
-    all(...params: P): T[];
-    get(...params: P): T | undefined;
-    run(...params: P): void;
+export interface SqlStatement<T> {
+    all(...params: unknown[]): T[];
+    get(...params: unknown[]): T | null;
+    run(...params: unknown[]): {
+        readonly changes: number;
+    };
 }
 /**
  * Storage protocols supported by adapters
  */
-export type StorageProtocol = 'document' | 'keyvalue' | 'repository' | 'record';
+export type StorageProtocol = 'document' | 'keyvalue' | 'repository' | 'record' | 'object';
 /**
  * Storage adapter capabilities
  */
@@ -70,6 +84,8 @@ export interface StorageAdapterCapabilities {
     supportsSideEffects: boolean;
     /** Whether adapter supports raw SQL queries */
     supportsRawQueries: boolean;
+    /** Whether record updates support atomic conditional `where` preconditions */
+    supportsConditionalWrites?: boolean;
 }
 /**
  * Main storage adapter interface
@@ -92,7 +108,7 @@ export interface StorageAdapterCapabilities {
  * }
  * ```
  */
-export interface StorageAdapterInterface<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+export interface StorageAdapterInterface<TConfig extends StorageAdapterConfig = StorageAdapterConfig> {
     /**
      * Unique adapter identifier
      */
@@ -110,6 +126,13 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * Check if adapter is configured and ready
      */
     isConfigured(): boolean;
+    /**
+     * Diagnose one manifest's adapter configuration without opening a store,
+     * performing persistence I/O, or resolving credentials. Results contain
+     * actionable, value-free facts. Adapters without provider-specific
+     * configuration requirements may omit this capability.
+     */
+    diagnoseConfiguration?(input: StorageAdapterConfigurationDiagnosticInput, runtime: Pick<RuntimeRef, 'getBinding'>): StorageAdapterConfigurationDiagnostic | Promise<StorageAdapterConfigurationDiagnostic>;
     /**
      * Get a document store for a namespace
      *
@@ -125,7 +148,7 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * const config = await store.load();
      * ```
      */
-    documentStore<T>(namespace: string, schema: z.ZodType<T>, manifest?: unknown): StorageDocumentStoreInterface<T>;
+    documentStore<T>(namespace: string, schema: z.ZodType<T>, manifest?: Partial<StorageManifestDescriptor>): StorageDocumentStoreInterface<T>;
     /**
      * Get a key-value store for a namespace
      *
@@ -183,7 +206,24 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * const tree = await todos.getTree({ where: { sessionId: '...' }});
      * ```
      */
-    record<T = unknown>(descriptor: StorageRecordDescriptor): StorageRecordInterface<T>;
+    /**
+     * `context` is the runtime context the record reads and writes through; an
+     * adapter whose records resolve paths and hooks on a runtime requires it.
+     */
+    record<T = unknown>(descriptor: StorageRecordDescriptor, context?: KindContext): StorageRecordInterface<T>;
+    /**
+     * Get a key-addressed object (blob) store. Only adapters declaring the
+     * `object` protocol implement this — R2, S3/GCS, SharePoint. The store
+     * handles arbitrary bytes addressed by an opaque key, with streaming and
+     * URL semantics (see {@link StorageObjectStoreInterface}).
+     *
+     * @param namespace Optional logical container (bucket, or SharePoint
+     *   site+folder). Adapters that bind their container via `configure()` may
+     *   ignore it.
+     * @param config Optional per-call config overrides.
+     * @throws If the adapter doesn't support the object protocol.
+     */
+    objectStore?(namespace?: string, config?: StorageAdapterConfig): StorageObjectStoreInterface;
     /**
      * Enumerate the top-level "drives" exposed by this adapter.
      *
@@ -194,9 +234,13 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * descriptor are required to implement this method. Adapters that
      * don't browse omit it.
      *
+     * @param config - Optional per-call adapter config. An adapter that takes
+     *   it uses it as given for this call (its credentials included), because
+     *   the resolved adapter instance is shared and `configure()` would race
+     *   across concurrent scopes; omitted, the configured config applies.
      * @returns Promise resolving to all drives the current credential can see.
      */
-    listDrives?(): Promise<StorageDrive[]>;
+    listDrives?(config?: StorageAdapterConfig): Promise<StorageDrive[]>;
     /**
      * Enumerate files + directories inside a drive at the given path.
      *
@@ -207,9 +251,59 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * @param path - Path relative to the drive root. Use `''` (or omit
      *   when calling with two args) for the drive's top level. Segments
      *   joined with `/`.
+     * @param config - Optional per-call adapter config, as for `listDrives`.
      * @returns Promise resolving to the entries at that path.
      */
-    list?(driveId: string, path?: string): Promise<StorageEntry[]>;
+    list?(driveId: string, path?: string, config?: StorageAdapterConfig): Promise<StorageEntry[]>;
+    /**
+     * Enumerate files + directories inside a folder addressed by provider item id.
+     *
+     * Optional extension for providers whose path addressing can be lossy or
+     * unreliable for some folder names. SharePoint/Graph supports this via
+     * `/drive/items/{item-id}/children`.
+     *
+     * @param driveId - Drive identifier from `listDrives()`.
+     * @param itemId - Stable provider-side folder item id from a prior list/search result.
+     * @returns Promise resolving to the entries under that folder.
+     */
+    listItem?(driveId: string, itemId: string): Promise<StorageEntry[]>;
+    /**
+     * Search for files matching a text query within a drive.
+     *
+     * Only adapters that declare the `search` capability implement this method.
+     * Non-searchable object stores (R2, S3, GCS) do NOT implement it.
+     *
+     * @param driveId - Drive identifier from `listDrives()`.
+     * @param query - Free-text search query (content + metadata).
+     * @param opts.path - Optional subtree path to scope the search.
+     * @param opts.limit - Maximum results to return.
+     * @returns Promise resolving to matching entries.
+     */
+    search?(driveId: string, query: string, opts?: {
+        path?: string;
+        limit?: number;
+    }): Promise<StorageEntry[]>;
+    /**
+     * Mint a fresh, directly-fetchable download URL for a FILE entry — a URL a
+     * server-side consumer (e.g. a document renderer) can fetch with NO auth
+     * header. Optional extension for providers that can sign source URLs
+     * (SharePoint/Graph pre-authenticated download URLs).
+     *
+     * Prefer `ref.itemId` when both are given: provider path addressing can be
+     * lossy (search hits with partial parent paths, moved/renamed files), while
+     * the item id stays stable.
+     *
+     * @param driveId - Drive identifier from `listDrives()`.
+     * @param ref - The entry's stable item id and/or drive-root-relative path.
+     * @param config - Per-call adapter config (integration/site overrides);
+     *   passed explicitly because the resolved adapter instance is shared and
+     *   `configure()` would race across concurrent scopes.
+     * @returns The signed URL, or `null` when the entry cannot be resolved.
+     */
+    sourceUrlForEntry?(driveId: string, ref: {
+        itemId?: string;
+        path?: string;
+    }, config?: StorageAdapterConfig): Promise<string | null>;
     /**
      * Ensure adapter is fully initialized and database is ready for use.
      * Unlike initialize(), this also creates the database connection on first access.
@@ -223,7 +317,42 @@ export interface StorageAdapterInterface<TConfig extends Record<string, unknown>
      * @returns The raw database connection (e.g., bun:sqlite Database)
      * @throws If database is not initialized
      */
-    getDatabaseConnection(): unknown;
+    getDatabaseConnection(): StorageDatabaseConnection;
+    /**
+     * Get the database connection for a `storage/record`'s already-resolved
+     * `{ basePath, dbName }` target (the same values the adapter's own
+     * `configure()` receives for this record — see `StorageRecord`'s private
+     * `getAdapterConfig()`).
+     *
+     * Optional: only meaningful for adapters (like `storage.localdb`) whose
+     * database handle is a shared runtime singleton but whose actual physical
+     * file varies per descriptor (different `scope`/`dbName`). Those adapters
+     * resolve the connection from a `dbPath`-keyed pool instead of their own
+     * mutable `this.database`/`this.config`, so two `StorageRecord`s with
+     * different descriptors resolved concurrently can't race each other's
+     * `configure()` + `ensureReady()` + `getDatabaseConnection()` sequence
+     * onto the wrong physical database.
+     *
+     * Deliberately takes the caller's already-resolved `basePath`/`dbName`
+     * rather than re-deriving them from scope here — a `storage/record`'s
+     * scope→path mapping (`StorageRecord.getBasePath()`) is its own, distinct
+     * from a `storage/manifest` document-store's scope→path mapping, and
+     * conflating them would silently retarget every existing local record
+     * store to a different (empty) file. Adapters without per-descriptor
+     * targets (memory, a single remote connection, etc.) don't need to
+     * implement this; callers fall back to `ensureReady()` +
+     * `getDatabaseConnection()`.
+     *
+     * @param config.basePath - Directory the record's database file lives in.
+     * @param config.dbName - Database filename (adapter default if omitted).
+     * @param config.runtime - The record's runtime: the shared adapter reports this call's failures to its Logging.
+     * @returns The raw database connection scoped to that target.
+     */
+    getRecordDatabaseConnection?(config: {
+        basePath: string;
+        dbName?: string;
+        runtime: RuntimeRef;
+    }): Promise<StorageDatabaseConnection>;
     /**
      * Initialize the adapter (create tables, connect, etc.)
      * Called automatically on first use if not called explicitly.
@@ -245,7 +374,7 @@ export interface StorageHealthStatus {
     healthy: boolean;
     latencyMs?: number;
     error?: string;
-    details?: Record<string, unknown>;
+    details?: StorageHealthDetails;
 }
 /**
  * Extended adapter descriptor for storage adapters
@@ -269,11 +398,14 @@ export interface StorageAdapterDescriptorFields {
 /**
  * Config for file-based adapters (JSON, SQLite)
  */
-export interface FileBasedAdapterConfig {
+export interface FileBasedAdapterConfig extends StorageAdapterConfig {
     /** Base path for storage files */
     basePath: string;
-    /** Index signature for Record<string, unknown> compatibility */
-    [key: string]: unknown;
+    /**
+     * The configuring manifest's or record's runtime. A shared adapter reports
+     * failures to its Logging, never to an ambient default.
+     */
+    runtime?: RuntimeRef;
 }
 /**
  * Config for LocalDB adapter (SQLite)
@@ -302,19 +434,22 @@ export interface LocalDBAdapterConfig extends FileBasedAdapterConfig {
 export interface JSONAdapterConfig extends FileBasedAdapterConfig {
     /** Optional filename override for document manifests */
     filename?: string;
+    /**
+     * The configuring manifest's runtime lifecycle (RC07). The cross-process
+     * document lock waits on it: bounded by `wait`, paced by `delay`.
+     */
+    lifecycle?: Pick<import('@vibesdotdev/kernel').RuntimeLifecycle, 'wait' | 'delay'>;
     /** Pretty print JSON (default: false in prod) */
     prettyPrint?: boolean;
 }
 /**
  * Config for Memory adapter
  */
-export interface MemoryAdapterConfig {
+export interface MemoryAdapterConfig extends StorageAdapterConfig {
     /** Maximum items per namespace (for cache eviction) */
     maxItems?: number;
     /** Default TTL in milliseconds */
     defaultTTL?: number;
-    /** Index signature for Record<string, unknown> compatibility */
-    [key: string]: unknown;
 }
 /**
  * Config for Cloud Direct adapter (running ON cloud)
@@ -330,25 +465,9 @@ export interface CloudDirectAdapterConfig {
 /**
  * Config for Cloud API adapter (consumer → cloud bridge)
  */
-export interface CloudAPIAdapterConfig {
-    /** API endpoint URL (full origin, e.g. `https://ai.vibes.dev`). Optional
-     * when `ownerApp` is set — the adapter then resolves the origin from
-     * `config/environment.apps[ownerApp]` at init time. */
-    apiEndpoint?: string;
-    /** Owning app id (e.g. `'ai'`, `'tools'`, `'platform'`). When set, the
-     * adapter looks up `config/environment.apps[ownerApp]` to determine
-     * the base origin for requests. Lets storage manifests declare which
-     * cloud worker hosts their data without hardcoding origins per
-     * environment. Pairs with the runtime's `config/environment` kind so
-     * the same descriptor works in local / staging / production. */
-    ownerApp?: string;
-    /** API authentication token */
-    apiToken?: string;
-    /** Request timeout in milliseconds */
-    timeout?: number;
-    /** Index signature for Record<string, unknown> compatibility */
-    [key: string]: unknown;
-}
+/** The runtime the cloud-api adapter resolves origins and credentials on. */
+export type CloudAPIAdapterRuntime = RuntimeRef;
+export type CloudAPIAdapterConfig = import('../schemas/cloud-api.ts').CloudConfigFields;
 /**
  * Cloud settings client interface for API-based storage.
  * Generic methods allow type-safe storage operations.
@@ -359,7 +478,7 @@ export interface CloudSettingsClient {
     /** Set settings in cloud */
     set<T>(namespace: string, data: T): Promise<void>;
     /** Reconcile a records collection against its canonical CRUD endpoint */
-    reconcile<T extends Record<string, unknown>>(namespace: string, data: T): Promise<void>;
+    reconcile<T extends CloudRecordCollection>(namespace: string, data: T): Promise<void>;
     /** Perform a raw request against a configured cloud endpoint */
     request<T>(path: string, options?: RequestInit): Promise<T | null>;
     /** Delete settings from cloud */

package/dist/interfaces/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/interfaces/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/interfaces/adapter.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/document-store.d.ts

@@ -5,6 +5,9 @@
  * Schema validation is handled by the adapter.
  */
 import type { z } from 'zod/v4';
+import type { StoredLayer } from '../schemas/record/query-values.ts';
+import type { DocumentRevisionAccess } from '../schemas/document-revision.ts';
+export type { DocumentRevisionAccess, DocumentRevisionMetadata, DocumentRevisionRead } from '../schemas/document-revision.ts';
 /**
  * Callback for change subscriptions
  */
@@ -13,6 +16,10 @@ export type DocumentChangeCallback<T> = (data: T | null) => void;
  * Unsubscribe function returned by subscribe()
  */
 export type Unsubscribe = () => void;
+/**
+ * Atomic update transform for adapters that can serialize document updates.
+ */
+export type DocumentUpdateTransform<T> = (current: T | null) => T | Promise<T>;
 /**
  * Document store for single-document storage
  *
@@ -23,17 +30,43 @@ export type Unsubscribe = () => void;
  * await store.save({ ...config, temperature: 0.7 });
  * ```
  */
+/** Options for a document read. */
+export interface StorageLoadOptions {
+    /**
+     * The caller's cancellation: an adapter that performs I/O passes it on (a
+     * remote adapter to its request); an aborted read refuses `CANCELLED`.
+     */
+    signal?: AbortSignal;
+}
 export interface StorageDocumentStoreInterface<T> {
+    /** Optional authoritative freshness, supplied by the selected adapter only. */
+    readonly revisions?: DocumentRevisionAccess<T>;
     /**
      * Load the document
+     * @param options - The caller's signal (optional, additive)
      * @returns The document or null if not found
      */
-    load(): Promise<T | null>;
+    load(options?: StorageLoadOptions): Promise<T | null>;
+    /**
+     * Load the stored layer as written: validated against the schema, but with
+     * no `.default()` filled — `null` when nothing is stored. This is a layered
+     * reader's input: it merges raw layers, then parses once, so a default can
+     * never shadow a layer composed above the stored one. `load()` keeps its
+     * meaning (the parsed document) for ordinary callers. Optional: an adapter
+     * path without it (e.g. localdb custom tables) leaves layered reads refused.
+     */
+    loadStored?(options?: StorageLoadOptions): Promise<StoredLayer>;
     /**
      * Save the document
      * @param data The document to save
      */
     save(data: T): Promise<void>;
+    /**
+     * Atomically update the document when supported by the adapter.
+     * The transform may be retried by optimistic adapters, so it must not
+     * perform external side effects.
+     */
+    update?(transform: DocumentUpdateTransform<T>): Promise<T>;
     /**
      * Check if the document exists
      */
@@ -42,6 +75,13 @@ export interface StorageDocumentStoreInterface<T> {
      * Delete the document
      */
     delete(): Promise<void>;
+    /**
+     * List persisted documents immediately below this store's namespace.
+     * Returns full child namespaces, without loading their documents. Nested
+     * descendants and documents from other namespaces must not be returned.
+     * Optional: adapters without namespace discovery leave this unavailable.
+     */
+    listChildNamespaces?(): Promise<string[]>;
     /**
      * Get the storage path/location (for debugging)
      */

package/dist/interfaces/document-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-store.d.ts","sourceRoot":"","sources":["../../src/interfaces/document-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC/C;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAChB,6BAA6B,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"document-store.d.ts","sourceRoot":"","sources":["../../src/interfaces/document-store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE9H;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE/E;;;;;;;;;GASG;AACH,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC/C,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAE/C;;;;OAIG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEtD;;;;;;;OAOG;IACH,UAAU,CAAC,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhE;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE3D;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE3B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE1C;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAChB,6BAA6B,CAAC,CAAC,CAAC,CAAC"}