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

package/README.md

@@ -5,6 +5,13 @@ includes an in-memory implementation for local development and tests. Use it
 when an application needs a small record store, or when an adapter needs to
 implement the same storage contract for a durable provider.
 
+Agents use the configured storage provider to retain accepted work and the
+recorded model interaction. The in-memory factory keeps these records only while
+the process runs; choose a database provider when they must survive a restart.
+Applications read an Agent's history through its repository, as shown in the
+[support example](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/README.md). Adapter implementation
+details are in the [coding-agent reference](REFERENCE.md#provider-spi).
+
 This is an experimental snapshot package. Use Node 24 or newer and generated
 Protobuf record schemas before configuring storage.
 

package/REFERENCE.md

@@ -1,6 +1,6 @@
 # @spine-event-engine/storage reference
 
-This reference is for agents working with the Spine TS storage contract.
+This reference is for coding agents working with the Spine TS storage contract.
 
 ## Public entry point
 
@@ -16,9 +16,118 @@ types, and entity history interfaces.
 Storage-adapter implementers import the complete provider-only contract set from
 `@spine-event-engine/storage/provider`: Event Store record access, Entity
 history and Entity commit contracts, query values, tenant boundaries/catalogs,
-and delivery-cleanup handles. The storage root intentionally does not export
+and record access. The storage root intentionally does not export
 these provider seams; application code uses its root storage contracts instead.
 
+The provider entry point also exports `AgentHistoryStorage`,
+`AgentHistoryStorageFactories`, `AgentHistoryKeys`, and
+`AgentHistoryConformance`. Calling `AgentHistoryStorageFactories.create()` to
+open a handle fails if the supplied factory has not registered the capability.
+Agent repository registration requires this capability. Opening the actual
+tenant handle also checks the selected provider before accepting Agent work.
+Agent history's append-only entries
+retain the original conversation record or Event envelope,
+ID, and occurrence time. The full, conversation, System, and domain views use
+separate indexes. Conversation reads require a `ConversationId`. The complete
+order is occurrence seconds and nanoseconds descending, then conversation,
+System, domain, then unsigned UTF-8 record ID ascending. `AgentHistoryKeys`
+derives a sortable index value from that order; it is not a record identity.
+
+Provider reads require a positive count and accept an optional complete
+ordering-key boundary and positive byte limit. Omitting the byte limit adds no
+provider-contract default. A configured byte limit counts the sum of serialized
+`AgentHistoryEntry` wrapper lengths, excluding provider framing. A page reports
+whether older entries remain; if the first entry exceeds a configured byte
+limit, the read rejects. Limits never remove stored entries. Identical repeated appends
+are accepted, while different content with the same category and record ID
+is rejected. `AgentHistoryConformance` runs reusable view, order, paging,
+scope, and retention checks for adapter implementations. The memory provider
+retains entries across handles sharing a backend during the process lifetime;
+it does not provide restart durability.
+The PostgreSQL, MySQL, and Datastore providers store complete entries in one
+tenant-scoped `agent_history` record family with native full, category, and
+conversation ordering indexes. Each derives a bounded physical record ID from
+the full state type, Agent key, category, and original record ID, then checks
+immutable payload equality on repeated appends. Their provider references
+specify physical index and payload constraints.
+
+## Tenant catalog paging
+
+Storage adapters implement `TenantCatalog.page({ count, signal, after? })` from
+the provider entry point. `count` is a positive safe integer and bounds
+native candidates examined, including candidates filtered out as unrelated
+namespaces. `signal` accepts a native `AbortSignal`; `TenantCatalogSignal`
+describes the required members without requiring DOM declarations in storage
+consumers. `TenantCatalogReads.require()` performs common request validation.
+
+A `TenantCatalogPage` returns complete `boundaries`, `hasMore`, and an opaque
+`after` continuation when more candidates remain. Pass that continuation to the
+same catalog instance. Forged or cross-catalog continuations are rejected; the
+cursor is an in-process value, not a durable domain record. An empty page can
+still have more candidates. Continue until `hasMore` is false, rather than
+stopping at the first empty page. Repeating a valid continuation may repeat the
+page. A fresh sweep starts without a continuation.
+
+Memory pages use an admission-time index and capture its length for that sweep;
+PostgreSQL and MySQL page their configured tenant collections. Datastore pages
+its bounded early-admission cache and then native namespace metadata using a
+query limit and native cursor. A tenant can appear in both phases. Existing
+Agent claims prevent that duplicate discovery from running the same accepted
+invocation concurrently. An empty native `MORE_RESULTS_AFTER_LIMIT` tail that repeats its cursor ends
+that sweep; other continuing pages must advance. Datastore destroys its query
+stream when the caller cancels the read.
+
+Catalogs check cancellation before starting work and before returning a result.
+Paging is a finite traversal, not an atomic catalog snapshot: a concurrent
+admission can appear in the current or next sweep. Agent recovery uses this
+paged contract; the separate `all()` operation remains available for existing
+callers that require the complete catalog.
+
+## Agent execution storage
+
+`AgentExecutionStorageFactories` opens the provider-only execution handle for an
+Agent repository and tenant. `supports()` checks factory registration without
+opening a tenant. It does not replace the provider checks made when admitting
+work. Application code configures a storage factory; it does not claim or poll
+these records directly.
+
+The handle's `capacity` reports encoded execution, per-instance and history-record
+limits plus a transaction payload limit where the provider enforces one.
+`AgentExecutionSizes` measures the full internal Protobuf wrappers, including
+scope and metadata. The runtime must allow for the bounded response and complete
+record overhead before dispatch; a payload limit is not a history retention rule.
+
+`admit()` stores the original signal, typed recipient and selected handlers once.
+`claim()` permits one execution at a time for an Agent instance. `renew()`,
+`update()`, `complete()` and `markDelivered()` check the current claim token.
+Updates also compare the exact previously read record. Completion compares the
+initial Entity Version and stores the Entity changes, mandatory histories, model
+preferences and original outgoing Command obligations in one provider operation. Emitted
+domain Events are retained in immutable Agent history and handed to the normal
+EventBus after completion; they are not saved delivery obligations. This includes
+handlers that change no state or produce only a Command.
+
+Pending queries read one pending invocation per Agent instance from an index. A page
+carries its original time cutoff and the provider-observed continuation, so the
+caller can continue even when another execution claims a returned invocation.
+These internal pages are separate from application history pages. Eligibility
+and claim expiry use Spine `Time`; original Inbox order determines which signal
+runs next within an instance.
+
+Each saved outgoing Command can receive one dispatch plan before transport
+begins. The plan and original Command envelope cannot be replaced.
+`markDelivered()` requires that plan and a current claim. Command retries must
+still visit every saved recipient; these records do not make downstream
+application callbacks execute exactly once. Independently, the framework's
+internal EventStore retry operation accepts an identical existing envelope;
+ordinary public EventStore append still rejects duplicate IDs. EventStore
+history is not an Agent Event delivery queue.
+
+The memory implementation coordinates changes only within a shared in-process
+backend. PostgreSQL, transactional MySQL and Datastore use native transactions.
+Database query, index and payload requirements are documented in each provider's
+reference. No execution-storage operation trims the Agent's history.
+
 ## Record storage
 
 `StorageFactory.createRecordStorage(context, spec, group?)` returns an
@@ -109,6 +218,17 @@ history stores generated `EventId`/`Event` rows in that same state-type-named
 group. The framework Event Store is a separate, ungrouped `EventId`/`Event`
 record family.
 
+`EventStore.append()` and `appendAll()` store immutable complete Events. An
+identical Event ID and envelope is a successful retry without rewriting; a
+conflicting envelope is rejected. Batch append validates the supplied IDs and
+tenant before writing, then leaves any completed prefix when a later write
+fails. Retrying the same input continues with those IDs. `accept()` and
+`acceptThenAppend()` are strict new-admission operations: an existing ID is
+rejected even when its Event is identical. `acceptThenAppend()` checks absence,
+runs its callback, then inserts with an atomic absent-slot condition. Competing
+callbacks may both run and may each have effects, but at most one Event is stored.
+The framework EventBus dispatches only after strict insertion succeeds.
+
 History ports are lazy. When a history is disabled, the in-memory provider does
 not open or allocate its grouped records. Current Entity loading always uses
 the current record, never retained history. Event history is diagnostic data,
@@ -121,8 +241,12 @@ errors reject. There is no Entity conflict result. This changes the published
 `storage/provider` types for custom adapters; application APIs and persisted
 record layouts are unchanged.
 
-The in-memory provider prepares only the affected records before applying them
-together. Saving one Entity does not copy other Entities or whole history/Event
-Store collections. Automatic Entity versions, immutable-record checks and
-unrelated Inbox conditional updates remain. Other providers document their
-transaction and partial-write guarantees separately.
+The built-in providers capture prepared input before I/O and write state history,
+diagnostic Events, delivery Events, then current state as independent records.
+SQL and Datastore providers automatically retry one classified transient Entity
+persistence failure using that captured input. In memory, a caller retry must
+reuse the same versions and Event IDs without rerunning the handler. A later
+failure leaves completed writes in place. The presence of a delivery Event
+alone does not prove the entire Entity save completed. Concurrent saves may
+interleave, including current-state writes. Automatic Entity versions,
+single-record atomic compare-and-set, and immutable-record checks remain.

package/dist/entity/agent-execution-record-spec.d.ts

@@ -0,0 +1,87 @@
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { type AgentExecutionHead, type AgentExecutionRecord, type AgentExecutionScope, type AgentInboxOrder, type AgentInvocationKey, type AgentSignalKey } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { RecordSpec } from "../record/record-spec.js";
+import { StorageGroup } from "../record/storage-group.js";
+/**
+ * Describes physical execution record families and their indexed keys.
+ */
+interface AgentExecutionRecordLayout {
+    /**
+     * Shared invocation record family.
+     */
+    readonly invocationGroup: StorageGroup;
+    /**
+     * Shared per-instance claim and preference family.
+     */
+    readonly headGroup: StorageGroup;
+    /**
+     * Encodes the complete Agent instance scope.
+     *
+     * @param scope Generated state type and Agent key.
+     * @returns Complete encoded Agent instance scope.
+     */
+    scope(scope: AgentExecutionScope): string;
+    /**
+     * Encodes full Agent scope for binary-collated continuations.
+     *
+     * @param scope Generated state type and Agent key.
+     * @returns Binary-collated Agent instance scope key.
+     */
+    scopeOrder(scope: AgentExecutionScope): string;
+    /**
+     * Encodes the original source and Agent scope.
+     *
+     * @param key Original Agent invocation identity.
+     * @returns Complete immutable invocation key.
+     */
+    invocation(key: AgentInvocationKey): string;
+    /**
+     * Encodes the typed original Command or Event ID.
+     *
+     * @param signal Original signal identity.
+     * @returns Complete typed source signal key.
+     */
+    signal(signal: AgentSignalKey): string;
+    /**
+     * Encodes full Inbox time, version and source ID for binary order.
+     *
+     * @param order Original Inbox order.
+     * @returns Complete binary-collated Inbox order key.
+     */
+    order(order: AgentInboxOrder): string;
+    /**
+     * Encodes provider eligibility time and complete Agent scope.
+     *
+     * @param eligibleAt Time when this head becomes eligible.
+     * @param scope Generated state type and Agent key.
+     * @returns Complete binary-collated eligibility and scope key.
+     */
+    pendingKey(eligibleAt: Timestamp, scope: AgentExecutionScope): string;
+    /**
+     * Encodes the strict upper bound before all scopes at this time.
+     *
+     * @param asOf Fixed eligibility cutoff for the page.
+     * @returns Strict eligibility upper-bound key.
+     */
+    pendingLower(asOf: Timestamp): string;
+    /**
+     * Creates the indexed invocation record specification.
+     *
+     * @param digest Fixed-width digest of the complete indexed value.
+     * @returns Invocation record layout and complete native index columns.
+     */
+    invocationSpec(digest: (value: string) => string): RecordSpec<string, AgentExecutionRecord>;
+    /**
+     * Creates the indexed per-instance head specification.
+     *
+     * @param digest Fixed-width digest of the complete indexed value.
+     * @returns Per-instance head layout and complete native index columns.
+     */
+    headSpec(digest: (value: string) => string): RecordSpec<string, AgentExecutionHead>;
+}
+/**
+ * Materializes complete Agent execution records and full indexed identities.
+ */
+export declare const AgentExecutionRecords: AgentExecutionRecordLayout;
+export {};
+//# sourceMappingURL=agent-execution-record-spec.d.ts.map

package/dist/entity/agent-execution-record-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-record-spec.d.ts","sourceRoot":"","sources":["../../src/entity/agent-execution-record-spec.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,+EAA+E,CAAC;AAIvF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAM1D;;GAEG;AACH,UAAU,0BAA0B;IAClC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,YAAY,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IAEjC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAE1C;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAE/C;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAE5C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAAC;IAEvC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;IAEtC;;;;;;OAMG;IACH,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAEtE;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAEtC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAE5F;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CACrF;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,0BA8KnC,CAAC"}

package/dist/entity/agent-execution-record-spec.js

@@ -0,0 +1,230 @@
+/*
+ * 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 { ScalarType } from "@bufbuild/protobuf";
+import { AgentExecutionHeadSchema, AgentExecutionRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { RecordColumn } from "../record/record-column.js";
+import { ColumnTypes } from "../record/column-type.js";
+import { RecordSpec } from "../record/record-spec.js";
+import { StorageGroup } from "../record/storage-group.js";
+const string = ColumnTypes.scalar(ScalarType.STRING);
+const invocationGroup = new StorageGroup("agent_execution");
+const headGroup = new StorageGroup("agent_execution_head");
+/**
+ * Materializes complete Agent execution records and full indexed identities.
+ */
+export const AgentExecutionRecords = {
+    /**
+     * Shared physical invocation family inside one provider tenant.
+     */
+    invocationGroup: invocationGroup,
+    /**
+     * Shared physical per-instance head family inside one provider tenant.
+     */
+    headGroup: headGroup,
+    /**
+     * Encodes complete Agent scope without truncation.
+     *
+     * @param scope Generated state type and canonical typed Agent key.
+     * @returns Unambiguous complete scope text.
+     */
+    scope(scope) {
+        if (!scope.stateType || !scope.agentKey)
+            throw new TypeError("Agent execution requires complete state type and Agent key.");
+        return JSON.stringify([scope.stateType, scope.agentKey]);
+    },
+    /**
+     * Encodes every scope byte for unambiguous binary continuation order.
+     *
+     * @param scope Generated state type and canonical typed Agent key.
+     * @returns Prefix-safe full ordering text.
+     */
+    scopeOrder(scope) {
+        this.scope(scope);
+        return `${utf8Hex(scope.stateType)}!${utf8Hex(scope.agentKey)}`;
+    },
+    /**
+     * Encodes one original source identity within its Agent scope.
+     *
+     * @param key Agent instance and original Command or Event ID.
+     * @returns Complete immutable invocation identity.
+     */
+    invocation(key) {
+        if (key.scope === undefined || key.sourceSignal === undefined)
+            throw new TypeError("Agent execution requires scope and original source ID.");
+        return JSON.stringify([this.scope(key.scope), this.signal(key.sourceSignal)]);
+    },
+    /**
+     * Encodes a typed source ID without optional MessageId Version metadata.
+     *
+     * @param signal Original Command or Event identity.
+     * @returns Complete typed source identity.
+     */
+    signal(signal) {
+        const id = signal.id;
+        if (id.case === "command" && id.value.uuid)
+            return JSON.stringify(["command", id.value.uuid]);
+        if (id.case === "event" && id.value.value)
+            return JSON.stringify(["event", id.value.value]);
+        throw new TypeError("Agent execution requires an original Command or Event ID.");
+    },
+    /**
+     * Encodes full Timestamp, Inbox version and source ID for native binary order.
+     *
+     * @param order Existing Inbox acceptance order.
+     * @returns Prefix-safe order text.
+     */
+    order(order) {
+        const at = order.receivedAt;
+        if (at === undefined ||
+            order.sourceSignal === undefined ||
+            order.inboxVersion < 0n ||
+            order.inboxVersion > 18446744073709551615n)
+            throw new TypeError("Agent execution requires complete Inbox order.");
+        if (at.seconds < -62135596800n ||
+            at.seconds > 253402300799n ||
+            at.nanos < 0 ||
+            at.nanos > 999_999_999)
+            throw new RangeError("Agent Inbox Timestamp is out of range.");
+        const seconds = (at.seconds + 62135596800n).toString().padStart(12, "0");
+        const nanos = at.nanos.toString().padStart(9, "0");
+        const version = order.inboxVersion.toString().padStart(20, "0");
+        const signal = order.sourceSignal.id;
+        const id = signal.case === "command"
+            ? signal.value.uuid
+            : signal.case === "event"
+                ? signal.value.value
+                : undefined;
+        if (!id)
+            throw new TypeError("Agent Inbox order requires an original source ID.");
+        const rank = signal.case === "command" ? "0" : "1";
+        return `${seconds}:${nanos}:${version}:${rank}${utf8Hex(id)}`;
+    },
+    /**
+     * Encodes full provider eligibility time and complete instance scope.
+     *
+     * @param eligibleAt Time when this head becomes eligible.
+     * @param scope Generated state type and Agent key.
+     * @returns Complete binary-collated eligibility and scope key.
+     */
+    pendingKey(eligibleAt, scope) {
+        return `${timestampKey(eligibleAt)}!${this.scopeOrder(scope)}`;
+    },
+    /**
+     * Returns an exclusive upper bound before all scopes at the sampled time.
+     *
+     * @param asOf Fixed eligibility cutoff for the page.
+     * @returns Strict eligibility upper-bound key.
+     */
+    pendingLower(asOf) {
+        return `${timestampKey(asOf)}!`;
+    },
+    /**
+     * Builds materialized invocation columns under one fixed-width provider digest.
+     *
+     * @param digest Physical identity digest of the full logical key.
+     * @returns Shared native record specification.
+     */
+    invocationSpec(digest) {
+        return new RecordSpec({
+            sourceType: AgentExecutionRecordSchema,
+            recordType: AgentExecutionRecordSchema,
+            idKind: "string",
+            extractId: (record) => digest(this.invocation(requiredInvocation(record))),
+            columns: [
+                new RecordColumn("state_type", string, (record) => requiredInvocation(record).scope.stateType),
+                new RecordColumn("agent_key", string, (record) => requiredInvocation(record).scope.agentKey),
+                new RecordColumn("scope_digest", string, (record) => digest(this.scope(requiredInvocation(record).scope))),
+                new RecordColumn("status", string, (record) => String(record.status)),
+                new RecordColumn("order_key", string, (record) => this.order(requiredOrder(record))),
+            ],
+        });
+    },
+    /**
+     * Builds materialized current-head columns under one provider digest.
+     *
+     * @param digest Physical identity digest of the full Agent scope.
+     * @returns Shared native head specification.
+     */
+    headSpec(digest) {
+        return new RecordSpec({
+            sourceType: AgentExecutionHeadSchema,
+            recordType: AgentExecutionHeadSchema,
+            idKind: "string",
+            extractId: (record) => digest(this.scope(requiredScope(record))),
+            columns: [
+                new RecordColumn("state_type", string, (record) => requiredScope(record).stateType),
+                new RecordColumn("agent_key", string, (record) => requiredScope(record).agentKey),
+                new RecordColumn("scope_digest", string, (record) => digest(this.scope(requiredScope(record)))),
+                new RecordColumn("state_digest", string, (record) => digest(requiredScope(record).stateType)),
+                new RecordColumn("pending_key", string, (record) => headPendingKey(record, this)),
+            ],
+        });
+    },
+};
+/**
+ * Reads the immutable accepted invocation identity from a record.
+ */
+function requiredInvocation(record) {
+    const key = record.accepted?.key;
+    if (key?.scope === undefined || key.sourceSignal === undefined)
+        throw new TypeError("Agent execution record requires its original invocation key.");
+    return key;
+}
+/**
+ * Reads the original Inbox order from a record.
+ */
+function requiredOrder(record) {
+    const order = record.accepted?.order;
+    if (order === undefined)
+        throw new TypeError("Agent execution record requires Inbox order.");
+    return order;
+}
+/**
+ * Reads the complete Agent instance scope from a head.
+ */
+function requiredScope(head) {
+    if (head.scope === undefined)
+        throw new TypeError("Agent execution head requires its scope.");
+    return head.scope;
+}
+/**
+ * Encodes an optional lease expiry for native index eligibility.
+ */
+function timestampKey(value) {
+    if (value.seconds < -62135596800n ||
+        value.seconds > 253402300799n ||
+        value.nanos < 0 ||
+        value.nanos > 999_999_999)
+        throw new RangeError("Agent execution Timestamp is out of range.");
+    return `${(value.seconds + 62135596800n).toString().padStart(12, "0")}:${value.nanos.toString().padStart(9, "0")}`;
+}
+/**
+ * Materializes the head candidate or a value beyond every valid Timestamp.
+ */
+function headPendingKey(head, layout) {
+    const present = [head.pending, head.pendingOrder, head.eligibleAt].filter((value) => value !== undefined).length;
+    if (present === 0)
+        return "~";
+    if (present !== 3 || head.eligibleAt === undefined)
+        throw new TypeError("Agent execution head has incomplete discovery metadata.");
+    return layout.pendingKey(head.eligibleAt, requiredScope(head));
+}
+/**
+ * Encodes every UTF-8 byte without locale-dependent collation.
+ */
+function utf8Hex(value) {
+    const encoder = new globalThis.TextEncoder();
+    return [...encoder.encode(value)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=agent-execution-record-spec.js.map

package/dist/entity/agent-execution-record-spec.js.map

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

package/dist/entity/agent-execution-sizes.d.ts

@@ -0,0 +1,30 @@
+import type { AgentHistoryEntry } from "@spine-event-engine/proto/agent";
+import { type AgentExecutionHead, type AgentExecutionRecord, type AgentExecutionScope } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+/**
+ * Calculates complete internal Protobuf row sizes before an external Agent call.
+ */
+export declare const AgentExecutionSizes: {
+    /**
+     * Calculates the retained execution journal and accepted source facts.
+     *
+     * @param record Complete execution record proposed for persistence.
+     * @returns Exact serialized execution-record bytes.
+     */
+    record(record: AgentExecutionRecord): number;
+    /**
+     * Calculates per-instance claim, eligibility and preferences.
+     *
+     * @param head Complete head proposed for persistence.
+     * @returns Exact serialized head bytes.
+     */
+    head(head: AgentExecutionHead): number;
+    /**
+     * Calculates a history entry inside its persisted scope envelope.
+     *
+     * @param scope Generated state type and canonical Agent key.
+     * @param entry Original conversation, System or domain entry.
+     * @returns Exact serialized internal history-record bytes.
+     */
+    history(scope: AgentExecutionScope, entry: AgentHistoryEntry): number;
+};
+//# sourceMappingURL=agent-execution-sizes.d.ts.map

package/dist/entity/agent-execution-sizes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-sizes.d.ts","sourceRoot":"","sources":["../../src/entity/agent-execution-sizes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,+EAA+E,CAAC;AAKvF;;GAEG;AACH,eAAO,MAAM,mBAAmB;IAC9B;;;;;OAKG;mBACY,oBAAoB,GAAG,MAAM;IAI5C;;;;;OAKG;eACQ,kBAAkB,GAAG,MAAM;IAItC;;;;;;OAMG;mBACY,mBAAmB,SAAS,iBAAiB,GAAG,MAAM;CAMtE,CAAC"}

package/dist/entity/agent-execution-sizes.js

@@ -0,0 +1,51 @@
+/*
+ * 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 { toBinary } from "@bufbuild/protobuf";
+import { AgentExecutionHeadSchema, AgentExecutionRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { AgentHistoryRecordSchema } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
+import { AgentHistoryRecords } from "./agent-history-record-spec.js";
+/**
+ * Calculates complete internal Protobuf row sizes before an external Agent call.
+ */
+export const AgentExecutionSizes = {
+    /**
+     * Calculates the retained execution journal and accepted source facts.
+     *
+     * @param record Complete execution record proposed for persistence.
+     * @returns Exact serialized execution-record bytes.
+     */
+    record(record) {
+        return toBinary(AgentExecutionRecordSchema, record).length;
+    },
+    /**
+     * Calculates per-instance claim, eligibility and preferences.
+     *
+     * @param head Complete head proposed for persistence.
+     * @returns Exact serialized head bytes.
+     */
+    head(head) {
+        return toBinary(AgentExecutionHeadSchema, head).length;
+    },
+    /**
+     * Calculates a history entry inside its persisted scope envelope.
+     *
+     * @param scope Generated state type and canonical Agent key.
+     * @param entry Original conversation, System or domain entry.
+     * @returns Exact serialized internal history-record bytes.
+     */
+    history(scope, entry) {
+        return toBinary(AgentHistoryRecordSchema, AgentHistoryRecords.record(scope.stateType, scope.agentKey, entry)).length;
+    },
+};
+//# sourceMappingURL=agent-execution-sizes.js.map

package/dist/entity/agent-execution-sizes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-sizes.js","sourceRoot":"","sources":["../../src/entity/agent-execution-sizes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EACL,wBAAwB,EACxB,0BAA0B,GAI3B,MAAM,+EAA+E,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6EAA6E,CAAC;AAEvH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;;;;;OAKG;IACH,MAAM,CAAC,MAA4B;QACjC,OAAO,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;IAC7D,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,IAAwB;QAC3B,OAAO,QAAQ,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC;IACzD,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,KAA0B,EAAE,KAAwB;QAC1D,OAAO,QAAQ,CACb,wBAAwB,EACxB,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CACnE,CAAC,MAAM,CAAC;IACX,CAAC;CACF,CAAC"}