@retinue/agentkit 0.1.0

package/dist/adapters/memory/artifact-exports.js

@@ -0,0 +1,102 @@
+/**
+ * In-memory `ArtifactExportStore` — the reference implementation (#134).
+ *
+ * The only interesting behaviour is `claim`, and it is interesting for one reason: **it must be a claim, not
+ * an insert.** Two requests for the same PDF must produce one render, and the second must be told so rather
+ * than starting a duplicate. A blind insert would render the same document twice and leave two rows pointing
+ * at two identical files.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const tenantMap = (outer, tenantId) => {
+    let inner = outer.get(tenantId);
+    if (!inner)
+        outer.set(tenantId, (inner = new Map()));
+    return inner;
+};
+/** The uniqueness the store enforces: one export per version per format. */
+const slotKey = (artifactId, version, format) => `${artifactId} ${version} ${format}`;
+const assertTimestamp = (at, field) => {
+    if (Number.isNaN(Date.parse(at)))
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `${field} must be an ISO timestamp, got ${JSON.stringify(at)}`,
+            retryable: false,
+        });
+};
+/** Keyset on `(createdAt, id)`, matching the Postgres adapter's encoding so the conformance suite exercises
+ * the real contract rather than a simpler one the reference adapter happened to have. */
+const encodeCursor = (createdAt, id) => Buffer.from(`${createdAt} ${id}`, "utf8").toString("base64url");
+const decodeCursor = (cursor) => {
+    const [createdAt, id] = Buffer.from(cursor, "base64url").toString("utf8").split(" ");
+    return createdAt === undefined || id === undefined ? null : { createdAt, id };
+};
+const paginate = (rows, limit, cursor) => {
+    const sorted = [...rows].sort((a, b) => a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt.localeCompare(b.createdAt));
+    const after = cursor === undefined ? null : decodeCursor(cursor);
+    const start = after === null
+        ? 0
+        : sorted.findIndex((r) => r.createdAt > after.createdAt || (r.createdAt === after.createdAt && r.id > after.id));
+    const from = start < 0 ? sorted.length : start;
+    const items = sorted.slice(from, from + limit);
+    const last = items[items.length - 1];
+    return from + limit < sorted.length && last !== undefined
+        ? { items, nextCursor: encodeCursor(last.createdAt, last.id) }
+        : { items };
+};
+export const createMemoryArtifactExportStore = () => {
+    const byTenant = new Map();
+    const slots = new Map();
+    return {
+        async claim({ tenantId, export: requested }) {
+            assertTimestamp(requested.createdAt, "createdAt");
+            const rows = tenantMap(byTenant, tenantId);
+            const slotIndex = tenantMap(slots, tenantId);
+            const key = slotKey(requested.artifactId, requested.version, requested.format);
+            const existingId = slotIndex.get(key);
+            if (existingId !== undefined) {
+                const existing = rows.get(existingId);
+                // The slot is taken. Returned rather than refused, because the caller's next move is the same either
+                // way: read this row. `claimed: false` is what stops it *rendering*.
+                if (existing !== undefined)
+                    return { claimed: false, export: existing };
+            }
+            const created = { ...requested, state: "pending" };
+            rows.set(created.id, created);
+            slotIndex.set(key, created.id);
+            return { claimed: true, export: created };
+        },
+        async complete({ tenantId, id, state, fileId, byteSize, checksum, failureReason, failureMessage, at }) {
+            assertTimestamp(at, "at");
+            const rows = tenantMap(byTenant, tenantId);
+            const existing = rows.get(id);
+            // Absent means the export was removed under the worker. Reported rather than thrown: an ordinary race,
+            // and a worker that threw would retry a row that no longer exists.
+            if (existing === undefined)
+                return { recorded: false };
+            rows.set(id, {
+                ...existing,
+                state,
+                ...(fileId === undefined ? {} : { fileId }),
+                ...(byteSize === undefined ? {} : { byteSize }),
+                ...(checksum === undefined ? {} : { checksum }),
+                ...(failureReason === undefined ? {} : { failureReason }),
+                ...(failureMessage === undefined ? {} : { failureMessage }),
+                renderedAt: at,
+            });
+            return { recorded: true };
+        },
+        async get({ tenantId, id }) {
+            // Absent from *this tenant's* map, so a foreign id is null without a comparison anyone could get wrong.
+            return tenantMap(byTenant, tenantId).get(id) ?? null;
+        },
+        async find({ tenantId, artifactId, version, format }) {
+            const id = tenantMap(slots, tenantId).get(slotKey(artifactId, version, format));
+            return id === undefined ? null : (tenantMap(byTenant, tenantId).get(id) ?? null);
+        },
+        async listByArtifact({ tenantId, artifactId, limit, cursor }) {
+            const rows = [...tenantMap(byTenant, tenantId).values()].filter((e) => e.artifactId === artifactId);
+            return paginate(rows, limit, cursor);
+        },
+    };
+};
+//# sourceMappingURL=artifact-exports.js.map

package/dist/adapters/memory/artifacts.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-memory `ArtifactStore` — the reference implementation (#133).
+ *
+ * Two things it takes as seriously as the Postgres adapter will, because the conformance suite measures the
+ * others against this one and a laxer reference makes a production failure a passing test (the lesson #129
+ * learned when a placeholder timestamp sailed through here and was rejected by Postgres):
+ *
+ * - **Tenant partitioning is by outer map, not a filter.** An artifact id from one tenant cannot resolve
+ *   another's row because it is not in that tenant's map at all.
+ * - **`addVersion` is a compare-and-set.** A blind append would let two concurrent regenerations both become
+ *   version 2, and one would silently replace the other — which breaks the one property AC-2 asks for.
+ */
+import type { ArtifactStore } from "../../persistence/index.js";
+export declare const createMemoryArtifactStore: () => ArtifactStore;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/adapters/memory/artifacts.js

@@ -0,0 +1,134 @@
+/**
+ * In-memory `ArtifactStore` — the reference implementation (#133).
+ *
+ * Two things it takes as seriously as the Postgres adapter will, because the conformance suite measures the
+ * others against this one and a laxer reference makes a production failure a passing test (the lesson #129
+ * learned when a placeholder timestamp sailed through here and was rejected by Postgres):
+ *
+ * - **Tenant partitioning is by outer map, not a filter.** An artifact id from one tenant cannot resolve
+ *   another's row because it is not in that tenant's map at all.
+ * - **`addVersion` is a compare-and-set.** A blind append would let two concurrent regenerations both become
+ *   version 2, and one would silently replace the other — which breaks the one property AC-2 asks for.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const tenantMap = (outer, tenantId) => {
+    let inner = outer.get(tenantId);
+    if (!inner)
+        outer.set(tenantId, (inner = new Map()));
+    return inner;
+};
+/** Keyset cursor on `(createdAt, id)` — the same encoding the other stores use, for the same reason. */
+const encodeCursor = (createdAt, id) => Buffer.from(`${createdAt} ${id}`, "utf8").toString("base64url");
+const decodeCursor = (cursor) => {
+    const [createdAt, id] = Buffer.from(cursor, "base64url").toString("utf8").split(" ");
+    return createdAt === undefined || id === undefined ? null : { createdAt, id };
+};
+const paginate = (rows, limit, cursor) => {
+    const sorted = [...rows].sort((a, b) => a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt.localeCompare(b.createdAt));
+    const after = cursor === undefined ? null : decodeCursor(cursor);
+    const start = after === null
+        ? 0
+        : sorted.findIndex((r) => r.createdAt > after.createdAt || (r.createdAt === after.createdAt && r.id > after.id));
+    const from = start < 0 ? sorted.length : start;
+    const items = sorted.slice(from, from + limit);
+    const last = items[items.length - 1];
+    return from + limit < sorted.length && last !== undefined
+        ? { items, nextCursor: encodeCursor(last.createdAt, last.id) }
+        : { items };
+};
+/** Versions page on the contiguous version number, which is an exact cursor rather than an approximate one. */
+const paginateVersions = (versions, limit, cursor) => {
+    const after = cursor === undefined ? 0 : Number.parseInt(cursor, 10);
+    const from = Number.isSafeInteger(after) && after > 0 ? after : 0;
+    const sorted = [...versions].sort((a, b) => a.version - b.version);
+    const items = sorted.filter((v) => v.version > from).slice(0, limit);
+    const last = items[items.length - 1];
+    return last !== undefined && sorted.some((v) => v.version > last.version)
+        ? { items, nextCursor: String(last.version) }
+        : { items };
+};
+const assertTimestamp = (at, field) => {
+    if (Number.isNaN(Date.parse(at)))
+        throw new AgentPlatformError({
+            code: "invalid_input",
+            message: `${field} must be an ISO timestamp, got ${JSON.stringify(at)}`,
+            retryable: false,
+        });
+};
+export const createMemoryArtifactStore = () => {
+    const byTenant = new Map();
+    return {
+        async create({ tenantId, artifact, version }) {
+            const entries = tenantMap(byTenant, tenantId);
+            if (entries.has(artifact.id))
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `artifact ${artifact.id} already exists`,
+                    retryable: false,
+                });
+            assertTimestamp(artifact.createdAt, "createdAt");
+            const created = { ...artifact, latestVersion: 1, updatedAt: artifact.createdAt };
+            entries.set(artifact.id, {
+                artifact: created,
+                // Version 1 is created with the artifact: an artifact with no version is not a thing a reader can
+                // resolve, and allowing the state would mean every reader handling it.
+                versions: [{ ...version, artifactId: artifact.id, version: 1 }],
+            });
+            return created;
+        },
+        async addVersion({ tenantId, id, expectedLatestVersion, version }) {
+            const entry = tenantMap(byTenant, tenantId).get(id);
+            // The compare. Two concurrent regenerations both hold `expectedLatestVersion: 1`; exactly one wins,
+            // and the loser is told so rather than silently overwriting the winner's version 2.
+            if (entry === undefined || entry.artifact.latestVersion !== expectedLatestVersion)
+                return { added: false };
+            if (entry.artifact.deletedAt !== undefined)
+                return { added: false };
+            assertTimestamp(version.createdAt, "version.createdAt");
+            const next = expectedLatestVersion + 1;
+            entry.versions.push({ ...version, artifactId: id, version: next });
+            entry.artifact = { ...entry.artifact, latestVersion: next, updatedAt: version.createdAt };
+            return { added: true, version: next };
+        },
+        async get({ tenantId, id }) {
+            // Absent from *this tenant's* map, so a foreign id is null without a comparison anyone could get wrong.
+            return tenantMap(byTenant, tenantId).get(id)?.artifact ?? null;
+        },
+        async getVersion({ tenantId, id, version }) {
+            const entry = tenantMap(byTenant, tenantId).get(id);
+            if (entry === undefined)
+                return null;
+            // The latest by default. A reader who does not ask for a version wants the current one, and an earlier
+            // version stays resolvable by asking — which is AC-2 from the reading side.
+            const wanted = version ?? entry.artifact.latestVersion;
+            return entry.versions.find((v) => v.version === wanted) ?? null;
+        },
+        async listByConversation({ tenantId, conversationId, limit, cursor }) {
+            const rows = [...tenantMap(byTenant, tenantId).values()]
+                .map((e) => e.artifact)
+                // Live only: a deleted artifact reappearing in a conversation is a deleted document coming back.
+                .filter((a) => a.conversationId === conversationId && a.deletedAt === undefined);
+            return paginate(rows, limit, cursor);
+        },
+        async listVersions({ tenantId, id, limit, cursor }) {
+            const entry = tenantMap(byTenant, tenantId).get(id);
+            if (entry === undefined)
+                return { items: [] };
+            // Paged on the version *number*, not on `(createdAt, id)` like every other listing here. Versions are
+            // 1-based and contiguous, so the number is an exact cursor — and two versions created in the same
+            // millisecond would tie under a timestamp keyset, which for a history is the one place order must not
+            // be approximate.
+            return paginateVersions(entry.versions, limit, cursor);
+        },
+        async softDelete({ tenantId, id, at }) {
+            assertTimestamp(at, "at");
+            const entry = tenantMap(byTenant, tenantId).get(id);
+            if (entry === undefined)
+                return { deleted: false };
+            // Idempotent: deleting twice is the same as deleting once, which a retried request depends on.
+            entry.artifact = { ...entry.artifact, deletedAt: entry.artifact.deletedAt ?? at, updatedAt: at };
+            return { deleted: true };
+        },
+    };
+};
+//# sourceMappingURL=artifacts.js.map

package/dist/adapters/memory/blobs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * In-memory blob store — `docs/03` → Tool results. Holds spilled tool output for read-back via
+ * `read_tool_output`. Tenant-partitioned so a `BlobRef` never resolves another tenant's bytes.
+ */
+import type { BlobStore } from "../../persistence/index.js";
+export declare const createMemoryBlobStore: () => BlobStore;
+//# sourceMappingURL=blobs.d.ts.map

package/dist/adapters/memory/blobs.js

@@ -0,0 +1,27 @@
+/**
+ * In-memory blob store — `docs/03` → Tool results. Holds spilled tool output for read-back via
+ * `read_tool_output`. Tenant-partitioned so a `BlobRef` never resolves another tenant's bytes.
+ */
+import { asId } from "../../core/ids.js";
+export const createMemoryBlobStore = () => {
+    const byTenant = new Map();
+    let counter = 0;
+    const tenant = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    return {
+        async put({ tenantId, value }) {
+            const ref = `blob:${tenantId}:${(counter += 1)}`;
+            tenant(tenantId).set(ref, value);
+            return asId(ref);
+        },
+        async get({ tenantId, ref }) {
+            const store = tenant(tenantId);
+            return store.has(ref) ? store.get(ref) : null;
+        },
+    };
+};
+//# sourceMappingURL=blobs.js.map

package/dist/adapters/memory/evaluation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * In-memory `EvaluationStore` — the reference implementation (#141).
+ *
+ * The interesting behaviour is `completeRun`: aggregates are computed from the recorded cases at completion,
+ * not accumulated as they arrive. A run whose totals were accumulated could disagree with its own case rows
+ * after a re-record, and the number that gates a release must be derivable from the evidence behind it.
+ */
+import type { EvalCaseResult, EvalDimensionSummary, EvaluationStore } from "../../persistence/index.js";
+/** Aggregates from the case rows. One function, so the two adapters cannot disagree about what a mean is. */
+export declare const summarise: (cases: readonly EvalCaseResult[]) => {
+    total: number;
+    passed: number;
+    meanScore: number;
+    byDimension: readonly EvalDimensionSummary[];
+    costMinorUnits: number;
+};
+export declare const createMemoryEvaluationStore: () => EvaluationStore;
+//# sourceMappingURL=evaluation.d.ts.map

package/dist/adapters/memory/evaluation.js

@@ -0,0 +1,148 @@
+/**
+ * In-memory `EvaluationStore` — the reference implementation (#141).
+ *
+ * The interesting behaviour is `completeRun`: aggregates are computed from the recorded cases at completion,
+ * not accumulated as they arrive. A run whose totals were accumulated could disagree with its own case rows
+ * after a re-record, and the number that gates a release must be derivable from the evidence behind it.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const tenantMap = (outer, tenantId) => {
+    let inner = outer.get(tenantId);
+    if (!inner)
+        outer.set(tenantId, (inner = new Map()));
+    return inner;
+};
+/** Aggregates from the case rows. One function, so the two adapters cannot disagree about what a mean is. */
+export const summarise = (cases) => {
+    const byDimension = new Map();
+    let passed = 0;
+    let score = 0;
+    let cost = 0;
+    for (const result of cases) {
+        if (result.verdict.pass)
+            passed += 1;
+        score += result.verdict.score;
+        cost += result.costMinorUnits;
+        const entry = byDimension.get(result.dimension) ?? { total: 0, passed: 0, score: 0 };
+        entry.total += 1;
+        if (result.verdict.pass)
+            entry.passed += 1;
+        entry.score += result.verdict.score;
+        byDimension.set(result.dimension, entry);
+    }
+    return {
+        total: cases.length,
+        passed,
+        // Zero for an empty run rather than NaN: a run that scored nothing has a mean of zero, and NaN would
+        // propagate into every comparison that touched it.
+        meanScore: cases.length === 0 ? 0 : score / cases.length,
+        byDimension: [...byDimension.entries()]
+            // Sorted by name so two runs' breakdowns line up in a diff.
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([dimension, e]) => ({
+            dimension,
+            total: e.total,
+            passed: e.passed,
+            meanScore: e.total === 0 ? 0 : e.score / e.total,
+        })),
+        costMinorUnits: cost,
+    };
+};
+export const createMemoryEvaluationStore = () => {
+    const byTenant = new Map();
+    return {
+        async startRun({ tenantId, id, release, startedAt }) {
+            const runs = tenantMap(byTenant, tenantId);
+            if (runs.has(id))
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `evaluation run ${id} already exists`,
+                    retryable: false,
+                });
+            const run = {
+                id,
+                release,
+                startedAt,
+                total: 0,
+                passed: 0,
+                meanScore: 0,
+                byDimension: [],
+                costMinorUnits: 0,
+                graderVersions: {},
+            };
+            runs.set(id, { run, cases: new Map() });
+            return run;
+        },
+        async recordCase({ tenantId, runId, result }) {
+            const stored = tenantMap(byTenant, tenantId).get(runId);
+            // Absent means the run is gone — reported rather than thrown, because a resumed harness losing a race is
+            // ordinary and a thrown error would abandon the whole run.
+            if (stored === undefined)
+                return { recorded: false };
+            // Idempotent on the case id: a resumed run must not double-count a case it already scored.
+            stored.cases.set(result.caseId, result);
+            return { recorded: true };
+        },
+        async completeRun({ tenantId, runId, finishedAt, graderVersions }) {
+            const stored = tenantMap(byTenant, tenantId).get(runId);
+            if (stored === undefined)
+                throw new AgentPlatformError({
+                    code: "not_found",
+                    message: `no such evaluation run ${runId}`,
+                    retryable: false,
+                });
+            const summary = summarise([...stored.cases.values()]);
+            stored.run = { ...stored.run, finishedAt, graderVersions, ...summary };
+            return stored.run;
+        },
+        async get({ tenantId, runId }) {
+            // Absent from *this tenant's* map, so a foreign run id is null without a comparison anyone could get
+            // wrong — one tenant's quality gate is not another's business.
+            return tenantMap(byTenant, tenantId).get(runId)?.run ?? null;
+        },
+        async latest({ tenantId, release }) {
+            const runs = [...tenantMap(byTenant, tenantId).values()]
+                .map((s) => s.run)
+                // Completed only: an in-flight run has partial totals, and comparing against one would report every
+                // case it has not reached yet as a regression.
+                .filter((r) => r.finishedAt !== undefined && (release === undefined || r.release === release))
+                // Tie-broken by start then id, because two runs can finish in the same instant — a fixed clock in a
+                // test, or simply a fast pair — and "the latest run" must not depend on insertion order. An unstable
+                // answer here is a gate comparing against an arbitrary one of two runs.
+                .sort((a, b) => {
+                const byFinish = (b.finishedAt ?? "").localeCompare(a.finishedAt ?? "");
+                if (byFinish !== 0)
+                    return byFinish;
+                const byStart = b.startedAt.localeCompare(a.startedAt);
+                return byStart !== 0 ? byStart : b.id.localeCompare(a.id);
+            });
+            return runs[0] ?? null;
+        },
+        async list({ tenantId, limit, cursor }) {
+            const runs = [...tenantMap(byTenant, tenantId).values()]
+                .map((s) => s.run)
+                // Newest first, which is the order a release history is read in.
+                .sort((a, b) => (b.startedAt !== a.startedAt ? b.startedAt.localeCompare(a.startedAt) : a.id.localeCompare(b.id)));
+            const start = cursor === undefined ? 0 : runs.findIndex((r) => r.id === cursor) + 1;
+            const items = runs.slice(start, start + limit);
+            const last = items[items.length - 1];
+            return start + limit < runs.length && last !== undefined
+                ? { items, nextCursor: last.id }
+                : { items };
+        },
+        async listCaseResults({ tenantId, runId, limit, cursor }) {
+            const stored = tenantMap(byTenant, tenantId).get(runId);
+            if (stored === undefined)
+                return { items: [] };
+            const cases = [...stored.cases.values()].sort((a, b) => a.caseId.localeCompare(b.caseId));
+            const start = cursor === undefined ? 0 : cases.findIndex((c) => c.caseId > cursor);
+            const at = start < 0 ? cases.length : start;
+            const items = cases.slice(at, at + limit);
+            const last = items[items.length - 1];
+            return at + limit < cases.length && last !== undefined
+                ? { items, nextCursor: last.caseId }
+                : { items };
+        },
+    };
+};
+//# sourceMappingURL=evaluation.js.map

package/dist/adapters/memory/files.d.ts

@@ -0,0 +1,27 @@
+/**
+ * In-memory file metadata and content — the reference implementations (#129).
+ *
+ * The reference adapter is the baseline the conformance matrix measures the others against, so it
+ * implements every method rather than the convenient ones. Two things it takes seriously despite being
+ * in-memory:
+ *
+ * - **Tenant partitioning is by outer map, not by a filter.** A `contentKey` from one tenant cannot resolve
+ *   another's bytes because it is not in that tenant's map at all. #91 found an `AgentStore` that accepted
+ *   `TenantScope` and quietly ignored it, which is why this is structural rather than a `where` clause.
+ * - **`transition` is a compare-and-set.** A blind write would let a delete racing an upload leave a file
+ *   `stored` after its bytes were scheduled for removal, and the in-memory adapter is where that bug would
+ *   be invisible.
+ */
+import type { FileContentStore, FileMetadataStore, FileState } from "../../persistence/index.js";
+export declare const createMemoryFileMetadataStore: () => FileMetadataStore;
+/**
+ * In-memory bytes.
+ *
+ * `signedUrl` returns `null` rather than inventing a URL: this adapter has no signing mechanism, and the
+ * port says `null` means "proxy the read instead". A fabricated URL would be a URL that does not work, which
+ * is worse than an honest absence — and it would let a caller believe AC-6's mediated access was exercised
+ * when it was not.
+ */
+export declare const createMemoryFileContentStore: () => FileContentStore;
+export declare const FILE_STATES_FOR_TEST: readonly FileState[];
+//# sourceMappingURL=files.d.ts.map

package/dist/adapters/memory/flows.d.ts

@@ -0,0 +1,16 @@
+/**
+ * In-memory flow definitions and executions — the reference implementations (#187, #186).
+ *
+ * Two properties this takes seriously despite being in-memory, because both are the kind that an in-memory
+ * adapter is where the bug would be invisible:
+ *
+ * - **Tenant partitioning is by outer map, not a filter.** An execution id from one tenant cannot resolve
+ *   another's document because it is not in that tenant's map at all.
+ * - **`save` is monotonic on `steps`.** A save carrying fewer completed steps than the stored one is ignored. Two
+ *   workers holding the same execution would otherwise let the slower one move it backwards, and a flow that goes
+ *   backwards re-performs external writes — the failure this whole module exists to prevent.
+ */
+import type { FlowDefinitionStore, FlowExecutionStore } from "../../persistence/index.js";
+export declare const createMemoryFlowDefinitionStore: () => FlowDefinitionStore;
+export declare const createMemoryFlowExecutionStore: () => FlowExecutionStore;
+//# sourceMappingURL=flows.d.ts.map

package/dist/adapters/memory/flows.js

@@ -0,0 +1,117 @@
+/**
+ * In-memory flow definitions and executions — the reference implementations (#187, #186).
+ *
+ * Two properties this takes seriously despite being in-memory, because both are the kind that an in-memory
+ * adapter is where the bug would be invisible:
+ *
+ * - **Tenant partitioning is by outer map, not a filter.** An execution id from one tenant cannot resolve
+ *   another's document because it is not in that tenant's map at all.
+ * - **`save` is monotonic on `steps`.** A save carrying fewer completed steps than the stored one is ignored. Two
+ *   workers holding the same execution would otherwise let the slower one move it backwards, and a flow that goes
+ *   backwards re-performs external writes — the failure this whole module exists to prevent.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const tenantMap = (byTenant, tenantId) => {
+    const existing = byTenant.get(tenantId);
+    if (existing !== undefined)
+        return existing;
+    const created = new Map();
+    byTenant.set(tenantId, created);
+    return created;
+};
+const page = (items, request, key) => {
+    const take = Math.max(1, Math.min(request.limit ?? 50, 500));
+    const after = request.cursor;
+    const eligible = after === undefined ? items : items.filter((item) => key(item) > after);
+    const slice = eligible.slice(0, take);
+    return {
+        items: slice,
+        ...(eligible.length > take && slice.length > 0 ? { nextCursor: key(slice[slice.length - 1]) } : {}),
+    };
+};
+export const createMemoryFlowDefinitionStore = () => {
+    // Keyed `flowId@version`, because a version is part of a definition's identity rather than a column on it.
+    const byTenant = new Map();
+    return {
+        async put({ tenantId, definition }) {
+            const store = tenantMap(byTenant, String(tenantId));
+            const key = `${definition.flowId}@${definition.version}`;
+            if (store.has(key)) {
+                // A version that changed is not a version. Refusing here is what lets an execution pin one and trust it.
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `${definition.flowId} version ${definition.version} already exists — publish a new version instead`,
+                    retryable: false,
+                });
+            }
+            store.set(key, definition);
+        },
+        async get({ tenantId, flowId, version }) {
+            return tenantMap(byTenant, String(tenantId)).get(`${flowId}@${version}`) ?? null;
+        },
+        async latest({ tenantId, flowId }) {
+            const versions = [...tenantMap(byTenant, String(tenantId)).values()]
+                .filter((definition) => definition.flowId === flowId)
+                .sort((a, b) => b.version - a.version);
+            return versions[0] ?? null;
+        },
+        async list({ tenantId, ...request }) {
+            // Latest version per flow: a list of every version of every flow is a list nobody wants, and the caller
+            // asking "what flows are there" means distinct flows.
+            const latest = new Map();
+            for (const definition of tenantMap(byTenant, String(tenantId)).values()) {
+                const current = latest.get(definition.flowId);
+                if (current === undefined || definition.version > current.version)
+                    latest.set(definition.flowId, definition);
+            }
+            const sorted = [...latest.values()].sort((a, b) => a.flowId.localeCompare(b.flowId));
+            return page(sorted, request, (definition) => definition.flowId);
+        },
+    };
+};
+export const createMemoryFlowExecutionStore = () => {
+    const byTenant = new Map();
+    return {
+        async create({ tenantId, execution }) {
+            const store = tenantMap(byTenant, String(tenantId));
+            if (store.has(execution.id)) {
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `flow execution ${execution.id} already exists`,
+                    retryable: false,
+                });
+            }
+            store.set(execution.id, execution);
+        },
+        async save({ tenantId, execution }) {
+            const store = tenantMap(byTenant, String(tenantId));
+            const stored = store.get(execution.id);
+            // Monotonic. A slower worker's stale document must not move the execution backwards.
+            if (stored !== undefined && execution.steps < stored.steps)
+                return;
+            store.set(execution.id, execution);
+        },
+        async get({ tenantId, executionId }) {
+            return tenantMap(byTenant, String(tenantId)).get(executionId) ?? null;
+        },
+        async waitingOnSignal({ tenantId, signal, limit }) {
+            return [...tenantMap(byTenant, String(tenantId)).values()]
+                .filter((execution) => execution.status === "waiting" && execution.waitingSignal === signal)
+                .sort((a, b) => a.startedAt.localeCompare(b.startedAt))
+                .slice(0, Math.max(1, Math.min(limit ?? 50, 500)));
+        },
+        async waitingOnRun({ tenantId, runId }) {
+            // `status === "waiting"` as well as the id: a stale `waitingRunId` on a running execution must not be
+            // resumed by a run finishing, because it is not waiting for one.
+            return ([...tenantMap(byTenant, String(tenantId)).values()].find((execution) => execution.status === "waiting" && execution.waitingRunId === runId) ?? null);
+        },
+        async listByFlow({ tenantId, flowId, ...request }) {
+            const matching = [...tenantMap(byTenant, String(tenantId)).values()]
+                .filter((execution) => execution.flowId === flowId)
+                // Newest first: the inspector's question is "what happened just now".
+                .sort((a, b) => b.startedAt.localeCompare(a.startedAt) || a.id.localeCompare(b.id));
+            return page(matching, request, (execution) => execution.id);
+        },
+    };
+};
+//# sourceMappingURL=flows.js.map

package/dist/adapters/memory/hitl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * In-memory HITL adapters — `docs/04` → Questions & Approvals. Durable pending questions/approvals
+ * and standing approval grants for tests/dev. `answerQuestion`/`decideApproval` are idempotent so a
+ * continuation is queued exactly once; grants respect revocation and expiry.
+ */
+import type { ApprovalGrantStore, InteractionStore } from "../../persistence/index.js";
+export declare const createMemoryInteractionStore: () => InteractionStore;
+export declare const createMemoryApprovalGrantStore: () => ApprovalGrantStore;
+//# sourceMappingURL=hitl.d.ts.map