@xmemory/temporal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) xmemory Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,27 @@
+xmemory Temporal integration
+Copyright (c) xmemory Inc.
+
+This product is licensed under the MIT License (see LICENSE). The following
+notices supplement — but do not modify — that license.
+
+SCOPE. The MIT license covers only this Temporal integration — the source code
+in this directory (the `xmemory-temporal` and `@xmemory/temporal` plugin
+packages), which is a thin client over the xmemory API wired into Temporal.
+
+PROPRIETARY SERVICE. The xmemory service that this integration talks to, and the
+underlying technology behind it — including the xmemory backend, its memory
+engine, schemas, extraction and reader models, APIs, and hosted
+infrastructure — are proprietary to xmemory Inc. and are NOT licensed under the
+MIT license. Nothing in this license grants any right to access, copy, reverse
+engineer, reimplement, or create derivative works of the xmemory service or its
+underlying technology. Use of the service is governed by the Terms & Conditions
+at https://xmemory.ai/terms-and-conditions.html and the Privacy Policy at
+https://xmemory.ai/privacy-policy.html, and requires valid credentials issued by
+xmemory Inc.
+
+TRADEMARKS. The "xmemory" name and logo are trademarks of xmemory Inc. The MIT
+license does not grant permission to use them, except as required for reasonable
+and customary use in describing the origin of the Software. "Temporal" is a
+trademark of Temporal Technologies, Inc.; this is an independent, unofficial
+integration and is not affiliated with, endorsed by, or sponsored by Temporal
+Technologies, Inc.

package/README.md

@@ -0,0 +1,371 @@
+# @xmemory/temporal
+
+Durable agent memory for [Temporal](https://temporal.io) — add
+[xmemory](https://xmemory.ai) reads and writes to your workflows as replay-safe
+Temporal Activities, with one plugin line on your Worker.
+
+> An agent's memory is exactly the state you don't want to lose when a worker
+> crashes mid-turn. Putting xmemory behind Temporal makes a memory write a
+> durable step: it survives process death, redeploys, and rolling upgrades, and
+> Temporal — not your code — owns its retries and timeouts.
+
+A Python port with the same API ships as
+[`xmemory-temporal`](https://github.com/xmemory-ai/xmemory-temporal).
+
+### Memory is untrusted data, both ways
+
+What goes in is user-controlled text. What comes back is that text plus whatever
+the extraction engine made of it. Neither is a safe source of instructions: a read
+result in a prompt is the indirect prompt-injection path, and the same string in a
+shell or a query is the ordinary injection path. Quote it, bound it, and keep it
+out of anything that decides what to do next.
+
+## What you get
+
+- **Memory as Activities.** `read`, `write`, `writeAsyncStart` + `writeStatus` run as
+  Activities (all I/O stays out of workflow code, so workflows replay
+  deterministically).
+- **A durable deep write.** `writeDurable(text)` enqueues a write and polls it to
+  completion from the workflow, so a multi-minute extraction survives worker
+  restarts — the poll state lives in workflow history, not a worker process.
+- **A near-zero-diff migration.** The workflow-side handle mirrors the plain
+  xmemory client's methods, so agent code that already calls `inst.read(...)` /
+  `inst.write(...)` keeps working — it just dispatches to an Activity. Two
+  deliberate differences: the enqueue is `writeAsyncStart` (the client calls it
+  `writeAsync`), and results are projected into this package's own DTOs so a
+  client field rename cannot break replay of a completed workflow.
+- **Temporal-owned retries and timeouts.** xmemory errors map to typed
+  `ApplicationFailure`s with retryable/non-retryable verdicts, so you can tune
+  `RetryPolicy` against stable error-type strings.
+- **Opt-in auto-capture** of activity results into memory, via an Activity
+  interceptor that never touches the replay path.
+
+## Install
+
+```bash
+npm install @xmemory/temporal
+```
+
+Requires Node.js 22.12+ and `@temporalio/*` 1.20.
+
+Two things to know if you type-check with `skipLibCheck: false`:
+
+- Add `@types/ms` to your own devDependencies. `@temporalio/common` references
+  `ms`, which ships no types.
+- Use `@types/node` 22 or 24. Temporal's own declarations do not compile against
+  25 or newer (`EventEmitter<[never]>` fails its own constraint, still true in
+  `@temporalio/worker` 1.22.0), so those need `skipLibCheck: true` until the SDK
+  catches up. The runtime is unaffected — only the types.
+
+## Quickstart
+
+Register the plugin on your **Worker**:
+
+```ts
+import { NativeConnection, Worker } from '@temporalio/worker';
+import { XmemoryPlugin } from '@xmemory/temporal';
+
+const plugin = new XmemoryPlugin({ instanceId: '<your-instance-id>' }); // reads XMEM_API_KEY
+const connection = await NativeConnection.connect({ address: 'localhost:7233' });
+const worker = await Worker.create({
+  connection,
+  taskQueue: 'my-agent',
+  workflowsPath: require.resolve('./workflows'),
+  plugins: [plugin],
+});
+```
+
+Then call memory from inside a workflow:
+
+```ts
+// workflows.ts
+import { xmemoryForWorkflow } from '@xmemory/temporal/workflow';
+
+export async function myWorkflow(userName: string, userMessage: string): Promise<unknown> {
+  const mem = xmemoryForWorkflow();
+  // Name whom the fact is about — a memory store has no ambient "current user".
+  await mem.writeDurable(`${userName}: ${userMessage}`);
+  return (await mem.read(`what do we know about ${userName}?`)).readerResult;
+}
+```
+
+One worker, one instance. The activities bind to whatever instance the plugin
+configured, so **every worker polling a task queue must share that configuration**.
+Per-tenant isolation means a task queue per tenant, not a per-workflow option; the
+example above uses one shared instance and names the user in the text rather than
+isolating them.
+
+Which queue is a trust decision: derive the tenant from an authenticated identity,
+never from a caller- or model-supplied value. A workflow argument naming a task
+queue is a request to read someone else's memory.
+
+Workflow code imports from **`@xmemory/temporal/workflow`**, not the package
+root. That subpath is a leaf: it reaches no Activity code and no xmemory client,
+so Temporal's workflow bundler accepts it. The root entry loads the plugin and
+the client, which the bundler rejects by design, so it belongs in worker setup
+only. A CI step bundles a workflow against the built package to keep it that
+way.
+
+> **Use one plugin instance per Worker.** The bound client lives in a per-plugin
+> holder, so reusing one plugin object across two Workers is last-bind-wins.
+
+Runnable end-to-end scripts live in [`examples/`](./examples): create an instance
+with a schema, run a worker, and drive a support-agent workflow.
+
+## Timeouts
+
+**The workflow owns every activity budget.** `xmemoryForWorkflow()` sets each
+call's `startToCloseTimeout`, and the activity derives its xmemory client timeout
+from the deadline Temporal assigned it, always a margin below, so the client gives
+up first and you get an attributable xmemory error instead of an opaque Temporal
+activity timeout. An activity scheduled with neither close timeout fails fast with
+`XmemoryNoDeadline` rather than picking a budget of its own.
+
+The margin covers the whole attempt, including work Temporal does before the
+activity function runs. Keep it larger than your Client-level activity interceptors.
+The ordering holds above timer resolution: a deadline of a few milliseconds is too
+short to fit a call and a margin, and which side fires first is then a coin toss.
+
+```ts
+const mem = xmemoryForWorkflow({
+  readTimeout: '60s',      // a deep read on a large instance
+  writeTimeout: '5m',
+});
+```
+
+The client timeout is derived, not configured separately, so lowering a workflow's
+budget lowers the client's with it. `DEFAULT_TIMEOUTS` supplies the defaults;
+`{ clientMarginMs }` tunes the gap.
+
+Each of those bounds one **attempt**. Nothing bounds the retry sequence unless you
+say so: a server asking for an hour before the next try is honoured as asked, so a
+rate-limited read can sit in retries far longer than its own timeout suggests. Set
+`totalTimeout` when a call has a deadline of its own — it becomes the activity's
+`scheduleToCloseTimeout`, covering every attempt.
+
+```ts
+const mem = xmemoryForWorkflow({ readTimeout: '30s', totalTimeout: '2m' });
+```
+
+**A timed-out write is indeterminate.** Nothing distinguishes "never arrived" from
+"arrived, response lost", and the request is abandoned rather than cancelled (the
+client exposes no `AbortSignal`). So write Activities default to
+`maximumAttempts: 1` and surface the failure. Treat a timed-out write as *may or may
+not have happened*, and reconcile with a read if it matters.
+
+## Durable writes
+
+`writeDurable(text)` enqueues a deep write and polls it to completion from the
+workflow, so the wait is a Temporal timer in server-side history rather than a
+blocked activity slot. Redeploy the worker fleet mid-write and nothing is lost:
+the poll loop resumes on the new worker and completes.
+
+```ts
+const status = await mem.writeDurable(text, { maxWaitMs: 15 * 60_000 });
+```
+
+Each poll adds history events — an activity, a timer, and the workflow tasks driving
+them — and how many is a detail of your SDK and server versions, not something this
+package can predict for you. Backoff slows the growth until the interval reaches
+`maxPollIntervalMs`, after which history grows linearly with the wait. Keep
+`pollIntervalMs` at seconds rather than milliseconds, since that history is shared
+with the rest of your workflow; the loop warns once Temporal itself suggests
+continuing as new.
+
+Two different kinds of pacing sit here, so the names are worth separating.
+`pollIntervalMs` and `maxPollIntervalMs` set how long the loop waits *between*
+polls. `writeStatusRetry` sets how one poll retries when it fails — attempts and
+backoff for the activity itself:
+
+```ts
+const mem = xmemoryForWorkflow({
+  writeStatusRetry: { attempts: 4, intervalMs: 2_000, maxIntervalMs: 8_000 },
+});
+```
+
+Those are plain numbers rather than a Temporal `RetryPolicy`, and this package
+builds the policy from them. Temporal compiles a policy when it schedules the
+activity, which for the first poll is *after* the write is enqueued — so a policy it
+refuses would leave a queued write nobody is watching. There is no policy to refuse
+if the package builds it.
+
+This helper cannot call `continueAsNew` for you — it runs inside *your* workflow,
+and restarting that would discard your state. For multi-hour waits, run
+`writeDurable` in a child workflow.
+
+`maxWaitMs` bounds the *waiting*: every poll is scheduled to finish inside it. The
+one exception is the last observation, which happens **at** the deadline so a write
+that lands late is still seen rather than reported as a timeout — so a call can
+return up to one status poll after `maxWaitMs`. When the server has asked for a
+retry delay longer than the wait has left, that final poll is skipped instead:
+arriving before the server said it would answer is worse than not looking.
+
+For the fire-and-forget pattern (kick off several writes, keep working, join
+before the turn ends), `writeAsyncStart()` and `writeStatus()` are public too.
+
+## Credentials never reach workflow history
+
+The config holds the **name** of the environment variable that supplies the API
+key (`XMEM_API_KEY` by default), never the key itself — so nothing secret is ever
+serialized into activity arguments, which Temporal persists in the clear. Pass
+the key in-process instead with `new XmemoryPlugin(config, { apiKey })` if you
+prefer.
+
+**Your memory text and queries, however, *are* in history.** Queries, written text,
+and `readerResult` are activity payloads, persisted in the clear and visible in the
+Web UI. The error mapping keeps raw transport strings and the server's failure
+detail out of failures (set `logServerErrorDetail: true` to log the reason
+worker-side), but the payloads themselves remain.
+
+`includeContentInSummary: false` (the default) only affects the one-line activity
+*summary*. For sensitive memory text, install a Temporal **Payload Codec**; this
+plugin does not impose one, since a codec applies to every payload in the
+namespace, not just xmemory's.
+
+## Replay safety and idempotency
+
+Two things keep memory operations correct under retries and replay:
+
+- **Replay never re-issues an operation.** All I/O is in Activities; workflow
+  code only schedules Activities and sleeps. Temporal replays workflow code but
+  never re-runs a completed Activity, so a replay never repeats a memory read or
+  write. The suite proves this with a forced-replay (`maxCachedWorkflows: 0`)
+  side-effects test.
+- **Writes default to at-most-once.** Primary-key dedup looks like it would make
+  retries safe, but PK extraction is non-deterministic: a model normalizes the same
+  value differently across runs (`Dr. Robert Kim` vs `Robert Kim`), and a
+  disagreement forks a new row. So a lost-response retry can duplicate. Write
+  Activities default to `maximumAttempts: 1` and surface the failure to your
+  workflow. Reads and status polls are idempotent and retry generously.
+
+**Structured writes are the reliable way to make a write retryable.** Pass
+explicit mutations instead of free text and the primary key is one you supply, so
+nothing is extracted and re-applying the write is deterministic.
+
+Retrying is opted into per handle, through `writeRetryPolicy`, and an opted-in handle
+is no longer at-most-once: every write through it retries, text writes and creates
+included. So give keyed structured writes a handle of their own, and keep the
+default handle for everything else. Always set `maximumAttempts` — Temporal reads an
+omitted one as unlimited.
+
+```ts
+const keyedWrites = xmemoryForWorkflow({ writeRetryPolicy: { maximumAttempts: 3 } });
+await keyedWrites.write('', {
+  structuredMutations: [
+    {
+      object_mutation: {
+        object_type: 'Customer',
+        update: { key: { customerId: 'c-1' }, values: { tier: 'gold' } },
+      },
+    },
+  ],
+});
+```
+
+A mutation is a `create`, `update`, or `delete` on one object or relation. An
+update or delete names the key it addresses, so a retry hits the same row. A create
+does not — the server assigns the key — so a create is not safe to retry.
+
+For text writes, opt into retries only when your primary keys are literal
+identifiers appearing verbatim in the text, such as a `customerId` you supply. That
+is a convention you keep, not something the API enforces.
+
+[`examples/setup-memory.ts`](./examples/setup-memory.ts) shows creating an
+instance with a schema.
+
+## Error handling
+
+xmemory errors become `ApplicationFailure`s with stable `type` strings you can
+match in a `RetryPolicy` (`nonRetryableErrorTypes: [...]`). The mapping is
+derived from the server's error codes:
+
+| xmemory condition | `type` | Retryable? |
+|---|---|---|
+| transport error / timeout / HTTP ≥ 500 / 408 | `XmemoryServerError` / `XmemoryUnavailable` | yes |
+| `RATE_LIMITED` (429) | `XmemoryRateLimited` | yes — honors `Retry-After` |
+| `QUOTA_EXCEEDED` + `daily_quota_exceeded` | `XmemoryDailyQuotaExceeded` | yes (long backoff) |
+| `QUOTA_EXCEEDED` + `monthly_quota_exceeded` | `XmemoryMonthlyQuotaExceeded` | no |
+| `QUOTA_EXCEEDED` (kind unknown) | `XmemoryQuotaExceeded` | no |
+| `UNAUTHORIZED` / `FORBIDDEN` | `XmemoryAuthFailed` | no |
+| `NOT_FOUND` | `XmemoryNotFound` | no |
+| validation / conflict / schema-evolution rejections | `XmemoryBadRequest` / `XmemorySchemaRejected` | no |
+| activities registered without the plugin | `XmemoryNotBound` | no |
+| an activity scheduled with neither close timeout | `XmemoryNoDeadline` | no |
+| durable-write options that cannot be honored | `XmemoryBadOptions` | no — the same arguments fail identically |
+| an unrecognized code | `XmemoryUnknown` | follows the HTTP status |
+
+Plus three raised by the durable write loop (`writeDurable`), from a polled
+`writeStatus`, all non-retryable:
+
+| durable-write outcome | `type` |
+|---|---|
+| the queued write reported `failed` | `XmemoryWriteFailed` |
+| the queued write id was `not_found` | `XmemoryWriteNotFound` |
+| polling exceeded `maxWait` | `XmemoryWriteTimeout` |
+
+An unrecognized error code never raises and keeps its own type — a stricter client
+that crashed on a newer server's code would break during rolling deploys. Whether it
+is retried comes from the HTTP status rather than the code: 5xx, 408, 429 and a
+missing status are retried, while a 4xx is terminal however it is labelled. Retrying
+a 401 until the attempts run out helps nobody, and on a write it repeats a call that
+cannot succeed.
+
+> **Note.** 402 means `QUOTA_EXCEEDED` only. `TRIAL_ENDED` was removed from the
+> xmemory contract when trials were retired end-to-end; do not rely on it.
+
+## Auto-capture (opt-in)
+
+```ts
+const plugin = new XmemoryPlugin(
+  { instanceId: '<your-instance-id>' },
+  {
+    autoCapture: {
+      project: (activityName, result) => summarize(result), // return undefined to skip
+      sampleRate: 0.25,
+    },
+  },
+);
+```
+
+Off by default. It runs as an **Activity** interceptor, outside the replay path;
+`project` decides what to remember, sampling bounds fan-out, and a capture failure
+never fails the wrapped activity. Capture is an enqueue (`writeAsync`) clamped to
+what the activity has left of its deadline, and skipped when nothing is left, so it
+cannot push the activity past its `startToClose`.
+
+Your `project` function is the exception: it is synchronous code, and JavaScript
+cannot interrupt it. One that blocks longer than the activity has left will push it
+past the deadline however carefully the enqueue is budgeted. Keep projections
+cheap.
+
+> **Auto-capture is at-least-once.** If a worker dies after the capture enqueue but
+> before the Activity's completion is recorded, the Activity runs again and captures
+> again — and since primary keys are extracted, a duplicate can fork an entity.
+> Capture facts a duplicate would not corrupt.
+
+> **Naming caveat.** Auto-capture skips any activity whose name starts with
+> `xmemory_` (to avoid capturing its own writes). If you name one of *your* own
+> activities `xmemory_...`, it will be silently skipped. It also never captures
+> Queries.
+
+## Testing
+
+```bash
+npm ci
+npm run lint    # tsc over src + test + examples (strict)
+npm test        # tsc, then node:test over test/*.test.ts
+```
+
+The suite runs with no live backend (a fake instance is injected). See
+[`TESTING.md`](./TESTING.md) for the full strategy.
+
+## Legal
+
+- Privacy policy: <https://xmemory.ai/privacy-policy.html>
+- Terms: <https://xmemory.ai/terms-and-conditions.html>
+
+**MIT licensed** — see [`LICENSE`](./LICENSE). The grant covers this integration's
+code only. The xmemory service and its technology remain proprietary to xmemory
+Inc.; using it requires valid credentials and is governed by the Terms above. The
+scope and trademark notices live in [`NOTICE`](./NOTICE), kept separate so the
+package classifies cleanly as MIT.

package/dist/activities.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The xmemory activities: the only place this package does I/O.
+ *
+ * The client is injected through a holder, so tests substitute a fake with no
+ * patching. Each call's client timeout is derived from the deadline Temporal
+ * assigned the activity.
+ */
+import type { InstanceHandle } from 'xmemory';
+import type { XmemoryConfig } from './config';
+import { type ReadInput, type ReadOutput, type WriteInput, type WriteOutput, type WriteStartOutput, type WriteStatusInput, type WriteStatusOutput } from './dto';
+import { ACTIVITY_READ, ACTIVITY_WRITE, ACTIVITY_WRITE_START, ACTIVITY_WRITE_STATUS } from './names';
+export { ACTIVITY_READ, ACTIVITY_WRITE, ACTIVITY_WRITE_START, ACTIVITY_WRITE_STATUS };
+/** The client methods this package calls. Injectable, so tests need no backend. */
+export type XmemoryInstance = Pick<InstanceHandle, 'read' | 'write' | 'writeAsync' | 'writeStatus'>;
+/** Holds the injected client so activity functions can close over it. */
+export declare class InstanceHolder {
+    private instance;
+    bind(instance: XmemoryInstance): void;
+    get(): XmemoryInstance;
+}
+export interface XmemoryActivities {
+    [ACTIVITY_READ]: (input: ReadInput) => Promise<ReadOutput>;
+    [ACTIVITY_WRITE]: (input: WriteInput) => Promise<WriteOutput>;
+    [ACTIVITY_WRITE_START]: (input: WriteInput) => Promise<WriteStartOutput>;
+    [ACTIVITY_WRITE_STATUS]: (input: WriteStatusInput) => Promise<WriteStatusOutput>;
+}
+export declare function createActivities(holder: InstanceHolder, config: XmemoryConfig): XmemoryActivities;

package/dist/activities.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * The xmemory activities: the only place this package does I/O.
+ *
+ * The client is injected through a holder, so tests substitute a fake with no
+ * patching. Each call's client timeout is derived from the deadline Temporal
+ * assigned the activity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstanceHolder = exports.ACTIVITY_WRITE_STATUS = exports.ACTIVITY_WRITE_START = exports.ACTIVITY_WRITE = exports.ACTIVITY_READ = void 0;
+exports.createActivities = createActivities;
+const activity_1 = require("@temporalio/activity");
+const common_1 = require("@temporalio/common");
+const deadline_1 = require("./deadline");
+const defaults_1 = require("./defaults");
+const dto_1 = require("./dto");
+const errors_1 = require("./errors");
+const names_1 = require("./names");
+Object.defineProperty(exports, "ACTIVITY_READ", { enumerable: true, get: function () { return names_1.ACTIVITY_READ; } });
+Object.defineProperty(exports, "ACTIVITY_WRITE", { enumerable: true, get: function () { return names_1.ACTIVITY_WRITE; } });
+Object.defineProperty(exports, "ACTIVITY_WRITE_START", { enumerable: true, get: function () { return names_1.ACTIVITY_WRITE_START; } });
+Object.defineProperty(exports, "ACTIVITY_WRITE_STATUS", { enumerable: true, get: function () { return names_1.ACTIVITY_WRITE_STATUS; } });
+/** Holds the injected client so activity functions can close over it. */
+class InstanceHolder {
+    instance;
+    bind(instance) {
+        this.instance = instance;
+    }
+    get() {
+        if (!this.instance) {
+            // The plugin's runWorker hook never bound a client. Retrying cannot fix it.
+            throw common_1.ApplicationFailure.create({
+                message: 'xmemory activities are not bound to a client — register XmemoryPlugin on the Worker ' +
+                    'rather than registering the activity functions directly.',
+                type: errors_1.TYPE_NOT_BOUND,
+                nonRetryable: true,
+            });
+        }
+        return this.instance;
+    }
+}
+exports.InstanceHolder = InstanceHolder;
+/**
+ * What to hand the client: the text, or the mutations when there are any.
+ *
+ * Checked at runtime, because activity inputs arrive as JSON and nothing enforces
+ * their TypeScript types. The client's `write` and `writeAsync` are overloaded on
+ * the first argument and treat anything but a string as structured mutations, so a
+ * `text` that arrived as an array would skip extraction and apply as an update or
+ * delete, and a `structuredMutations` string would be written as memory.
+ *
+ * An empty list is refused too: the client answers `[]` with a plain Error, which
+ * the mapper reads as a retryable transport failure. Called outside the try, or
+ * `toApplicationFailure` would remap the verdict.
+ */
+function requireWritePayload(input) {
+    const mutations = input.structuredMutations ?? undefined;
+    if (mutations !== undefined) {
+        if (!Array.isArray(mutations)) {
+            throw badOptions(`xmemory structuredMutations must be a list of mutations, got ${kindOf(mutations)}`);
+        }
+        if (mutations.length === 0) {
+            throw badOptions('xmemory write was given an empty structuredMutations list; omit it to write text instead');
+        }
+        return mutations;
+    }
+    const text = input.text;
+    if (typeof text !== 'string') {
+        throw badOptions(`xmemory write text must be a string, got ${kindOf(text)}`);
+    }
+    return text;
+}
+// The kind only, never the value: failure messages are persisted to history.
+function kindOf(value) {
+    return value === null ? 'null' : Array.isArray(value) ? 'an array' : typeof value;
+}
+function badOptions(message) {
+    return common_1.ApplicationFailure.create({ message, type: errors_1.TYPE_BAD_OPTIONS, nonRetryable: true });
+}
+function createActivities(holder, config) {
+    const defaultLogic = config.defaultExtractionLogic ?? 'fast';
+    /**
+     * Client budget for the running activity, from its own deadline. Derived rather
+     * than kept as a second worker-side copy, so "the client gives up first" holds
+     * even when a workflow lowers its timeout.
+     */
+    const budgetMs = () => {
+        const info = activity_1.Context.current().info;
+        const deadlineMs = (0, deadline_1.activityBudgetMs)(info);
+        if (deadlineMs === null) {
+            throw common_1.ApplicationFailure.create({
+                message: `activity ${info.activityType} was scheduled without a deadline: ` +
+                    'set startToCloseTimeout or scheduleToCloseTimeout on it.',
+                type: errors_1.TYPE_NO_DEADLINE,
+                nonRetryable: true,
+            });
+        }
+        if (deadlineMs <= 0) {
+            // Temporal has given up on this attempt; a token budget would send a request
+            // nobody reads, and a write the server could still accept.
+            throw common_1.ApplicationFailure.create({
+                message: `activity ${info.activityType} is past its deadline`,
+                type: errors_1.TYPE_DEADLINE_EXPIRED,
+            });
+        }
+        return (0, defaults_1.clientTimeoutMs)(deadlineMs, config.clientMarginMs);
+    };
+    const writeOptions = (input, timeoutMs) => ({
+        extractionLogic: (input.extractionLogic ?? defaultLogic),
+        ...(input.diffEngine !== undefined ? { diffEngine: input.diffEngine } : {}),
+        timeoutMs,
+    });
+    return {
+        async [names_1.ACTIVITY_READ](input) {
+            // Outside the try: an unbound-client or missing-deadline failure must keep
+            // its non-retryable type rather than being re-mapped by toApplicationFailure.
+            const instance = holder.get();
+            const timeoutMs = budgetMs();
+            try {
+                const result = await (0, deadline_1.withDeadline)(instance.read(input.query, {
+                    ...(input.readMode !== undefined ? { readMode: input.readMode } : {}),
+                    ...(input.scope !== undefined ? { scope: input.scope } : {}),
+                    timeoutMs,
+                }), timeoutMs);
+                return (0, dto_1.projectRead)(result);
+            }
+            catch (err) {
+                throw (0, errors_1.toApplicationFailure)(err);
+            }
+        },
+        async [names_1.ACTIVITY_WRITE](input) {
+            const instance = holder.get();
+            const ms = budgetMs();
+            const payload = requireWritePayload(input);
+            try {
+                // A structured write carries its own keys, so the server applies it without
+                // running the extractor; text and extractionLogic are moot.
+                const result = await (0, deadline_1.withDeadline)(typeof payload === 'string'
+                    ? instance.write(payload, writeOptions(input, ms))
+                    : instance.write(payload, { timeoutMs: ms }), ms);
+                return (0, dto_1.projectWrite)(result);
+            }
+            catch (err) {
+                throw (0, errors_1.toApplicationFailure)(err);
+            }
+        },
+        async [names_1.ACTIVITY_WRITE_START](input) {
+            const instance = holder.get();
+            const ms = budgetMs();
+            const payload = requireWritePayload(input);
+            try {
+                return (0, dto_1.projectWriteStart)(await (0, deadline_1.withDeadline)(typeof payload === 'string'
+                    ? instance.writeAsync(payload, writeOptions(input, ms))
+                    : instance.writeAsync(payload, { timeoutMs: ms }), ms));
+            }
+            catch (err) {
+                throw (0, errors_1.toApplicationFailure)(err);
+            }
+        },
+        async [names_1.ACTIVITY_WRITE_STATUS](input) {
+            const instance = holder.get();
+            const timeoutMs = budgetMs();
+            const writeId = input.writeId;
+            try {
+                const result = await (0, deadline_1.withDeadline)(instance.writeStatus(writeId, { timeoutMs }), timeoutMs);
+                const projected = (0, dto_1.projectWriteStatus)(result);
+                if (projected.writeId !== writeId) {
+                    // Before logging: another write's detail would otherwise be logged under
+                    // the id we asked about, and its outcome read as ours.
+                    throw new Error('xmemory returned a status for a different write');
+                }
+                const errorDetail = result.error_detail;
+                if (errorDetail) {
+                    // Never the return value: history keeps Activity results in the clear.
+                    // Not verbatim in the log either unless asked for — the detail is not
+                    // promised user-safe, and logs travel.
+                    activity_1.Context.current().log.warn('xmemory write failed', 
+                    // `=== true`, not truthiness: this config can come from a file or an
+                    // env var, and the string "false" would otherwise turn the detail on.
+                    config.logServerErrorDetail === true
+                        ? { writeId, errorDetail }
+                        : {
+                            writeId,
+                            errorDetailLength: errorDetail.length,
+                            note: 'detail withheld from logs and history; set logServerErrorDetail to include it',
+                        });
+                }
+                return projected;
+            }
+            catch (err) {
+                throw (0, errors_1.toApplicationFailure)(err);
+            }
+        },
+    };
+}