@xmemory/temporal 1.0.0

package/dist/workflow.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The workflow-facing xmemory surface.
+ *
+ * `WorkflowXmemory` mirrors the plain client's method *names*, so existing agent
+ * call sites keep working and just dispatch to an activity. Two differences: the
+ * enqueue is `writeAsyncStart`, and results are this package's own DTOs rather than
+ * the client's raw shapes. Replay-safe by construction: only `proxyActivities` and
+ * `sleep`, no I/O and no wall-clock.
+ */
+import type { Duration, RetryPolicy } from '@temporalio/common';
+import type { ReadMode, WriteMutation, ReadScope, ReadOutput, WriteOutput, WriteStartOutput, WriteStatusOutput } from './dto';
+/** How one status poll retries. Turned into a RetryPolicy by this package. */
+export interface WriteStatusRetry {
+    /** Attempts per poll, including the first. Default 10; `Infinity` for unlimited. */
+    attempts?: number;
+    /** Delay before the first retry, in ms. Default 1000. */
+    intervalMs?: number;
+    /** Ceiling on the backed-off delay, in ms. Default 20000. */
+    maxIntervalMs?: number;
+    /**
+     * Failure `type`s that end the polling instead of being retried.
+     *
+     * Only useful for types this package maps as retryable — an already
+     * non-retryable failure stops the polling on its own.
+     */
+    nonRetryableErrorTypes?: readonly string[];
+}
+export interface WorkflowXmemoryOptions {
+    readTimeout?: Duration;
+    writeTimeout?: Duration;
+    writeStartTimeout?: Duration;
+    writeStatusTimeout?: Duration;
+    readRetryPolicy?: RetryPolicy;
+    writeRetryPolicy?: RetryPolicy;
+    /**
+     * How each status poll retries.
+     *
+     * Scalars rather than a `RetryPolicy`: Temporal compiles a policy when it
+     * schedules the Activity, and for the first poll that is after `writeDurable` has
+     * enqueued the write. Built here, it cannot be a policy Temporal refuses. Distinct
+     * from `WriteDurableOptions.pollIntervalMs`, which paces the loop between polls.
+     */
+    writeStatusRetry?: WriteStatusRetry;
+    /**
+     * Total bound on a call including its retries, as `scheduleToCloseTimeout`.
+     *
+     * The per-call timeouts above bound one *attempt*. Nothing bounds the sequence
+     * unless this is set, and the server's own `Retry-After` is honoured as given —
+     * so a rate-limited read with an hour-long hint can sit in retries for hours.
+     * Unset by default, which is Temporal's behaviour; set it when a call has a
+     * deadline of its own.
+     */
+    totalTimeout?: Duration;
+    includeContentInSummary?: boolean;
+}
+export interface WriteDurableOptions {
+    extractionLogic?: 'fast' | 'deep';
+    diffEngine?: boolean;
+    structuredMutations?: readonly WriteMutation[];
+    pollIntervalMs?: number;
+    maxPollIntervalMs?: number;
+    maxWaitMs?: number;
+}
+export declare class WorkflowXmemory {
+    private readonly opts;
+    constructor(options?: WorkflowXmemoryOptions);
+    read(query: string, options?: {
+        readMode?: ReadMode;
+        scope?: ReadScope;
+    }): Promise<ReadOutput>;
+    /**
+     * Write memory, from free `text` or explicit `structuredMutations`.
+     *
+     * Structured mutations skip extraction, so an update or delete addressed by a
+     * primary key is safe to retry. A create without one is not: the server assigns
+     * the key, so a lost response plus a retry inserts the record twice.
+     */
+    write(text: string, options?: {
+        extractionLogic?: 'fast' | 'deep';
+        diffEngine?: boolean;
+        structuredMutations?: readonly WriteMutation[];
+    }): Promise<WriteOutput>;
+    /**
+     * Enqueue a write and return its id, without waiting for it.
+     *
+     * Nothing is forced here: an omitted `extractionLogic` resolves worker-side to
+     * `XmemoryConfig.defaultExtractionLogic`. Only `writeDurable` asks for `deep`.
+     */
+    writeAsyncStart(text: string, options?: {
+        extractionLogic?: 'fast' | 'deep';
+        diffEngine?: boolean;
+        structuredMutations?: readonly WriteMutation[];
+    }): Promise<WriteStartOutput>;
+    /** Poll a queued write once. The caller owns the overall wait. */
+    writeStatus(writeId: string): Promise<WriteStatusOutput>;
+    /**
+     * `writeStatus` with an optional deadline, for `writeDurable`.
+     *
+     * `bound` caps the whole poll, retries included. Without it a rate-limited poll
+     * can back off far past the caller's `maxWaitMs` and surface as
+     * XmemoryRateLimited instead of XmemoryWriteTimeout.
+     *
+     * `singleAttempt` is for the last look taken *at* the deadline, which nothing
+     * else bounds. Letting it retry turned a 10s wait into 35s.
+     */
+    private pollStatus;
+    /**
+     * Enqueue a write and poll it to completion, durably. The poll loop lives in
+     * workflow history, so a slow extraction survives worker restarts — the whole
+     * reason to put Temporal in front of xmemory. The enqueue is the only
+     * non-idempotent step; the extraction is observed through idempotent polls.
+     *
+     * `text` is required, with no default: a default made it optional in the emitted
+     * declaration, and `writeDurable()` then enqueued an empty deep write. A caller
+     * sending only `structuredMutations` passes `''` and means it.
+     */
+    writeDurable(text: string, options?: WriteDurableOptions): Promise<WriteStatusOutput>;
+    /** The configured total bound, as proxy options. Empty when none is set. */
+    private totalBound;
+    /** The tighter of the loop's own bound and the caller's `totalTimeout`. */
+    private pollBound;
+    private summary;
+}
+/**
+ * A {@link WorkflowXmemory} handle. Carries only configuration (no per-call
+ * mutable state), so making a fresh one per call is correct and cheap.
+ */
+export declare function xmemoryForWorkflow(options?: WorkflowXmemoryOptions): WorkflowXmemory;
+export { TYPE_AUTH_FAILED, TYPE_BAD_OPTIONS, TYPE_BAD_REQUEST, TYPE_DAILY_QUOTA_EXCEEDED, TYPE_DEADLINE_EXPIRED, TYPE_MONTHLY_QUOTA_EXCEEDED, TYPE_NOT_BOUND, TYPE_NOT_FOUND, TYPE_NO_DEADLINE, TYPE_QUOTA_EXCEEDED, TYPE_RATE_LIMITED, TYPE_SCHEMA_REJECTED, TYPE_SERVER_ERROR, TYPE_UNAVAILABLE, TYPE_UNKNOWN, TYPE_WRITE_FAILED, TYPE_WRITE_NOT_FOUND, TYPE_WRITE_TIMEOUT, } from './names';
+export type { ObjectMutationBody, ReadMode, ReadOutput, ReadScope, RelationEndpoint, RelationMutationBody, RelationsScope, ScopeObject, SubAnswer, WriteMutation, WriteOutput, WriteStartOutput, WriteStatusOutput, } from './dto';

package/dist/workflow.js

@@ -0,0 +1,412 @@
+"use strict";
+/**
+ * The workflow-facing xmemory surface.
+ *
+ * `WorkflowXmemory` mirrors the plain client's method *names*, so existing agent
+ * call sites keep working and just dispatch to an activity. Two differences: the
+ * enqueue is `writeAsyncStart`, and results are this package's own DTOs rather than
+ * the client's raw shapes. Replay-safe by construction: only `proxyActivities` and
+ * `sleep`, no I/O and no wall-clock.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TYPE_WRITE_TIMEOUT = exports.TYPE_WRITE_NOT_FOUND = exports.TYPE_WRITE_FAILED = exports.TYPE_UNKNOWN = exports.TYPE_UNAVAILABLE = exports.TYPE_SERVER_ERROR = exports.TYPE_SCHEMA_REJECTED = exports.TYPE_RATE_LIMITED = exports.TYPE_QUOTA_EXCEEDED = exports.TYPE_NO_DEADLINE = exports.TYPE_NOT_FOUND = exports.TYPE_NOT_BOUND = exports.TYPE_MONTHLY_QUOTA_EXCEEDED = exports.TYPE_DEADLINE_EXPIRED = exports.TYPE_DAILY_QUOTA_EXCEEDED = exports.TYPE_BAD_REQUEST = exports.TYPE_BAD_OPTIONS = exports.TYPE_AUTH_FAILED = exports.WorkflowXmemory = void 0;
+exports.xmemoryForWorkflow = xmemoryForWorkflow;
+const workflow_1 = require("@temporalio/workflow");
+const common_1 = require("@temporalio/common");
+const names_1 = require("./names");
+// The workflow owns every activity budget: what is set here is what Temporal
+// enforces AND what each activity derives its client timeout from, so the two
+// can never disagree. `DEFAULT_TIMEOUTS` is only the source of the numbers.
+const defaults_1 = require("./defaults");
+// Terminal `WriteQueueStatus` values (see xmemory's WriteQueueStatus).
+const STATUS_COMPLETED = 'completed';
+const STATUS_FAILED = 'failed';
+const STATUS_NOT_FOUND = 'not_found';
+// Non-terminal states we keep polling through. Listed explicitly so a new,
+// unseen server-side state is recognised as unknown and logged, rather than
+// passing silently — the loop polls on either way, since a state the enum has
+// grown must not fail a write that is still in flight.
+const STATUS_IN_PROGRESS = new Set(['queued', 'processing', 'extracting', 'extracted', 'applying']);
+const DEFAULT_READ_RETRY = {
+    initialInterval: '1s',
+    backoffCoefficient: 2,
+    maximumInterval: '30s',
+    maximumAttempts: 10,
+};
+// At-most-once: xmemory assigns primary keys with a model, so a re-extraction can
+// normalize the same value differently and fork the record. A failed write is
+// surfaced to the workflow rather than retried. See the README's idempotency
+// section for when opting in is safe.
+const DEFAULT_WRITE_RETRY = { maximumAttempts: 1 };
+/**
+ * A duration in ms, or a non-retryable option failure.
+ *
+ * `msToNumber` throws a raw TypeError on a malformed string and passes `Infinity`
+ * straight through; either reaches Temporal and fails the Workflow Task over and
+ * over, with a durable write already enqueued.
+ */
+function durationMs(value, label) {
+    let ms;
+    try {
+        ms = (0, common_1.msToNumber)(value);
+    }
+    catch (err) {
+        throw workflow_1.ApplicationFailure.create({
+            message: `${label} is not a valid duration: ${String(err)}`,
+            type: names_1.TYPE_BAD_OPTIONS,
+            nonRetryable: true,
+        });
+    }
+    // `< 1`, not `<= 0`: Temporal truncates a sub-millisecond duration to zero, and a
+    // zeroed startToClose falls back to the default schedule-to-close — ten years.
+    if (!Number.isFinite(ms) || ms < 1 || ms > defaults_1.MAX_DURATION_MS) {
+        throw workflow_1.ApplicationFailure.create({
+            message: `${label} must be between 1 and ${defaults_1.MAX_DURATION_MS}ms, got ${ms}`,
+            type: names_1.TYPE_BAD_OPTIONS,
+            nonRetryable: true,
+        });
+    }
+    return ms;
+}
+const DEFAULT_WRITE_STATUS_RETRY = { attempts: 10, intervalMs: 1_000, maxIntervalMs: 20_000 };
+/**
+ * A poll retry policy built from scalars rather than taken from the caller.
+ *
+ * Temporal compiles a retry policy when it schedules the Activity, which for the
+ * first status poll is *after* `writeDurable` has enqueued the write — so an
+ * unusable one leaves a queued write nobody polls. Building it here means there is
+ * no policy to be unusable: three numbers are checked, and what Temporal gets is
+ * something it always accepts.
+ */
+function buildWriteStatusRetry(retry) {
+    const opts = retry ?? {};
+    const attempts = opts.attempts ?? DEFAULT_WRITE_STATUS_RETRY.attempts;
+    // `Infinity` is Temporal's own spelling of unlimited, and compiles away to unset.
+    if (attempts !== Number.POSITIVE_INFINITY && (!Number.isInteger(attempts) || attempts < 1)) {
+        throw workflow_1.ApplicationFailure.create({
+            message: `writeStatusRetry.attempts must be a positive integer or Infinity, got ${String(attempts)}`,
+            type: names_1.TYPE_BAD_OPTIONS,
+            nonRetryable: true,
+        });
+    }
+    const intervalMs = durationMs(opts.intervalMs ?? DEFAULT_WRITE_STATUS_RETRY.intervalMs, 'writeStatusRetry.intervalMs');
+    const maxIntervalMs = durationMs(opts.maxIntervalMs ?? DEFAULT_WRITE_STATUS_RETRY.maxIntervalMs, 'writeStatusRetry.maxIntervalMs');
+    if (maxIntervalMs < intervalMs) {
+        throw workflow_1.ApplicationFailure.create({
+            message: `writeStatusRetry.maxIntervalMs (${maxIntervalMs}) must not be below intervalMs (${intervalMs})`,
+            type: names_1.TYPE_BAD_OPTIONS,
+            nonRetryable: true,
+        });
+    }
+    const types = opts.nonRetryableErrorTypes;
+    return {
+        initialInterval: intervalMs,
+        backoffCoefficient: 2,
+        maximumInterval: maxIntervalMs,
+        maximumAttempts: attempts,
+        ...(types !== undefined ? { nonRetryableErrorTypes: [...types] } : {}),
+    };
+}
+class WorkflowXmemory {
+    opts;
+    constructor(options = {}) {
+        this.opts = {
+            readTimeout: options.readTimeout ?? defaults_1.DEFAULT_TIMEOUTS.readMs,
+            writeTimeout: options.writeTimeout ?? defaults_1.DEFAULT_TIMEOUTS.writeMs,
+            writeStartTimeout: options.writeStartTimeout ?? defaults_1.DEFAULT_TIMEOUTS.writeStartMs,
+            writeStatusTimeout: options.writeStatusTimeout ?? defaults_1.DEFAULT_TIMEOUTS.writeStatusMs,
+            readRetry: options.readRetryPolicy ?? DEFAULT_READ_RETRY,
+            writeRetry: options.writeRetryPolicy ?? DEFAULT_WRITE_RETRY,
+            pollRetry: buildWriteStatusRetry(options.writeStatusRetry),
+            totalTimeout: options.totalTimeout,
+            // `=== true`, not truthiness: options can be built from config, and the string
+            // "false" would otherwise put memory text into the Activity summary, which is
+            // persisted to workflow history.
+            includeContent: options.includeContentInSummary === true,
+        };
+    }
+    async read(query, options = {}) {
+        const acts = (0, workflow_1.proxyActivities)({
+            startToCloseTimeout: this.opts.readTimeout,
+            ...this.totalBound(),
+            retry: this.opts.readRetry,
+            summary: this.summary('read', query),
+        });
+        // Named fields, not a spread, and the positional value last: an options object
+        // carrying its own `query` would otherwise replace what the caller passed.
+        return acts[names_1.ACTIVITY_READ]({ readMode: options.readMode, scope: options.scope, query });
+    }
+    /**
+     * Write memory, from free `text` or explicit `structuredMutations`.
+     *
+     * Structured mutations skip extraction, so an update or delete addressed by a
+     * primary key is safe to retry. A create without one is not: the server assigns
+     * the key, so a lost response plus a retry inserts the record twice.
+     */
+    async write(text, options = {}) {
+        const acts = (0, workflow_1.proxyActivities)({
+            startToCloseTimeout: this.opts.writeTimeout,
+            ...this.totalBound(),
+            retry: this.opts.writeRetry,
+            summary: this.summary('write', text, options.extractionLogic),
+        });
+        return acts[names_1.ACTIVITY_WRITE]({
+            extractionLogic: options.extractionLogic,
+            diffEngine: options.diffEngine,
+            structuredMutations: options.structuredMutations,
+            text,
+        });
+    }
+    /**
+     * Enqueue a write and return its id, without waiting for it.
+     *
+     * Nothing is forced here: an omitted `extractionLogic` resolves worker-side to
+     * `XmemoryConfig.defaultExtractionLogic`. Only `writeDurable` asks for `deep`.
+     */
+    async writeAsyncStart(text, options = {}) {
+        const logic = options.extractionLogic;
+        const acts = (0, workflow_1.proxyActivities)({
+            startToCloseTimeout: this.opts.writeStartTimeout,
+            ...this.totalBound(),
+            retry: this.opts.writeRetry,
+            summary: this.summary('write_start', text, logic),
+        });
+        return acts[names_1.ACTIVITY_WRITE_START]({
+            text,
+            extractionLogic: logic,
+            diffEngine: options.diffEngine,
+            structuredMutations: options.structuredMutations,
+        });
+    }
+    /** Poll a queued write once. The caller owns the overall wait. */
+    async writeStatus(writeId) {
+        return this.pollStatus(writeId, undefined);
+    }
+    /**
+     * `writeStatus` with an optional deadline, for `writeDurable`.
+     *
+     * `bound` caps the whole poll, retries included. Without it a rate-limited poll
+     * can back off far past the caller's `maxWaitMs` and surface as
+     * XmemoryRateLimited instead of XmemoryWriteTimeout.
+     *
+     * `singleAttempt` is for the last look taken *at* the deadline, which nothing
+     * else bounds. Letting it retry turned a 10s wait into 35s.
+     */
+    async pollStatus(writeId, bound, singleAttempt = false) {
+        const acts = (0, workflow_1.proxyActivities)({
+            startToCloseTimeout: this.opts.writeStatusTimeout,
+            ...this.pollBound(bound),
+            retry: singleAttempt ? { ...this.opts.pollRetry, maximumAttempts: 1 } : this.opts.pollRetry,
+            summary: `xmemory write_status: ${writeId}`,
+        });
+        return acts[names_1.ACTIVITY_WRITE_STATUS]({ writeId });
+    }
+    /**
+     * Enqueue a write and poll it to completion, durably. The poll loop lives in
+     * workflow history, so a slow extraction survives worker restarts — the whole
+     * reason to put Temporal in front of xmemory. The enqueue is the only
+     * non-idempotent step; the extraction is observed through idempotent polls.
+     *
+     * `text` is required, with no default: a default made it optional in the emitted
+     * declaration, and `writeDurable()` then enqueued an empty deep write. A caller
+     * sending only `structuredMutations` passes `''` and means it.
+     */
+    async writeDurable(text, options = {}) {
+        // Everything below is validated before the enqueue: a rejected option must not
+        // leave a queued write behind that nobody is waiting on.
+        let delayMs = options.pollIntervalMs ?? 2_000;
+        const capMs = options.maxPollIntervalMs ?? 30_000;
+        const maxWaitMs = options.maxWaitMs ?? 15 * 60_000;
+        const statusBudgetMs = durationMs(this.opts.writeStatusTimeout, 'writeDurable: writeStatusTimeout');
+        for (const [name, value] of [
+            ['maxWaitMs', maxWaitMs],
+            ['pollIntervalMs', delayMs],
+            ['maxPollIntervalMs', capMs],
+        ]) {
+            // Below a millisecond Temporal truncates to zero, which hot-polls against its
+            // timer floor; the upper bound is what setTimeout and the service can represent.
+            if (!Number.isFinite(value) || value < 1 || value > defaults_1.MAX_DURATION_MS) {
+                throw workflow_1.ApplicationFailure.create({
+                    message: `writeDurable: ${name} must be between 1 and ${defaults_1.MAX_DURATION_MS}, got ${value}`,
+                    type: names_1.TYPE_BAD_OPTIONS,
+                    nonRetryable: true,
+                });
+            }
+        }
+        if (capMs < delayMs) {
+            throw workflow_1.ApplicationFailure.create({
+                message: `writeDurable: maxPollIntervalMs (${capMs}) must not be below pollIntervalMs (${delayMs})`,
+                type: names_1.TYPE_BAD_OPTIONS,
+                nonRetryable: true,
+            });
+        }
+        const start = await this.writeAsyncStart(text, {
+            extractionLogic: options.extractionLogic ?? 'deep',
+            structuredMutations: options.structuredMutations,
+            diffEngine: options.diffEngine,
+        });
+        // `Date.now()` is workflow time inside a Temporal workflow, so this is
+        // replay-safe.
+        const deadline = Date.now() + maxWaitMs;
+        let warnedHistory = false;
+        let lastStatus;
+        const maxWaitElapsed = () => workflow_1.ApplicationFailure.create({
+            message: `xmemory write ${start.writeId} did not complete within ${maxWaitMs}ms`,
+            type: names_1.TYPE_WRITE_TIMEOUT,
+            nonRetryable: true,
+            details: [{ writeId: start.writeId, lastStatus: lastStatus ?? 'unknown' }],
+        });
+        let final = false;
+        for (;;) {
+            let leftMs = deadline - Date.now();
+            if (leftMs <= 0 && !final)
+                throw maxWaitElapsed();
+            // Ordinary polls are bounded by the wait. The last observation happens *at*
+            // the deadline and gets one ordinary budget: the grace on top of the wait.
+            const boundMs = final ? statusBudgetMs : Math.min(leftMs, statusBudgetMs);
+            let backoffMs = delayMs;
+            let hintMs;
+            try {
+                const status = await this.pollStatus(start.writeId, boundMs, final);
+                lastStatus = status.writeStatus;
+                const terminal = interpretStatus(status);
+                if (terminal)
+                    return terminal;
+            }
+            catch (err) {
+                // Cancellation must reach the caller as cancellation, not as a timeout
+                // verdict we invented.
+                if ((0, workflow_1.isCancellation)(err))
+                    throw err;
+                if (!(err instanceof common_1.ActivityFailure))
+                    throw err;
+                const cause = err.cause;
+                if (cause instanceof common_1.ApplicationFailure && cause.nonRetryable)
+                    throw err;
+                // A `nonRetryableErrorTypes` match is reported here, not on the cause,
+                // whose own `nonRetryable` stays false. Polling on would hide the failure
+                // behind a timeout verdict of our own.
+                if (err.retryState === common_1.RetryState.NON_RETRYABLE_FAILURE)
+                    throw err;
+                // A poll ending is not the wait ending: Temporal stops one when its retries
+                // are spent. Honor the server's pacing, which arrives in `details`.
+                const detail = (cause instanceof common_1.ApplicationFailure ? cause.details?.[0] : undefined);
+                if (typeof detail?.retryAfterSeconds === 'number') {
+                    hintMs = detail.retryAfterSeconds * 1_000;
+                    backoffMs = Math.max(backoffMs, hintMs);
+                }
+            }
+            // Polling grows history, and this helper cannot call continueAsNew from
+            // inside the caller's workflow. Surface Temporal's own signal so they can
+            // move the durable write into a child workflow. Checked every iteration, so
+            // a loop that is about to stop still reports it.
+            if (!warnedHistory && (0, workflow_1.workflowInfo)().continueAsNewSuggested) {
+                warnedHistory = true;
+                workflow_1.log.warn('xmemory writeDurable has polled into a history Temporal suggests continuing-as-new', {
+                    writeId: start.writeId,
+                    hint: 'run it in a child workflow, or raise maxPollIntervalMs',
+                });
+            }
+            if (final)
+                throw maxWaitElapsed();
+            // Decided on the clock, not the budget allocated before the poll: a fast
+            // reply must leave room for the next one.
+            leftMs = deadline - Date.now();
+            if (backoffMs < leftMs) {
+                await (0, workflow_1.sleep)(backoffMs);
+                delayMs = Math.min(delayMs * 1.5, capMs);
+                continue;
+            }
+            if (hintMs !== undefined && hintMs > leftMs) {
+                // The server will not answer before the deadline, so a last look would only
+                // arrive early.
+                await (0, workflow_1.sleep)(Math.max(0, leftMs));
+                throw maxWaitElapsed();
+            }
+            // Our own cadence does not fit. Wait the rest of the wait out, then take one
+            // last look: the write may still land inside it.
+            final = true;
+            await (0, workflow_1.sleep)(Math.max(0, leftMs));
+        }
+    }
+    /** The configured total bound, as proxy options. Empty when none is set. */
+    totalBound() {
+        return this.opts.totalTimeout === undefined ? {} : { scheduleToCloseTimeout: this.opts.totalTimeout };
+    }
+    /** The tighter of the loop's own bound and the caller's `totalTimeout`. */
+    pollBound(bound) {
+        if (bound === undefined)
+            return this.totalBound();
+        if (this.opts.totalTimeout === undefined)
+            return { scheduleToCloseTimeout: bound };
+        // Temporal already accepted `totalTimeout` when it scheduled the enqueue.
+        return { scheduleToCloseTimeout: Math.min((0, common_1.msToNumber)(bound), (0, common_1.msToNumber)(this.opts.totalTimeout)) };
+    }
+    summary(op, content, logic) {
+        const label = logic ? `xmemory ${op} (${logic})` : `xmemory ${op}`;
+        return this.opts.includeContent ? `${label}: ${content.slice(0, 60)}` : `${label}: ${content.length} chars`;
+    }
+}
+exports.WorkflowXmemory = WorkflowXmemory;
+function interpretStatus(status) {
+    const value = status.writeStatus;
+    if (value === STATUS_COMPLETED)
+        return status;
+    if (value === STATUS_FAILED) {
+        // The server's detail never leaves the worker: Temporal persists both Activity
+        // results and failure details to cleartext history.
+        throw workflow_1.ApplicationFailure.create({
+            message: `xmemory write ${status.writeId} failed`,
+            type: names_1.TYPE_WRITE_FAILED,
+            nonRetryable: true,
+            details: [{ writeId: status.writeId, writeStatus: status.writeStatus }],
+        });
+    }
+    if (value === STATUS_NOT_FOUND) {
+        // `writeAsync` is transactional, so a returned id is always queryable. A
+        // not_found here means the write is genuinely gone.
+        throw workflow_1.ApplicationFailure.create({
+            message: `xmemory write ${status.writeId} not found`,
+            type: names_1.TYPE_WRITE_NOT_FOUND,
+            nonRetryable: true,
+            details: [{ writeId: status.writeId }],
+        });
+    }
+    // In-progress or unrecognized: keep polling. The enum has grown before, and a new
+    // state must not fail in-flight writes.
+    if (!STATUS_IN_PROGRESS.has(value)) {
+        workflow_1.log.warn('xmemory returned an unrecognized write status; continuing to poll', {
+            writeId: status.writeId,
+            writeStatus: value,
+        });
+    }
+    return null;
+}
+/**
+ * A {@link WorkflowXmemory} handle. Carries only configuration (no per-call
+ * mutable state), so making a fresh one per call is correct and cheap.
+ */
+function xmemoryForWorkflow(options = {}) {
+    return new WorkflowXmemory(options ?? {});
+}
+// Re-exported here so workflow code can branch on a failure's `type` without
+// importing the package root, which pulls in the worker and client modules.
+var names_2 = require("./names");
+Object.defineProperty(exports, "TYPE_AUTH_FAILED", { enumerable: true, get: function () { return names_2.TYPE_AUTH_FAILED; } });
+Object.defineProperty(exports, "TYPE_BAD_OPTIONS", { enumerable: true, get: function () { return names_2.TYPE_BAD_OPTIONS; } });
+Object.defineProperty(exports, "TYPE_BAD_REQUEST", { enumerable: true, get: function () { return names_2.TYPE_BAD_REQUEST; } });
+Object.defineProperty(exports, "TYPE_DAILY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_2.TYPE_DAILY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_DEADLINE_EXPIRED", { enumerable: true, get: function () { return names_2.TYPE_DEADLINE_EXPIRED; } });
+Object.defineProperty(exports, "TYPE_MONTHLY_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_2.TYPE_MONTHLY_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_NOT_BOUND", { enumerable: true, get: function () { return names_2.TYPE_NOT_BOUND; } });
+Object.defineProperty(exports, "TYPE_NOT_FOUND", { enumerable: true, get: function () { return names_2.TYPE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_NO_DEADLINE", { enumerable: true, get: function () { return names_2.TYPE_NO_DEADLINE; } });
+Object.defineProperty(exports, "TYPE_QUOTA_EXCEEDED", { enumerable: true, get: function () { return names_2.TYPE_QUOTA_EXCEEDED; } });
+Object.defineProperty(exports, "TYPE_RATE_LIMITED", { enumerable: true, get: function () { return names_2.TYPE_RATE_LIMITED; } });
+Object.defineProperty(exports, "TYPE_SCHEMA_REJECTED", { enumerable: true, get: function () { return names_2.TYPE_SCHEMA_REJECTED; } });
+Object.defineProperty(exports, "TYPE_SERVER_ERROR", { enumerable: true, get: function () { return names_2.TYPE_SERVER_ERROR; } });
+Object.defineProperty(exports, "TYPE_UNAVAILABLE", { enumerable: true, get: function () { return names_2.TYPE_UNAVAILABLE; } });
+Object.defineProperty(exports, "TYPE_UNKNOWN", { enumerable: true, get: function () { return names_2.TYPE_UNKNOWN; } });
+Object.defineProperty(exports, "TYPE_WRITE_FAILED", { enumerable: true, get: function () { return names_2.TYPE_WRITE_FAILED; } });
+Object.defineProperty(exports, "TYPE_WRITE_NOT_FOUND", { enumerable: true, get: function () { return names_2.TYPE_WRITE_NOT_FOUND; } });
+Object.defineProperty(exports, "TYPE_WRITE_TIMEOUT", { enumerable: true, get: function () { return names_2.TYPE_WRITE_TIMEOUT; } });

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@xmemory/temporal",
+  "version": "1.0.0",
+  "description": "Temporal plugin for xmemory \u2014 durable agent memory as Temporal Activities",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xmemory-ai/xmemory-temporal-ts.git"
+  },
+  "homepage": "https://github.com/xmemory-ai/xmemory-temporal-ts#readme",
+  "bugs": {
+    "url": "https://github.com/xmemory-ai/xmemory-temporal-ts/issues"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "default": "./dist/workflow.js"
+    }
+  },
+  "//sideEffects": "No module has import-time side effects, so a bundler can drop what a consumer does not use. Workflow code imports @xmemory/temporal/workflow, a leaf that reaches no Activity or client code.",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "//pin": "The @temporalio worker plugin surface is experimental; pin to the 1.20.x line (~) rather than allowing 1.x minors, so a plugin-API change cannot land unreviewed.",
+  "dependencies": {
+    "xmemory": "^3.8.3"
+  },
+  "devDependencies": {
+    "@temporalio/activity": "~1.20.0",
+    "@temporalio/client": "~1.20.0",
+    "@temporalio/common": "~1.20.0",
+    "@temporalio/testing": "~1.20.0",
+    "@temporalio/worker": "~1.20.0",
+    "@temporalio/workflow": "~1.20.0",
+    "@types/ms": "^2.1.0",
+    "@types/node": "^22",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc --noEmit -p tsconfig.test.json",
+    "test": "tsc --noEmit -p tsconfig.test.json && node --import tsx --test test/*.test.ts",
+    "check:bundle": "node --import tsx scripts/check-workflow-bundle.ts",
+    "check:declarations": "node --import tsx scripts/check-declarations.ts",
+    "check:smoke": "node --import tsx scripts/check-package-smoke.ts",
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "@temporalio/activity": "~1.20.0",
+    "@temporalio/client": "~1.20.0",
+    "@temporalio/common": "~1.20.0",
+    "@temporalio/worker": "~1.20.0",
+    "@temporalio/workflow": "~1.20.0"
+  },
+  "//peer": "The Worker plugin contract is the host SDK's, and a plugin that bundles its own copy would run against a second, different Temporal runtime \u2014 the host's Worker would not even recognise it. Declared as peers so one SDK is installed, and kept in devDependencies for building and testing here."
+}