@arnilo/prism 0.0.23 → 0.0.25

package/dist/testing/agent-event-source-conformance.js

@@ -0,0 +1,54 @@
+// ponytail: runner-free durable-event contract probe for database adapters.
+/** Assert durable append/page/replay ownership and cursor behavior without a database dependency. */
+export async function assertAgentEventSourceConforms(factory) {
+    const source = await factory();
+    const ownership = { tenantId: "tenant-a", accountId: "account-a", userId: "user-a" };
+    const input = { ownership, sessionId: "session-a", runId: "run-a" };
+    const first = event("event-a", "agent_started", input);
+    const second = event("event-b", "turn_started", input, "2026-01-01T00:00:01.000Z");
+    const storedFirst = await source.append(first);
+    const storedSecond = await source.append(second);
+    equal(storedFirst.sequence, 1, "first durable event must receive sequence 1");
+    equal(storedSecond.sequence, 2, "durable sequence must increase per run");
+    equal((await source.append(first)).sequence, 1, "identical duplicate append must be idempotent");
+    await rejects(() => source.append({ ...first, timestamp: "2026-01-01T00:00:02.000Z" }), "changed duplicate append must fail");
+    const page = await source.page({ ...input, limit: 1 });
+    equal(page.items.length, 1, "page limit must be honored");
+    equal(page.items[0].record.id, first.id, "page order must follow sequence");
+    if (!page.nextCursor)
+        throw new Error("truncated page must include a cursor");
+    const secondPage = await source.page({ ...input, after: page.nextCursor, limit: 1 });
+    equal(secondPage.items[0]?.record.id, second.id, "cursor must be exclusive");
+    const iterator = source.subscribe({ ...input, after: secondPage.items[0].cursor })[Symbol.asyncIterator]();
+    const pending = iterator.next();
+    const third = await source.append(event("event-c", "turn_started", input, "2026-01-01T00:00:02.000Z"));
+    equal((await pending).value?.record.id, third.id, "replay/live handoff dropped an event");
+    await iterator.return?.();
+    const terminal = await source.append(event("event-d", "agent_finished", input, "2026-01-01T00:00:03.000Z"));
+    const final = await source.page({ ...input, after: secondPage.items[0].cursor, limit: 10 });
+    equal(final.items.at(-1)?.record.id, terminal.id, "terminal page must include its terminal event");
+    equal(final.terminal, true, "terminal event must close only after prior events are delivered");
+    await rejects(() => source.page({ ...input, ownership: { ...ownership, tenantId: "tenant-b" }, after: page.nextCursor }), "foreign cursor must fail closed");
+    await rejects(() => source.append({ ...event("event-unredacted", "turn_started", input), redacted: false }), "unredacted append must fail");
+    await rejects(() => source.page({ ...input, limit: 0 }), "invalid page limit must fail");
+}
+function event(id, type, input, timestamp = "2026-01-01T00:00:00.000Z") {
+    const event = type === "turn_started"
+        ? { type, sessionId: input.sessionId, runId: input.runId, turn: 1 }
+        : { type, sessionId: input.sessionId, runId: input.runId };
+    return { id, ...input.ownership, sessionId: input.sessionId, runId: input.runId, type, timestamp, event, redacted: true };
+}
+function equal(actual, expected, message) {
+    if (actual !== expected)
+        throw new Error(`${message}; expected ${String(expected)}, received ${String(actual)}`);
+}
+async function rejects(action, message) {
+    try {
+        await action();
+    }
+    catch {
+        return;
+    }
+    throw new Error(message);
+}
+//# sourceMappingURL=agent-event-source-conformance.js.map

package/dist/testing/persistence-schema.d.ts

@@ -1,7 +1,7 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 5;
-export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
+export declare const PERSISTENCE_SCHEMA_VERSION = 7;
+export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_agent_event_streams" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {
     readonly name: string;

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 5;
+export const PERSISTENCE_SCHEMA_VERSION = 7;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -177,6 +177,17 @@ export function createPersistenceSchemaModel() {
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
+            {
+                name: "prism_agent_event_streams",
+                primaryKey: ["session_id", "run_id"],
+                columns: [
+                    { name: "session_id", type: "text" },
+                    { name: "run_id", type: "text" },
+                    { name: "next_sequence", type: "integer" },
+                    { name: "updated_at", type: "timestamp" },
+                ],
+                foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
+            },
             {
                 name: "prism_tool_calls",
                 primaryKey: ["id"],
@@ -369,6 +380,7 @@ export function createPersistenceSchemaModel() {
                 name: "prism_agent_events_run_sequence_idx",
                 table: "prism_agent_events",
                 columns: ["run_id", "sequence"],
+                unique: true,
                 purpose: "stable per-run event timeline pagination",
             },
             {
@@ -377,6 +389,12 @@ export function createPersistenceSchemaModel() {
                 columns: ["session_id", "timestamp", "id"],
                 purpose: "event stream pagination",
             },
+            {
+                name: "prism_agent_events_owner_timestamp_sequence_idx",
+                table: "prism_agent_events",
+                columns: ["tenant_id", "account_id", "user_id", "timestamp", "sequence", "id"],
+                purpose: "owned durable event retention cleanup",
+            },
             {
                 name: "prism_tool_calls_session_name_started_idx",
                 table: "prism_tool_calls",
@@ -463,34 +481,51 @@ function migrationStep(version, name, description) {
     const content = version === 1
         ? {
             tables: model.tables
-                .filter((table) => table.name !== "prism_run_feedback")
+                .filter((table) => table.name !== "prism_run_feedback" && table.name !== "prism_agent_event_streams")
                 .map((table) => table.name === "prism_usage"
                 ? { ...table, columns: table.columns.filter((column) => !["scope", "turn", "attempt"].includes(column.name)) }
                 : table),
-            indexes: model.indexes.filter((index) => !index.name.startsWith("prism_usage_session_scope_") && !index.name.startsWith("prism_run_feedback_")),
+            indexes: model.indexes
+                .filter((index) => !index.name.startsWith("prism_usage_session_scope_") &&
+                !index.name.startsWith("prism_run_feedback_") &&
+                !index.name.startsWith("prism_agent_event_streams_") &&
+                !index.name.startsWith("prism_agent_events_owner_timestamp_"))
+                .map((index) => index.name === "prism_agent_events_run_sequence_idx"
+                ? (() => {
+                    const { unique: _unique, ...legacy } = index;
+                    return legacy;
+                })()
+                : index),
         }
-        : version === 2
-            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-            : version === 3
+        : version === 7
+            ? { indexes: ["prism_agent_events_owner_timestamp_sequence_idx"] }
+            : version === 6
                 ? {
-                    tables: ["prism_run_feedback"],
-                    indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
+                    tables: ["prism_agent_event_streams"],
+                    indexes: ["prism_agent_events_run_sequence_idx"],
                 }
-                : version === 4
-                    ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
-                        { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
-                    : version === 5
+                : version === 2
+                    ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+                    : version === 3
                         ? {
-                            tables: ["prism_legal_holds", "prism_tenant_quotas"],
-                            indexes: [
-                                "prism_legal_holds_owner_resource_idx",
-                                "prism_legal_holds_created_id_idx",
-                                "prism_tenant_quotas_owner_kind_idx",
-                            ],
+                            tables: ["prism_run_feedback"],
+                            indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
                         }
-                        : (() => {
-                            throw new Error(`Unknown migration version ${version}`);
-                        })();
+                        : version === 4
+                            ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                                { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                            : version === 5
+                                ? {
+                                    tables: ["prism_legal_holds", "prism_tenant_quotas"],
+                                    indexes: [
+                                        "prism_legal_holds_owner_resource_idx",
+                                        "prism_legal_holds_created_id_idx",
+                                        "prism_tenant_quotas_owner_kind_idx",
+                                    ],
+                                }
+                                : (() => {
+                                    throw new Error(`Unknown migration version ${version}`);
+                                })();
     return {
         version,
         name,
@@ -509,6 +544,8 @@ export function createPersistenceMigrationContract() {
             migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
             migrationStep(4, "004_session_search", "Add bounded session search indexes and adapter-local FTS objects."),
             migrationStep(5, "005_lifecycle_hold_quota", "Add legal-hold and tenant-quota tables for retention lifecycle."),
+            migrationStep(6, "006_agent_event_source", "Add transactional per-run event counters and unique durable event sequencing."),
+            migrationStep(7, "007_agent_event_retention_index", "Add an exact-owner durable-event retention cleanup index."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/tool-effect-store-conformance.d.ts

@@ -0,0 +1,9 @@
+import type { AgentIdentity, ToolEffectKey, ToolEffectStore } from "../contracts.js";
+export interface ToolEffectStoreConformanceOptions {
+    readonly identity?: AgentIdentity;
+    readonly ownership?: ToolEffectKey["ownership"];
+    readonly key?: string;
+}
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export declare function assertToolEffectStoreConforms(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;
+export declare function runToolEffectStoreConformance(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;

package/dist/testing/tool-effect-store-conformance.js

@@ -0,0 +1,85 @@
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export async function assertToolEffectStoreConforms(factory, options = {}) {
+    const store = await factory();
+    const identity = options.identity ?? testIdentity();
+    const ownership = options.ownership ?? { tenantId: identity.tenantId };
+    const base = key(identity, ownership, options.key ?? "prism:tool-effect:v1:conformance");
+    const first = await store.begin(base);
+    if (first.outcome !== "acquired" || first.record.status !== "pending" || !first.record.claimToken) {
+        throw new Error("store must acquire an absent tool effect as pending with a claim token");
+    }
+    const duplicate = await store.begin(base);
+    if (duplicate.outcome !== "existing" || duplicate.record.status !== "pending") {
+        throw new Error("store must return existing pending effects without a second claim");
+    }
+    const dispatched = await store.markDispatched(transition(base, first.record));
+    if (dispatched.status !== "dispatched" || dispatched.version !== first.record.version + 1) {
+        throw new Error("store must transition a claimed pending effect to dispatched");
+    }
+    const result = { toolCallId: base.toolCallId, name: base.toolName, value: { ok: true } };
+    const completed = await store.complete({ ...transition(base, dispatched), result });
+    if (completed.status !== "completed" || completed.result?.toolCallId !== base.toolCallId) {
+        throw new Error("store must retain a completed bounded result");
+    }
+    const replay = await store.begin(base);
+    if (replay.outcome !== "existing" || replay.record.status !== "completed") {
+        throw new Error("store must preserve completed duplicate state");
+    }
+    await expectReject(() => store.markDispatched(transition(base, dispatched)), "store must reject stale claim/version transitions");
+    const unknownKey = key(identity, ownership, `${base.key}:unknown`, "call-unknown");
+    const unknownPending = await store.begin(unknownKey);
+    const unknownDispatched = await store.markDispatched(transition(unknownKey, unknownPending.record));
+    const unknown = await store.markUnknown({ ...transition(unknownKey, unknownDispatched), failure: { code: "test" } });
+    if (unknown.status !== "unknown")
+        throw new Error("store must mark dispatched effects unknown");
+    const resolved = await store.resolveUnknown({
+        ...unknownKey,
+        expectedVersion: unknown.version,
+        status: "failed_terminal",
+        failure: { code: "test" },
+    });
+    if (resolved.status !== "failed_terminal")
+        throw new Error("store must CAS-resolve unknown effects");
+    const cleanup = await store.cleanup({ ownership, before: new Date(Date.now() + 60_000).toISOString(), limit: 100 });
+    if (cleanup.deleted < 1)
+        throw new Error("store cleanup must remove terminal effects");
+}
+export async function runToolEffectStoreConformance(factory, options = {}) {
+    await assertToolEffectStoreConforms(factory, options);
+}
+function key(identity, ownership, value, toolCallId = "call") {
+    return {
+        identity,
+        ownership,
+        key: value,
+        sessionId: "session",
+        runId: "run",
+        toolCallId,
+        toolName: "effect.tool",
+        argumentsHash: "a".repeat(64),
+    };
+}
+function transition(base, record) {
+    if (!record.claimToken)
+        throw new Error("store transition record lacks claim token");
+    return { ...base, claimToken: record.claimToken, expectedVersion: record.version };
+}
+async function expectReject(run, message) {
+    try {
+        await run();
+    }
+    catch {
+        return;
+    }
+    throw new Error(message);
+}
+function testIdentity() {
+    return {
+        tenantId: "tenant",
+        principal: { kind: "service", id: "conformance" },
+        scopes: ["tools:execute"],
+        issuedAt: "2026-01-01T00:00:00.000Z",
+        verified: true,
+    };
+}
+//# sourceMappingURL=tool-effect-store-conformance.js.map

package/dist/tool-effects.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObject, ToolEffectKey, ToolEffectStore } from "./contracts.js";
+export type ToolEffectErrorCode = "ERR_PRISM_TOOL_EFFECT_REQUIRED" | "ERR_PRISM_TOOL_EFFECT_CONFLICT" | "ERR_PRISM_TOOL_EFFECT_UNKNOWN" | "ERR_PRISM_TOOL_EFFECT_COMPLETED" | "ERR_PRISM_TOOL_EFFECT_LIMIT";
+export declare class ToolEffectError extends Error {
+    readonly code: ToolEffectErrorCode;
+    constructor(code: ToolEffectErrorCode, message: string);
+}
+/** Stable JSON representation for an already-validated tool arguments object. */
+export declare function canonicalToolEffectJson(value: unknown): string;
+export declare function toolEffectArgumentsHash(argumentsValue: JsonObject): string;
+/** Derives the only core-authoritative key. Callers never supply this from model input. */
+export declare function deriveToolEffectKey(input: Omit<ToolEffectKey, "key" | "signal">): string;
+/** In-process reference. Use a durable adapter for cross-replica claims. */
+export declare function createMemoryToolEffectStore(options?: {
+    readonly now?: () => number;
+}): ToolEffectStore;

package/dist/tool-effects.js

@@ -0,0 +1,338 @@
+import { createHash, randomUUID } from "node:crypto";
+import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
+export class ToolEffectError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ToolEffectError";
+    }
+}
+const DEFAULT_CLAIM_TTL_MS = 15 * 60_000;
+const HARD_CLAIM_TTL_MS = 60 * 60_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const HARD_MAX_ATTEMPTS = 10;
+const DEFAULT_CLEANUP_LIMIT = 100;
+const HARD_CLEANUP_LIMIT = 500;
+const MAX_EFFECT_KEY_BYTES = 96;
+const MAX_TOOL_NAME_BYTES = 512;
+const MAX_IDENTIFIER_BYTES = 512;
+const MAX_RESULT_BYTES = 64 * 1024;
+const MAX_REFERENCE_BYTES = 1024;
+const MAX_RECORD_BYTES = 128 * 1024;
+/** Stable JSON representation for an already-validated tool arguments object. */
+export function canonicalToolEffectJson(value) {
+    return JSON.stringify(canonical(value));
+}
+export function toolEffectArgumentsHash(argumentsValue) {
+    return createHash("sha256").update(canonicalToolEffectJson(argumentsValue)).digest("hex");
+}
+/** Derives the only core-authoritative key. Callers never supply this from model input. */
+export function deriveToolEffectKey(input) {
+    const value = canonicalToolEffectJson({
+        tenantId: input.ownership.tenantId,
+        accountId: input.ownership.accountId ?? null,
+        userId: input.ownership.userId ?? null,
+        principalId: input.identity.principal.id,
+        sessionId: input.sessionId,
+        runId: input.runId,
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        argumentsHash: input.argumentsHash,
+    });
+    return `prism:tool-effect:v1:${createHash("sha256").update(value).digest("hex")}`;
+}
+/** In-process reference. Use a durable adapter for cross-replica claims. */
+export function createMemoryToolEffectStore(options = {}) {
+    const records = new Map();
+    const now = options.now ?? Date.now;
+    function current(input) {
+        throwIfAborted(input.signal);
+        validateKey(input);
+        const found = records.get(recordKey(input));
+        if (!found)
+            return undefined;
+        assertMatches(found, input);
+        const expired = expire(found, now());
+        if (expired !== found)
+            records.set(recordKey(input), expired);
+        return expired;
+    }
+    function save(record, identity) {
+        const frozen = freezeRecord(record);
+        assertRecordSize(frozen);
+        records.set(recordKey({ identity, key: frozen.key }), frozen);
+        return frozen;
+    }
+    return {
+        async get(input) {
+            return current(input);
+        },
+        async begin(input) {
+            const existing = current(input);
+            const timestamp = now();
+            const ttl = claimTtl(input.claimTtlMs);
+            const attempts = maxAttempts(input.maxAttempts);
+            if (!existing)
+                return { outcome: "acquired", record: save(claim(input, 1, timestamp, ttl), input.identity) };
+            if (existing.status === "failed_retryable" && existing.attempt < attempts) {
+                return { outcome: "acquired", record: save(claim(input, existing.attempt + 1, timestamp, ttl, existing), input.identity) };
+            }
+            return { outcome: "existing", record: existing };
+        },
+        async markDispatched(input) {
+            const record = requireClaim(current(input), input, ["pending"]);
+            return save({ ...record, status: "dispatched", version: record.version + 1, updatedAt: timestamp(now()) }, input.identity);
+        },
+        async complete(input) {
+            const record = requireClaim(current(input), input, ["dispatched"]);
+            const result = input.result === undefined ? undefined : validateResult(input.result, input);
+            const resultRef = input.resultRef === undefined ? undefined : validateReference(input.resultRef);
+            return save({
+                ...withoutClaim(record),
+                status: "completed",
+                version: record.version + 1,
+                ...(result === undefined ? {} : { result }),
+                ...(resultRef === undefined ? {} : { resultRef }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async fail(input) {
+            const record = requireClaim(current(input), input, ["pending", "dispatched"]);
+            return save({
+                ...withoutClaim(record),
+                status: input.status,
+                version: record.version + 1,
+                failure: validateFailure(input.failure),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async markUnknown(input) {
+            const record = requireClaim(current(input), input, ["dispatched"]);
+            return save({
+                ...withoutClaim(record),
+                status: "unknown",
+                version: record.version + 1,
+                ...(input.failure === undefined ? {} : { failure: validateFailure(input.failure) }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async resolveUnknown(input) {
+            const record = current(input);
+            if (!record || record.status !== "unknown" || record.version !== input.expectedVersion)
+                throw conflict();
+            const result = input.result === undefined ? undefined : validateResult(input.result, input);
+            const resultRef = input.resultRef === undefined ? undefined : validateReference(input.resultRef);
+            return save({
+                ...record,
+                status: input.status,
+                version: record.version + 1,
+                ...(result === undefined ? {} : { result }),
+                ...(resultRef === undefined ? {} : { resultRef }),
+                ...(input.failure === undefined ? {} : { failure: validateFailure(input.failure) }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async cleanup(input) {
+            throwIfAborted(input.signal);
+            const before = Date.parse(input.before);
+            if (!Number.isFinite(before))
+                throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "cleanup boundary is invalid");
+            validateOwnership(input.ownership);
+            const limit = cleanupLimit(input.limit);
+            let deleted = 0;
+            for (const [id, record] of records) {
+                throwIfAborted(input.signal);
+                if (deleted >= limit)
+                    break;
+                if (!sameOwnership(record, input.ownership) || !isTerminal(record.status) || Date.parse(record.updatedAt) >= before)
+                    continue;
+                records.delete(id);
+                deleted += 1;
+            }
+            return { deleted };
+        },
+    };
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        const out = {};
+        for (const key of Object.keys(value).sort())
+            out[key] = canonical(value[key]);
+        return out;
+    }
+    throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "tool effect values must be JSON");
+}
+function claim(input, attempt, currentTime, ttl, previous) {
+    return {
+        ...owner(input.ownership),
+        key: input.key,
+        sessionId: input.sessionId,
+        runId: input.runId,
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        argumentsHash: input.argumentsHash,
+        status: "pending",
+        attempt,
+        version: (previous?.version ?? 0) + 1,
+        claimToken: randomUUID(),
+        createdAt: previous?.createdAt ?? timestamp(currentTime),
+        updatedAt: timestamp(currentTime),
+        expiresAt: timestamp(currentTime + ttl),
+    };
+}
+function expire(record, currentTime) {
+    if ((record.status !== "pending" && record.status !== "dispatched") || !record.expiresAt || Date.parse(record.expiresAt) > currentTime)
+        return record;
+    const status = record.status === "pending" ? "failed_retryable" : "unknown";
+    return freezeRecord({
+        ...withoutClaim(record),
+        status,
+        version: record.version + 1,
+        failure: { code: "ERR_PRISM_TOOL_EFFECT_EXPIRED" },
+        updatedAt: timestamp(currentTime),
+    });
+}
+function requireClaim(record, input, statuses) {
+    if (!record || !statuses.includes(record.status) || record.version !== input.expectedVersion || record.claimToken !== input.claimToken)
+        throw conflict();
+    return record;
+}
+function withoutClaim(record) {
+    const { claimToken: _claimToken, expiresAt: _expiresAt, ...rest } = record;
+    return rest;
+}
+function validateKey(input) {
+    assertIdentityActive(input.identity);
+    validateOwnership(input.ownership);
+    assertIdentityMatchesOwnership(input.identity, input.ownership);
+    if (input.ownership.tenantId !== input.identity.tenantId ||
+        input.ownership.accountId !== input.identity.accountId ||
+        input.ownership.userId !== input.identity.userId)
+        throw conflict();
+    validateText(input.key, MAX_EFFECT_KEY_BYTES, "effect key");
+    validateText(input.sessionId, MAX_IDENTIFIER_BYTES, "session id");
+    validateText(input.runId, MAX_IDENTIFIER_BYTES, "run id");
+    validateText(input.toolCallId, MAX_IDENTIFIER_BYTES, "tool call id");
+    validateText(input.toolName, MAX_TOOL_NAME_BYTES, "tool name");
+    if (!/^[a-f0-9]{64}$/.test(input.argumentsHash))
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "arguments hash is invalid");
+}
+function validateOwnership(ownership) {
+    if (!ownership.tenantId?.trim())
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect ownership is required");
+    for (const value of [ownership.tenantId, ownership.accountId, ownership.userId]) {
+        if (value !== undefined)
+            validateText(value, MAX_IDENTIFIER_BYTES, "ownership");
+    }
+}
+function assertMatches(record, input) {
+    if (record.key !== input.key ||
+        record.sessionId !== input.sessionId ||
+        record.runId !== input.runId ||
+        record.toolCallId !== input.toolCallId ||
+        record.toolName !== input.toolName ||
+        record.argumentsHash !== input.argumentsHash ||
+        !sameOwnership(record, input.ownership)) {
+        throw conflict();
+    }
+}
+function validateResult(result, input) {
+    if (result.toolCallId !== input.toolCallId || result.name !== input.toolName)
+        throw conflict();
+    return jsonSnapshot(result, MAX_RESULT_BYTES, "tool result");
+}
+function validateReference(reference) {
+    validateText(reference, MAX_REFERENCE_BYTES, "effect reference");
+    return reference;
+}
+function validateFailure(failure) {
+    validateText(failure.code, 128, "effect failure code");
+    return Object.freeze({ ...failure, ...(failure.reference === undefined ? {} : { reference: validateReference(failure.reference) }) });
+}
+function assertRecordSize(record) {
+    void jsonSnapshot(record, MAX_RECORD_BYTES, "tool effect record");
+}
+function jsonSnapshot(value, maxBytes, label) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} must be JSON serializable`);
+    }
+    if (text === undefined || Buffer.byteLength(text) > maxBytes)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} exceeds limits`);
+    return JSON.parse(text);
+}
+function freezeRecord(record) {
+    return freezeJson(jsonSnapshot(record, MAX_RECORD_BYTES, "tool effect record"));
+}
+function freezeJson(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    for (const child of Object.values(value))
+        freezeJson(child);
+    return Object.freeze(value);
+}
+function owner(ownership) {
+    return {
+        tenantId: ownership.tenantId,
+        ...(ownership.accountId === undefined ? {} : { accountId: ownership.accountId }),
+        ...(ownership.userId === undefined ? {} : { userId: ownership.userId }),
+    };
+}
+function sameOwnership(left, right) {
+    return left.tenantId === right.tenantId && left.accountId === right.accountId && left.userId === right.userId;
+}
+function recordKey(input) {
+    return JSON.stringify([
+        input.identity.tenantId,
+        input.identity.accountId ?? "",
+        input.identity.userId ?? "",
+        input.identity.principal.id,
+        input.key,
+    ]);
+}
+function isTerminal(status) {
+    return status === "completed" || status === "failed_terminal";
+}
+function timestamp(value) {
+    return new Date(value).toISOString();
+}
+function claimTtl(value) {
+    const ttl = value ?? DEFAULT_CLAIM_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > HARD_CLAIM_TTL_MS)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "claim TTL exceeds limits");
+    return ttl;
+}
+function maxAttempts(value) {
+    const attempts = value ?? DEFAULT_MAX_ATTEMPTS;
+    if (!Number.isSafeInteger(attempts) || attempts < 1 || attempts > HARD_MAX_ATTEMPTS)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "effect attempts exceed limits");
+    return attempts;
+}
+function cleanupLimit(value) {
+    const limit = value ?? DEFAULT_CLEANUP_LIMIT;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > HARD_CLEANUP_LIMIT)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "cleanup limit exceeds limits");
+    return limit;
+}
+function validateText(value, maxBytes, label) {
+    if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > maxBytes)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} is required and bounded`);
+}
+function conflict() {
+    return new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect transition conflict");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//# sourceMappingURL=tool-effects.js.map