@polpo-ai/core 0.15.45 → 0.15.47

package/dist/scheduling/store.js

@@ -0,0 +1,635 @@
+import { nanoid } from "nanoid";
+import { assertScheduleRunStatusTransition, assertScheduleStatusTransition, isTerminalScheduleRunStatus, } from "./state-machine.js";
+import { normalizeCreateScheduleInput, normalizeScheduleMetadata, normalizeUpdateScheduleInput, } from "./validation.js";
+export class ScheduleStoreError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+export class ScheduleNotFoundError extends ScheduleStoreError {
+    constructor(entity, id) {
+        super(`${entity} "${id}" was not found`, "NOT_FOUND");
+    }
+}
+export class ScheduleConflictError extends ScheduleStoreError {
+    constructor(message) {
+        super(message, "CONFLICT");
+    }
+}
+export class ScheduleInvalidStateError extends ScheduleStoreError {
+    constructor(message) {
+        super(message, "INVALID_STATE");
+    }
+}
+export class InMemoryScheduleStore {
+    schedules = new Map();
+    runs = new Map();
+    runIdsByIdempotencyKey = new Map();
+    options;
+    constructor(options = {}) {
+        this.options = {
+            now: options.now ?? (() => new Date()),
+            createId: options.createId ?? ((kind) => `${kind}-${nanoid()}`),
+        };
+    }
+    async create(input) {
+        const now = this.now();
+        const normalized = normalizeCreateScheduleInput(input, { now });
+        const id = normalized.id ?? this.options.createId("schedule");
+        if (this.schedules.has(id)) {
+            throw new ScheduleConflictError(`Schedule "${id}" already exists`);
+        }
+        const schedule = {
+            id,
+            ...(normalized.name === undefined ? {} : { name: normalized.name }),
+            ...(normalized.description === undefined
+                ? {}
+                : { description: normalized.description }),
+            timing: normalized.timing,
+            invocation: normalized.invocation,
+            status: normalized.status,
+            policy: normalized.policy,
+            metadata: normalized.metadata,
+            createdAt: now.toISOString(),
+            updatedAt: now.toISOString(),
+            revision: 1,
+        };
+        this.schedules.set(id, clone(schedule));
+        return clone(schedule);
+    }
+    async list(filter = {}) {
+        const statuses = normalizeStatusFilter(filter.status);
+        return [...this.schedules.values()]
+            .filter((schedule) => (filter.includeDeleted || schedule.status !== "deleted")
+            && (!statuses || statuses.has(schedule.status))
+            && (!filter.surface || schedule.invocation.surface === filter.surface))
+            .sort(compareCreated)
+            .map(clone);
+    }
+    async get(id) {
+        const schedule = this.schedules.get(id);
+        return schedule ? clone(schedule) : null;
+    }
+    async update(id, patch, options = {}) {
+        const existing = this.requireSchedule(id);
+        assertRevision(existing, options.expectedRevision);
+        if (existing.status === "deleted") {
+            throw new ScheduleInvalidStateError(`Schedule "${id}" is deleted`);
+        }
+        const now = this.now();
+        const normalized = normalizeUpdateScheduleInput(patch, { now });
+        const nextStatus = normalized.status ?? existing.status;
+        try {
+            assertScheduleStatusTransition(existing.status, nextStatus);
+        }
+        catch (error) {
+            throw new ScheduleInvalidStateError(errorMessage(error));
+        }
+        const updated = {
+            ...existing,
+            ...(normalized.timing === undefined ? {} : { timing: normalized.timing }),
+            ...(normalized.invocation === undefined
+                ? {}
+                : { invocation: normalized.invocation }),
+            ...(normalized.status === undefined ? {} : { status: normalized.status }),
+            ...(normalized.policy === undefined
+                ? {}
+                : { policy: { ...existing.policy, ...normalized.policy } }),
+            ...(normalized.metadata === undefined
+                ? {}
+                : { metadata: normalized.metadata }),
+            updatedAt: now.toISOString(),
+            revision: existing.revision + 1,
+        };
+        applyNullableStringPatch(updated, "name", normalized.name);
+        applyNullableStringPatch(updated, "description", normalized.description);
+        this.schedules.set(id, clone(updated));
+        return clone(updated);
+    }
+    async markDeleted(id, options = {}) {
+        const existing = this.requireSchedule(id);
+        assertRevision(existing, options.expectedRevision);
+        if (existing.status === "deleted")
+            return;
+        try {
+            assertScheduleStatusTransition(existing.status, "deleted");
+        }
+        catch (error) {
+            throw new ScheduleInvalidStateError(errorMessage(error));
+        }
+        const now = this.now().toISOString();
+        this.schedules.set(id, {
+            ...existing,
+            status: "deleted",
+            updatedAt: now,
+            revision: existing.revision + 1,
+        });
+    }
+    async updateOperationalState(id, patch, options = {}) {
+        const existing = this.requireSchedule(id);
+        assertRevision(existing, options.expectedRevision);
+        const normalized = normalizeScheduleOperationalStatePatch(patch);
+        const updated = {
+            ...existing,
+            revision: existing.revision + 1,
+            updatedAt: this.now().toISOString(),
+        };
+        applyNullableField(updated, "nextOccurrenceAt", normalized.nextOccurrenceAt);
+        applyNullableField(updated, "lastOccurrenceAt", normalized.lastOccurrenceAt);
+        applyNullableField(updated, "driver", normalized.driver);
+        this.schedules.set(id, clone(updated));
+        return clone(updated);
+    }
+    async createRun(input) {
+        const normalized = normalizeCreateScheduleRunInput(input);
+        const duplicateId = this.runIdsByIdempotencyKey.get(normalized.idempotencyKey);
+        if (duplicateId) {
+            const duplicate = this.runs.get(duplicateId);
+            if (!duplicate) {
+                throw new ScheduleInvalidStateError(`Schedule run idempotency index is corrupted for "${normalized.idempotencyKey}"`);
+            }
+            assertSameScheduleOccurrence(duplicate, normalized);
+            return clone(duplicate);
+        }
+        const schedule = this.requireSchedule(normalized.scheduleId);
+        if (schedule.status !== "active") {
+            throw new ScheduleInvalidStateError(`Schedule "${schedule.id}" is not active`);
+        }
+        const id = normalized.id ?? this.options.createId("schedule-run");
+        if (this.runs.has(id)) {
+            throw new ScheduleConflictError(`Schedule run "${id}" already exists`);
+        }
+        const now = this.now().toISOString();
+        const run = {
+            id,
+            scheduleId: normalized.scheduleId,
+            occurrenceAt: normalized.occurrenceAt,
+            triggerId: normalized.triggerId,
+            idempotencyKey: normalized.idempotencyKey,
+            status: "pending",
+            attempts: 0,
+            references: {},
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.runs.set(id, clone(run));
+        this.runIdsByIdempotencyKey.set(run.idempotencyKey, id);
+        return clone(run);
+    }
+    async getRun(id) {
+        const run = this.runs.get(id);
+        return run ? clone(run) : null;
+    }
+    async listRuns(filter = {}) {
+        const statuses = normalizeRunStatusFilter(filter.status);
+        const limit = normalizeLimit(filter.limit);
+        const direction = normalizeRunOrder(filter.order);
+        return [...this.runs.values()]
+            .filter((run) => (!filter.scheduleId || run.scheduleId === filter.scheduleId)
+            && (!statuses || statuses.has(run.status)))
+            .sort((a, b) => direction * (a.occurrenceAt.localeCompare(b.occurrenceAt)
+            || a.createdAt.localeCompare(b.createdAt)
+            || a.id.localeCompare(b.id)))
+            .slice(0, limit)
+            .map(clone);
+    }
+    async claimRun(id, lease) {
+        const now = this.now();
+        const normalizedLease = normalizeScheduleLease(lease, now);
+        const run = this.requireRun(id);
+        if (isTerminalScheduleRunStatus(run.status))
+            return null;
+        const schedule = this.requireSchedule(run.scheduleId);
+        if (schedule.status !== "active")
+            return null;
+        if ((run.status === "claimed" || run.status === "running")
+            && run.lease
+            && Date.parse(run.lease.expiresAt) > now.getTime()) {
+            return null;
+        }
+        if (run.status !== "pending"
+            && run.status !== "claimed"
+            && run.status !== "running") {
+            return null;
+        }
+        const activeRuns = [...this.runs.values()].filter((candidate) => candidate.id !== run.id
+            && candidate.scheduleId === run.scheduleId
+            && isActiveRun(candidate)
+            && Boolean(candidate.lease)
+            && Date.parse(candidate.lease.expiresAt) > now.getTime()).length;
+        if (activeRuns >= schedule.policy.maxConcurrency)
+            return null;
+        try {
+            assertScheduleRunStatusTransition(run.status, "claimed");
+        }
+        catch (error) {
+            throw new ScheduleInvalidStateError(errorMessage(error));
+        }
+        const claimed = {
+            ...run,
+            status: "claimed",
+            attempts: run.attempts + 1,
+            lease: normalizedLease,
+            updatedAt: now.toISOString(),
+        };
+        this.runs.set(id, clone(claimed));
+        return clone(claimed);
+    }
+    async renewLease(id, lease) {
+        const now = this.now();
+        const normalizedLease = normalizeScheduleLease(lease, now);
+        const run = this.requireRun(id);
+        if (!isActiveRun(run) || !leaseMatches(run.lease, normalizedLease))
+            return false;
+        if (!run.lease || Date.parse(run.lease.expiresAt) <= now.getTime())
+            return false;
+        if (Date.parse(normalizedLease.expiresAt) < Date.parse(run.lease.expiresAt)) {
+            return false;
+        }
+        this.runs.set(id, {
+            ...run,
+            lease: normalizedLease,
+            updatedAt: now.toISOString(),
+        });
+        return true;
+    }
+    async startRun(id, lease) {
+        const now = this.now();
+        const normalizedLease = normalizeScheduleLease(lease, now);
+        const run = this.requireOwnedActiveRun(id, normalizedLease, now);
+        const schedule = this.requireSchedule(run.scheduleId);
+        if (schedule.status !== "active") {
+            throw new ScheduleInvalidStateError(`Schedule "${schedule.id}" is not active`);
+        }
+        if (run.status !== "claimed") {
+            throw new ScheduleInvalidStateError(`Schedule run "${id}" must be claimed before it can start`);
+        }
+        const started = {
+            ...run,
+            status: "running",
+            lease: normalizedLease,
+            startedAt: run.startedAt ?? now.toISOString(),
+            updatedAt: now.toISOString(),
+        };
+        this.runs.set(id, clone(started));
+        return clone(started);
+    }
+    async releaseRun(id, lease) {
+        const now = this.now();
+        const normalizedLease = normalizeScheduleLease(lease, now);
+        const run = this.requireOwnedActiveRun(id, normalizedLease, now);
+        const released = {
+            ...run,
+            status: "pending",
+            updatedAt: now.toISOString(),
+        };
+        delete released.lease;
+        this.runs.set(id, clone(released));
+        return clone(released);
+    }
+    async completeRun(id, input) {
+        const now = this.now();
+        const completion = normalizeCompleteScheduleRunInput(input, now);
+        const run = this.requireRun(id);
+        if (isTerminalScheduleRunStatus(run.status)) {
+            throw new ScheduleConflictError(`Schedule run "${id}" is already terminal`);
+        }
+        const owned = this.requireOwnedActiveRun(id, completion.lease, now);
+        try {
+            assertScheduleRunStatusTransition(owned.status, completion.status);
+        }
+        catch (error) {
+            throw new ScheduleInvalidStateError(errorMessage(error));
+        }
+        const completed = {
+            ...owned,
+            status: completion.status,
+            references: completion.references,
+            ...(completion.result === undefined ? {} : { result: completion.result }),
+            ...(completion.error === undefined ? {} : { error: completion.error }),
+            completedAt: now.toISOString(),
+            updatedAt: now.toISOString(),
+        };
+        delete completed.lease;
+        this.runs.set(id, clone(completed));
+        return clone(completed);
+    }
+    async countActiveRuns(scheduleId) {
+        const now = this.now().getTime();
+        return [...this.runs.values()].filter((run) => run.scheduleId === scheduleId
+            && isActiveRun(run)
+            && Boolean(run.lease)
+            && Date.parse(run.lease.expiresAt) > now).length;
+    }
+    requireSchedule(id) {
+        const schedule = this.schedules.get(id);
+        if (!schedule)
+            throw new ScheduleNotFoundError("Schedule", id);
+        return schedule;
+    }
+    requireRun(id) {
+        const run = this.runs.get(id);
+        if (!run)
+            throw new ScheduleNotFoundError("Schedule run", id);
+        return run;
+    }
+    requireOwnedActiveRun(id, lease, now) {
+        const run = this.requireRun(id);
+        if (!isActiveRun(run) || !run.lease || !leaseMatches(run.lease, lease)) {
+            throw new ScheduleConflictError(`Schedule run "${id}" is not owned by this lease`);
+        }
+        if (Date.parse(run.lease.expiresAt) <= now.getTime()) {
+            throw new ScheduleConflictError(`Schedule run "${id}" lease has expired`);
+        }
+        return run;
+    }
+    now() {
+        const now = new Date(this.options.now());
+        if (!Number.isFinite(now.getTime())) {
+            throw new ScheduleInvalidStateError("Schedule store clock returned an invalid date");
+        }
+        return now;
+    }
+}
+export function normalizeCreateScheduleRunInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Schedule run input must be an object");
+    }
+    assertOnlyKeys(input, ["id", "scheduleId", "occurrenceAt", "triggerId", "idempotencyKey"], "Schedule run input");
+    return {
+        ...(input.id === undefined ? {} : { id: nonEmpty(input.id, "Schedule run id") }),
+        scheduleId: nonEmpty(input.scheduleId, "Schedule run scheduleId"),
+        occurrenceAt: absoluteTimestamp(input.occurrenceAt, "Schedule run occurrenceAt"),
+        triggerId: nonEmpty(input.triggerId, "Schedule run triggerId"),
+        idempotencyKey: nonEmpty(input.idempotencyKey, "Schedule run idempotencyKey"),
+    };
+}
+export function normalizeScheduleLease(value, now, requireFuture = true) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule run lease must be an object");
+    }
+    assertOnlyKeys(value, ["owner", "token", "expiresAt"], "Schedule run lease");
+    const normalized = {
+        owner: nonEmpty(value.owner, "Schedule run lease owner"),
+        token: nonEmpty(value.token, "Schedule run lease token"),
+        expiresAt: absoluteTimestamp(value.expiresAt, "Schedule run lease expiresAt"),
+    };
+    if (requireFuture && Date.parse(normalized.expiresAt) <= now.getTime()) {
+        throw new Error("Schedule run lease expiresAt must be in the future");
+    }
+    return normalized;
+}
+export function normalizeCompleteScheduleRunInput(value, now) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule run completion must be an object");
+    }
+    assertOnlyKeys(value, ["lease", "status", "references", "result", "error"], "Schedule run completion");
+    if (!["succeeded", "failed", "skipped", "cancelled"].includes(value.status)) {
+        throw new Error("Schedule run completion status is invalid");
+    }
+    const references = normalizeReferences(value.references);
+    const result = value.result === undefined
+        ? undefined
+        : normalizeScheduleMetadata(value.result, "Schedule run result");
+    const error = value.error === undefined ? undefined : normalizeRunError(value.error);
+    if (value.status === "failed" && !error) {
+        throw new Error("A failed schedule run completion requires error details");
+    }
+    if (value.status === "succeeded" && error) {
+        throw new Error("A succeeded schedule run completion cannot include an error");
+    }
+    return {
+        lease: normalizeScheduleLease(value.lease, now, false),
+        status: value.status,
+        references,
+        ...(result === undefined ? {} : { result }),
+        ...(error === undefined ? {} : { error }),
+    };
+}
+export function normalizeScheduleOperationalStatePatch(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule operational state patch must be an object");
+    }
+    assertOnlyKeys(value, ["nextOccurrenceAt", "lastOccurrenceAt", "driver"], "Schedule operational state patch");
+    if (Object.keys(value).length === 0) {
+        throw new Error("Schedule operational state patch must include at least one field");
+    }
+    return {
+        ...(value.nextOccurrenceAt === undefined
+            ? {}
+            : {
+                nextOccurrenceAt: value.nextOccurrenceAt === null
+                    ? null
+                    : absoluteTimestamp(value.nextOccurrenceAt, "Schedule nextOccurrenceAt"),
+            }),
+        ...(value.lastOccurrenceAt === undefined
+            ? {}
+            : {
+                lastOccurrenceAt: value.lastOccurrenceAt === null
+                    ? null
+                    : absoluteTimestamp(value.lastOccurrenceAt, "Schedule lastOccurrenceAt"),
+            }),
+        ...(value.driver === undefined
+            ? {}
+            : {
+                driver: value.driver === null
+                    ? null
+                    : normalizeDriverRegistration(value.driver),
+            }),
+    };
+}
+function normalizeReferences(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule run references must be an object");
+    }
+    const allowed = new Set([
+        "runtimeId",
+        "taskId",
+        "loopRunId",
+        "sessionId",
+        "channelEventId",
+        "providerDeliveryId",
+    ]);
+    const normalized = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`Schedule run references contains unsupported field "${key}"`);
+        }
+        normalized[key] = nonEmpty(child, `Schedule run reference ${key}`);
+    }
+    return normalized;
+}
+function normalizeRunError(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule run error must be an object");
+    }
+    assertOnlyKeys(value, ["code", "message", "retryable", "metadata"], "Schedule run error");
+    if (typeof value.retryable !== "boolean") {
+        throw new Error("Schedule run error retryable must be a boolean");
+    }
+    return {
+        code: nonEmpty(value.code, "Schedule run error code"),
+        message: nonEmpty(value.message, "Schedule run error message"),
+        retryable: value.retryable,
+        ...(value.metadata === undefined
+            ? {}
+            : {
+                metadata: normalizeScheduleMetadata(value.metadata, "Schedule run error metadata"),
+            }),
+    };
+}
+function normalizeDriverRegistration(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule driver registration must be an object");
+    }
+    assertOnlyKeys(value, ["kind", "status", "providerId", "metadata", "error", "updatedAt"], "Schedule driver registration");
+    if (!["pending", "registered", "failed", "not_required"].includes(value.status)) {
+        throw new Error("Schedule driver registration status is invalid");
+    }
+    if (value.status === "registered" && value.providerId === undefined) {
+        throw new Error("A registered schedule driver requires providerId");
+    }
+    if (value.status === "failed" && value.error === undefined) {
+        throw new Error("A failed schedule driver registration requires error details");
+    }
+    if (value.status !== "failed" && value.error !== undefined) {
+        throw new Error("Only a failed schedule driver registration may include an error");
+    }
+    return {
+        kind: nonEmpty(value.kind, "Schedule driver kind"),
+        status: value.status,
+        ...(value.providerId === undefined
+            ? {}
+            : { providerId: nonEmpty(value.providerId, "Schedule driver providerId") }),
+        ...(value.metadata === undefined
+            ? {}
+            : {
+                metadata: normalizeScheduleMetadata(value.metadata, "Schedule driver metadata"),
+            }),
+        ...(value.error === undefined ? {} : { error: normalizeDriverError(value.error) }),
+        updatedAt: absoluteTimestamp(value.updatedAt, "Schedule driver updatedAt"),
+    };
+}
+function normalizeDriverError(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Schedule driver error must be an object");
+    }
+    assertOnlyKeys(value, ["code", "message", "retryable"], "Schedule driver error");
+    if (typeof value.retryable !== "boolean") {
+        throw new Error("Schedule driver error retryable must be a boolean");
+    }
+    return {
+        code: nonEmpty(value.code, "Schedule driver error code"),
+        message: nonEmpty(value.message, "Schedule driver error message"),
+        retryable: value.retryable,
+    };
+}
+export function assertSameScheduleOccurrence(existing, input) {
+    if (existing.scheduleId !== input.scheduleId
+        || existing.occurrenceAt !== input.occurrenceAt
+        || existing.triggerId !== input.triggerId) {
+        throw new ScheduleConflictError(`Schedule run idempotency key "${input.idempotencyKey}" is already used by another occurrence`);
+    }
+}
+function assertRevision(schedule, expected) {
+    if (expected === undefined)
+        return;
+    if (!Number.isInteger(expected) || expected < 1) {
+        throw new Error("Schedule expectedRevision must be a positive integer");
+    }
+    if (schedule.revision !== expected) {
+        throw new ScheduleConflictError(`Schedule "${schedule.id}" revision conflict: expected ${expected}, found ${schedule.revision}`);
+    }
+}
+function applyNullableStringPatch(schedule, key, value) {
+    if (value === undefined)
+        return;
+    if (value === null) {
+        delete schedule[key];
+    }
+    else {
+        schedule[key] = value;
+    }
+}
+function applyNullableField(schedule, key, value) {
+    if (value === undefined)
+        return;
+    if (value === null)
+        delete schedule[key];
+    else
+        schedule[key] = value;
+}
+function normalizeStatusFilter(status) {
+    if (status === undefined)
+        return undefined;
+    return new Set(Array.isArray(status) ? status : [status]);
+}
+function normalizeRunStatusFilter(status) {
+    if (status === undefined)
+        return undefined;
+    return new Set(Array.isArray(status) ? status : [status]);
+}
+function normalizeLimit(limit) {
+    if (limit === undefined)
+        return Number.POSITIVE_INFINITY;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1_000) {
+        throw new Error("Schedule run list limit must be an integer between 1 and 1000");
+    }
+    return limit;
+}
+function normalizeRunOrder(order) {
+    if (order === undefined || order === "desc")
+        return -1;
+    if (order === "asc")
+        return 1;
+    throw new Error('Schedule run order must be "asc" or "desc"');
+}
+function isActiveRun(run) {
+    return run.status === "claimed" || run.status === "running";
+}
+function leaseMatches(current, candidate) {
+    return Boolean(current
+        && current.owner === candidate.owner
+        && current.token === candidate.token);
+}
+function compareCreated(a, b) {
+    return a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id);
+}
+function absoluteTimestamp(value, label) {
+    const text = nonEmpty(value, label);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(text)) {
+        throw new Error(`${label} must be an absolute ISO timestamp`);
+    }
+    const date = new Date(text);
+    if (!Number.isFinite(date.getTime())) {
+        throw new Error(`${label} must be a valid timestamp`);
+    }
+    return date.toISOString();
+}
+function nonEmpty(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    if (value.trim().length > 512) {
+        throw new Error(`${label} exceeds the 512-character limit`);
+    }
+    return value.trim();
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function assertOnlyKeys(value, allowed, label) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key)) {
+            throw new Error(`${label} contains unsupported field "${key}"`);
+        }
+    }
+}
+//# sourceMappingURL=store.js.map