@retinue/agentkit 0.2.0 → 0.3.0

package/dist/models/pricing.js

@@ -13,11 +13,27 @@
  * Cached input is billed at the cache-read rate when present. This is what feeds usage accounting.
  */
 export const computeModelCostMinorUnits = (pricing, usage) => {
+    /**
+     * Three kinds of input token, and all three are inside `inputTokens` — task #247.
+     *
+     * Measured against a live provider: `noCacheTokens + cacheReadTokens + cacheWriteTokens === inputTokens`. So
+     * fresh input is the remainder after both cache quantities, and adding them on top would double-bill — the
+     * same trap `nonTextInput` exists for.
+     *
+     * A cache **write** is not a discount. Anthropic charges 1.25× a fresh input token to write an entry, so
+     * folding writes into fresh input *under-bills* the first turn of every conversation — the direction that
+     * looks like a saving and is not. `cacheWritePerMillion` existed in `ModelPricing` and was read by nothing
+     * until now.
+     */
     const cachedIn = usage.cachedInputTokens ?? 0;
-    const freshIn = Math.max(0, usage.inputTokens - cachedIn);
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+    const freshIn = Math.max(0, usage.inputTokens - cachedIn - cacheWrite);
     const perMillion = (tokens, price) => (tokens * price) / 1_000_000;
     const tokenCost = perMillion(freshIn, pricing.inputPerMillion) +
         perMillion(cachedIn, pricing.cacheReadPerMillion ?? pricing.inputPerMillion) +
+        // Defaulting a write to the plain input rate is the conservative choice: it neither invents a premium a
+        // provider does not charge nor silently discounts one it does.
+        perMillion(cacheWrite, pricing.cacheWritePerMillion ?? pricing.inputPerMillion) +
         perMillion(usage.outputTokens, pricing.outputPerMillion);
     /**
      * Non-text input, charged **only** where the provider prices it separately — #185 AC-4.

package/dist/models/provider-factory.js

@@ -45,14 +45,16 @@ export const createProviderFactory = (config = {}) => {
                         });
                     }
                     return createOpenAICompatible({ name: c.name ?? "openai-compatible", baseURL: c.baseURL, apiKey: c.apiKey })(model.modelId);
-                case "bedrock":
-                    // Bedrock wiring (@ai-sdk/amazon-bedrock + AWS credentials) is a follow-up.
-                    throw new AgentPlatformError({
-                        code: "capability_unavailable",
-                        message: "Amazon Bedrock provider is not wired yet",
-                        retryable: false,
-                    });
                 default: {
+                    /**
+                     * Unreachable while `MODEL_PROVIDERS` and this switch agree — which is the point, and is now the
+                     * *only* thing standing between a declared provider and a runtime failure.
+                     *
+                     * `"bedrock"` used to have a case here that threw. It was removed from the union in #256 rather than
+                     * wired, because a declared provider that throws is worse than an absent one: it typechecks,
+                     * satisfies this `never` assertion, and fails for whoever selects it first. `provider-coverage.test.ts`
+                     * is what turns "mentioned in a switch" into "actually constructs".
+                     */
                     const exhaustive = model.provider;
                     throw new AgentPlatformError({
                         code: "capability_unavailable",

package/dist/models/streaming.d.ts

@@ -89,6 +89,14 @@ export type ModelTurnTool = {
     /** Zod schema or JSON-schema object; a permissive object schema is used when absent. */
     readonly inputSchema?: unknown;
     execute(input: unknown, options?: ModelToolCallOptions): Promise<unknown>;
+    /**
+     * The tool's category, when the caller knows it — task #244.
+     *
+     * Optional and never sent to the provider. It exists so a caller can express a policy *about* categories —
+     * `AgentManifest.toolPolicy.categories` names the ones that must stay resident when the catalogue is bounded —
+     * without the engine having to reach back into the registry for a descriptor it was already handed.
+     */
+    readonly category?: string;
 };
 export type ModelTurnRequest = {
     readonly model: ResolvedModel;
@@ -116,6 +124,29 @@ export type ModelTurnRequest = {
      * `temperature` matters for a second reason: the evaluation harness (#141) rests its reproducibility argument
      * partly on temperature zero, and there was no way to ask for it on a real run.
      */
+    /**
+     * Ask the model for a value conforming to a schema, rather than prose — task #243.
+     *
+     * Neutral on purpose: this layer sits below `agents/`, so it takes a schema rather than an
+     * `AgentManifest["responseFormat"]`. The engine does the mapping.
+     *
+     * The schema must be validatable by this process — see `structuredValidator`. A bare JSON schema is refused,
+     * because the AI SDK's `jsonSchema()` wrapper leaves `validate` undefined: it constrains the provider request
+     * and checks nothing on the way back, which would make "structured" a request rather than a guarantee. That
+     * distinction is the entire point of the task.
+     */
+    readonly structuredOutput?: {
+        readonly schema: unknown;
+    };
+    /**
+     * Where this turn's prompt prefix may be cached, and how — task #247.
+     *
+     * `"explicit"` makes this layer emit the provider's cache directive; `"automatic"` and `"none"` emit nothing,
+     * for opposite reasons — one needs no help and the other would reject the field. Mapped by the engine from
+     * `ModelDefinition.capabilities.promptCaching`, so a caller that supplies no definition sends nothing, which
+     * is the behaviour every existing host already has.
+     */
+    readonly promptCaching?: "automatic" | "explicit" | "none";
     readonly maxOutputTokens?: number;
     readonly temperature?: number;
     readonly topP?: number;
@@ -124,7 +155,26 @@ export type ModelTurnRequest = {
 export type NeutralUsage = {
     readonly inputTokens: number;
     readonly outputTokens: number;
+    /**
+     * Input tokens served from a prompt cache — a **subset** of `inputTokens`, not an addition to it.
+     *
+     * Read from the provider's `inputTokenDetails.cacheReadTokens` (task #247). It used to be read from
+     * `totalUsage.cachedInputTokens`, **a field the AI SDK does not send** — so this was zero on every turn, and
+     * `computeModelCostMinorUnits` billed cached tokens at the full input rate. Measured against a live model, a
+     * turn reusing a 9,700-token prefix reported 9,472 cache-read tokens and this platform recorded none of them.
+     */
     readonly cachedInputTokens: number;
+    /**
+     * Input tokens written *into* a prompt cache — also a subset of `inputTokens`.
+     *
+     * Its own quantity because it is priced differently and, on some providers, priced **higher** than a fresh
+     * input token: Anthropic charges 1.25× to write a cache entry. Folding it into fresh input under-bills a
+     * cache write and over-credits the first turn of every conversation, which is the direction that looks like a
+     * saving and is not.
+     *
+     * Absent means "not reported", not "none" — the rule `imageCount` already follows.
+     */
+    readonly cacheWriteTokens?: number;
     readonly reasoningTokens?: number;
     /**
      * Non-text input, counted from what **we sent** rather than from what the provider reported — #185 AC-4.
@@ -158,9 +208,48 @@ export type NeutralStreamChunk = {
 } | {
     readonly type: "finish";
     readonly usage: NeutralUsage;
+}
+/** A validated structured answer — emitted once, at the end, only when `structuredOutput` was asked for. */
+ | {
+    readonly type: "structured-output";
+    readonly value: unknown;
 } | {
     readonly type: "error";
     readonly error: unknown;
 };
+/**
+ * A schema this process can actually check, or a refusal — task #243.
+ *
+ * The rule: **only a schema with a validator is accepted for structured output.** Zod (a direct dependency) and
+ * anything else implementing Standard Schema qualify. A bare JSON-schema object does not, and refusing it is a
+ * deliberate choice rather than an omission:
+ *
+ * - The AI SDK's `jsonSchema()` wrapper returns `{ _type, jsonSchema, validate }` with **`validate` undefined**.
+ *   It constrains the provider's generation and validates nothing coming back. Accepting one would mean the
+ *   platform says "structured", the provider mostly complies, and nobody checks — which is a softer version of
+ *   the bug being fixed, not a fix.
+ * - Validating JSON schema properly needs `ajv`, and that is a new runtime dependency for every consumer of a
+ *   package whose entire dependency list is `ai` and `zod`. Not worth it when `z.object({...})` is one line and
+ *   already validates.
+ *
+ * So this fails closed, at wiring time, with a message naming the fix. Tools keep taking JSON schema — a tool's
+ * arguments are validated by the provider and a bad call is a tool error the model can see and retry, which is
+ * a different situation from a guarantee made to a caller about a return value.
+ */
+export declare const structuredValidator: (schema: unknown) => ((value: unknown) => {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+});
+/**
+ * The cache-read count, from wherever the provider put it — task #247.
+ *
+ * Exported so the arithmetic is testable without a provider: the whole defect this fixes was a field name that
+ * did not exist, which no amount of testing *through* a fake could reveal.
+ */
+export declare const cacheRead: (usage: Record<string, unknown>) => number;
+/** The cache-write count, or `undefined` when the provider did not report one. */
+export declare const cacheWrite: (usage: Record<string, unknown>) => number | undefined;
 export declare function streamModelTurn(req: ModelTurnRequest): AsyncIterable<NeutralStreamChunk>;
 //# sourceMappingURL=streaming.d.ts.map

package/dist/models/streaming.js

@@ -6,7 +6,7 @@
  * continues — and yields provider-neutral chunks. The agent engine consumes these chunks without
  * ever importing the SDK, so switching providers changes nothing above this layer.
  */
-import { jsonSchema, stepCountIs, streamText, tool as aiTool } from "ai";
+import { Output, jsonSchema, stepCountIs, streamText, tool as aiTool } from "ai";
 import { AgentPlatformError } from "../core/errors.js";
 /** The text of a turn, for callers that count tokens or log. Non-text parts contribute nothing. */
 export const turnText = (message) => typeof message.content === "string"
@@ -58,6 +58,62 @@ export const modalitiesOf = (messages) => {
     }
     return [...found];
 };
+/**
+ * A schema this process can actually check, or a refusal — task #243.
+ *
+ * The rule: **only a schema with a validator is accepted for structured output.** Zod (a direct dependency) and
+ * anything else implementing Standard Schema qualify. A bare JSON-schema object does not, and refusing it is a
+ * deliberate choice rather than an omission:
+ *
+ * - The AI SDK's `jsonSchema()` wrapper returns `{ _type, jsonSchema, validate }` with **`validate` undefined**.
+ *   It constrains the provider's generation and validates nothing coming back. Accepting one would mean the
+ *   platform says "structured", the provider mostly complies, and nobody checks — which is a softer version of
+ *   the bug being fixed, not a fix.
+ * - Validating JSON schema properly needs `ajv`, and that is a new runtime dependency for every consumer of a
+ *   package whose entire dependency list is `ai` and `zod`. Not worth it when `z.object({...})` is one line and
+ *   already validates.
+ *
+ * So this fails closed, at wiring time, with a message naming the fix. Tools keep taking JSON schema — a tool's
+ * arguments are validated by the provider and a bad call is a tool error the model can see and retry, which is
+ * a different situation from a guarantee made to a caller about a return value.
+ */
+export const structuredValidator = (schema) => {
+    const standard = schema?.["~standard"];
+    if (schema !== null && typeof schema === "object" && typeof standard?.validate === "function") {
+        return (value) => {
+            const result = standard.validate(value);
+            // Standard Schema is allowed to return a promise; a validator that cannot answer synchronously is not
+            // usable here, and silently treating a pending promise as success is how this would pass having checked
+            // nothing. Refuse instead.
+            if (result instanceof Promise)
+                return { ok: false, detail: "the schema validates asynchronously, which this path cannot await" };
+            if (result.issues === undefined || result.issues.length === 0)
+                return { ok: true };
+            return {
+                ok: false,
+                detail: result.issues
+                    .map((i) => `${(i.path ?? []).join(".") || "(root)"}: ${i.message ?? "invalid"}`)
+                    .join("; "),
+            };
+        };
+    }
+    if (isZodSchema(schema)) {
+        const parse = schema
+            .safeParse;
+        return (value) => {
+            const result = parse.call(schema, value);
+            return result.success ? { ok: true } : { ok: false, detail: result.error?.message ?? "invalid" };
+        };
+    }
+    throw new AgentPlatformError({
+        code: "capability_unavailable",
+        message: "a structured response format needs a schema this process can validate — a Zod schema, or anything " +
+            "implementing Standard Schema. A plain JSON-schema object is refused: the AI SDK sends it to the " +
+            "provider but validates nothing on the way back, so the platform would be promising a shape it never " +
+            "checks. Use `z.object({ … })`.",
+        retryable: false,
+    });
+};
 const isZodSchema = (s) => typeof s === "object" && s !== null && typeof s.safeParse === "function";
 /** A JSON-schema-shaped object: `{ type: "object", … }`. Enough to tell one from a Zod schema or from absence. */
 const isJsonSchema = (s) => typeof s === "object" && s !== null && typeof s.type === "string";
@@ -148,6 +204,25 @@ const toModelContent = (content) => {
                 ...(part.filename === undefined ? {} : { filename: part.filename }),
             });
 };
+/**
+ * The cache-read count, from wherever the provider put it — task #247.
+ *
+ * Exported so the arithmetic is testable without a provider: the whole defect this fixes was a field name that
+ * did not exist, which no amount of testing *through* a fake could reveal.
+ */
+export const cacheRead = (usage) => {
+    const details = usage.inputTokenDetails;
+    if (details?.cacheReadTokens !== undefined)
+        return num(details.cacheReadTokens);
+    return num(usage.cachedInputTokens);
+};
+/** The cache-write count, or `undefined` when the provider did not report one. */
+export const cacheWrite = (usage) => {
+    const details = usage.inputTokenDetails;
+    if (details?.cacheWriteTokens !== undefined)
+        return num(details.cacheWriteTokens);
+    return usage.cacheWriteTokens === undefined ? undefined : num(usage.cacheWriteTokens);
+};
 export async function* streamModelTurn(req) {
     /**
      * Refuse a modality the model cannot take — #185.
@@ -173,11 +248,52 @@ export async function* streamModelTurn(req) {
             });
     }
     const messages = req.messages.map((m) => ({ role: m.role, content: toModelContent(m.content) }));
+    /**
+     * Validated before the call, not after — task #243 AC-2/AC-3.
+     *
+     * A schema this process cannot check makes "structured" a request rather than a guarantee, and finding that
+     * out after a paid generation is finding it out in the worst place. `structuredValidator` throws here.
+     */
+    const validate = req.structuredOutput === undefined ? undefined : structuredValidator(req.structuredOutput.schema);
     const result = streamText({
         model: req.model,
         ...(req.system ? { system: req.system } : {}),
         messages,
         ...(req.tools && req.tools.length > 0 ? { tools: toToolSet(req.tools) } : {}),
+        /**
+         * `output` rather than `streamObject`, because tools must keep working — AC-4.
+         *
+         * `streamObject` has no tool loop at all, so a structured agent would silently lose every tool. This keeps
+         * `streamText`'s model↔tool loop and constrains only the final answer.
+         *
+         * The option is `output`, **not** `experimental_output`. It was named the latter in `ai@4` and the name was
+         * dropped in `ai@7`; passing the old one is not an error, it is *ignored* — `streamText` accepts the unknown
+         * key, the model is never constrained, and `result.output` comes back as ordinary prose. Written down
+         * because that is the whole defect class this task exists to close, met again inside the fix: the first
+         * version of this code passed `experimental_output`, typechecked, and did nothing. Only the live check
+         * against a real model found it.
+         */
+        ...(req.structuredOutput === undefined
+            ? {}
+            : { output: Output.object({ schema: req.structuredOutput.schema }) }),
+        /**
+         * The cache breakpoint, for providers that need one told — task #247.
+         *
+         * Only `"explicit"`. Anthropic caches nothing unless a block carries `cache_control`, so a platform that
+         * emitted nothing got no caching there at all — which is what this did. OpenAI needs no directive and would
+         * treat one as an unknown field, so `"automatic"` deliberately sends nothing.
+         *
+         * The breakpoint goes on the **system** block, which is where the stable prefix is: the system prompt and
+         * the tool catalogue are byte-identical across every turn of a conversation, and the history after them is
+         * not. Anthropic caches everything *up to* a breakpoint, so marking the system block caches the prompt and
+         * the tool definitions together.
+         *
+         * `providerOptions` rather than a top-level field, because this is provider-specific by construction and the
+         * AI SDK's neutral surface has no cache concept. A provider that ignores the namespace is unaffected.
+         */
+        ...(req.promptCaching === "explicit"
+            ? { providerOptions: { anthropic: { cacheControl: { type: "ephemeral" } } } }
+            : {}),
         stopWhen: stepCountIs(req.maxSteps ?? 8),
         ...(req.abortSignal ? { abortSignal: req.abortSignal } : {}),
         // Spread conditionally so an unset parameter leaves the provider's own default alone, rather than pinning it
@@ -190,6 +306,15 @@ export async function* streamModelTurn(req) {
     for await (const chunk of result.fullStream) {
         switch (chunk.type) {
             case "text-delta":
+                /**
+                 * Swallowed on a structured turn — AC-5.
+                 *
+                 * With `experimental_output` the model's text *is* the JSON, arriving a fragment at a time. Forwarding it
+                 * would put half-built JSON in the transcript as prose and leave a reader watching `{"na` appear. The
+                 * decision is one complete part at the end instead; tool calls still stream, so the turn is not silent.
+                 */
+                if (req.structuredOutput !== undefined)
+                    break;
                 yield { type: "text-delta", id: chunk.id ?? "text", text: chunk.text ?? "" };
                 break;
             case "tool-call":
@@ -249,7 +374,20 @@ export async function* streamModelTurn(req) {
                     usage: {
                         inputTokens: num(usage.inputTokens),
                         outputTokens: num(usage.outputTokens),
-                        cachedInputTokens: num(usage.cachedInputTokens),
+                        /**
+                         * From `inputTokenDetails`, with the old field as a fallback — task #247.
+                         *
+                         * The AI SDK reports the breakdown as
+                         * `inputTokenDetails: { noCacheTokens, cacheReadTokens, cacheWriteTokens }`, and **not** as
+                         * `cachedInputTokens`. Reading the latter — which is what this did — yielded `undefined` on every
+                         * provider, so `num()` made it zero and every cached token was billed at the full input rate.
+                         *
+                         * The fallback is kept because the field is what a *host-supplied* `streamTurn` would most naturally
+                         * set, and because a future SDK may reinstate it. Order matters: the detailed breakdown wins, since
+                         * it is the one a real provider fills in.
+                         */
+                        cachedInputTokens: cacheRead(usage),
+                        ...(cacheWrite(usage) === undefined ? {} : { cacheWriteTokens: cacheWrite(usage) }),
                         ...(usage.reasoningTokens !== undefined ? { reasoningTokens: num(usage.reasoningTokens) } : {}),
                         /**
                          * Non-text input, counted from the request rather than read from the response — #185 AC-4.
@@ -272,5 +410,44 @@ export async function* streamModelTurn(req) {
                 break;
         }
     }
+    if (validate === undefined)
+        return;
+    /**
+     * The structured answer, after the loop and after validation — AC-2.
+     *
+     * Read from the SDK's resolved output rather than reassembled from the text deltas that were swallowed above:
+     * the SDK has already parsed the JSON, and re-parsing a string this layer discarded would be two chances to
+     * get it wrong.
+     *
+     * Every failure here is a **run failure**, deliberately. The alternative is emitting the text as an ordinary
+     * answer, which is precisely the defect this task fixes: an agent that asked for a schema, got prose, and had
+     * no way to tell. A caller who wanted best-effort prose did not set a structured response format.
+     */
+    let value;
+    try {
+        value = await result.output;
+    }
+    catch (thrown) {
+        throw new AgentPlatformError({
+            code: "provider_error",
+            message: "the model produced no value conforming to the structured response format: " +
+                errorMessageOf(thrown) +
+                ". The turn is failed rather than returning the raw text, which would be prose presented as a " +
+                "validated object.",
+            retryable: true,
+        });
+    }
+    // Belt and braces over the SDK's own parse. `Output.object` validates a Standard Schema, but this layer is
+    // where the guarantee is made, and a guarantee that depends on a dependency's internals is a guarantee that
+    // changes when the dependency does.
+    const verdict = validate(value);
+    if (!verdict.ok)
+        throw new AgentPlatformError({
+            code: "provider_error",
+            message: `the model's answer does not satisfy the structured response format — ${verdict.detail}. ` +
+                "The turn is failed rather than returning it unchecked.",
+            retryable: true,
+        });
+    yield { type: "structured-output", value };
 }
 //# sourceMappingURL=streaming.js.map

package/dist/persistence/index.d.ts

@@ -237,7 +237,36 @@ export interface RunStore {
         workerId: string;
         leaseMs: number;
         now: string;
+        /**
+         * Refuse the claim when the tenant already holds this many **live leases** — REQ-058 (#246), task #265.
+         *
+         * Enforced *here*, inside the claim, and that placement is the whole design. Counting live leases and
+         * then claiming in a second statement is check-then-act: two workers in two processes both read
+         * "3 of 4 used" and both claim, and the tenant runs at 5. An adapter must make this one atomic
+         * operation — one SQL statement, or one turn of the event loop for the reference adapter.
+         *
+         * **Live leases, not a counter.** A counter incremented at admission and decremented at completion leaks
+         * a unit every time a worker dies mid-run, and a leaked unit is invisible until the tenant's effective
+         * concurrency has silently reached zero. A lease expires on its own, so a crashed worker's slot returns
+         * without anybody noticing it was gone.
+         *
+         * The run being claimed is never counted against itself, so recovering an expired lease is not blocked
+         * by the limit it is trying to satisfy.
+         *
+         * Absent or non-positive means unlimited.
+         */
+        maxConcurrent?: number;
     }): Promise<Run | null>;
+    /**
+     * How many of a tenant's runs hold a live lease right now.
+     *
+     * **Not the enforcement path** — `claim` is, because only `claim` can be atomic with the decision. This
+     * exists for two honest uses: telling an operator why a tenant's work is waiting, and letting the worker
+     * label a refused claim. A slightly stale answer costs a wrong log line, never a wrong admission.
+     */
+    countLive(input: TenantScope & {
+        now: string;
+    }): Promise<number>;
     /** Extend the lease. Returns false when the claim was lost (reaped/stolen) so the worker aborts. */
     keepalive(input: TenantScope & {
         id: RunId;
@@ -1524,6 +1553,207 @@ export interface KeywordIndex {
         sourceTypes?: readonly KnowledgeSourceType[];
     }): Promise<readonly KeywordSearchHit[]>;
 }
+/**
+ * Entities and relationships extracted from chunks, so retrieval can answer what no chunk says.
+ *
+ * A fourth port beside `KnowledgeStore`, `VectorIndex` and `KeywordIndex`, for the same reason those are three
+ * rather than one: it answers a different question and can be backed by a different system. A deployment on
+ * Postgres satisfies all four with one database; one that later wants a graph database swaps this alone.
+ *
+ * **Provenance is structural, not decorative.** Every entity and every edge records the chunk ids it was
+ * extracted from, and a row without provenance cannot be written. The retriever surfaces graph-derived material
+ * as *citable* hits, so a claim with no traceable chunk is one the model would present as though a document
+ * said it. `SEMANTIC_RELEVANCE_FLOOR` exists so retrieval can say "nothing"; this exists so the graph cannot say
+ * "something" without saying where from.
+ *
+ * **A source's contribution is what gets replaced, not the entity.** An entity like "retry budget" is mentioned
+ * by many sources, so re-indexing one document must not delete it — it must withdraw *that document's* claims
+ * and leave the rest. Hence the split: contributions are per source and per chunk, and an entity exists exactly
+ * as long as some contribution still names it. Deleting a source therefore prunes the entities only that source
+ * knew about, automatically, with no reference counting for anybody to get wrong.
+ */
+/** An entity's type as the extractor named it — free text, lowercased. Not a union: a corpus decides its own. */
+export type KnowledgeEntity = {
+    /** Deterministic and readable: `type:normalised-name`. See `entityId` in `knowledge/graph.ts`. */
+    readonly id: string;
+    /** The canonical surface form — the one chosen deterministically from everything merged into it. */
+    readonly name: string;
+    readonly type: string;
+    readonly description?: string;
+    /**
+     * Every distinct spelling merged into this entity, sorted — AC-6.
+     *
+     * Resolution merges things that are not the same, and the mistake is invisible unless the merges are
+     * recorded. Storing the surface forms turns "why is this entity called that" from an archaeology problem
+     * into a lookup.
+     */
+    readonly surfaceForms: readonly string[];
+    /** Chunk ids this entity was extracted from, sorted. Never empty. */
+    readonly provenance: readonly string[];
+};
+export type KnowledgeRelationship = {
+    /** Deterministic: `fromId|type|toId`. */
+    readonly id: string;
+    readonly fromId: string;
+    readonly toId: string;
+    readonly type: string;
+    readonly description?: string;
+    /** How many chunks asserted this edge. The obvious traversal ordering, and it needs no calibration. */
+    readonly weight: number;
+    /** Chunk ids this edge was extracted from, sorted. Never empty. */
+    readonly provenance: readonly string[];
+};
+/** What one source contributed, as written. The store merges these into entities and edges. */
+/**
+ * A community as stored: the cluster, and whatever summary has been written for it.
+ *
+ * `summaryFingerprint` is the mechanism behind visible staleness. A summary records the membership it was
+ * written against; when the graph changes and the community's `fingerprint` moves on, the two differ and the
+ * summary is knowably out of date — without a timestamp anybody has to interpret, and without re-reading the
+ * summary to guess.
+ */
+export type StoredCommunity = {
+    readonly id: string;
+    readonly level: number;
+    readonly entityIds: readonly string[];
+    readonly relationshipIds: readonly string[];
+    readonly chunkIds: readonly string[];
+    readonly fingerprint: string;
+    readonly summary?: string;
+    /** The `fingerprint` the summary was written against. Differs from `fingerprint` exactly when stale. */
+    readonly summaryFingerprint?: string;
+    readonly summarisedAt?: string;
+};
+/** True when a community has a summary that no longer describes its membership. */
+export declare const isCommunityStale: (community: StoredCommunity) => boolean;
+export type GraphContribution = {
+    readonly entities: readonly KnowledgeEntity[];
+    readonly relationships: readonly KnowledgeRelationship[];
+};
+/**
+ * Whether this tenant uses the graph at all, and which of its sources do.
+ *
+ * Two levels, because the cost is per chunk and paid at index time. A tenant switch alone would mean enabling
+ * the feature silently multiplies every tenant's indexing bill — including for the ad-hoc PDF somebody attached
+ * to one conversation. A per-source flag alone would leave no single place to say "this deployment does not use
+ * GraphRAG", which is the guarantee AC-1 rests on.
+ *
+ * A source flag is stored and honoured **independently** of the tenant switch, so a deployment can mark its
+ * handbook today and enable the tenant next week without re-marking anything.
+ */
+export type GraphSettings = {
+    readonly enabled: boolean;
+    /** When it was last changed, for an operator wondering why a bill moved. */
+    readonly updatedAt: string;
+};
+export interface GraphStore {
+    getSettings(input: TenantScope): Promise<GraphSettings>;
+    setEnabled(input: TenantScope & {
+        enabled: boolean;
+        at: string;
+    }): Promise<GraphSettings>;
+    /** Marks one source. Independent of the tenant switch — see `GraphSettings`. */
+    setSourceEnabled(input: TenantScope & {
+        sourceType: KnowledgeSourceType;
+        sourceId: string;
+        enabled: boolean;
+    }): Promise<void>;
+    isSourceEnabled(input: TenantScope & {
+        sourceType: KnowledgeSourceType;
+        sourceId: string;
+    }): Promise<boolean>;
+    listEnabledSources(input: TenantScope & PageRequest): Promise<Page<{
+        readonly sourceType: KnowledgeSourceType;
+        readonly sourceId: string;
+    }>>;
+    /**
+     * Replaces one source's contribution to the graph.
+     *
+     * Replace rather than append, for the reason `replaceSource` is: re-indexing a changed document must not
+     * leave its old claims in the graph. Entities and edges no source names any more are pruned by this call.
+     *
+     * Refuses a row with empty provenance rather than storing an untraceable claim.
+     */
+    replaceSourceGraph(input: TenantScope & {
+        sourceType: KnowledgeSourceType;
+        sourceId: string;
+        contribution: GraphContribution;
+    }): Promise<{
+        readonly entities: number;
+        readonly relationships: number;
+        readonly pruned: number;
+    }>;
+    deleteSourceGraph(input: TenantScope & {
+        sourceType: KnowledgeSourceType;
+        sourceId: string;
+    }): Promise<{
+        readonly pruned: number;
+    }>;
+    getEntity(input: TenantScope & {
+        id: string;
+    }): Promise<KnowledgeEntity | null>;
+    /** Entities by exact id, for a query-side resolver that has already normalised. */
+    getEntities(input: TenantScope & {
+        ids: readonly string[];
+    }): Promise<readonly KnowledgeEntity[]>;
+    /**
+     * Entities whose **normalised name** matches, across every type — REQ-064 (#270), task #273.
+     *
+     * A query says "the retry budget" and the graph holds `concept:retry budget`; the type is not in the
+     * question and cannot be. So resolution is by name, and the caller supplies names already normalised by
+     * `normaliseName`.
+     *
+     * That the id *is* `type:normalisedName` is what makes this a suffix match rather than a second stored
+     * column, and it is why query-side and index-side resolution agree by construction: the id was built by the
+     * same function the caller just called. A separate `normalised_name` column would be a second copy to drift.
+     */
+    resolveEntities(input: TenantScope & {
+        normalisedNames: readonly string[];
+    }): Promise<readonly KnowledgeEntity[]>;
+    listEntities(input: TenantScope & PageRequest & {
+        type?: string;
+    }): Promise<Page<KnowledgeEntity>>;
+    /** Every edge touching any of `entityIds`, in either direction. The traversal primitive. */
+    neighbours(input: TenantScope & {
+        entityIds: readonly string[];
+        limit: number;
+    }): Promise<readonly KnowledgeRelationship[]>;
+    /**
+     * Replaces the whole community hierarchy — REQ-064 (#270), task #272.
+     *
+     * Whole rather than per level, because clustering is global: an entity moving between communities can change
+     * every level above it, and a partial write would leave a hierarchy whose levels disagree about who is in
+     * what. Summaries already written are carried over for communities whose fingerprint is unchanged, which is
+     * what makes re-summarisation incremental — the expensive half — while clustering stays global and cheap.
+     */
+    replaceCommunities(input: TenantScope & {
+        communities: readonly StoredCommunity[];
+    }): Promise<{
+        readonly written: number;
+        readonly summariesKept: number;
+    }>;
+    listCommunities(input: TenantScope & PageRequest & {
+        level?: number;
+    }): Promise<Page<StoredCommunity>>;
+    getCommunity(input: TenantScope & {
+        id: string;
+    }): Promise<StoredCommunity | null>;
+    /** Records a generated summary against the fingerprint it was written for. */
+    setCommunitySummary(input: TenantScope & {
+        id: string;
+        summary: string;
+        fingerprint: string;
+        at: string;
+    }): Promise<void>;
+    /**
+     * A stable serialisation of the whole graph, for the determinism assertion — AC-6.
+     *
+     * On the port rather than built by the test, so *every* adapter is held to it. A test that serialised the
+     * graph itself would prove the reference adapter deterministic and say nothing about Postgres, where row
+     * order is the thing most likely to differ.
+     */
+    fingerprint(input: TenantScope): Promise<string>;
+}
 /**
  * Content-addressable blob storage for spilled tool output (`docs/03` → Tool results). A large
  * result is offloaded here and referenced by an authorized `BlobRef`, read back via

package/dist/persistence/index.js

@@ -214,6 +214,8 @@ export const KEYWORD_STOPWORDS = new Set([
 export const stripStopwords = (query) => (query.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)*/g) ?? [])
     .filter((term) => !KEYWORD_STOPWORDS.has(term))
     .join(" ");
+/** True when a community has a summary that no longer describes its membership. */
+export const isCommunityStale = (community) => community.summary !== undefined && community.summaryFingerprint !== community.fingerprint;
 export const ADAPTER_CAPABILITIES = [
     "transactions",
     "row-level-security",