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

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

@@ -0,0 +1,79 @@
+import { type AgentHistoryEntry } from "@spine-event-engine/proto/agent";
+import { type AgentHistoryRecord } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
+import { RecordColumn } from "../record/record-column.js";
+import { RecordSpec } from "../record/record-spec.js";
+import { StorageGroup } from "../record/storage-group.js";
+/**
+ * Describes materialization of original Agent history records and indexed columns.
+ */
+interface AgentHistoryRecordLayout {
+    /**
+     * Identifies the physical family shared within one tenant.
+     */
+    readonly group: StorageGroup;
+    /**
+     * Builds the complete internal envelope.
+     *
+     * @param stateType Generated Agent state type name.
+     * @param agentKey Canonical typed identifier key.
+     * @param entry Complete original history entry.
+     * @returns Internal storage envelope.
+     */
+    record(stateType: string, agentKey: string, entry: AgentHistoryEntry): AgentHistoryRecord;
+    /**
+     * Encodes the immutable logical record identity.
+     *
+     * @param record Internal history envelope.
+     * @returns Complete logical identity.
+     */
+    slot(record: AgentHistoryRecord): string;
+    /**
+     * Encodes the complete Agent repository scope.
+     *
+     * @param stateType Generated Agent state type name.
+     * @param agentKey Canonical typed identifier key.
+     * @returns Complete logical scope.
+     */
+    scope(stateType: string, agentKey: string): string;
+    /**
+     * Builds provider columns with a fixed-width physical digest.
+     *
+     * @param digest Provider digest of a complete logical identity.
+     * @returns Shared native record specification.
+     */
+    spec(digest: (value: string) => string): RecordSpec<string, AgentHistoryRecord>;
+    /**
+     * Reads the validated repository scope from an envelope.
+     *
+     * @param record Internal history envelope.
+     * @returns Complete original scope.
+     */
+    requiredScope(record: AgentHistoryRecord): NonNullable<AgentHistoryRecord["scope"]>;
+    /**
+     * Reads the original history entry from an envelope.
+     *
+     * @param record Internal history envelope.
+     * @returns Complete original history entry.
+     */
+    requiredEntry(record: AgentHistoryRecord): AgentHistoryEntry;
+    /**
+     * Builds the materialized repository scope columns.
+     *
+     * @param digest Provider digest of a complete logical identity.
+     * @returns Complete scope columns.
+     */
+    scopeColumns(digest: (value: string) => string): RecordColumn<AgentHistoryRecord>[];
+    /**
+     * Builds the materialized order and conversation columns.
+     *
+     * @param digest Provider digest of a complete logical identity.
+     * @returns Complete order and conversation columns.
+     */
+    orderColumns(digest: (value: string) => string): RecordColumn<AgentHistoryRecord>[];
+}
+/**
+ * Internal record layout for one tenant's shared Agent history family.
+ */
+export declare const AgentHistoryRecords: AgentHistoryRecordLayout;
+export {};
+//# sourceMappingURL=agent-history-record-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-history-record-spec.d.ts","sourceRoot":"","sources":["../../src/entity/agent-history-record-spec.ts"],"names":[],"mappings":"AAeA,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,6EAA6E,CAAC;AAErF,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAQ1D;;GAEG;AACH,UAAU,wBAAwB;IAChC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAAC;IAE1F;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAEzC;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnD;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAEhF;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,WAAW,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpF;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,iBAAiB,CAAC;IAE7D;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,YAAY,CAAC,kBAAkB,CAAC,EAAE,CAAC;IAEpF;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,YAAY,CAAC,kBAAkB,CAAC,EAAE,CAAC;CACrF;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,wBAsJjC,CAAC"}

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

@@ -0,0 +1,147 @@
+/*
+ * 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 { create, ScalarType } from "@bufbuild/protobuf";
+import { AgentHistoryEntrySchema } from "@spine-event-engine/proto/agent";
+import { AgentHistoryRecordSchema, AgentHistoryStorageKeySchema as AgentStorageKeySchema, } from "@spine-event-engine/proto/generated/spine/server/agent/history_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";
+import { AgentHistoryKeys } from "./agent-history.js";
+/**
+ * Physical family shared by Agent state types within one tenant.
+ */
+const agentHistoryGroup = new StorageGroup("agent_history");
+/**
+ * Internal record layout for one tenant's shared Agent history family.
+ */
+export const AgentHistoryRecords = {
+    /**
+     * Physical family shared by Agent state types within one tenant.
+     */
+    group: agentHistoryGroup,
+    /**
+     * Stores one original entry with its canonical repository scope.
+     *
+     * @param stateType Generated Agent state type name.
+     * @param agentKey Canonical typed identifier key.
+     * @param entry Complete original history entry.
+     * @returns Internal storage envelope.
+     */
+    record(stateType, agentKey, entry) {
+        if (stateType.length === 0 || agentKey.length === 0)
+            throw new TypeError("Agent history requires state type and Agent key.");
+        AgentHistoryKeys.fromEntry(entry);
+        return create(AgentHistoryRecordSchema, {
+            scope: create(AgentStorageKeySchema, { stateType, agentKey }),
+            entry,
+        });
+    },
+    /**
+     * Builds the full logical identity hashed into a provider physical ID.
+     *
+     * @param record Internal history envelope.
+     * @returns Unambiguous identity without an ordering position.
+     */
+    slot(record) {
+        const scope = AgentHistoryRecords.requiredScope(record);
+        const key = AgentHistoryKeys.fromEntry(AgentHistoryRecords.requiredEntry(record));
+        return JSON.stringify([scope.stateType, scope.agentKey, key.category, key.recordId]);
+    },
+    /**
+     * Encodes the complete repository scope before provider hashing.
+     *
+     * @param stateType Generated Agent state type.
+     * @param agentKey Canonical typed Agent key.
+     * @returns Unambiguous complete scope identity.
+     */
+    scope(stateType, agentKey) {
+        return JSON.stringify([stateType, agentKey]);
+    },
+    /**
+     * Builds materialized columns with one provider's bounded physical digest.
+     *
+     * @param digest Maps a complete identity to a fixed-width digest.
+     * @returns Shared record specification for native providers.
+     */
+    spec(digest) {
+        return new RecordSpec({
+            sourceType: AgentHistoryEntrySchema,
+            recordType: AgentHistoryRecordSchema,
+            idKind: "string",
+            extractId: (record) => digest(AgentHistoryRecords.slot(record)),
+            columns: [
+                ...AgentHistoryRecords.scopeColumns(digest),
+                ...AgentHistoryRecords.orderColumns(digest),
+            ],
+        });
+    },
+    /**
+     * Reads the repository scope required by every stored history entry.
+     *
+     * @param record Stored history envelope.
+     * @returns Complete original scope.
+     */
+    requiredScope(record) {
+        if (record.scope === undefined ||
+            record.scope.stateType.length === 0 ||
+            record.scope.agentKey.length === 0)
+            throw new TypeError("Agent history record requires a complete repository scope.");
+        return record.scope;
+    },
+    /**
+     * Reads the original history entry required by the storage envelope.
+     *
+     * @param record Stored history envelope.
+     * @returns Complete original history entry.
+     */
+    requiredEntry(record) {
+        if (record.entry === undefined)
+            throw new TypeError("Agent history record requires an entry.");
+        return record.entry;
+    },
+    /**
+     * Builds complete scope columns and their bounded indexed digest.
+     *
+     * @param digest Provider physical-identity digest.
+     * @returns Native scope columns.
+     */
+    scopeColumns(digest) {
+        const string = ColumnTypes.scalar(ScalarType.STRING);
+        return [
+            new RecordColumn("state_type", string, (record) => AgentHistoryRecords.requiredScope(record).stateType),
+            new RecordColumn("agent_key", string, (record) => AgentHistoryRecords.requiredScope(record).agentKey),
+            new RecordColumn("scope_digest", string, (record) => digest(AgentHistoryRecords.scope(AgentHistoryRecords.requiredScope(record).stateType, AgentHistoryRecords.requiredScope(record).agentKey))),
+        ];
+    },
+    /**
+     * Builds complete order and conversation selector columns.
+     *
+     * @param digest Provider physical-identity digest.
+     * @returns Native order and conversation columns.
+     */
+    orderColumns(digest) {
+        const string = ColumnTypes.scalar(ScalarType.STRING);
+        const conversation = (record) => record.entry?.item.case === "conversationRecord"
+            ? (record.entry.item.value.conversation?.value ?? "")
+            : "";
+        return [
+            new RecordColumn("category", string, (record) => AgentHistoryKeys.fromEntry(AgentHistoryRecords.requiredEntry(record)).category),
+            new RecordColumn("conversation_key", string, conversation),
+            new RecordColumn("conversation_digest", string, (record) => digest(conversation(record))),
+            new RecordColumn("order_key", string, (record) => AgentHistoryKeys.indexValue(AgentHistoryKeys.fromEntry(AgentHistoryRecords.requiredEntry(record)))),
+        ];
+    },
+};
+//# sourceMappingURL=agent-history-record-spec.js.map

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

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

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

@@ -0,0 +1,196 @@
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { AgentHistoryEntry, ConversationId } from "@spine-event-engine/proto/agent";
+import type { StorageContext } from "../storage/storage.js";
+/**
+ * Converts a typed Agent identifier to its canonical storage key.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+interface AgentHistoryIdCodec<Id> {
+    /**
+     * Maps one typed Agent identifier to its canonical key.
+     *
+     * @param id Typed Agent identifier.
+     * @returns Canonical key within the repository scope.
+     */
+    readonly key: (id: Id) => string;
+}
+/**
+ * Identifies one existing record in the Agent history order.
+ */
+export interface AgentHistoryOrderKey {
+    /**
+     * Original occurrence timestamp, with full seconds and nanoseconds.
+     */
+    readonly occurredAt: Timestamp;
+    /**
+     * Selects the category tie-break after equal timestamps.
+     */
+    readonly category: "conversation" | "system" | "domain";
+    /**
+     * Immutable record or Event ID.
+     */
+    readonly recordId: string;
+}
+/**
+ * Selects one indexed view of the Agent's append-only history.
+ */
+export type AgentHistoryView = AgentHistoryFullView | AgentHistoryConversationView | AgentHistorySystemView | AgentHistoryDomainView;
+/**
+ * Selects every recorded category.
+ */
+interface AgentHistoryFullView {
+    /**
+     * Identifies the full view.
+     */
+    readonly kind: "full";
+}
+/**
+ * Selects records of one conversation.
+ */
+interface AgentHistoryConversationView {
+    /**
+     * Identifies the conversation view.
+     */
+    readonly kind: "conversation";
+    /**
+     * Existing conversation identifier.
+     */
+    readonly conversation: ConversationId;
+}
+/**
+ * Selects recorded Agent System Events.
+ */
+interface AgentHistorySystemView {
+    /**
+     * Identifies the System view.
+     */
+    readonly kind: "system";
+}
+/**
+ * Selects recorded Agent domain Events.
+ */
+interface AgentHistoryDomainView {
+    /**
+     * Identifies the domain view.
+     */
+    readonly kind: "domain";
+}
+/**
+ * Identifies a repository and its complete tenant boundary for Agent history.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export interface AgentHistoryStorageInput<Id> {
+    /**
+     * Bounded Context and complete tenant selection.
+     */
+    readonly context: StorageContext;
+    /**
+     * Generated Agent state type name.
+     */
+    readonly stateType: string;
+    /**
+     * Canonical typed Entity ID conversion supplied by the repository.
+     */
+    readonly id: AgentHistoryIdCodec<Id>;
+}
+/**
+ * Selects a bounded provider page after an optional complete ordering key.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export interface AgentHistoryRead<Id> {
+    /**
+     * Typed Agent identifier in the configured repository scope.
+     */
+    readonly entityId: Id;
+    /**
+     * Full, conversation, System, or domain index.
+     */
+    readonly view: AgentHistoryView;
+    /**
+     * Last returned key from the preceding page, when continuing.
+     */
+    readonly after?: AgentHistoryOrderKey;
+    /**
+     * Maximum number of entries to return; any positive safe integer is allowed.
+     */
+    readonly count: number;
+    /**
+     * Optional maximum sum of serialized AgentHistoryEntry byte lengths.
+     */
+    readonly maxBytes?: number;
+}
+/**
+ * Returns one bounded page and indicates whether older entries remain.
+ */
+export interface AgentHistoryPage {
+    /**
+     * Independent copies of complete Proto history entries.
+     */
+    readonly entries: readonly AgentHistoryEntry[];
+    /**
+     * True when another entry follows this page in the selected view.
+     */
+    readonly hasMore: boolean;
+}
+/**
+ * Provider handle for one repository state type and tenant boundary.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export interface AgentHistoryStorage<Id> {
+    /**
+     * Adds one immutable occurrence, or accepts an identical repeated append.
+     *
+     * @param entityId Typed Agent identifier.
+     * @param entry Complete conversation, System, or domain entry.
+     * @returns Resolves after the occurrence is recorded.
+     */
+    append(entityId: Id, entry: AgentHistoryEntry): Promise<void>;
+    /**
+     * Reads a bounded live continuation from one indexed view.
+     *
+     * @param request Scope, view, complete-key boundary, and response bounds.
+     * @returns Independent entries and whether older results remain.
+     */
+    read(request: AgentHistoryRead<Id>): Promise<AgentHistoryPage>;
+    /**
+     * Closes this handle without deleting any recorded history.
+     */
+    close(): void;
+}
+/**
+ * Operations on the complete, provider-independent ordering key.
+ */
+export interface AgentHistoryKeyOperations {
+    /**
+     * Reads the original ordering key from a history entry.
+     *
+     * @param entry Complete history entry.
+     * @returns Original complete ordering key.
+     */
+    fromEntry(entry: AgentHistoryEntry): AgentHistoryOrderKey;
+    /**
+     * Encodes a key for binary-collated provider indexes.
+     *
+     * @param key Original complete ordering key.
+     * @returns Prefix-safe sortable index value.
+     */
+    indexValue(key: AgentHistoryOrderKey): string;
+    /**
+     * Compares two keys in newest-first order.
+     *
+     * @param left First complete key.
+     * @param right Second complete key.
+     * @returns Negative, zero, or positive comparison.
+     */
+    compare(left: AgentHistoryOrderKey, right: AgentHistoryOrderKey): number;
+}
+/**
+ * Builds and compares the provider-independent complete Agent history key.
+ */
+export declare const AgentHistoryKeys: AgentHistoryKeyOperations;
+export {};
+//# sourceMappingURL=agent-history.d.ts.map

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

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

package/dist/entity/agent-history.js

@@ -0,0 +1,136 @@
+/*
+ * 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.
+ */
+const minSeconds = -62135596800n;
+const maxSeconds = 253402300799n;
+const categoryRank = {
+    conversation: "0",
+    system: "1",
+    domain: "2",
+};
+/**
+ * Builds and compares the provider-independent complete Agent history key.
+ */
+export const AgentHistoryKeys = Object.freeze({
+    /**
+     * Validates enclosed time and identity while reading the complete key.
+     *
+     * @param entry Recorded Proto oneof.
+     * @returns Complete key after validating the enclosed occurrence time.
+     */
+    fromEntry(entry) {
+        const occurredAt = entry.occurredAt;
+        const item = entry.item;
+        if (occurredAt === undefined || item.case === undefined)
+            throw new TypeError("Agent history requires an occurrence time and one item.");
+        if (item.case === "conversationRecord") {
+            const record = item.value;
+            if (record.conversation?.value === undefined || record.conversation.value.length === 0)
+                throw new TypeError("Conversation history requires a ConversationId.");
+            HistoryValidation.sameTime(occurredAt, record.occurredAt);
+            return { occurredAt, category: "conversation", recordId: record.id?.value ?? "" };
+        }
+        const event = item.value;
+        HistoryValidation.sameTime(occurredAt, event.context?.timestamp);
+        return {
+            occurredAt,
+            category: item.case === "systemEvent" ? "system" : "domain",
+            recordId: event.id?.value ?? "",
+        };
+    },
+    /**
+     * Encodes the full key for binary-collated SQL and Datastore range indexes.
+     *
+     * @param key Original complete history key.
+     * @returns Fixed-width reverse time, category rank, and prefix-safe UTF-8 hex ID.
+     */
+    indexValue(key) {
+        HistoryValidation.timestamp(key.occurredAt);
+        if (key.recordId.length === 0)
+            throw new TypeError("Agent history record ID is required.");
+        const seconds = (maxSeconds - key.occurredAt.seconds).toString().padStart(12, "0");
+        const nanos = (999999999 - key.occurredAt.nanos).toString().padStart(9, "0");
+        const rank = categoryRank[key.category];
+        if (rank === undefined)
+            throw new TypeError("Agent history category is required.");
+        const id = Utf8Ids.hex(key.recordId);
+        return `${seconds}${nanos}${rank}${id}!`;
+    },
+    /**
+     * Compares complete keys in newest-first Agent history order.
+     *
+     * @param left First complete key.
+     * @param right Second complete key.
+     * @returns Negative, zero, or positive key comparison.
+     */
+    compare(left, right) {
+        const first = this.indexValue(left);
+        const second = this.indexValue(right);
+        return first < second ? -1 : first > second ? 1 : 0;
+    },
+});
+/**
+ * Encodes valid Unicode IDs as unsigned UTF-8 byte hex for prefix-safe keys.
+ */
+const Utf8Ids = Object.freeze({
+    /**
+     * Encodes an identifier without locale collation or platform byte APIs.
+     *
+     * @param value Existing immutable record ID.
+     * @returns Lowercase two-digit hex for every UTF-8 byte.
+     */
+    hex(value) {
+        const encoded = encodeURIComponent(value);
+        let result = "";
+        for (let index = 0; index < encoded.length; index += 1) {
+            if (encoded[index] === "%") {
+                result += encoded.slice(index + 1, index + 3).toLowerCase();
+                index += 2;
+            }
+            else {
+                result += encoded.charCodeAt(index).toString(16).padStart(2, "0");
+            }
+        }
+        return result;
+    },
+});
+/**
+ * Validates original occurrence times before indexing.
+ */
+const HistoryValidation = Object.freeze({
+    /**
+     * Verifies an enclosed occurrence time.
+     *
+     * @param wrapper History wrapper occurrence time.
+     * @param enclosed Enclosed record or Event occurrence time.
+     */
+    sameTime(wrapper, enclosed) {
+        this.timestamp(wrapper);
+        if (wrapper.seconds !== enclosed?.seconds || wrapper.nanos !== enclosed.nanos)
+            throw new TypeError("Agent history wrapper time must equal its recorded occurrence time.");
+    },
+    /**
+     * Checks the complete Protobuf Timestamp range.
+     *
+     * @param value Original occurrence time.
+     */
+    timestamp(value) {
+        if (typeof value.seconds !== "bigint" ||
+            value.seconds < minSeconds ||
+            value.seconds > maxSeconds)
+            throw new RangeError("Agent history timestamp seconds are outside the Protobuf range.");
+        if (!Number.isInteger(value.nanos) || value.nanos < 0 || value.nanos > 999999999)
+            throw new RangeError("Agent history timestamp nanoseconds are outside the Protobuf range.");
+    },
+});
+//# sourceMappingURL=agent-history.js.map

package/dist/entity/agent-history.js.map

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