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

package/dist/agent/agent-acceptance-receipts.d.ts

@@ -0,0 +1,69 @@
+import type { Any } from "@bufbuild/protobuf/wkt";
+import type { CommandId, EventId } from "@spine-event-engine/proto";
+import { type AgentAcceptanceReceipt } from "@spine-event-engine/proto/generated/spine/server/agent/acceptance_receipt_pb.js";
+import { RecordSpec, StorageGroup, type StorageContext, type StorageFactory } from "@spine-event-engine/storage";
+import type { DeliveryLabel } from "../delivery/inbox.js";
+/**
+ * Declarative physical family shared by runtime use and explicit preparation.
+ */
+export declare const agentAcceptanceReceiptSpec: RecordSpec<string, AgentAcceptanceReceipt>;
+/**
+ * Stable physical group for Agent acceptance evidence.
+ */
+export declare const agentAcceptanceReceiptGroup: StorageGroup;
+/**
+ * Typed source and recipient of one Agent delivery.
+ */
+export interface AgentAcceptanceInput {
+    /**
+     * Generated Agent state type.
+     */
+    readonly stateType: string;
+    /**
+     * Original typed recipient, including the exact Any type URL.
+     */
+    readonly recipientId: Any;
+    /**
+     * Original typed Command or Event identifier.
+     */
+    readonly source: {
+        readonly kind: "command";
+        readonly id: CommandId;
+    } | {
+        readonly kind: "event";
+        readonly id: EventId;
+    };
+    /**
+     * Delivery route that selected the Agent.
+     */
+    readonly action: DeliveryLabel;
+}
+/**
+ * Retains one atomic receipt handle per complete tenant boundary.
+ *
+ * @internal
+ */
+export declare class AgentAcceptanceReceipts {
+    #private;
+    /**
+     * Creates an inert receipt helper without opening storage.
+     *
+     * @param factory Provider factory used only when the first receipt is admitted.
+     */
+    constructor(factory: StorageFactory);
+    /**
+     * Accepts one typed delivery atomically; only `true` may permit live execution.
+     *
+     * @param context Complete physical tenant scope.
+     * @param input Typed delivery identity.
+     * @returns Whether this attempt first established the immutable receipt.
+     */
+    accept(context: StorageContext, input: AgentAcceptanceInput): Promise<boolean>;
+    /**
+     * Closes retained handles after fencing new admissions and draining admitted CAS operations.
+     *
+     * @returns Repeatable completion after admitted CAS operations and all handles settle.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=agent-acceptance-receipts.d.ts.map

package/dist/agent/agent-acceptance-receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-acceptance-receipts.d.ts","sourceRoot":"","sources":["../../src/agent/agent-acceptance-receipts.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,iFAAiF,CAAC;AACzF,OAAO,EACL,UAAU,EACV,YAAY,EAEZ,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,UAAU,CAAC,MAAM,EAAE,sBAAsB,CAQ9E,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,YAAyD,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAA;KAAE,GACpD;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAErD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;;GAIG;AACH,qBAAa,uBAAuB;;IAWlC;;;;OAIG;gBACS,OAAO,EAAE,cAAc;IAInC;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBpF;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAwEvB"}

package/dist/agent/agent-acceptance-receipts.js

@@ -0,0 +1,198 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { createHash } from "node:crypto";
+import { clone, create } from "@bufbuild/protobuf";
+import { AgentAcceptanceKeySchema, AgentAcceptanceReceiptSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/acceptance_receipt_pb.js";
+import { RecordSpec, StorageGroup, } from "@spine-event-engine/storage";
+import { TenantBoundary } from "@spine-event-engine/storage/provider";
+/**
+ * Declarative physical family shared by runtime use and explicit preparation.
+ */
+export const agentAcceptanceReceiptSpec = new RecordSpec({
+    idKind: "string",
+    recordType: AgentAcceptanceReceiptSchema,
+    extractId: (receipt) => {
+        if (receipt.key === undefined)
+            throw new TypeError("Agent receipt has no identity.");
+        return ReceiptIdentity.slot(receipt.key);
+    },
+});
+/**
+ * Stable physical group for Agent acceptance evidence.
+ */
+export const agentAcceptanceReceiptGroup = new StorageGroup("spine_agent_acceptance");
+/**
+ * Retains one atomic receipt handle per complete tenant boundary.
+ *
+ * @internal
+ */
+export class AgentAcceptanceReceipts {
+    #factory;
+    #storages = new Map();
+    #active = 0;
+    #resolveIdle;
+    #closing;
+    /**
+     * Creates an inert receipt helper without opening storage.
+     *
+     * @param factory Provider factory used only when the first receipt is admitted.
+     */
+    constructor(factory) {
+        this.#factory = factory;
+    }
+    /**
+     * Accepts one typed delivery atomically; only `true` may permit live execution.
+     *
+     * @param context Complete physical tenant scope.
+     * @param input Typed delivery identity.
+     * @returns Whether this attempt first established the immutable receipt.
+     */
+    async accept(context, input) {
+        if (this.#closing !== undefined)
+            throw new Error("Agent acceptance receipts are closed.");
+        this.#active++;
+        try {
+            const key = clone(AgentAcceptanceKeySchema, this.#key(input));
+            const slot = ReceiptIdentity.slot(key);
+            const storage = this.#storage(context);
+            if (!storage.atomicCompareAndSet)
+                throw new Error("Agent acceptance requires atomic compare-and-set storage.");
+            if (await storage.compareAndSet(slot, undefined, create(AgentAcceptanceReceiptSchema, { key })))
+                return true;
+            const previous = await storage.read(slot);
+            if (previous?.key === undefined)
+                throw new Error("Agent acceptance receipt is missing after lost CAS.");
+            if (ReceiptIdentity.text(previous.key) !== ReceiptIdentity.text(key))
+                throw new Error("Agent acceptance receipt identity conflict.");
+            return false;
+        }
+        finally {
+            this.#active--;
+            if (this.#active === 0)
+                this.#resolveIdle?.();
+        }
+    }
+    /**
+     * Closes retained handles after fencing new admissions and draining admitted CAS operations.
+     *
+     * @returns Repeatable completion after admitted CAS operations and all handles settle.
+     */
+    close() {
+        if (this.#closing !== undefined)
+            return this.#closing;
+        const idle = this.#active === 0
+            ? Promise.resolve()
+            : new Promise((resolve) => {
+                this.#resolveIdle = () => {
+                    resolve();
+                };
+            });
+        this.#closing = idle.then(() => {
+            this.#closeStorages();
+        });
+        return this.#closing;
+    }
+    /**
+     * Constructs one generated identity without changing the supplied type URL.
+     * @param input Typed delivery identity.
+     * @returns Its generated complete identity evidence.
+     */
+    #key(input) {
+        if (input.stateType.trim().length === 0 || input.recipientId.typeUrl.length === 0)
+            throw new TypeError("Agent acceptance requires a state type and typed recipient.");
+        return create(AgentAcceptanceKeySchema, {
+            stateType: input.stateType,
+            recipientId: input.recipientId,
+            source: input.source.kind === "command"
+                ? { case: "command", value: input.source.id }
+                : { case: "event", value: input.source.id },
+            action: input.action,
+        });
+    }
+    /**
+     * Finds or creates one handle for a complete physical tenant scope.
+     * @param context Complete physical scope.
+     * @returns Retained atomic record handle.
+     */
+    #storage(context) {
+        const boundary = TenantBoundary.of(context);
+        const retained = this.#storages.get(boundary.key);
+        if (retained !== undefined)
+            return retained;
+        const selected = boundary.tenantId === undefined
+            ? { name: context.name, multitenant: false }
+            : { name: context.name, multitenant: true, tenantId: boundary.tenantId };
+        const storage = this.#factory.createRecordStorage(selected, agentAcceptanceReceiptSpec, agentAcceptanceReceiptGroup);
+        this.#storages.set(boundary.key, storage);
+        return storage;
+    }
+    /**
+     * Attempts every retained close and preserves all cleanup failures.
+     */
+    #closeStorages() {
+        const errors = [];
+        for (const storage of this.#storages.values()) {
+            try {
+                storage.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        this.#storages.clear();
+        if (errors.length !== 0)
+            throw new AggregateError(errors, "Agent receipt cleanup failed.");
+    }
+}
+/**
+ * Encodes one complete typed identity for provider slots and collision checks.
+ */
+const ReceiptIdentity = Object.freeze({
+    /**
+     * Encodes declared identity fields with stable framing and exact Any bytes.
+     *
+     * @param key Complete generated identity evidence.
+     * @returns Stable v1 tuple text for slot derivation and collision checking.
+     */
+    text(key) {
+        const recipient = key.recipientId;
+        const source = key.source;
+        const sourceId = source.case === "command"
+            ? source.value.uuid
+            : source.case === "event"
+                ? source.value.value
+                : undefined;
+        if (!key.stateType || !recipient?.typeUrl || !sourceId || !key.action)
+            throw new TypeError("Agent acceptance receipt has incomplete identity.");
+        return JSON.stringify([
+            "spine.server.agent.AgentAcceptanceKey/v1",
+            key.stateType,
+            recipient.typeUrl,
+            Buffer.from(recipient.value).toString("base64"),
+            source.case,
+            sourceId,
+            key.action,
+        ]);
+    },
+    /**
+     * Calculates the fixed provider slot from the complete typed identity.
+     *
+     * @param key Complete generated identity evidence.
+     * @returns Versioned 67-character record slot.
+     */
+    slot(key) {
+        return `v1:${createHash("sha256").update(this.text(key), "utf8").digest("hex")}`;
+    },
+});
+//# sourceMappingURL=agent-acceptance-receipts.js.map

package/dist/agent/agent-acceptance-receipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-acceptance-receipts.js","sourceRoot":"","sources":["../../src/agent/agent-acceptance-receipts.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent-execution-capacity.d.ts

@@ -1,8 +1,23 @@
 import type { AiRegistry } from "@spine-event-engine/ai";
-interface CapacityRequest {
-    readonly key: string;
-    readonly signal: AbortSignal;
-    readonly run: () => Promise<void>;
+/**
+ * A local slot retained before an Agent receipt is accepted.
+ */
+export interface AgentCapacityReservation {
+    /**
+     * Settles after this reservation releases or its admitted turn finishes.
+     */
+    readonly completed: Promise<void>;
+    /**
+     * Starts work after Inbox acknowledgement and the Agent turn become available.
+     *
+     * @param onRun Callback to run after capacity admission.
+     * @returns Completion after admitted Agent work finishes.
+     */
+    run(onRun: () => Promise<void>): Promise<void>;
+    /**
+     * Clears a slot when receipt or acknowledgement admission does not complete.
+     */
+    release(): void;
 }
 /**
  * Schedules active Agent transitions and resident waiting hints across one AI registry.
@@ -32,12 +47,25 @@ export declare class AgentExecutionCapacity {
      */
     full(): boolean;
     /**
-     * Tries to retain one descriptor; overflow remains in durable storage.
+     * Observes released Agent identities and available registry capacity.
+     *
+     * @param onAvailable Callback invoked when capacity becomes available.
+     * @returns A callback that removes this capacity listener.
+     */
+    onAvailable(onAvailable: (key: string) => void): () => void;
+    /**
+     * Captures the current release generation for gap-free rechecking.
+     *
+     * @returns The current release generation for gap-free rechecking.
+     */
+    availabilityGeneration(): number;
+    /**
+     * Acquires bounded resident capacity before a durable Agent receipt attempt.
      *
-     * @param request Keyed work hint and cancellation signal from one Bounded Context.
-     * @returns Completion of retained work, or undefined when admission is declined.
+     * @param key Physical or logical identity key.
+     * @param signal Signal or cancellation signal for this operation.
+     * @returns A capacity reservation or undefined when admission is unavailable.
      */
-    trySubmit(request: CapacityRequest): Promise<void> | undefined;
+    reserve(key: string, signal: AbortSignal): AgentCapacityReservation | undefined;
 }
-export {};
 //# sourceMappingURL=agent-execution-capacity.d.ts.map

package/dist/agent/agent-execution-capacity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-execution-capacity.d.ts","sourceRoot":"","sources":["../../src/agent/agent-execution-capacity.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,UAAU,eAAe;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAWD;;GAEG;AACH,qBAAa,sBAAsB;;IAc/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAR1B;;;;;OAKG;gBAEgB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA;IASlC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,GAAG,sBAAsB;IAYxD;;;;OAIG;IACH,IAAI,IAAI,OAAO;IASf;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS;CA2E/D"}
+{"version":3,"file":"agent-execution-capacity.d.ts","sourceRoot":"","sources":["../../src/agent/agent-execution-capacity.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAcD;;GAEG;AACH,qBAAa,sBAAsB;;IAkB/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAR1B;;;;;OAKG;gBAEgB,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,MAAM,CAAC,EAAE,MAAM,YAAA;IASlC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,GAAG,sBAAsB;IAYxD;;;;OAIG;IACH,IAAI,IAAI,OAAO;IASf;;;;;OAKG;IACH,WAAW,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAO3D;;;;OAIG;IACH,sBAAsB,IAAI,MAAM;IAIhC;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,wBAAwB,GAAG,SAAS;CA8GhF"}

package/dist/agent/agent-execution-capacity.js

@@ -22,6 +22,8 @@ export class AgentExecutionCapacity {
     #entries = new Map();
     #active = new Set();
     #waiting = [];
+    #listeners = new Set();
+    #availabilityGeneration = 0;
     /**
      * Creates a registry gate with optional active and resident waiting limits.
      *
@@ -62,17 +64,39 @@ export class AgentExecutionCapacity {
             this.#waiting.length >= this.queued);
     }
     /**
-     * Tries to retain one descriptor; overflow remains in durable storage.
+     * Observes released Agent identities and available registry capacity.
      *
-     * @param request Keyed work hint and cancellation signal from one Bounded Context.
-     * @returns Completion of retained work, or undefined when admission is declined.
+     * @param onAvailable Callback invoked when capacity becomes available.
+     * @returns A callback that removes this capacity listener.
      */
-    trySubmit(request) {
-        if (request.signal.aborted || this.#entries.has(request.key) || this.full())
+    onAvailable(onAvailable) {
+        this.#listeners.add(onAvailable);
+        return () => {
+            this.#listeners.delete(onAvailable);
+        };
+    }
+    /**
+     * Captures the current release generation for gap-free rechecking.
+     *
+     * @returns The current release generation for gap-free rechecking.
+     */
+    availabilityGeneration() {
+        return this.#availabilityGeneration;
+    }
+    /**
+     * Acquires bounded resident capacity before a durable Agent receipt attempt.
+     *
+     * @param key Physical or logical identity key.
+     * @param signal Signal or cancellation signal for this operation.
+     * @returns A capacity reservation or undefined when admission is unavailable.
+     */
+    reserve(key, signal) {
+        if (signal.aborted || this.#entries.has(key) || this.full())
             return undefined;
         const completion = Promise.withResolvers();
         const entry = {
-            ...request,
+            key,
+            signal,
             completion,
             started: false,
             settled: false,
@@ -83,21 +107,39 @@ export class AgentExecutionCapacity {
         this.#entries.set(entry.key, entry);
         entry.signal.addEventListener("abort", entry.onAbort, { once: true });
         if (this.concurrent === undefined || this.#active.size < this.concurrent)
-            this.#start(entry);
+            this.#active.add(entry);
         else
             this.#waiting.push(entry);
-        return completion.promise;
+        return {
+            completed: entry.completion.promise,
+            run: (onRun) => this.#run(entry, onRun),
+            release: () => {
+                this.#cancelWaiting(entry);
+            },
+        };
+    }
+    /**
+     * Starts a reserved descriptor only when it has an active slot.
+     */
+    #run(entry, onRun) {
+        if (entry.settled || entry.run !== undefined)
+            throw new Error("Agent capacity reservation is no longer available.");
+        entry.run = onRun;
+        if (this.#active.has(entry))
+            this.#start(entry);
+        return entry.completion.promise;
     }
     /**
      * Starts a retained descriptor only after it receives an active slot.
      */
     #start(entry) {
+        if (entry.run === undefined || entry.started || entry.settled)
+            return;
         entry.started = true;
-        this.#active.add(entry);
         void Promise.resolve()
             .then(() => {
             if (!entry.signal.aborted)
-                return entry.run();
+                return entry.run?.();
         })
             .then(() => {
             this.#finish(entry);
@@ -111,10 +153,15 @@ export class AgentExecutionCapacity {
     #cancelWaiting(entry) {
         if (entry.started || entry.settled)
             return;
-        const index = this.#waiting.indexOf(entry);
-        if (index >= 0)
-            this.#waiting.splice(index, 1);
-        this.#settle(entry);
+        if (this.#active.has(entry))
+            this.#finish(entry);
+        else {
+            const index = this.#waiting.indexOf(entry);
+            if (index >= 0)
+                this.#waiting.splice(index, 1);
+            this.#settle(entry);
+            this.#notifyAvailable(entry.key);
+        }
     }
     /**
      * Releases a finished slot once, then starts the oldest eligible hint.
@@ -127,9 +174,20 @@ export class AgentExecutionCapacity {
         while ((this.concurrent === undefined || this.#active.size < this.concurrent) &&
             this.#waiting.length > 0) {
             const next = this.#waiting.shift();
-            if (next !== undefined && !next.settled)
+            if (next !== undefined && !next.settled) {
+                this.#active.add(next);
                 this.#start(next);
+            }
         }
+        this.#notifyAvailable(entry.key);
+    }
+    /**
+     * Wakes eligibility observers after active and queued positions settle.
+     */
+    #notifyAvailable(key) {
+        this.#availabilityGeneration += 1;
+        for (const listener of this.#listeners)
+            listener(key);
     }
     /**
      * Removes one reservation and completes its bounded wait promise.

package/dist/agent/agent-execution-capacity.js.map

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

package/dist/agent/agent-history.d.ts

@@ -1,5 +1,5 @@
 import type { ConversationHistoryRead, HistoryPage, HistoryRead } from "@spine-event-engine/ai";
-import type { Event } from "@spine-event-engine/proto";
+import type { ActorContext, Event } from "@spine-event-engine/proto";
 import { type AgentHistoryEntry, type ConversationRecord } from "@spine-event-engine/proto/agent";
 import { type AgentHistoryPage, type AgentHistoryStorage, type AgentHistoryView } from "@spine-event-engine/storage/provider";
 /**
@@ -24,16 +24,16 @@ export interface AgentHistoryScope {
     readonly entity: string;
 }
 /**
- * Returns a saved complete page or delegates to a live provider read.
+ * Reads a current indexed provider page through one live Agent interceptor.
  *
  * @param scope Exact repository and Agent scope.
- * @param view Indexed history view.
  * @param request Public read request.
  * @param live Loads the current provider page only when needed.
  * @param maxBytes Optional response-byte ceiling for this read.
- * @returns The saved or newly loaded complete provider page.
+ * @param present Applies outward policy after accounting for provider bytes.
+ * @returns The current complete provider page.
  */
-export type AgentHistoryJournal = (scope: AgentHistoryScope, view: AgentHistoryView, request: HistoryRead, live: () => Promise<AgentHistoryPage>, maxBytes: number | undefined) => Promise<AgentHistoryPage>;
+export type AgentHistoryReadInterceptor = (scope: AgentHistoryScope, request: HistoryRead, live: () => Promise<AgentHistoryPage>, maxBytes: number | undefined, present: (page: AgentHistoryPage) => Promise<HistoryPage<AgentHistoryEntry>>) => Promise<HistoryPage<AgentHistoryEntry>>;
 /**
  * Repository binding for an Agent's mandatory indexed history.
  *
@@ -49,17 +49,37 @@ export interface AgentHistoryBinding<Id> {
      */
     readonly entityId: Id;
     /**
-     * Full cursor and journal scope.
+     * Full cursor and read scope.
      */
     readonly scope: AgentHistoryScope;
     /**
-     * Optional durable read replay interceptor.
+     * Optional live read interceptor.
      */
-    readonly journal?: AgentHistoryJournal;
+    readonly interceptRead?: AgentHistoryReadInterceptor;
     /**
      * Optional maximum serialized entry bytes in one response.
      */
     readonly maxBytes?: number;
+    /**
+     * Admits the complete protected page, including interceptor and provider work.
+     * @param onRead Complete page read to admit.
+     * @returns Its result after all work settles.
+     */
+    readonly onAdmit?: (onRead: () => Promise<HistoryPage<AgentHistoryEntry>>) => Promise<HistoryPage<AgentHistoryEntry>>;
+    /**
+     * Captures active signal metadata before the protected read can await.
+     * @returns Detached actor context when a handler supplies one.
+     */
+    readonly captureActor?: () => ActorContext | undefined;
+    /**
+     * Transforms outward domain records after provider read and before read completion.
+     * @param page Retained provider entries and original continuation.
+     * @param view Requested history category.
+     * @param request Captured page request.
+     * @param actorContext Actor metadata from the active handler, when present.
+     * @returns Visible entries with the original continuation.
+     */
+    readonly filterPage?: (page: HistoryPage<AgentHistoryEntry>, view: AgentHistoryView, request: HistoryRead, actorContext?: ActorContext) => Promise<HistoryPage<AgentHistoryEntry>>;
 }
 /**
  * Internal accessors shared by the Agent base and repository runtime.
@@ -74,13 +94,13 @@ export interface AgentHistoryReadAccess {
      */
     bind<Id>(entity: object, binding: AgentHistoryBinding<Id>): void;
     /**
-     * Binds a journal that records and replays this handler's history reads.
+     * Binds a read interceptor for the current handler invocation.
      *
      * @param entity Agent with an existing repository history binding.
-     * @param journal Intercepts history reads during the handler.
+     * @param interceptRead Intercepts current provider reads during the handler.
      * @returns Callback that restores the original history binding after the handler finishes.
      */
-    withJournal(entity: object, journal: AgentHistoryJournal): () => void;
+    withReadInterceptor(entity: object, interceptRead: AgentHistoryReadInterceptor): () => void;
     /**
      * Reads all categories.
      *
@@ -129,9 +149,10 @@ export interface AgentHistoryReadAccess {
      * @param binding Exact Agent repository and tenant storage scope.
      * @param view Indexed history view.
      * @param request Public page request.
+     * @param actorContext Actor metadata captured at invocation.
      * @returns Retained entries and opaque continuation.
      */
-    readBound<Id>(binding: AgentHistoryBinding<Id>, view: AgentHistoryView, request: HistoryRead): Promise<HistoryPage<AgentHistoryEntry>>;
+    readBound<Id>(binding: AgentHistoryBinding<Id>, view: AgentHistoryView, request: HistoryRead, actorContext?: ActorContext): Promise<HistoryPage<AgentHistoryEntry>>;
     /**
      * Persists a genuine framework System Event.
      *

package/dist/agent/agent-history.d.ts.map

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