@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.26

package/dist/repository/repository.js

@@ -12,7 +12,7 @@
  * the License.
  */
 import { clone, create, equals, ScalarType, toBinary, } from "@bufbuild/protobuf";
-import { AnySchema, Int32ValueSchema, Int64ValueSchema, StringValueSchema, } from "@bufbuild/protobuf/wkt";
+import { AnySchema, Int32ValueSchema, Int64ValueSchema, StringValueSchema, TimestampSchema, } from "@bufbuild/protobuf/wkt";
 import { ValidationException, RejectionThrowable, Validate, TypeUrls, AnyPacker, Identifiers, StringifierRegistry, Time, } from "@spine-event-engine/core";
 import { CommandContextSchema, ActorContextSchema, CommandIdSchema, CommandSchema, EventContextSchema, EventIdSchema, EventSchema, MessageIdSchema, TenantIdSchema, RejectionEventContextSchema, VersionSchema, EntityOption_Kind, } from "@spine-event-engine/proto";
 import * as EntityLog from "@spine-event-engine/proto/generated/spine/system/server/entity_log_events_pb.js";
@@ -22,7 +22,7 @@ import { EventStore, StorageQueryPolicy, } from "@spine-event-engine/storage";
 import { TenantBoundary, eventStoreAccess, StoragePreparations, } from "@spine-event-engine/storage/provider";
 import { EntityCommitStorageFactories } from "@spine-event-engine/storage/provider";
 import { AgentHistoryStorageFactories, } from "@spine-event-engine/storage/provider";
-import { AgentHistoryEntrySchema, AgentInvocationTerminatedSchema, AgentModelSelectionChangedSchema as SelectionChangedSchema, AiModelKind, ModelRefSchema, ModelPreferenceSchema, ConversationIdSchema, } from "@spine-event-engine/proto/agent";
+import { AgentHistoryEntrySchema, AgentInvocationTerminatedSchema, AgentModelSelectionChangedSchema as SelectionChangedSchema, AiModelKind, ModelRefSchema, ModelPreferenceSchema, ConversationRecordSchema, ConversationIdSchema, AgentHistoryCursorSchema, } from "@spine-event-engine/proto/agent";
 import { registryOptions } from "@spine-event-engine/ai/spi/runtime";
 import { CommandValidationError } from "../bus/command-errors.js";
 import { SignalPublisher } from "../runtime/signal-publisher.js";
@@ -32,10 +32,12 @@ import { CommandRoutingInternals, } from "./command-routing.js";
 import { EventRoutingInternals } from "./event-routing.js";
 import { StateUpdateRoutingInternals, } from "./state-update-routing.js";
 import { RoutingDeclarations } from "./routing-declarations.js";
+import { snapshotTrustedReader, } from "@spine-event-engine/core/spi/trusted-reader";
+import { Code, ConnectError } from "@connectrpc/connect";
 import { EventDispatcherOriginSchemas } from "../bus/event-dispatcher-origin-schemas.js";
 import { receptionObservation } from "../delivery/reception-observation.js";
 import { commitFenced, withDeliveryCommitFence } from "./commit-fence.js";
-import { AgentHistoryReads } from "../agent/agent-history.js";
+import { AgentHistoryReads, } from "../agent/agent-history.js";
 import { AgentLiveAiRuntime } from "../agent/agent-live-ai-runtime.js";
 import { AgentLiveAudit } from "../agent/agent-live-audit.js";
 import { AgentLiveBudget } from "../agent/agent-live-budget.js";
@@ -258,7 +260,14 @@ const RepositoryAgentReads = {
             : validated;
         const tenant = scope.tenantId === undefined ? undefined : RepositoryTenants.require(scope.tenantId);
         const context = RepositoryTenants.storageContextForTenant(runtime.context, tenant);
-        return { runtime, context, id: copiedId };
+        const readSide = {
+            ...(scope.actorContext === undefined
+                ? {}
+                : { actorContext: clone(ActorContextSchema, scope.actorContext) }),
+            ...(scope.reader === undefined ? {} : snapshotTrustedReader(scope.reader)),
+            ...(scope.signal === undefined ? {} : { signal: scope.signal }),
+        };
+        return { runtime, context, id: copiedId, readSide };
     },
     /**
      * Returns a detached public history request before provider access.
@@ -269,7 +278,9 @@ const RepositoryAgentReads = {
     request(request) {
         return {
             pageSize: request.pageSize,
-            ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+            ...(request.cursor === undefined
+                ? {}
+                : { cursor: clone(AgentHistoryCursorSchema, request.cursor) }),
         };
     },
     /**
@@ -313,22 +324,95 @@ const RepositoryAgentReads = {
      * @returns Detached history entries and opaque continuation.
      */
     async historyPage(repository, captured, view, request) {
+        this.checkCanceled(captured.readSide.signal);
         if (repositoryRuntimes.get(repository) !== captured.runtime)
             throw new Error("Agent read requires an active repository.");
         await captured.runtime.onAdmit(captured.context.tenantId);
-        return RepositoryStorage.track(repository, async () => {
-            const input = RepositoryStorage.entityStorageInput(repository, captured.context);
-            const history = RepositoryStorage.openRepositoryAgentHistory(repository, captured.runtime.storageFactory, input);
-            const page = await AgentHistoryReads.readBound({
-                storage: history,
-                entityId: captured.id,
-                scope: repositoryAccess.agentHistoryScope(captured.context, input, captured.id),
-            }, view, request);
-            return {
-                items: page.items,
-                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
-            };
-        });
+        this.checkCanceled(captured.readSide.signal);
+        const page = await RepositoryStorage.track(repository, () => this.loadHistoryPage(repository, captured, view, request));
+        this.checkCanceled(captured.readSide.signal);
+        return page;
+    },
+    /**
+     * Rejects canceled public history reads even when no policy callback runs.
+     * @param signal Current caller cancellation, if supplied.
+     */
+    checkCanceled(signal) {
+        if (signal?.aborted)
+            throw new ConnectError("Read canceled.", Code.Canceled);
+    },
+    /**
+     * Reads a retained Agent page and transforms only its outward domain values.
+     *
+     * @param repository Registered Agent repository.
+     * @param captured Stable Entity, tenant, and reader facts.
+     * @param view Indexed history category.
+     * @param request Detached page request.
+     * @returns Visible entries and original continuation.
+     */
+    async loadHistoryPage(repository, captured, view, request) {
+        const input = RepositoryStorage.entityStorageInput(repository, captured.context);
+        const history = RepositoryStorage.openRepositoryAgentHistory(repository, captured.runtime.storageFactory, input);
+        const page = await AgentHistoryReads.readBound({
+            storage: history,
+            entityId: captured.id,
+            scope: repositoryAccess.agentHistoryScope(captured.context, input, captured.id),
+        }, view, request);
+        return this.visibleHistory(captured.runtime.stand, page, captured.id, view, request, captured.context.tenantId, captured.readSide);
+    },
+    /**
+     * Transforms returned Agent domain roots while retaining the original page cursor.
+     *
+     * @param stand Producing context's read policy.
+     * @param page Captured history page before outward transformation.
+     * @param entityId Agent identifier used for this call.
+     * @param view Requested history category.
+     * @param request Original page request.
+     * @param tenantId Effective tenant of this Agent.
+     * @param readSide Trusted in-process caller facts captured with the reader.
+     * @returns Visible entries with the provider's original continuation.
+     */
+    async visibleHistory(stand, page, entityId, view, request, tenantId, readSide = {}) {
+        const facts = {
+            operation: { kind: "history", history: { source: "agent", entityId, view, request } },
+            ...(tenantId === undefined ? {} : { effectiveTenant: tenantId }),
+            ...readSide,
+        };
+        const items = [];
+        for (const entry of page.items) {
+            const visible = await this.visibleEntry(stand, entry, facts);
+            if (visible !== undefined)
+                items.push(visible);
+        }
+        return { items, ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }) };
+    },
+    /**
+     * Transforms one retained Agent entry without changing its wrapper or cursor.
+     *
+     * @param stand Producing context's outward read policy.
+     * @param entry Captured indexed history entry.
+     * @param facts Actual read operation and trusted invocation facts.
+     * @returns Visible entry, or undefined when policy removed its root.
+     */
+    async visibleEntry(stand, entry, facts) {
+        const item = entry.item;
+        let visible;
+        if (item.case === "conversationRecord") {
+            const value = await standAccess.filterState(stand, ConversationRecordSchema, item.value, facts);
+            if (value !== null)
+                visible = { case: "conversationRecord", value };
+        }
+        else if (item.case === "systemEvent" || item.case === "domainEvent") {
+            const value = await standAccess.filterEvent(stand, item.value, facts);
+            if (value !== null)
+                visible =
+                    item.case === "systemEvent"
+                        ? { case: "systemEvent", value }
+                        : { case: "domainEvent", value };
+        }
+        return visible === undefined
+            ? undefined
+            : create(AgentHistoryEntrySchema, { ...entry, item: visible });
     },
     /**
      * Returns one typed category from the full Proto history oneof.
@@ -483,6 +567,9 @@ export const repositoryAccess = Object.freeze({
         }
         return schemas;
     },
+    /**
+     * Returns the AI registry configured for this repository, if present.
+     */
     agentConfiguration(repository) {
         const ai = repositoryAiConfigurations.get(repository);
         return ai === undefined ? {} : { ai };
@@ -512,6 +599,9 @@ export const repositoryAccess = Object.freeze({
             ...read,
         }));
     },
+    /**
+     * Reads one tenant-admitted Agent history page through retained history storage.
+     */
     async agentHistoryPage(repository, entityId, request, tenantId) {
         if (repository.entityFamily !== "agent")
             throw new TypeError("Agent history requires an Agent repository.");
@@ -531,7 +621,7 @@ export const repositoryAccess = Object.freeze({
         });
     },
     /**
-     * Computes the opaque cursor scope for a registered Agent history read.
+     * Returns the opaque cursor scope for a registered Agent history read.
      */
     agentHistoryScope(context, input, entityId) {
         return {
@@ -1170,7 +1260,7 @@ class AggregateCommandExecution {
         this.#publishCommandDispatch(intake.route.entityId);
         let produced;
         try {
-            produced = await this.#invokeAssignee(loaded.entity, intake.assignee.handler, intake.message, EntityInvocation.commandHandlerContext(this.#command));
+            produced = await this.#invokeAssignee(loaded.entity, intake.assignee.handler, intake.message, EntityInvocation.commandHandlerContext(this.#command), this.#command.context?.actorContext);
         }
         catch (error) {
             return this.#postAssigneeRejection(intake, error);
@@ -1227,26 +1317,45 @@ class AggregateCommandExecution {
      * @param handler Assignee declaration to invoke.
      * @param message Decoded Command message.
      * @param context Copied Command context for the handler.
+     * @param actorContext Actor metadata of the Command signal.
      * @returns The handler's raw result after a successful commit.
      */
-    async #invokeAssignee(entity, handler, message, context) {
-        transactionalEntityAccess.start(entity);
+    async #invokeAssignee(entity, handler, message, context, actorContext) {
+        const releaseActor = entityHistoryAccess.bindActor(entity, actorContext);
+        let started = false;
         try {
-            const produced = await EntityInvocation.invokeEntityMethod(entity, handler.methodName, message, handler.parameterCount, context);
-            const signals = this.#support.normalizeProducedSignals(produced);
-            if (signals.length === 0)
-                throw receptionObservation.recordPostHandlerFailure(new Error("Repository aggregate command handlers must return at least one event."));
-            RepositoryHandlers.requireDeclaredOutputs(handler, signals);
-            const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, true));
-            if (commit.status === "rejected") {
-                throw EntityInvocation.rejectedTransition(commit.validation.error);
-            }
-            return produced;
+            transactionalEntityAccess.start(entity);
+            started = true;
+            return await this.#invokeAndCommitAssignee(entity, handler, message, context);
         }
         catch (error) {
-            transactionalEntityAccess.rollback(entity);
+            if (started)
+                transactionalEntityAccess.rollback(entity);
             throw error;
         }
+        finally {
+            releaseActor();
+        }
+    }
+    /**
+     * Checks a declared Aggregate result and commits its accepted transition.
+     *
+     * @param entity Current Aggregate draft.
+     * @param handler Declared Command handler.
+     * @param message Decoded domain Command.
+     * @param context Detached signal context supplied to the handler.
+     * @returns Raw handler result after commit.
+     */
+    async #invokeAndCommitAssignee(entity, handler, message, context) {
+        const produced = await EntityInvocation.invokeEntityMethod(entity, handler.methodName, message, handler.parameterCount, context);
+        const signals = this.#support.normalizeProducedSignals(produced);
+        if (signals.length === 0)
+            throw receptionObservation.recordPostHandlerFailure(new Error("Repository aggregate command handlers must return at least one event."));
+        RepositoryHandlers.requireDeclaredOutputs(handler, signals);
+        const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, true));
+        if (commit.status === "rejected")
+            throw EntityInvocation.rejectedTransition(commit.validation.error);
+        return produced;
     }
     /**
      * Binds each produced result to the target and pre-dispatch version.
@@ -1421,16 +1530,23 @@ class AggregateEventExecution {
     async #invokeHandlers(entityId, loaded, intake) {
         const eventContext = EntityInvocation.eventHandlerContext(this.#event);
         const events = [];
-        transactionalEntityAccess.start(loaded.entity);
+        const releaseActor = entityHistoryAccess.bindActor(loaded.entity, this.#runtime.signalMetadata.originFromEvent(this.#event).actorContext);
+        let started = false;
         try {
+            transactionalEntityAccess.start(loaded.entity);
+            started = true;
             await this.#invokeReactors(entityId, loaded, intake, eventContext, events);
             await this.#commitEntity(loaded.entity, events.length > 0);
             return Object.freeze(events);
         }
         catch (error) {
-            transactionalEntityAccess.rollback(loaded.entity);
+            if (started)
+                transactionalEntityAccess.rollback(loaded.entity);
             throw error;
         }
+        finally {
+            releaseActor();
+        }
     }
     /**
      * Invokes each reactor, checks its declared output, and collects bound Events.
@@ -1734,20 +1850,26 @@ class ProjectionEventExecution {
      * @returns Completion after the subscriber transaction commits.
      */
     async #invokeSubscribers(entity, subscribers, packedMessage) {
-        transactionalEntityAccess.start(entity);
+        const releaseActor = entityHistoryAccess.bindActor(entity, this.#runtime.signalMetadata.originFromEvent(this.#event).actorContext);
+        let started = false;
         try {
+            transactionalEntityAccess.start(entity);
+            started = true;
             for (const subscriber of subscribers) {
                 await this.#invokeSubscriber(entity, subscriber, packedMessage);
             }
             const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
-            if (commit.status === "rejected") {
+            if (commit.status === "rejected")
                 throw EntityInvocation.rejectedTransition(commit.validation.error);
-            }
         }
         catch (error) {
-            transactionalEntityAccess.rollback(entity);
+            if (started)
+                transactionalEntityAccess.rollback(entity);
             throw error;
         }
+        finally {
+            releaseActor();
+        }
     }
     /**
      * Invokes one Event subscriber and checks its raw return value.
@@ -1773,22 +1895,40 @@ class ProjectionEventExecution {
      * @returns Completion after the subscriber transaction commits.
      */
     async #invokeStateSubscribers(entity, subscribers, state) {
-        transactionalEntityAccess.start(entity);
+        const releaseActor = entityHistoryAccess.bindActor(entity, this.#runtime.signalMetadata.originFromEvent(this.#event).actorContext);
+        let started = false;
         try {
-            for (const subscriber of subscribers) {
-                const context = EntityInvocation.eventHandlerContext(this.#event);
-                const result = await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, state, subscriber.handler.parameterCount, context);
-                if (result !== undefined)
-                    throw receptionObservation.recordPostHandlerFailure(new Error(`Projection subscriber "${subscriber.handler.methodName}" must not return signals.`));
-            }
+            transactionalEntityAccess.start(entity);
+            started = true;
+            await this.#runStateSubscribers(entity, subscribers, state);
             const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
             if (commit.status === "rejected")
                 throw EntityInvocation.rejectedTransition(commit.validation.error);
         }
         catch (error) {
-            transactionalEntityAccess.rollback(entity);
+            if (started)
+                transactionalEntityAccess.rollback(entity);
             throw error;
         }
+        finally {
+            releaseActor();
+        }
+    }
+    /**
+     * Delivers one state update to each declared Projection subscriber.
+     *
+     * @param entity Projection currently in its transaction.
+     * @param subscribers Subscribers selected for the source state.
+     * @param state Decoded source Entity state.
+     * @returns Completion after all subscribers accept the state.
+     */
+    async #runStateSubscribers(entity, subscribers, state) {
+        for (const subscriber of subscribers) {
+            const context = EntityInvocation.eventHandlerContext(this.#event);
+            const result = await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, state, subscriber.handler.parameterCount, context);
+            if (result !== undefined)
+                throw receptionObservation.recordPostHandlerFailure(new Error(`Projection subscriber "${subscriber.handler.methodName}" must not return signals.`));
+        }
     }
     /**
      * Restores or creates a Projection and binds its storage history.
@@ -1867,7 +2007,11 @@ const ProcessManagerQueries = Object.freeze({
      * @returns Detached Projection state snapshots.
      */
     async load(stand, registeredSchema, plan, destination, query, schema) {
-        const results = await QueryReader.read(stand, registeredSchema, plan, destination, 10_000, query);
+        const results = await QueryReader.read(stand, registeredSchema, plan, destination, 10_000, query, {
+            operation: { kind: "query", query },
+            ...(query.context === undefined ? {} : { actorContext: query.context }),
+            ...(destination === undefined ? {} : { effectiveTenant: destination }),
+        });
         return Object.freeze(results.map((result) => clone(schema, result.state)));
     },
 });
@@ -2503,7 +2647,7 @@ class AgentLiveRunner {
      * @returns The handler bound to current protected history and AI capabilities.
      */
     bind(entity, facade, reads, actor) {
-        const history = AgentHistoryReads.withReadInterceptor(entity, (scope, request, live, maxBytes) => reads.history(scope, request, live, maxBytes));
+        const history = AgentHistoryReads.withReadInterceptor(entity, (scope, request, live, maxBytes, present) => reads.history(scope, request, live, maxBytes, present));
         let query;
         try {
             query = ProcessManagerQueries.bind(entity, this.runtime, actor, this.tenantId, (schema, request, live) => reads.query(schema, request, live));
@@ -3170,17 +3314,18 @@ class ProcessManagerEventExecution {
         const commands = [];
         const events = [];
         const releaseQuery = ProcessManagerQueries.bind(entity, this.#runtime, this.#runtime.signalMetadata.originFromEvent(this.#event).actorContext, tenantId);
-        transactionalEntityAccess.start(entity);
+        let started = false;
         try {
+            transactionalEntityAccess.start(entity);
+            started = true;
             await this.#invokeEventHandlers(entityId, entity, intake, eventContext, events, commands);
             await this.#commitEntity(entity, events.length > 0);
-            return Object.freeze({
-                commands: Object.freeze(commands),
-                events: Object.freeze(events),
-            });
+            const emitted = { commands: Object.freeze(commands), events: Object.freeze(events) };
+            return Object.freeze(emitted);
         }
         catch (error) {
-            transactionalEntityAccess.rollback(entity);
+            if (started)
+                transactionalEntityAccess.rollback(entity);
             throw error;
         }
         finally {
@@ -3758,22 +3903,50 @@ const RepositoryEntities = {
             throw new Error("Agent history storage is required.");
         const lifetime = RepositoryStorage.lifetime(repository);
         const runtime = repositoryRuntimes.get(repository);
-        AgentHistoryReads.bind(entity, {
+        if (runtime === undefined)
+            throw new Error("Agent history requires its active runtime.");
+        AgentHistoryReads.bind(entity, this.agentHistoryBinding(repository, entity, entityId, input, history, runtime, lifetime));
+    },
+    /**
+     * Captures retained Agent history admission and outward filtering in one binding.
+     *
+     * @param repository Repository tracking the active runtime.
+     * @param entity Restored Agent instance.
+     * @param entityId Typed Agent identifier.
+     * @param input Retained storage scope.
+     * @param history Indexed Agent history handle.
+     * @param runtime Current context services.
+     * @param lifetime Repository storage lifetime.
+     * @returns History binding with an invocation-time actor snapshot.
+     */
+    agentHistoryBinding(repository, entity, entityId, input, history, runtime, lifetime) {
+        return {
             storage: history,
             entityId,
             onAdmit: async (onRead) => {
-                if (runtime === undefined || repositoryRuntimes.get(repository) !== runtime)
+                if (repositoryRuntimes.get(repository) !== runtime)
                     throw new Error("Agent history requires its active runtime.");
                 await runtime.onAdmit(input.context.tenantId);
                 return RepositoryStorage.track(repository, onRead, lifetime);
             },
-            scope: {
-                context: input.context.name,
-                tenant: JSON.stringify(input.context.tenantId ?? null),
-                repository: input.sourceType.typeName,
-                entity: input.id.key(entityId),
-            },
-        });
+            captureActor: () => entityHistoryAccess.currentActor(entity),
+            filterPage: (page, view, request, actorContext) => RepositoryAgentReads.visibleHistory(runtime.stand, page, entityId, view, request, input.context.tenantId, actorContext === undefined ? {} : { actorContext }),
+            scope: this.agentHistoryScope(input, entityId),
+        };
+    },
+    /**
+     * Returns the exact retained Agent repository and typed ID for cursor validation.
+     * @param input Captured Agent storage scope.
+     * @param entityId Typed Agent identifier.
+     * @returns Stable scope encoded in history cursors.
+     */
+    agentHistoryScope(input, entityId) {
+        return {
+            context: input.context.name,
+            tenant: JSON.stringify(input.context.tenantId ?? null),
+            repository: input.sourceType.typeName,
+            entity: input.id.key(entityId),
+        };
     },
     /**
      * Restores an Entity from Stand or creates a fresh instance at Version zero.
@@ -6310,7 +6483,7 @@ const RepositoryStorage = {
 };
 Object.freeze(RepositoryStorage);
 /**
- * Internal repository history internals operations.
+ * Provides internal repository history operations.
  */
 const RepositoryHistoryInternals = {
     /**
@@ -6326,30 +6499,89 @@ const RepositoryHistoryInternals = {
     bindEntityHistory(repository, entity, storage, entityId, schema, tenantId) {
         const lifetime = RepositoryStorage.lifetime(repository);
         const runtime = repositoryRuntimes.get(repository);
-        const onAdmit = async () => {
-            if (runtime === undefined || repositoryRuntimes.get(repository) !== runtime)
-                throw new Error("Repository history requires its active runtime.");
-            await runtime.onAdmit(tenantId);
-        };
+        if (runtime === undefined)
+            throw new Error("Repository history requires its active runtime.");
+        const onAdmit = () => this.admitHistory(repository, runtime, tenantId);
         const { stateCache, eventCache } = this.boundHistoryCaches(storage, entityId, schema);
         entityStateHistoryCaches.set(entity, stateCache);
         entityHistoryAccess.bind(entity, {
-            stateAt: async (time) => {
-                await onAdmit();
-                return this.readBoundStateAt(repository, lifetime, storage, entityId, time);
-            },
-            states: async (depth) => {
-                await onAdmit();
-                return this.readBoundStates(repository, lifetime, schema, stateCache, depth);
-            },
-            events: async (depth) => {
-                await onAdmit();
-                return this.readBoundEvents(repository, lifetime, eventCache, depth);
-            },
+            ...this.historyReaders({
+                repository,
+                lifetime,
+                stand: runtime.stand,
+                storage,
+                schema,
+                entityId,
+                tenantId,
+                entity,
+                onAdmit,
+                stateCache,
+                eventCache,
+            }),
             stateMaintenance: this.boundStateMaintenance(repository, lifetime, storage.states, onAdmit),
             eventMaintenance: this.boundEventMaintenance(repository, lifetime, storage.events, onAdmit),
         });
     },
+    /**
+     * Admits retained history provider work only while repository membership remains current.
+     *
+     * @param repository Repository whose runtime must remain current.
+     * @param runtime Captured context runtime.
+     * @param tenantId Bound tenant when multitenant.
+     * @returns Completion after membership admission.
+     */
+    async admitHistory(repository, runtime, tenantId) {
+        if (repositoryRuntimes.get(repository) !== runtime)
+            throw new Error("Repository history requires its active runtime.");
+        await runtime.onAdmit(tenantId);
+    },
+    /**
+     * Captures each protected history call's actor and request before admission awaits.
+     *
+     * @param scope Bound repository, caches, and admission work.
+     * @returns State and Event read callbacks for the Entity.
+     */
+    historyReaders(scope) {
+        return {
+            stateAt: (time) => this.historyStateAt(scope, time),
+            states: (depth) => this.historyStates(scope, depth),
+            events: (depth) => this.historyEvents(scope, depth),
+        };
+    },
+    /**
+     * Captures an Entity's state-at request and actor before membership awaits.
+     * @param scope Bound history resources.
+     * @param time Caller-selected historical time.
+     * @returns Historical state, if retained and visible.
+     */
+    async historyStateAt(scope, time) {
+        const actor = entityHistoryAccess.currentActor(scope.entity);
+        const captured = clone(TimestampSchema, time);
+        await scope.onAdmit();
+        return this.readBoundStateAt(scope.repository, scope.lifetime, scope.stand, scope.storage, scope.schema, scope.entityId, captured, scope.tenantId, actor);
+    },
+    /**
+     * Captures an Entity state-history depth and actor before membership awaits.
+     * @param scope Bound history resources.
+     * @param depth Number of prior states requested.
+     * @returns Visible historical states in retained order.
+     */
+    async historyStates(scope, depth) {
+        const actor = entityHistoryAccess.currentActor(scope.entity);
+        await scope.onAdmit();
+        return this.readBoundStates(scope.repository, scope.lifetime, scope.stand, scope.schema, scope.stateCache, scope.entityId, depth, scope.tenantId, actor);
+    },
+    /**
+     * Captures an Entity Event-history depth and actor before membership awaits.
+     * @param scope Bound history resources.
+     * @param depth Number of prior Events requested.
+     * @returns Visible retained Event envelopes.
+     */
+    async historyEvents(scope, depth) {
+        const actor = entityHistoryAccess.currentActor(scope.entity);
+        await scope.onAdmit();
+        return this.readBoundEvents(scope.repository, scope.lifetime, scope.stand, scope.eventCache, scope.entityId, depth, scope.tenantId, actor);
+    },
     /**
      * Creates state and Event caches over retained history ports.
      *
@@ -6406,38 +6638,86 @@ const RepositoryHistoryInternals = {
      *
      * @param repository Registered repository.
      * @param lifetime Captured repository storage lifetime.
+     * @param stand Producing context's outward read policy.
      * @param storage Retained Entity read port.
+     * @param schema Historical state schema.
      * @param entityId Captured Entity identifier.
      * @param time Historical instant.
+     * @param tenantId Effective tenant of the bound Entity.
+     * @param actorContext Actor metadata of an active handler, when present.
      * @returns Historical state, if present.
      */
-    readBoundStateAt(repository, lifetime, storage, entityId, time) {
-        return RepositoryStorage.track(repository, async () => this.cloneHistoryState(await storage.states.stateAt(entityId, time)), lifetime);
+    readBoundStateAt(repository, lifetime, stand, storage, schema, entityId, time, tenantId, actorContext) {
+        return RepositoryStorage.track(repository, async () => {
+            const state = this.cloneHistoryState(await storage.states.stateAt(entityId, time));
+            if (state === undefined)
+                return undefined;
+            const visible = await standAccess.filterState(stand, schema, state, {
+                operation: { kind: "history", history: { source: "entity-state-at", entityId, time } },
+                ...(tenantId === undefined ? {} : { effectiveTenant: tenantId }),
+                ...(actorContext === undefined ? {} : { actorContext }),
+            });
+            return visible ?? undefined;
+        }, lifetime);
     },
     /**
      * Reads a complete bound state-history page within repository admission.
      *
      * @param repository Registered repository.
      * @param lifetime Captured repository storage lifetime.
+     * @param stand Producing context's outward read policy.
      * @param schema State schema used to unpack rows.
      * @param cache Bound state-history cache.
+     * @param entityId Captured Entity identifier.
      * @param depth Requested history depth.
+     * @param tenantId Effective tenant of the bound Entity.
+     * @param actorContext Actor metadata of an active handler, when present.
      * @returns Frozen historical states.
      */
-    readBoundStates(repository, lifetime, schema, cache, depth) {
-        return RepositoryStorage.track(repository, async () => this.freezeHistoryStates((await cache.read(depth)).map((record) => EntityRecords.unpack(schema, record).state)), lifetime);
+    readBoundStates(repository, lifetime, stand, schema, cache, entityId, depth, tenantId, actorContext) {
+        return RepositoryStorage.track(repository, async () => {
+            const states = this.freezeHistoryStates((await cache.read(depth)).map((record) => EntityRecords.unpack(schema, record).state));
+            const visible = [];
+            for (const state of states) {
+                const next = await standAccess.filterState(stand, schema, state, {
+                    operation: { kind: "history", history: { source: "entity-states", entityId, depth } },
+                    ...(tenantId === undefined ? {} : { effectiveTenant: tenantId }),
+                    ...(actorContext === undefined ? {} : { actorContext }),
+                });
+                if (next !== null)
+                    visible.push(Object.freeze(next));
+            }
+            return Object.freeze(visible);
+        }, lifetime);
     },
     /**
      * Reads a complete bound Event-history page within repository admission.
      *
      * @param repository Registered repository.
      * @param lifetime Captured repository storage lifetime.
+     * @param stand Producing context's outward read policy.
      * @param cache Bound Event-history cache.
+     * @param entityId Captured Entity identifier.
      * @param depth Requested history depth.
+     * @param tenantId Effective tenant of the bound Entity.
+     * @param actorContext Actor metadata of an active handler, when present.
      * @returns Frozen historical Events.
      */
-    readBoundEvents(repository, lifetime, cache, depth) {
-        return RepositoryStorage.track(repository, async () => this.freezeHistoryEvents(await cache.read(depth)), lifetime);
+    readBoundEvents(repository, lifetime, stand, cache, entityId, depth, tenantId, actorContext) {
+        return RepositoryStorage.track(repository, async () => {
+            const events = this.freezeHistoryEvents(await cache.read(depth));
+            const visible = [];
+            for (const event of events) {
+                const next = await standAccess.filterEvent(stand, event, {
+                    operation: { kind: "history", history: { source: "entity-events", entityId, depth } },
+                    ...(tenantId === undefined ? {} : { effectiveTenant: tenantId }),
+                    ...(actorContext === undefined ? {} : { actorContext }),
+                });
+                if (next !== null)
+                    visible.push(Object.freeze(next));
+            }
+            return Object.freeze(visible);
+        }, lifetime);
     },
     /**
      * Creates a history cache that serializes reads and extends prior results.