@retinue/agentkit 0.2.0 → 0.3.1

package/README.md

@@ -60,7 +60,7 @@ your own model catalogue when you need them — same code above.
 | **Injection containment** | Untrusted content is wrapped in a nonce-delimited envelope with delimiter forgery neutralised — structural, not a detector |
 | **Usage you can bill** | Per-model, per-principal token and cost accounting, with quotas enforced before a run is admitted |
 | **Flows and teams** | Durable multi-step workflows; a team compiles to a flow, and each member's turn is a child run with its own ceiling |
-| **Replaceable everything** | 31 ports, three adapter families, one conformance suite held over all of them |
+| **Replaceable everything** | 32 ports, three adapter families, one conformance suite held over all of them — [exported](https://docs.retinue.riseexperts.de/docs/getting-started/testing), so your adapter is held to it too |
 
 ## Composing it yourself
 

package/dist/adapters/audio/openai.d.ts

@@ -0,0 +1,36 @@
+/**
+ * OpenAI transcription and speech — REQ-062 (#257), task #258, AC-5 and AC-6.
+ *
+ * One adapter each, which is what the ACs ask for. Written against the HTTP API rather than through the AI SDK
+ * because the SDK's audio surface is narrower than the endpoints are: `verbose_json` carries the **duration**,
+ * and duration is what usage is charged on. An adapter that could not report it would under-bill silently,
+ * which AC-8 names as the failure to avoid.
+ *
+ * ## Where this lives, and why it is exempt from two audits
+ *
+ * `adapters/audio/`, beside `adapters/embeddings/openai.ts`, which is the same shape: an **operator-configured**
+ * provider endpoint that a model never names. Both audits that fire on this file — the raw `apiKey` field and
+ * the direct `fetch` — are exempted for that adapter with that reason, and this is exempted alongside it rather
+ * than by loosening either check.
+ *
+ * ## Credentials come in, never out of the environment
+ *
+ * The same rule every toolkit follows: a provider that read `process.env` could serve one tenant, whoever
+ * booted the process. The key is a constructor argument, and a deployment resolves it however it resolves the
+ * rest.
+ */
+import type { SpeechProvider, TranscriptionProvider } from "../../audio/index.js";
+export type OpenAiAudioConfig = {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    /** `whisper-1` is the one every account has. A deployment on a newer model names it. */
+    readonly model?: string;
+    readonly fetchImpl?: typeof fetch;
+    /** A ceiling on the wait, because a long recording is a long request and the default is none. */
+    readonly timeoutMs?: number;
+};
+export declare const openAiTranscription: (config: OpenAiAudioConfig) => TranscriptionProvider;
+export declare const openAiSpeech: (config: OpenAiAudioConfig & {
+    readonly voice?: string;
+}) => SpeechProvider;
+//# sourceMappingURL=openai.d.ts.map

package/dist/adapters/audio/openai.js

@@ -0,0 +1,136 @@
+/**
+ * OpenAI transcription and speech — REQ-062 (#257), task #258, AC-5 and AC-6.
+ *
+ * One adapter each, which is what the ACs ask for. Written against the HTTP API rather than through the AI SDK
+ * because the SDK's audio surface is narrower than the endpoints are: `verbose_json` carries the **duration**,
+ * and duration is what usage is charged on. An adapter that could not report it would under-bill silently,
+ * which AC-8 names as the failure to avoid.
+ *
+ * ## Where this lives, and why it is exempt from two audits
+ *
+ * `adapters/audio/`, beside `adapters/embeddings/openai.ts`, which is the same shape: an **operator-configured**
+ * provider endpoint that a model never names. Both audits that fire on this file — the raw `apiKey` field and
+ * the direct `fetch` — are exempted for that adapter with that reason, and this is exempted alongside it rather
+ * than by loosening either check.
+ *
+ * ## Credentials come in, never out of the environment
+ *
+ * The same rule every toolkit follows: a provider that read `process.env` could serve one tenant, whoever
+ * booted the process. The key is a constructor argument, and a deployment resolves it however it resolves the
+ * rest.
+ */
+import { AudioRejected, boundTranscript, failAudio, isAudioMediaType, MAX_SPEECH_CHARS } from "../../audio/index.js";
+const DEFAULT_BASE = "https://api.openai.com/v1";
+/** A status carried on the error, so `describeAudioFailure` can classify it. */
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const extensionFor = (mediaType) => {
+    const base = mediaType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return ({
+        "audio/mpeg": "mp3",
+        "audio/mp4": "mp4",
+        "audio/x-m4a": "m4a",
+        "audio/wav": "wav",
+        "audio/webm": "webm",
+        "audio/ogg": "ogg",
+        "audio/flac": "flac",
+    }[base] ?? "bin");
+};
+const send = async (config, path, body, headers = {}) => {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    /**
+     * A timeout, because the default is none.
+     *
+     * The eval harness lost 35 minutes of a paid run to a `fetch` with no timeout, and a transcription request
+     * is longer-lived than most — so the omission would be less visible here and cost more.
+     */
+    const signal = AbortSignal.timeout(config.timeoutMs ?? 120_000);
+    const response = await fetchImpl(`${(config.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "")}${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${config.apiKey}`, ...headers },
+        body,
+        signal,
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new HttpError(response.status, detail.slice(0, 400) || response.statusText);
+    }
+    return response;
+};
+export const openAiTranscription = (config) => ({
+    id: "openai",
+    async transcribe(request) {
+        // Checked here as well as at the boundary: this provider can be called directly, and a media type the API
+        // rejects produces a message about the request rather than about the format.
+        if (!isAudioMediaType(request.mediaType)) {
+            failAudio(new AudioRejected(`${request.mediaType} is not an audio format this adapter accepts.`), "openai");
+        }
+        const form = new FormData();
+        form.set("file", new Blob([request.audio], { type: request.mediaType }), request.filename ?? `audio.${extensionFor(request.mediaType)}`);
+        form.set("model", config.model ?? "whisper-1");
+        /**
+         * `verbose_json`, for the duration — AC-8.
+         *
+         * `json` returns the text alone. Audio is billed per second, so an adapter that asked for `json` would
+         * make every transcription cost nothing in the ledger: the recorder charges on `durationSeconds`, and
+         * absent means zero. That is the silent revenue hole the AC names, and this one field is the difference.
+         */
+        form.set("response_format", "verbose_json");
+        if (request.languageHint !== undefined)
+            form.set("language", request.languageHint);
+        try {
+            const response = await send(config, "/audio/transcriptions", form);
+            const payload = (await response.json());
+            const bounded = boundTranscript(typeof payload.text === "string" ? payload.text : "", request.maxTranscriptChars);
+            return {
+                text: bounded.text,
+                truncated: bounded.truncated,
+                ...(typeof payload.duration === "number" ? { durationSeconds: payload.duration } : {}),
+                ...(typeof payload.language === "string" ? { language: payload.language } : {}),
+            };
+        }
+        catch (error) {
+            return failAudio(error, "openai");
+        }
+    },
+});
+export const openAiSpeech = (config) => ({
+    id: "openai",
+    async speak(request) {
+        const text = request.text.trim();
+        if (text === "")
+            failAudio(new AudioRejected("There is nothing to say — the text is empty."), "openai");
+        if (text.length > MAX_SPEECH_CHARS) {
+            failAudio(new AudioRejected(`That is ${text.length} characters and the limit is ${MAX_SPEECH_CHARS}. Refused before the call, ` +
+                "because speech is billed per character and a runaway prompt is a runaway bill."), "openai");
+        }
+        const format = request.format ?? "mp3";
+        try {
+            const response = await send(config, "/audio/speech", JSON.stringify({
+                model: config.model ?? "tts-1",
+                input: text,
+                voice: request.voice ?? config.voice ?? "alloy",
+                response_format: format,
+            }), { "content-type": "application/json" });
+            const audio = new Uint8Array(await response.arrayBuffer());
+            return {
+                audio,
+                mediaType: { mp3: "audio/mpeg", wav: "audio/wav", opus: "audio/ogg", flac: "audio/flac" }[format],
+                /**
+                 * No duration. The endpoint does not report one, and computing it would mean decoding the audio —
+                 * so it is absent rather than guessed, and speech is charged per character instead. Stated because an
+                 * absent field that looked like an oversight would invite somebody to estimate it.
+                 */
+            };
+        }
+        catch (error) {
+            return failAudio(error, "openai");
+        }
+    },
+});
+//# sourceMappingURL=openai.js.map

package/dist/adapters/bullmq/lock.d.ts

@@ -43,8 +43,32 @@ export type RedisLockOptions = {
     /** Injectable for tests. Production uses `crypto.randomUUID`. */
     readonly newToken?: () => string;
 };
-export type RedisLockStore = DistributedLockStore & {
-    acquire(key: string, ttlMs: number): Promise<LockHandle | null>;
+/**
+ * What this adapter's handle actually carries — declared, because it was not.
+ *
+ * `acquire` was typed as returning the port's `LockHandle`, which is `{ released }` and nothing else, while the
+ * implementation returned `token`, `key` and `renew` as well. Three real capabilities, invisible to every typed
+ * caller: `renew` in particular is the whole lease-extension mechanism and could not be called at all without
+ * casting. The port stays narrow on purpose — a Postgres advisory lock has no token or namespaced key in this
+ * sense — so the *adapter* is the right place to say what it adds.
+ */
+export type RedisLockHandle = LockHandle & {
+    /** Per acquisition, never per store — see `newToken`. Releasing checks it, so it is the ownership proof. */
+    readonly token: string;
+    /** The namespaced key, so a lock cannot collide with the queue's own keys in a shared Redis. */
+    readonly key: string;
+    /** Extends the lease. Returns false once released, and false if another holder has taken the key. */
+    renew(nextTtlMs?: number): Promise<boolean>;
+};
+/**
+ * `Omit` rather than an intersection, and the difference is not cosmetic.
+ *
+ * `DistributedLockStore & { acquire(...) }` makes `acquire` an *overload set*, and a call resolves against the
+ * first signature — the port's, returning the narrow `LockHandle`. So the widened return type was written,
+ * compiled, and had no effect on any caller. Omitting the member first replaces it instead of adding to it.
+ */
+export type RedisLockStore = Omit<DistributedLockStore, "acquire"> & {
+    acquire(key: string, ttlMs: number): Promise<RedisLockHandle | null>;
 };
 export declare const createRedisLockStore: (redis: LockRedis, options?: RedisLockOptions) => RedisLockStore;
 /**

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

@@ -0,0 +1,10 @@
+/**
+ * The reference `ConnectionStore` — task #261.
+ *
+ * The baseline the other adapters are compared against, and the one the conformance suite runs first. It holds
+ * `SealedSecret`s exactly as Postgres does: an in-memory adapter that stored plaintext would make the raw-row
+ * assertion pass for the wrong reason, and the suite would then be asserting a different guarantee per adapter.
+ */
+import type { ConnectionStore } from "../../connections/index.js";
+export declare const createMemoryConnectionStore: (now?: () => string) => ConnectionStore;
+//# sourceMappingURL=connections.d.ts.map

package/dist/adapters/memory/connections.js

@@ -0,0 +1,87 @@
+/**
+ * The reference `ConnectionStore` — task #261.
+ *
+ * The baseline the other adapters are compared against, and the one the conformance suite runs first. It holds
+ * `SealedSecret`s exactly as Postgres does: an in-memory adapter that stored plaintext would make the raw-row
+ * assertion pass for the wrong reason, and the suite would then be asserting a different guarantee per adapter.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `no connection "${id}" for this tenant`, retryable: false });
+export const createMemoryConnectionStore = (now = () => new Date().toISOString()) => {
+    // Keyed by tenant, so a missing tenant filter is a missing map rather than a leak.
+    const byTenant = new Map();
+    const of = (tenantId) => {
+        const existing = byTenant.get(tenantId);
+        if (existing !== undefined)
+            return existing;
+        const created = new Map();
+        byTenant.set(tenantId, created);
+        return created;
+    };
+    return {
+        async create({ tenantId, connection }) {
+            const rows = of(tenantId);
+            if (rows.has(connection.id))
+                throw new AgentPlatformError({
+                    code: "conflict",
+                    message: `connection "${connection.id}" already exists for this tenant`,
+                    retryable: false,
+                });
+            const at = now();
+            const row = { ...connection, createdAt: at, updatedAt: at };
+            rows.set(connection.id, row);
+            return row;
+        },
+        async get({ tenantId, id, kind }) {
+            const row = of(tenantId).get(id);
+            // A caller that did not ask for an app registration must not receive one — see `ConnectionKind`.
+            if (row !== undefined && (row.kind ?? "connection") !== (kind ?? "connection"))
+                return null;
+            // A revoked connection reads as absent. Anything else would let a caller resolve a credential somebody
+            // deliberately withdrew.
+            return row === undefined || row.revokedAt !== undefined ? null : row;
+        },
+        async list({ tenantId, provider, kind }) {
+            return [...of(tenantId).values()]
+                .filter((c) => c.revokedAt === undefined &&
+                (provider === undefined || c.provider === provider) &&
+                (c.kind ?? "connection") === (kind ?? "connection"))
+                .sort((a, b) => (a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt.localeCompare(b.createdAt)));
+        },
+        async update({ tenantId, id, patch }) {
+            const rows = of(tenantId);
+            const existing = rows.get(id);
+            if (existing === undefined || existing.revokedAt !== undefined)
+                throw notFound(id);
+            const updated = {
+                ...existing,
+                ...(patch.label === undefined ? {} : { label: patch.label }),
+                ...(patch.sealed === undefined ? {} : { sealed: patch.sealed }),
+                ...(patch.metadata === undefined ? {} : { metadata: patch.metadata }),
+                ...(patch.grantedScopes === undefined ? {} : { grantedScopes: patch.grantedScopes }),
+                ...(patch.expiresAt === undefined ? {} : { expiresAt: patch.expiresAt }),
+                updatedAt: now(),
+            };
+            rows.set(id, updated);
+            return updated;
+        },
+        async revoke({ tenantId, id }) {
+            const rows = of(tenantId);
+            const existing = rows.get(id);
+            if (existing === undefined)
+                throw notFound(id);
+            // Idempotent: revoking twice is not an error, because a caller retrying a disconnect should not have to
+            // distinguish "already gone" from "failed".
+            if (existing.revokedAt !== undefined)
+                return;
+            rows.set(id, { ...existing, revokedAt: now(), updatedAt: now() });
+        },
+        async purge({ tenantId }) {
+            const rows = byTenant.get(tenantId);
+            const count = rows?.size ?? 0;
+            byTenant.delete(tenantId);
+            return count;
+        },
+    };
+};
+//# sourceMappingURL=connections.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * In-memory `GraphStore` — the reference implementation (REQ-064 #270, task #271).
+ *
+ * The same standard the in-memory `KnowledgeStore` holds itself to: this is not a stub that makes tests pass,
+ * it is the definition of the contract that the Postgres adapter is then held to by the same conformance suite.
+ * Three things it takes as seriously as a database would:
+ *
+ * - **Tenant isolation is structural.** Every map is keyed by tenant first, so cross-tenant reads are not
+ *   prevented by a filter somebody could forget — there is nowhere for another tenant's rows to be.
+ * - **Provenance is enforced, not assumed.** A row with no chunks is refused here, so the refusal is part of
+ *   the contract rather than a Postgres constraint that the reference adapter quietly tolerates.
+ * - **A source's contribution is what is replaced.** Entities are shared between sources; re-indexing one
+ *   document withdraws its claims and prunes only what nothing else asserts.
+ */
+import type { GraphStore } from "../../persistence/index.js";
+export declare const createMemoryGraphStore: () => GraphStore;
+//# sourceMappingURL=graph.d.ts.map

package/dist/adapters/memory/graph.js

@@ -0,0 +1,267 @@
+/**
+ * In-memory `GraphStore` — the reference implementation (REQ-064 #270, task #271).
+ *
+ * The same standard the in-memory `KnowledgeStore` holds itself to: this is not a stub that makes tests pass,
+ * it is the definition of the contract that the Postgres adapter is then held to by the same conformance suite.
+ * Three things it takes as seriously as a database would:
+ *
+ * - **Tenant isolation is structural.** Every map is keyed by tenant first, so cross-tenant reads are not
+ *   prevented by a filter somebody could forget — there is nowhere for another tenant's rows to be.
+ * - **Provenance is enforced, not assumed.** A row with no chunks is refused here, so the refusal is part of
+ *   the contract rather than a Postgres constraint that the reference adapter quietly tolerates.
+ * - **A source's contribution is what is replaced.** Entities are shared between sources; re-indexing one
+ *   document withdraws its claims and prunes only what nothing else asserts.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const sourceKey = (sourceType, sourceId) => `${sourceType} ${sourceId}`;
+const DEFAULT_SETTINGS = { enabled: false, updatedAt: "1970-01-01T00:00:00.000Z" };
+const uniqueSorted = (values) => [...new Set(values)].sort();
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * Every contribution, merged into the graph a reader sees.
+ *
+ * Recomputed on read rather than maintained on write. That is the right trade for a reference adapter: the
+ * merge rule then exists in exactly one place, and a bug in it cannot leave a stored graph subtly inconsistent
+ * with the contributions it came from. Postgres maintains merged rows for query speed and is held to producing
+ * the same answer by `fingerprint`.
+ */
+const mergeAll = (source) => {
+    /**
+     * Materialised, because this function walks it **twice** — entities, then relationships.
+     *
+     * The first version took the `Iterable` and looped it directly, which works for an array and is silently
+     * wrong for `Map.values()`: an iterator is exhausted by the first pass, so the second saw nothing and *every
+     * edge was dropped*. Entities were correct, so the graph looked plausible; only a traversal returned empty.
+     * Found by the neighbour-ordering test, and worth the parameter rename so the two loops cannot drift back.
+     */
+    const contributions = [...source];
+    const entities = new Map();
+    const relationships = new Map();
+    for (const contribution of contributions) {
+        for (const entity of contribution.entities) {
+            const existing = entities.get(entity.id);
+            if (existing === undefined) {
+                entities.set(entity.id, entity);
+                continue;
+            }
+            const description = (entity.description ?? "").length > (existing.description ?? "").length ? entity.description : existing.description;
+            entities.set(entity.id, {
+                id: entity.id,
+                // Lexicographically first, matching `mergeContributions`. "First written" would depend on source order,
+                // and source order is a thing that changes without the corpus changing.
+                name: existing.name < entity.name ? existing.name : entity.name,
+                type: existing.type,
+                ...(description === undefined ? {} : { description }),
+                surfaceForms: uniqueSorted([...existing.surfaceForms, ...entity.surfaceForms]),
+                provenance: uniqueSorted([...existing.provenance, ...entity.provenance]),
+            });
+        }
+    }
+    for (const contribution of contributions) {
+        for (const edge of contribution.relationships) {
+            const existing = relationships.get(edge.id);
+            if (existing === undefined) {
+                relationships.set(edge.id, edge);
+                continue;
+            }
+            const description = (edge.description ?? "").length > (existing.description ?? "").length ? edge.description : existing.description;
+            const provenance = uniqueSorted([...existing.provenance, ...edge.provenance]);
+            relationships.set(edge.id, {
+                ...existing,
+                ...(description === undefined ? {} : { description }),
+                weight: provenance.length,
+                provenance,
+            });
+        }
+    }
+    // An edge whose endpoints are gone goes with them — the state after a source is removed.
+    const kept = [...relationships.values()].filter((edge) => entities.has(edge.fromId) && entities.has(edge.toId));
+    return { entities: [...entities.values()].sort(byId), relationships: kept.sort(byId) };
+};
+/** Refuses an untraceable claim. See `GraphStore` — provenance is structural. */
+const assertProvenance = (contribution) => {
+    for (const entity of contribution.entities) {
+        if (entity.provenance.length === 0)
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: `entity ${entity.id} has no provenance; a graph claim with no chunk behind it is one the model would cite`,
+                retryable: false,
+            });
+    }
+    for (const edge of contribution.relationships) {
+        if (edge.provenance.length === 0)
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: `relationship ${edge.id} has no provenance; a graph claim with no chunk behind it is one the model would cite`,
+                retryable: false,
+            });
+    }
+};
+export const createMemoryGraphStore = () => {
+    const tenants = new Map();
+    const graphOf = (tenantId) => {
+        let graph = tenants.get(tenantId);
+        if (!graph) {
+            tenants.set(tenantId, (graph = { settings: DEFAULT_SETTINGS, sourceFlags: new Map(), contributions: new Map(), communities: new Map() }));
+        }
+        return graph;
+    };
+    const page = (items, limit, cursor) => {
+        const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10) || 0;
+        const slice = items.slice(offset, offset + limit);
+        const next = offset + slice.length;
+        return next < items.length ? { items: slice, nextCursor: String(next) } : { items: slice };
+    };
+    return {
+        async getSettings({ tenantId }) {
+            return graphOf(tenantId).settings;
+        },
+        async setEnabled({ tenantId, enabled, at }) {
+            const graph = graphOf(tenantId);
+            graph.settings = { enabled, updatedAt: at };
+            return graph.settings;
+        },
+        async setSourceEnabled({ tenantId, sourceType, sourceId, enabled }) {
+            // Stored regardless of the tenant switch — AC-2. Marking a handbook today and enabling the tenant next
+            // week must not require re-marking anything, so this never consults `settings`.
+            graphOf(tenantId).sourceFlags.set(sourceKey(sourceType, sourceId), enabled);
+        },
+        async isSourceEnabled({ tenantId, sourceType, sourceId }) {
+            return graphOf(tenantId).sourceFlags.get(sourceKey(sourceType, sourceId)) === true;
+        },
+        async listEnabledSources({ tenantId, limit, cursor }) {
+            const rows = [...graphOf(tenantId).sourceFlags.entries()]
+                .filter(([, enabled]) => enabled)
+                .map(([key]) => {
+                const at = key.indexOf(" ");
+                return { sourceType: key.slice(0, at), sourceId: key.slice(at + 1) };
+            })
+                .sort((a, b) => (sourceKey(a.sourceType, a.sourceId) < sourceKey(b.sourceType, b.sourceId) ? -1 : 1));
+            return page(rows, limit, cursor);
+        },
+        async replaceSourceGraph({ tenantId, sourceType, sourceId, contribution }) {
+            assertProvenance(contribution);
+            const graph = graphOf(tenantId);
+            const before = mergeAll(graph.contributions.values()).entities.length;
+            const key = sourceKey(sourceType, sourceId);
+            if (contribution.entities.length === 0 && contribution.relationships.length === 0) {
+                graph.contributions.delete(key);
+            }
+            else {
+                graph.contributions.set(key, { entities: contribution.entities, relationships: contribution.relationships });
+            }
+            const after = mergeAll(graph.contributions.values());
+            return {
+                entities: after.entities.length,
+                relationships: after.relationships.length,
+                // What this replacement removed from the graph, not what it removed from the source. An operator asking
+                // "did re-indexing lose anything" is asking the first question.
+                pruned: Math.max(0, before - after.entities.length),
+            };
+        },
+        async deleteSourceGraph({ tenantId, sourceType, sourceId }) {
+            const graph = graphOf(tenantId);
+            const before = mergeAll(graph.contributions.values()).entities.length;
+            graph.contributions.delete(sourceKey(sourceType, sourceId));
+            const after = mergeAll(graph.contributions.values()).entities.length;
+            return { pruned: Math.max(0, before - after) };
+        },
+        async getEntity({ tenantId, id }) {
+            return mergeAll(graphOf(tenantId).contributions.values()).entities.find((entity) => entity.id === id) ?? null;
+        },
+        async getEntities({ tenantId, ids }) {
+            const wanted = new Set(ids);
+            return mergeAll(graphOf(tenantId).contributions.values()).entities.filter((entity) => wanted.has(entity.id));
+        },
+        async resolveEntities({ tenantId, normalisedNames }) {
+            if (normalisedNames.length === 0)
+                return [];
+            // The name is everything after the first colon; `normaliseName` cannot produce one, so the split is safe.
+            const wanted = new Set(normalisedNames);
+            return mergeAll(graphOf(tenantId).contributions.values()).entities.filter((entity) => wanted.has(entity.id.slice(entity.id.indexOf(":") + 1)));
+        },
+        async listEntities({ tenantId, limit, cursor, type }) {
+            const all = mergeAll(graphOf(tenantId).contributions.values()).entities;
+            return page(type === undefined ? all : all.filter((entity) => entity.type === type), limit, cursor);
+        },
+        async neighbours({ tenantId, entityIds, limit }) {
+            const wanted = new Set(entityIds);
+            const { relationships } = mergeAll(graphOf(tenantId).contributions.values());
+            return relationships
+                .filter((edge) => wanted.has(edge.fromId) || wanted.has(edge.toId))
+                // Heaviest first — the edge the most chunks asserted is the one most worth traversing. Ties broken by
+                // id so the order is total, which is what makes a truncated traversal reproducible.
+                .sort((a, b) => (b.weight - a.weight) || byId(a, b))
+                .slice(0, Math.max(0, limit));
+        },
+        async replaceCommunities({ tenantId, communities }) {
+            const graph = graphOf(tenantId);
+            const previous = new Map(graph.communities);
+            graph.communities.clear();
+            let summariesKept = 0;
+            for (const community of communities) {
+                const before = previous.get(community.id);
+                /**
+                 * A summary survives a re-clustering **only when the membership is identical**.
+                 *
+                 * Carrying it over on id alone would attach a summary of the old members to the new ones — a
+                 * confidently wrong description of a community that changed, which is worse than having none.
+                 */
+                const keep = before?.summary !== undefined && before.summaryFingerprint === community.fingerprint;
+                if (keep)
+                    summariesKept += 1;
+                graph.communities.set(community.id, {
+                    ...community,
+                    ...(keep && before !== undefined
+                        ? {
+                            summary: before.summary,
+                            summaryFingerprint: before.summaryFingerprint,
+                            ...(before.summarisedAt === undefined ? {} : { summarisedAt: before.summarisedAt }),
+                        }
+                        : {}),
+                });
+            }
+            return { written: communities.length, summariesKept };
+        },
+        async listCommunities({ tenantId, limit, cursor, level }) {
+            const all = [...graphOf(tenantId).communities.values()]
+                .filter((community) => level === undefined || community.level === level)
+                .sort((a, b) => a.level - b.level || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+            return page(all, limit, cursor);
+        },
+        async getCommunity({ tenantId, id }) {
+            return graphOf(tenantId).communities.get(id) ?? null;
+        },
+        async setCommunitySummary({ tenantId, id, summary, fingerprint, at }) {
+            const graph = graphOf(tenantId);
+            const community = graph.communities.get(id);
+            if (community === undefined)
+                return;
+            graph.communities.set(id, { ...community, summary, summaryFingerprint: fingerprint, summarisedAt: at });
+        },
+        async fingerprint({ tenantId }) {
+            const { entities, relationships } = mergeAll(graphOf(tenantId).contributions.values());
+            /**
+             * A stable serialisation, on the port rather than in a test — AC-6.
+             *
+             * Every field that a re-index could plausibly reorder is included: surface forms and provenance are the
+             * two that actually caught bugs, because both are sets that arrive in whatever order extraction produced.
+             * Leaving them out would let the fingerprint agree while the graph differed.
+             */
+            const lines = [
+                ...entities.map((entity) => [
+                    "E",
+                    entity.id,
+                    entity.name,
+                    entity.type,
+                    entity.description ?? "",
+                    entity.surfaceForms.join(","),
+                    entity.provenance.join(","),
+                ].join("
")),
+                ...relationships.map((edge) => ["R", edge.id, edge.type, String(edge.weight), edge.description ?? "", edge.provenance.join(",")].join("
")),
+            ];
+            return lines.join("\n");
+        },
+    };
+};
+//# sourceMappingURL=graph.js.map

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

@@ -20,6 +20,7 @@ export * from "./files.js";
 export * from "./artifacts.js";
 export * from "./artifact-exports.js";
 export * from "./knowledge.js";
+export * from "./graph.js";
 export * from "./evaluation.js";
 /** Idempotency store reference adapter. */
 export * from "./idempotency.js";
@@ -36,4 +37,6 @@ export * from "./principal-memory.js";
 /** Message + agent reference adapters (used by the embedded agent facade). */
 export * from "./message-store.js";
 export * from "./flows.js";
+export * from "./rate-limit.js";
+export * from "./connections.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/memory/index.js

@@ -88,6 +88,7 @@ export * from "./files.js";
 export * from "./artifacts.js";
 export * from "./artifact-exports.js";
 export * from "./knowledge.js";
+export * from "./graph.js";
 export * from "./evaluation.js";
 /** Idempotency store reference adapter. */
 export * from "./idempotency.js";
@@ -104,4 +105,6 @@ export * from "./principal-memory.js";
 /** Message + agent reference adapters (used by the embedded agent facade). */
 export * from "./message-store.js";
 export * from "./flows.js";
+export * from "./rate-limit.js";
+export * from "./connections.js";
 //# sourceMappingURL=index.js.map

package/dist/adapters/memory/rate-limit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The rate-limit counter in memory — task #248.
+ *
+ * **For tests and a single-process deployment only.** Two workers each hold their own `Map`, so each allows the
+ * full rate and a limit of 60/minute becomes 60×N. That is not a caveat to be worked around; it is why
+ * `createRedisRateLimitStore` exists, and why the cross-process test in this task's suite runs against a real
+ * Redis rather than this.
+ *
+ * Old windows are dropped on write rather than on a timer: a timer in a store would keep a process alive and
+ * would need clearing, and the number of live windows is one per tenant.
+ */
+import type { RateLimitStore } from "../../usage/index.js";
+export declare const createMemoryRateLimitStore: () => RateLimitStore;
+//# sourceMappingURL=rate-limit.d.ts.map