@spine-event-engine/storage-datastore 2.0.0-snapshot.24 → 2.0.0-snapshot.26

package/dist/datastore/storage-factory.js

@@ -11,19 +11,18 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { Datastore } from "@google-cloud/datastore";
-import { StringifierRegistry } from "@spine-event-engine/core";
+import { and, Datastore, PropertyFilter } from "@google-cloud/datastore";
+import { defaultStringifierRegistry, StringifierRegistry } from "@spine-event-engine/core";
 import { RecordStorage, StorageFactory, } from "@spine-event-engine/storage";
-import {} from "@spine-event-engine/storage/provider";
-import { AgentExecutionRecords, AgentHistoryRecords, eventHistorySpec, stateHistorySpec, } from "@spine-event-engine/storage/provider";
-import { eventStoreRecordSpec } from "@spine-event-engine/storage/provider";
+import { StoragePreparations, TenantBoundary, } from "@spine-event-engine/storage/provider";
+import { AgentHistoryRecords, AgentModelPreferences, eventStoreRecordSpec, EventStoreGroups, eventHistorySpec, stateHistorySpec, } from "@spine-event-engine/storage/provider";
 import { EntityCommitStorageFactories } from "@spine-event-engine/storage/provider";
 import { AgentHistoryStorageFactories } from "@spine-event-engine/storage/provider";
-import { AgentExecutionStorageFactories } from "@spine-event-engine/storage/provider";
 import { DatastoreEntityCommitStorage, DatastoreEntityStorage, } from "./entity-history.js";
 import { DatastoreRecordStorage } from "./record-storage.js";
+import { RecordKinds } from "./record-kind.js";
+import { DatastoreIdColumn } from "./id-column.js";
 import { DatastoreAgentHistory, AgentHistoryHash } from "./agent-history.js";
-import { DatastoreAgentExecution } from "./agent-execution.js";
 import { DefaultNamespaceConverter, NamespaceAssignments, } from "./namespace.js";
 import { DatastoreTenantCatalog } from "./tenant-catalog.js";
 const maxClientSideScan = 1_000;
@@ -31,6 +30,12 @@ const maxClientSideScan = 1_000;
  * A Google Cloud Datastore-backed implementation of the Spine TS storage port.
  */
 export class DatastoreStorageFactory extends StorageFactory {
+    #commits = new Set();
+    #bundles = new Set();
+    /**
+     * Repeatable asynchronous close completion.
+     */
+    #closing;
     /**
      * Caller-supplied Datastore client.
      */
@@ -39,6 +44,10 @@ export class DatastoreStorageFactory extends StorageFactory {
      * Custom record creators indexed by source and record type.
      */
     #recordCreators;
+    /**
+     * Declarative custom record preparation callbacks by family.
+     */
+    #recordPreparers;
     /**
      * Physical layouts indexed by source and record type.
      */
@@ -47,6 +56,23 @@ export class DatastoreStorageFactory extends StorageFactory {
      * Custom Entity creators indexed by state type.
      */
     #entityCreators;
+    /**
+     * Declarative custom coherent Entity preparation callbacks by source type.
+     */
+    #entityPreparers;
+    /**
+     * Native physical definitions and successful or pending metadata checks.
+     */
+    #prepared = new Map();
+    #namespaces = new Map();
+    /**
+     * Complete admitted preparation and connection-check operations.
+     */
+    #work = new Set();
+    /**
+     * Remembered shared metadata check outcome while successful or in progress.
+     */
+    #connection;
     /**
      * Reversible tenant namespace assignment.
      */
@@ -55,6 +81,7 @@ export class DatastoreStorageFactory extends StorageFactory {
      * Message-valued ID and column conversion registry.
      */
     #stringifiers;
+    #eventStoreKinds;
     /**
      * Native tenant namespace catalog.
      */
@@ -65,130 +92,392 @@ export class DatastoreStorageFactory extends StorageFactory {
      * @returns A new factory builder.
      */
     static newBuilder() {
-        return new Builder((client, recordCreators, layouts, entityCreators, namespaceConverter, stringifiers) => new DatastoreStorageFactory(client, recordCreators, layouts, entityCreators, namespaceConverter, stringifiers));
+        return new Builder((client, recordCreators, recordPreparers, layouts, entityCreators, entityPreparers, namespaceConverter, stringifiers, eventStoreKinds) => new DatastoreStorageFactory(client, recordCreators, recordPreparers, layouts, entityCreators, entityPreparers, namespaceConverter, stringifiers, eventStoreKinds));
     }
     /**
      * Creates a factory from resolved dependencies.
      *
      * @param client The caller-owned Datastore client.
      * @param recordCreators Custom record-storage providers by record family.
+     * @param recordPreparers Declarative preparation callbacks by record family.
      * @param layouts Physical record layouts by record family.
      * @param entityCreators Custom Entity persistence providers by Entity type.
+     * @param entityPreparers Declarative preparation callbacks by Entity type.
      * @param namespaceConverter Converts complete tenants to native namespaces.
      * @param stringifiers Converts message-valued IDs and columns.
+     * @param eventStoreKinds Explicit native kinds by Event Store identity.
      * @internal
      */
-    constructor(client, recordCreators, layouts, entityCreators, namespaceConverter, stringifiers) {
+    constructor(client, recordCreators, recordPreparers, layouts, entityCreators, entityPreparers, namespaceConverter, stringifiers, eventStoreKinds) {
         super();
         this.#client = client;
         this.#recordCreators = recordCreators;
+        this.#recordPreparers = recordPreparers;
         this.#layouts = layouts;
         this.#entityCreators = entityCreators;
+        this.#entityPreparers = entityPreparers;
         this.#namespaceConverter = new NamespaceAssignments(namespaceConverter);
-        this.#stringifiers = new StringifierRegistry(stringifiers);
+        const shared = stringifiers === defaultStringifierRegistry;
+        this.#stringifiers = shared ? stringifiers : new StringifierRegistry(stringifiers);
+        this.#eventStoreKinds = eventStoreKinds;
         this.#catalog = new DatastoreTenantCatalog(client, this.#namespaceConverter);
+        StoragePreparations.register(this, {
+            prepareRecord: (context, spec, group, mode) => this.prepareRecord(context, spec, group, mode),
+            prepareEntity: (input, mode) => this.prepareEntity(input, mode),
+            prepareAgentHistory: (input) => this.prepareAgentHistory(input),
+            prepareAgentCommit: (input, mode) => this.prepareAgentCommit(input, mode),
+        });
         EntityCommitStorageFactories.register(this, {
-            createEntityCommitStorage: (input) => this.createEntityStorage(input).commits,
+            createEntityCommitStorage: (input) => this.createEntityCommitStorage(input),
         });
         this.registerAgentHistory();
-        this.registerAgentExecution();
     }
     /**
-     * Registers the required provider-only Agent history capability.
+     * Checks the shared namespace metadata with a bounded read-only query.
+     * @returns Completion after the metadata read; failures can be retried.
      */
-    registerAgentHistory() {
-        AgentHistoryStorageFactories.register(this, {
-            createAgentHistoryStorage: (input) => {
-                if (!this.isOpen())
-                    throw new Error("StorageFactory is closed.");
-                return new DatastoreAgentHistory(input, new DatastoreRecordStorage(input.context, AgentHistoryRecords.spec((value) => AgentHistoryHash.value(value)), this.#client, maxClientSideScan, AgentHistoryRecords.group, "spine_agent_history", this.#namespaceConverter, this.#stringifiers));
-            },
+    checkConnection() {
+        if (!this.isOpen())
+            return Promise.reject(new Error("StorageFactory is closed."));
+        if (this.#connection !== undefined)
+            return this.#connection;
+        const pending = this.admit(() => this.probe(this.#client.namespace ?? ""));
+        this.#connection = pending;
+        void pending.catch(() => {
+            if (this.#connection === pending)
+                this.#connection = undefined;
         });
+        return pending;
     }
     /**
-     * Registers the native transactional Agent execution capability.
+     * Performs one exact-key metadata read for a native namespace.
+     * @param namespace Native namespace to inspect.
+     * @returns Completion after the metadata query.
      */
-    registerAgentExecution() {
-        AgentExecutionStorageFactories.register(this, {
-            createAgentExecutionStorage: (input) => this.createAgentExecution(input),
-        });
+    async probe(namespace) {
+        const key = this.#client.key({ namespace: "", path: ["__namespace__", namespace || 1] });
+        const query = this.#client
+            .createQuery("", "__namespace__")
+            .select("__key__")
+            .filter(and([new PropertyFilter("__key__", ">=", key), new PropertyFilter("__key__", "<=", key)]));
+        await this.#client.runQuery(query);
     }
     /**
-     * Opens one Agent execution handle after factory lifecycle validation.
-     *
-     * @param input Requested fenced execution change.
-     * @returns Tenant-scoped Agent execution storage handle.
-     * @typeParam I Typed entity identifier.
-     * @typeParam S Generated Entity state.
+     * Admits asynchronous physical preparation before invoking callbacks.
+     * @param operation Work to perform within the factory lifetime.
+     * @returns Completion or rejection from the admitted work.
      */
-    createAgentExecution(input) {
+    admit(operation) {
         if (!this.isOpen())
-            throw new Error("StorageFactory is closed.");
-        return new DatastoreAgentExecution(input, this.executionRows(input));
+            return Promise.reject(new Error("StorageFactory is closed."));
+        const pending = Promise.resolve().then(operation);
+        this.#work.add(pending);
+        void pending.finally(() => this.#work.delete(pending)).catch(() => undefined);
+        return pending;
     }
     /**
-     * Opens the fixed execution kinds and existing Entity record families.
-     *
-     * @param input Requested fenced execution change.
-     * @returns Tenant-scoped native record handles.
-     * @typeParam I Typed entity identifier.
-     * @typeParam S Generated Entity state.
+     * Tracks a history batch before synchronously capturing caller-supplied values.
+     * @param operation Complete immutable audit group.
+     * @returns The admitted group outcome.
      */
-    executionRows(input) {
-        const context = input.entity.context;
-        const digest = (value) => AgentHistoryHash.value(value);
-        return {
-            invocation: this.executionRecord(context, AgentExecutionRecords.invocationSpec(digest), AgentExecutionRecords.invocationGroup, "spine_agent_execution"),
-            head: this.executionRecord(context, AgentExecutionRecords.headSpec(digest), AgentExecutionRecords.headGroup, "spine_agent_execution_head"),
-            history: this.executionRecord(context, AgentHistoryRecords.spec(digest), AgentHistoryRecords.group, "spine_agent_history"),
-            current: this.executionRecord(context, input.entity.recordSpec),
-            ...this.optionalExecutionRows(input),
-            events: this.executionRecord(context, eventStoreRecordSpec),
-        };
+    admitHistory = (operation) => {
+        if (!this.isOpen())
+            return Promise.reject(new Error("StorageFactory is closed."));
+        const { promise, resolve, reject } = Promise.withResolvers();
+        this.#work.add(promise);
+        void promise.finally(() => this.#work.delete(promise)).catch(() => undefined);
+        try {
+            void operation().then(() => {
+                resolve(undefined);
+            }, reject);
+        }
+        catch (error) {
+            reject(error);
+        }
+        return promise;
+    };
+    /**
+     * Prepares a declared record family without opening a storage handle.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Captured tenant context.
+     * @param spec The physical record declaration.
+     * @param group Optional history family.
+     * @param mode Creation or read-only checking.
+     * @returns Completion after native or custom preparation.
+     */
+    prepareRecord(context, spec, group, mode) {
+        return this.admit(() => this.prepareRecordAdmitted(context, spec, group, mode, true));
     }
     /**
-     * Opens optional existing Entity state and diagnostic record families.
-     *
-     * @param input Typed Agent repository and history configuration.
-     * @returns Optional native state and diagnostic handles.
+     * Prepares a family within an existing factory admission.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Captured tenant context.
+     * @param spec The physical record declaration.
+     * @param group Optional history family.
+     * @param mode Creation or read-only checking.
+     * @param allowCustom Whether ordinary custom creators are selected.
+     * @returns Completion after compatible preparation.
+     */
+    prepareRecordAdmitted(context, spec, group, mode, allowCustom) {
+        const resolved = this.resolve(spec, group, allowCustom);
+        if (resolved.creator !== undefined) {
+            const prepare = resolved.prepare;
+            if (prepare === undefined)
+                return Promise.reject(new Error("Custom Datastore record preparation is required."));
+            return prepare(context, spec, this.#client, mode);
+        }
+        return this.prepareNative(context, spec, group, resolved.layout?.kind);
+    }
+    /**
+     * Prepares current Entity and enabled history declarations without storage handles.
+     * @typeParam I Entity identifier type.
+     * @typeParam S Entity state type.
+     * @param input The declarative Entity family.
+     * @param mode Creation or read-only checking.
+     * @returns Completion after all requested families are checked.
+     */
+    prepareEntity(input, mode) {
+        return this.admit(async () => {
+            const custom = this.#entityCreators.get(input.sourceType.typeName);
+            if (custom !== undefined) {
+                const prepare = this.#entityPreparers.get(input.sourceType.typeName);
+                if (prepare === undefined)
+                    throw new Error("Custom Datastore Entity preparation is required.");
+                await prepare(input, this.#client, mode);
+                return;
+            }
+            if (this.columnSignature(input.columns) !== this.columnSignature(input.recordSpec.columns))
+                throw new Error("Datastore Entity query columns differ from current records.");
+            await this.prepareRecordAdmitted(input.context, input.recordSpec, undefined, mode, false);
+            if (input.stateHistory) {
+                const history = stateHistorySpec(input.stateSchema);
+                await this.prepareRecordAdmitted(input.context, history.spec, history.group, mode, false);
+            }
+            if (input.eventHistory) {
+                const history = eventHistorySpec(input.stateSchema);
+                await this.prepareRecordAdmitted(input.context, history.spec, history.group, mode, false);
+            }
+            await this.prepareRecordAdmitted(input.context, eventStoreRecordSpec, EventStoreGroups.forContext(input.context.name), mode, false);
+        });
+    }
+    /**
+     * Prepares the surviving Agent audit family.
+     * @typeParam I Agent identifier type.
+     * @param input Agent state and complete tenant context.
+     * @returns Completion after audit record compatibility is checked.
+     */
+    prepareAgentHistory(input) {
+        return this.admit(() => {
+            TenantBoundary.of(input.context);
+            if (!input.stateType.trim())
+                throw new TypeError("Agent state type is required.");
+            const spec = AgentHistoryRecords.spec((value) => AgentHistoryHash.value(value));
+            return this.prepareNative(input.context, spec, AgentHistoryRecords.group, "spine_agent_history");
+        });
+    }
+    /**
+     * Creates native live Agent current, audit, and preference requirements.
+     * @param input Declarative Agent Entity layout.
+     * @param mode Creation or read-only metadata check.
+     * @returns Completion after native definitions are compatible.
      * @typeParam I Typed Agent identifier.
      * @typeParam S Generated Agent state.
      */
-    optionalExecutionRows(input) {
-        const context = input.entity.context;
-        const state = input.entity.stateHistory
-            ? stateHistorySpec(input.entity.stateSchema)
-            : undefined;
-        const diagnostic = input.entity.eventHistory
-            ? eventHistorySpec(input.entity.stateSchema)
-            : undefined;
-        return {
-            ...(state === undefined
-                ? {}
-                : {
-                    states: this.executionRecord(context, state.spec, state.group),
-                }),
-            ...(diagnostic === undefined
-                ? {}
-                : {
-                    diagnostics: this.executionRecord(context, diagnostic.spec, diagnostic.group),
-                }),
+    prepareAgentCommit(input, mode) {
+        return this.admit(async () => {
+            if (this.#entityCreators.has(input.sourceType.typeName))
+                throw new Error("Custom Datastore Entity storage does not support native Agent transactions.");
+            if (this.columnSignature(input.columns) !== this.columnSignature(input.recordSpec.columns))
+                throw new Error("Datastore Entity query columns differ from current records.");
+            await this.prepareRecordAdmitted(input.context, input.recordSpec, undefined, mode, false);
+            if (input.stateHistory) {
+                const layout = stateHistorySpec(input.stateSchema);
+                await this.prepareRecordAdmitted(input.context, layout.spec, layout.group, mode, false);
+            }
+            if (input.eventHistory) {
+                const layout = eventHistorySpec(input.stateSchema);
+                await this.prepareRecordAdmitted(input.context, layout.spec, layout.group, mode, false);
+            }
+            await this.prepareRecordAdmitted(input.context, eventStoreRecordSpec, EventStoreGroups.forContext(input.context.name), mode, false);
+            await this.prepareAgentMetadata(input.context);
+        });
+    }
+    /**
+     * Checks the two native Agent audit families after current Entity declarations.
+     * @param context Complete tenant context.
+     * @returns Completion after both families are accessible.
+     */
+    async prepareAgentMetadata(context) {
+        await this.prepareNative(context, AgentHistoryRecords.spec((value) => AgentHistoryHash.value(value)), AgentHistoryRecords.group, "spine_agent_history");
+        await this.prepareNative(context, AgentModelPreferences.spec((value) => AgentHistoryHash.value(value)), AgentModelPreferences.group, "spine_agent_model_preferences");
+    }
+    /**
+     * Checks one native physical definition and its namespace read access.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Complete tenant context.
+     * @param spec The declared record family.
+     * @param group Optional physical group.
+     * @param explicitKind Configured or fixed native kind.
+     * @returns Completion after a compatible namespace read.
+     */
+    prepareNative(context, spec, group, explicitKind) {
+        const { namespace, kind, signature } = this.nativeDefinition(context, spec, group, explicitKind);
+        const family = JSON.stringify([namespace, kind]);
+        const prior = this.#prepared.get(family);
+        if (prior !== undefined && prior.signature !== signature)
+            throw new Error(`Datastore kind "${kind}" has an incompatible record definition.`);
+        if (prior?.ready)
+            return Promise.resolve();
+        if (prior?.pending !== undefined)
+            return prior.pending;
+        const entry = prior ?? {
+            signature,
+            ready: false,
+            declared: false,
+            pending: undefined,
         };
+        if (prior === undefined)
+            this.#prepared.set(family, entry);
+        return this.probePrepared(namespace, family, entry);
+    }
+    /**
+     * Checks one retained definition and records only successful readiness.
+     * @param namespace Native namespace to inspect.
+     * @param family Canonical physical family key.
+     * @param entry Existing compatible physical declaration.
+     * @returns Completion after the read-only metadata check.
+     */
+    probePrepared(namespace, family, entry) {
+        const pending = this.probe(namespace).then(() => {
+            entry.ready = true;
+            entry.pending = undefined;
+        }, (error) => {
+            entry.pending = undefined;
+            if (!entry.declared && this.#prepared.get(family) === entry)
+                this.#prepared.delete(family);
+            throw error;
+        });
+        entry.pending = pending;
+        return pending;
+    }
+    /**
+     * Records a successful native handle's pure layout for later compatibility checks.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Complete tenant context.
+     * @param spec The declared record family.
+     * @param group Optional physical group.
+     * @param explicitKind Configured or fixed native kind.
+     * @param mapping Actual native mapping from an opened handle.
+     */
+    declareNative(context, spec, group, explicitKind, mapping) {
+        const { namespace, kind, signature } = this.nativeDefinition(context, spec, group, explicitKind, mapping);
+        const family = JSON.stringify([namespace, kind]);
+        const prior = this.#prepared.get(family);
+        if (prior !== undefined && prior.signature !== signature)
+            throw new Error(`Datastore kind "${kind}" has an incompatible record definition.`);
+        if (prior === undefined)
+            this.#prepared.set(family, { signature, ready: false, declared: true, pending: undefined });
+        else
+            prior.declared = true;
     }
     /**
-     * Resolves one native kind through the existing record layout.
+     * Finds the pure native namespace, kind, and record layout declaration.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Complete tenant context.
+     * @param spec The declared record family.
+     * @param group Optional physical group.
+     * @param explicitKind Configured or fixed native kind.
+     * @param mapping Actual native mapping from an opened handle.
+     * @returns Canonical physical identity and signature.
+     */
+    nativeDefinition(context, spec, group, explicitKind, mapping) {
+        const namespace = mapping === undefined ? this.nativeNamespace(context) : (mapping.namespace ?? "");
+        const kind = mapping?.kind ?? this.selectedKind(spec, group, explicitKind);
+        if (!kind.trim() || Buffer.byteLength(kind, "utf8") > 1_500)
+            throw new Error("Datastore record kind must be non-blank and at most 1,500 bytes.");
+        new DatastoreIdColumn(spec.idType, this.#stringifiers);
+        if (typeof spec.idType !== "string")
+            this.#stringifiers.forMessage(spec.idType);
+        for (const column of spec.columns)
+            if (column.type.kind === "message")
+                this.#stringifiers.forMessage(column.type.message);
+        const signature = JSON.stringify([
+            spec.sourceType.typeName,
+            group === undefined ? null : (EventStoreGroups.identity(group) ?? group.name),
+            spec.recordType.typeName,
+            typeof spec.idType === "string" ? spec.idType : spec.idType.typeName,
+            this.columnSignature(spec.columns),
+        ]);
+        return { namespace, kind, signature };
+    }
+    /**
+     * Returns a configured or default native record kind.
      *
-     * @param context Captured event storage context.
-     * @param fixedKind Fixed native Datastore kind.
-     * @param group Fixed storage group.
-     * @param spec Typed record layout.
-     * @returns Typed native record handle.
-     * @typeParam I Typed entity identifier.
-     * @typeParam R Typed persisted record.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record message type.
+     * @param spec Declared record family.
+     * @param group Optional physical group.
+     * @param explicitKind Kind from a record layout.
+     * @returns The selected native kind.
+     */
+    selectedKind(spec, group, explicitKind) {
+        const identity = group === undefined ? undefined : EventStoreGroups.identity(group);
+        return ((identity === undefined ? undefined : this.#eventStoreKinds.get(identity)) ??
+            explicitKind ??
+            RecordKinds.of(spec.sourceType.typeName, spec.recordType.typeName, group));
+    }
+    /**
+     * Converts one complete tenant boundary to its native namespace.
+     * @param context Complete tenant context.
+     * @returns Its native Datastore namespace.
+     */
+    nativeNamespace(context) {
+        const boundary = TenantBoundary.of(context);
+        if (boundary.single)
+            return this.#client.namespace ?? "";
+        const cached = this.#namespaces.get(boundary.key);
+        if (cached !== undefined)
+            return cached;
+        const namespace = this.#namespaceConverter.toNamespace(boundary.tenantId);
+        this.#namespaces.set(boundary.key, namespace);
+        return namespace;
+    }
+    /**
+     * Captures physical column declarations without evaluating record callbacks.
+     * @typeParam R Stored record type.
+     * @param columns Declared query columns.
+     * @returns Stable physical column signature.
      */
-    executionRecord(context, spec, group, fixedKind) {
-        const kind = fixedKind ?? this.resolve(spec, group, false).layout?.kind;
-        return new DatastoreRecordStorage(context, spec, this.#client, maxClientSideScan, group, kind, this.#namespaceConverter, this.#stringifiers);
+    columnSignature(columns) {
+        return JSON.stringify(columns
+            .map(({ name, type }) => [
+            name,
+            type.kind,
+            type.kind === "scalar"
+                ? `${String(type.scalar)}:${String(type.longAsString)}`
+                : type.kind === "enum"
+                    ? type.enum.typeName
+                    : type.message.typeName,
+        ])
+            .sort(([first], [second]) => String(first).localeCompare(String(second))));
+    }
+    /**
+     * Registers the required provider-only Agent history capability.
+     */
+    registerAgentHistory() {
+        AgentHistoryStorageFactories.register(this, {
+            createAgentHistoryStorage: (input) => {
+                if (!this.isOpen())
+                    throw new Error("StorageFactory is closed.");
+                const spec = AgentHistoryRecords.spec((value) => AgentHistoryHash.value(value));
+                return new DatastoreAgentHistory(input, this.openNative(input.context, spec, AgentHistoryRecords.group, "spine_agent_history"), this.admitHistory);
+            },
+        });
     }
     /**
      * Creates the selected Entity provider bundle.
@@ -203,11 +492,104 @@ export class DatastoreStorageFactory extends StorageFactory {
             throw new Error("StorageFactory is closed.");
         const custom = this.#entityCreators.get(input.sourceType.typeName);
         if (custom !== undefined)
-            return custom(input, this.#client);
+            return this.retainBundle(custom(input, this.#client));
         const openRecords = (recordSpec, group) => this.createEntityRecordStorage(input.context, recordSpec, group);
         const storage = new DatastoreEntityStorage(input, openRecords);
         const commits = new DatastoreEntityCommitStorage(input, openRecords);
-        return new DefaultEntityHandle(storage, commits);
+        return this.retainBundle(new DefaultEntityHandle(storage, commits));
+    }
+    /**
+     * Registers a coherent Entity bundle for factory shutdown.
+     *
+     * @param bundle The coherent Entity storage bundle.
+     * @returns The tracked Entity storage bundle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    retainBundle(bundle) {
+        const retained = {
+            current: bundle.current,
+            states: bundle.states,
+            events: bundle.events,
+            commits: bundle.commits,
+            isOpen: () => bundle.isOpen(),
+            ...this.retainCleanup(bundle, () => this.#bundles.delete(retained)),
+        };
+        this.#bundles.add(retained);
+        return retained;
+    }
+    /**
+     * Acquires direct built-in commit access without an unused Entity read bundle.
+     *
+     * @param input The captured Entity persistence input.
+     * @returns The provider commit handle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    createEntityCommitStorage(input) {
+        if (!this.isOpen())
+            throw new Error("StorageFactory is closed.");
+        const custom = this.#entityCreators.get(input.sourceType.typeName);
+        if (custom !== undefined)
+            return this.createCustomCommitStorage(input, custom);
+        const openRecords = (recordSpec, group) => this.createEntityRecordStorage(input.context, recordSpec, group);
+        const commits = new DatastoreEntityCommitStorage(input, openRecords, () => this.#commits.delete(commits));
+        this.#commits.add(commits);
+        return commits;
+    }
+    /**
+     * Wraps a custom bundle while retaining its complete cleanup obligation.
+     * @param custom Registered custom Entity storage creator.
+     * @param input Captured Entity storage layout.
+     * @typeParam I Typed Entity identifier.
+     * @typeParam S Generated Entity state.
+     * @returns The adapted custom commit handle.
+     */
+    createCustomCommitStorage(input, custom) {
+        const bundle = custom(input, this.#client);
+        const unsupported = () => Promise.reject(new Error("Custom Datastore Entity storage does not support native Agent transactions."));
+        const adapter = {
+            commit: (work) => bundle.commits.commit(work),
+            readAgentPreferences: unsupported,
+            commitAgent: unsupported,
+            ...this.retainCleanup(bundle, () => this.#commits.delete(adapter)),
+        };
+        this.#commits.add(adapter);
+        return adapter;
+    }
+    /**
+     * Creates repeatable cleanup methods that retain a bundle until closure settles.
+     *
+     * @param bundle The complete provider bundle.
+     * @param onRemove Removes the settled factory root.
+     * @returns Repeatable close methods.
+     */
+    retainCleanup(bundle, onRemove) {
+        let closing;
+        return {
+            close: () => {
+                if (closing !== undefined)
+                    return closing;
+                try {
+                    closing = bundle.close();
+                }
+                catch (error) {
+                    closing = Promise.reject(error instanceof Error
+                        ? error
+                        : new Error("Datastore cleanup failed.", { cause: error }));
+                }
+                return (closing = closing.then(() => {
+                    onRemove();
+                }, (error) => {
+                    onRemove();
+                    throw error;
+                }));
+            },
+            closeIdle: () => {
+                bundle.closeIdle();
+                onRemove();
+            },
+        };
     }
     /**
      * Creates provider-specific Datastore record storage.
@@ -224,10 +606,10 @@ export class DatastoreStorageFactory extends StorageFactory {
         const creator = resolved.creator;
         if (creator !== undefined)
             return creator(context, recordSpec, this.#client, maxClientSideScan);
-        return new DatastoreRecordStorage(context, recordSpec, this.#client, maxClientSideScan, group, resolved.layout?.kind, this.#namespaceConverter, this.#stringifiers);
+        return this.openNative(context, recordSpec, group, resolved.layout?.kind);
     }
     /**
-     * Opens the built-in record provider for generated Entity families.
+     * Acquires the built-in record provider for generated Entity families.
      *
      * @typeParam I Record identifier type.
      * @typeParam R Stored record message type.
@@ -237,11 +619,35 @@ export class DatastoreStorageFactory extends StorageFactory {
      * @returns A built-in Datastore record handle.
      */
     createEntityRecordStorage(context, recordSpec, group) {
+        if (group?.name === AgentHistoryRecords.group.name)
+            return this.openNative(context, recordSpec, group, "spine_agent_history");
+        if (group?.name === AgentModelPreferences.group.name)
+            return this.openNative(context, recordSpec, group, "spine_agent_model_preferences");
         const resolved = this.resolve(recordSpec, group, false);
-        return new DatastoreRecordStorage(context, recordSpec, this.#client, maxClientSideScan, group, resolved.layout?.kind, this.#namespaceConverter, this.#stringifiers);
+        return this.openNative(context, recordSpec, group, resolved.layout?.kind);
+    }
+    /**
+     * Acquires one native record handle and retains its pure physical definition.
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored record type.
+     * @param context Complete tenant context.
+     * @param spec The declared record family.
+     * @param group Optional physical group.
+     * @param kind Configured or fixed native kind.
+     * @returns The native record handle.
+     */
+    openNative(context, spec, group, kind) {
+        const selectedKind = this.selectedKind(spec, group, kind);
+        const mapping = this.nativeDefinition(context, spec, group, selectedKind);
+        this.declareNative(context, spec, group, selectedKind, {
+            namespace: mapping.namespace,
+            kind: mapping.kind,
+        });
+        const storage = new DatastoreRecordStorage(context, spec, this.#client, maxClientSideScan, group, selectedKind, this.#namespaceConverter, this.#stringifiers, mapping.namespace);
+        return storage;
     }
     /**
-     * Resolves the registered creator and physical layout for a record family.
+     * Finds the registered creator and physical layout for a record family.
      *
      * @typeParam I Record identifier type.
      * @typeParam R Stored record message type.
@@ -255,10 +661,14 @@ export class DatastoreStorageFactory extends StorageFactory {
         const record = recordSpec.recordType.typeName;
         const exact = key(group?.name ?? source, record);
         const fallback = key(group === undefined ? source : record, group === undefined ? source : record);
+        const selected = includeCreator
+            ? this.#recordCreators.has(exact)
+                ? exact
+                : fallback
+            : undefined;
         return {
-            creator: includeCreator
-                ? (this.#recordCreators.get(exact) ?? this.#recordCreators.get(fallback))
-                : undefined,
+            creator: selected === undefined ? undefined : this.#recordCreators.get(selected),
+            prepare: selected === undefined ? undefined : this.#recordPreparers.get(selected),
             layout: this.#layouts.get(exact) ?? this.#layouts.get(fallback),
         };
     }
@@ -272,16 +682,54 @@ export class DatastoreStorageFactory extends StorageFactory {
     }
     /**
      * Closes the factory and its native tenant catalog.
+     *
+     * @returns Completion after retained resources are closed.
      */
     close() {
-        super.close();
-        void this.#catalog.close();
+        this.fenceClose();
+        if (this.#closing !== undefined)
+            return this.#closing;
+        const closing = Promise.withResolvers();
+        this.#closing = closing.promise;
+        this.drain().then(() => {
+            closing.resolve(undefined);
+        }, closing.reject);
+        return closing.promise;
+    }
+    /**
+     * Waits for admitted commits before closing remaining factory resources.
+     *
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    async drain() {
+        const errors = [];
+        await Promise.allSettled([...this.#work]);
+        const roots = [...this.#commits, ...this.#bundles];
+        const pending = roots.map((handle) => {
+            try {
+                return handle.close();
+            }
+            catch (error) {
+                return Promise.reject(error instanceof Error ? error : new Error("Datastore cleanup failed.", { cause: error }));
+            }
+        });
+        for (const result of await Promise.allSettled(pending))
+            if (result.status === "rejected")
+                errors.push(result.reason);
+        try {
+            await this.#catalog.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length)
+            throw new AggregateError(errors, "Datastore factory close failed.");
     }
 }
 /**
-
  * Configures a Datastore storage factory before construction.
-
  */
 class Builder {
     create;
@@ -293,6 +741,10 @@ class Builder {
      * Custom record creators indexed by family.
      */
     #recordCreators = new Map();
+    /**
+     * Optional preparation callbacks paired with custom record creators.
+     */
+    #recordPreparers = new Map();
     /**
      * Physical kind layouts indexed by family.
      */
@@ -301,6 +753,10 @@ class Builder {
      * Custom Entity creators indexed by state type.
      */
     #entityCreators = new Map();
+    /**
+     * Optional preparation callbacks paired with custom Entity creators.
+     */
+    #entityPreparers = new Map();
     /**
      * Converter for multitenant Datastore namespaces.
      */
@@ -308,7 +764,8 @@ class Builder {
     /**
      * Converter for message-valued IDs and columns.
      */
-    #stringifiers = new StringifierRegistry();
+    #stringifiers = defaultStringifierRegistry;
+    #eventStoreKinds = new Map();
     /**
      * Creates a builder with the selected factory constructor.
      *
@@ -344,7 +801,25 @@ class Builder {
      * @returns This builder.
      */
     setStringifierRegistry(registry) {
-        this.#stringifiers = new StringifierRegistry(registry);
+        this.#stringifiers =
+            registry === defaultStringifierRegistry ? registry : new StringifierRegistry(registry);
+        return this;
+    }
+    /**
+     * Sets the kind for one exact domain or system Event Store.
+     *
+     * @param boundedContextName Logical bounded-context name.
+     * @param kind Physical Datastore kind.
+     * @param role Domain or system Event Store role.
+     * @returns This builder.
+     */
+    setEventStoreKind(boundedContextName, kind, role = "domain") {
+        checkedLayout({ kind });
+        const group = EventStoreGroups.forContext(boundedContextName, role);
+        const identity = EventStoreGroups.identity(group);
+        if (identity === undefined)
+            throw new Error("Event Store identity is missing.");
+        this.#eventStoreKinds.set(identity, kind);
         return this;
     }
     /**
@@ -368,13 +843,21 @@ class Builder {
      * @param first Record type, or source type when three arguments are supplied.
      * @param second Creator, or record type when three arguments are supplied.
      * @param third Creator for a source-specific registration.
+     * @param fourth Declarative preparation for a source-specific registration.
      * @returns This builder.
      */
-    useRecordStorage(first, second, third) {
-        const [source, record, creator] = third === undefined
-            ? [undefined, first, second]
-            : [first, second, third];
-        this.#recordCreators.set(key(source?.typeName ?? record.typeName, record.typeName), creator);
+    useRecordStorage(first, second, third, fourth) {
+        const sourceSpecific = typeof second !== "function";
+        const source = sourceSpecific ? first : undefined;
+        const record = sourceSpecific ? second : first;
+        const creator = sourceSpecific ? third : second;
+        const prepare = sourceSpecific ? fourth : third;
+        const family = key(source?.typeName ?? record.typeName, record.typeName);
+        this.#recordCreators.set(family, creator);
+        if (prepare === undefined)
+            this.#recordPreparers.delete(family);
+        else
+            this.#recordPreparers.set(family, prepare);
         return this;
     }
     /**
@@ -383,10 +866,15 @@ class Builder {
      * @typeParam S Entity state message type.
      * @param sourceType Selects the Entity state type.
      * @param creator Builds its storage handle.
+     * @param prepare Optional declarative preparation for the coherent provider.
      * @returns This builder.
      */
-    useEntityStorage(sourceType, creator) {
+    useEntityStorage(sourceType, creator, prepare) {
         this.#entityCreators.set(sourceType.typeName, creator);
+        if (prepare === undefined)
+            this.#entityPreparers.delete(sourceType.typeName);
+        else
+            this.#entityPreparers.set(sourceType.typeName, prepare);
         return this;
     }
     /**
@@ -398,7 +886,7 @@ class Builder {
         if (this.#client === undefined)
             throw new Error("DatastoreStorageFactory builder requires a client.");
         rejectKindCollisions(this.#layouts);
-        return this.create(this.#client, new Map(this.#recordCreators), new Map(this.#layouts), new Map(this.#entityCreators), this.#namespaceConverter, this.#stringifiers);
+        return this.create(this.#client, new Map(this.#recordCreators), new Map(this.#recordPreparers), new Map(this.#layouts), new Map(this.#entityCreators), new Map(this.#entityPreparers), this.#namespaceConverter, this.#stringifiers, new Map(this.#eventStoreKinds));
     }
 }
 /**
@@ -408,6 +896,9 @@ class Builder {
  * @typeParam S Entity state message type.
  */
 class DefaultEntityHandle {
+    #open = true;
+    #idleOutcome;
+    #closing;
     /**
      * Current Entity record access.
      */
@@ -447,14 +938,85 @@ class DefaultEntityHandle {
      * @returns Whether operations remain available.
      */
     isOpen() {
-        return this.#storage.isOpen();
+        return this.#open && this.#storage.isOpen();
     }
     /**
      * Closes generated records and commit access.
+     *
+     * @returns Completion after retained resources are closed.
      */
     close() {
-        this.#storage.close();
-        this.commits.close();
+        if (this.#closing !== undefined)
+            return this.#closing;
+        this.#open = false;
+        if (this.#idleOutcome !== undefined) {
+            const failure = this.#idleOutcome.error;
+            return (this.#closing = failure === undefined ? Promise.resolve() : Promise.reject(failure));
+        }
+        const completion = this.commits.close();
+        return (this.#closing = this.drain(completion));
+    }
+    /**
+     * Closes read records after an admitted commit settles.
+     *
+     * @param completion The admitted commit completion.
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    async drain(completion) {
+        const errors = [];
+        try {
+            await completion;
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            this.#storage.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length)
+            throw new AggregateError(errors, "Datastore Entity close failed.");
+    }
+    /**
+     * Closes a bundle synchronously when no commit or close remains in progress.
+     */
+    closeIdle() {
+        if (this.#idleOutcome !== undefined) {
+            if (this.#idleOutcome.error !== undefined)
+                throw this.#idleOutcome.error;
+            return;
+        }
+        if (this.#closing !== undefined)
+            throw new Error("Entity bundle close is in progress.");
+        this.commits.assertIdle();
+        this.#open = false;
+        const errors = [];
+        try {
+            this.commits.closeIdle();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            this.#storage.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        const failure = errors.length > 1
+            ? new AggregateError(errors, "Datastore bundle idle close failed.")
+            : errors[0] === undefined
+                ? undefined
+                : errors[0] instanceof Error
+                    ? errors[0]
+                    : new Error("Datastore cleanup failed.", { cause: errors[0] });
+        this.#idleOutcome = failure === undefined ? {} : { error: failure };
+        if (failure !== undefined)
+            throw failure;
     }
 }
 function key(source, record) {