@inflexa-ai/harness 0.45.0 → 0.45.1

package/dist/tools/knowledge/environment.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The environment join of a procedure: which package of each step the farm
+ * holds, at which version, and which collection of the reference store the
+ * enrichment step names. The service knows the methods and the collections
+ * by name; the host knows what is installed. Joined here, the answer of
+ * `knowledge_recommend` carries the environment, and a planner has no reason
+ * to call the listing tools for the packages and the collection it was told
+ * to use. A model that hunts for what it already has was the cost of the
+ * Phase 0 campaigns on a small model.
+ *
+ * The installed packages come from two records the host reads, never from a
+ * list in the code: the `inflexa.lock` of the farm names the packages the
+ * store links, and the `image-packages.json` of the store names what the
+ * sandbox image itself ships, among them the R packages of the R runtime
+ * (`stats`, `survival`, `MASS`), which no farm lock lists. Both records are
+ * written by their producers and validated here.
+ *
+ * Absence is data: a package neither record names reads `present: false`,
+ * and a collection the store lacks reads `present: false`. The join never
+ * fills a gap and never names a path it did not read.
+ */
+import type { FarmPackage, RecommendResponse } from "./client.js";
+export interface EnvironmentPaths {
+    /** Host path of the farm `inflexa.lock`. Absent, the packages read as unknown. */
+    readonly farmLockFile?: string;
+    /** Host path of the `image-packages.json` of the store. Absent, the packages the image ships are unknown. */
+    readonly imagePackagesFile?: string;
+    /** Host path of the reference store. Absent, the collection reads as unknown. */
+    readonly refStorePath?: string;
+}
+export interface StepEnvironment {
+    readonly package?: {
+        readonly name: string;
+        readonly present: boolean;
+        readonly version?: string;
+    };
+    readonly collection?: {
+        readonly name: string;
+        readonly present: boolean;
+        readonly path?: string;
+        readonly title?: string;
+    };
+}
+/** Where each fact of the environment came from: a record the host read, or nothing. */
+export interface EnvironmentSource {
+    readonly farm: "lock" | "unknown";
+    /** `record` when the store carries the `image-packages.json` of the sandbox image. */
+    readonly image: "record" | "unknown";
+    readonly references: "store" | "unknown";
+}
+/** The recommend answer with an `environment` per step. */
+export type RecommendWithEnvironment = RecommendResponse & {
+    readonly environment_source?: EnvironmentSource;
+    readonly procedure: readonly (RecommendResponse["procedure"][number] & {
+        readonly environment?: StepEnvironment;
+    })[];
+};
+/**
+ * The packages installed in the sandbox, as the two records report them, with
+ * one entry per name. The farm lock comes first and it wins a collision,
+ * because a farm that links its own copy of a package is what a step loads.
+ * `packages` is absent when neither record is readable, thus a caller sends
+ * nothing to the knowledge service rather than an empty farm, and the answer
+ * reads `unknown` instead of "absent".
+ *
+ * Of the image record only the R runtime track joins the list. The conda
+ * tools and the Node packages of the image are not of the package tracks a
+ * template pins, and a name of one of them must not answer for a package.
+ *
+ * The same list serves the environment join of the recommend answer and the
+ * environment match of a rendered template, thus the two agree.
+ */
+export declare function installedPackages(paths: Pick<EnvironmentPaths, "farmLockFile" | "imagePackagesFile">): {
+    readonly packages?: readonly FarmPackage[];
+    readonly farm: EnvironmentSource["farm"];
+    readonly image: EnvironmentSource["image"];
+};
+export declare function joinEnvironment(answer: RecommendResponse, paths: EnvironmentPaths): Promise<RecommendWithEnvironment>;

package/dist/tools/knowledge/environment.js

@@ -0,0 +1,105 @@
+/**
+ * The environment join of a procedure: which package of each step the farm
+ * holds, at which version, and which collection of the reference store the
+ * enrichment step names. The service knows the methods and the collections
+ * by name; the host knows what is installed. Joined here, the answer of
+ * `knowledge_recommend` carries the environment, and a planner has no reason
+ * to call the listing tools for the packages and the collection it was told
+ * to use. A model that hunts for what it already has was the cost of the
+ * Phase 0 campaigns on a small model.
+ *
+ * The installed packages come from two records the host reads, never from a
+ * list in the code: the `inflexa.lock` of the farm names the packages the
+ * store links, and the `image-packages.json` of the store names what the
+ * sandbox image itself ships, among them the R packages of the R runtime
+ * (`stats`, `survival`, `MASS`), which no farm lock lists. Both records are
+ * written by their producers and validated here.
+ *
+ * Absence is data: a package neither record names reads `present: false`,
+ * and a collection the store lacks reads `present: false`. The join never
+ * fills a gap and never names a path it did not read.
+ */
+import { readFarmLockFile } from "../../sandbox/farm.js";
+import { readImagePackagesFile } from "../../sandbox/image-packages.js";
+import { readReferenceInventory } from "../sandbox/list-available-refs.js";
+/**
+ * The packages installed in the sandbox, as the two records report them, with
+ * one entry per name. The farm lock comes first and it wins a collision,
+ * because a farm that links its own copy of a package is what a step loads.
+ * `packages` is absent when neither record is readable, thus a caller sends
+ * nothing to the knowledge service rather than an empty farm, and the answer
+ * reads `unknown` instead of "absent".
+ *
+ * Of the image record only the R runtime track joins the list. The conda
+ * tools and the Node packages of the image are not of the package tracks a
+ * template pins, and a name of one of them must not answer for a package.
+ *
+ * The same list serves the environment join of the recommend answer and the
+ * environment match of a rendered template, thus the two agree.
+ */
+export function installedPackages(paths) {
+    const lock = paths.farmLockFile ? readFarmLockFile(paths.farmLockFile).unwrapOr(undefined) : undefined;
+    const record = paths.imagePackagesFile ? readImagePackagesFile(paths.imagePackagesFile).unwrapOr(undefined) : undefined;
+    if (!lock && !record)
+        return { farm: "unknown", image: "unknown" };
+    const packages = [];
+    const seen = new Set();
+    for (const pkg of [...(lock?.packages ?? []), ...(record?.r_base ?? [])]) {
+        const key = pkg.name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        packages.push({ name: pkg.name, version: pkg.version });
+    }
+    return { packages, farm: lock ? "lock" : "unknown", image: record ? "record" : "unknown" };
+}
+function tokens(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 1);
+}
+/** A collection term of the tree (`msigdb_hallmark_human`) matches an entry whose labels hold every token of the term. */
+function findCollection(term, entries) {
+    const wanted = tokens(term);
+    if (wanted.length === 0)
+        return undefined;
+    const candidates = entries.filter((entry) => {
+        const haystack = tokens([entry.path, entry.metadata?.datasetId ?? "", entry.metadata?.title ?? ""].join(" "));
+        return wanted.every((token) => haystack.includes(token));
+    });
+    // A directory entry names the dataset; a file inside it is the concrete artifact. Prefer the file.
+    return candidates.find((entry) => entry.kind === "file") ?? candidates[0];
+}
+export async function joinEnvironment(answer, paths) {
+    if (answer.match !== "applicable" && answer.match !== "flag")
+        return answer;
+    const installed = installedPackages(paths);
+    const farm = installed.packages ? new Map(installed.packages.map((pkg) => [pkg.name.toLowerCase(), pkg.version])) : undefined;
+    const inventory = paths.refStorePath ? await readReferenceInventory(paths.refStorePath).catch(() => undefined) : undefined;
+    const entries = inventory?.available ? inventory.entries : undefined;
+    const procedure = answer.procedure.map((step) => {
+        const environment = {};
+        const pkg = step.package;
+        if (pkg && farm) {
+            const version = farm.get(pkg.name.toLowerCase());
+            environment.package = { name: pkg.name, present: version !== undefined, ...(version !== undefined ? { version } : {}) };
+        }
+        const collection = step.parameters?.find((parameter) => parameter.name === "gene_set_collection");
+        if (collection && typeof collection.value === "string" && entries) {
+            const found = findCollection(collection.value, entries);
+            environment.collection = {
+                name: collection.value,
+                present: found !== undefined,
+                ...(found ? { path: found.path } : {}),
+                ...(found?.metadata?.title ? { title: found.metadata.title } : {}),
+            };
+        }
+        return Object.keys(environment).length > 0 ? { ...step, environment } : step;
+    });
+    return {
+        ...answer,
+        procedure,
+        environment_source: { farm: installed.farm, image: installed.image, references: entries ? "store" : "unknown" },
+    };
+}

package/dist/tools/knowledge/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Knowledge barrel — the three tools of the knowledge plane and the client
+ * interface they share.
+ *
+ * `createKnowledgeTools` gives the two planner tools when a client is bound,
+ * and nothing when it is not. Absence is the default state of the open-source
+ * host, and it is a normal condition: no tool attaches, no description enters
+ * the context, and the planner works from the prose skills as it does today.
+ * The template tool binds per step, because it needs the mutator of the step.
+ */
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import type { Tool } from "../define-tool.js";
+import type { KnowledgeClient } from "./client.js";
+import { type KnowledgeRecommendDeps } from "./recommend.js";
+export * from "./client.js";
+export * from "./environment.js";
+export * from "./local-slots.js";
+export * from "./pin.js";
+export * from "./skeleton.js";
+export * from "./check.js";
+export * from "./recommend.js";
+export * from "./situation.js";
+export * from "./template.js";
+export interface KnowledgeToolsDeps {
+    readonly client?: KnowledgeClient;
+    /** Host path of the farm `inflexa.lock`, or its resolver for each analysis, for the environment join of the recommend answer. */
+    readonly farmLockFile?: EnvironmentStorePaths["farmLockFile"];
+    /** Host path of the `image-packages.json` of the store, for the same join: the packages the sandbox image ships. */
+    readonly imagePackagesFile?: string;
+    /** Host path of the reference store, for the same join. */
+    readonly refStorePath?: string;
+    /** Receives each recommend answer the planner sees; see `KnowledgeRecommendDeps.onAnswer`. */
+    readonly onRecommend?: KnowledgeRecommendDeps["onAnswer"];
+}
+/**
+ * The planner tools: `knowledge_recommend` and `knowledge_check`, or an empty
+ * list with no client. The two share one pin: the first recommend answer
+ * fixes the release of the plan, and each later call carries it.
+ */
+export declare function createKnowledgeTools(deps: KnowledgeToolsDeps): Tool[];
+/**
+ * The digest of the three tool definitions as this host registers them: the
+ * id, the description, and the input schema of each, in id order. The
+ * snapshot of the service pins its wire contract under its own tool
+ * definition hash; this one names what the model saw, and a run records it,
+ * thus a changed description or schema is a visible change of the run and
+ * not a silent one.
+ */
+export declare function knowledgeToolDefinitionHash(): string;

package/dist/tools/knowledge/index.js

@@ -0,0 +1,70 @@
+/**
+ * Knowledge barrel — the three tools of the knowledge plane and the client
+ * interface they share.
+ *
+ * `createKnowledgeTools` gives the two planner tools when a client is bound,
+ * and nothing when it is not. Absence is the default state of the open-source
+ * host, and it is a normal condition: no tool attaches, no description enters
+ * the context, and the planner works from the prose skills as it does today.
+ * The template tool binds per step, because it needs the mutator of the step.
+ */
+import { createHash } from "node:crypto";
+import { createKnowledgeCheckTool } from "./check.js";
+import { createSnapshotPin } from "./pin.js";
+import { createKnowledgeRecommendTool } from "./recommend.js";
+import { createKnowledgeTemplateTool } from "./template.js";
+export * from "./client.js";
+export * from "./environment.js";
+export * from "./local-slots.js";
+export * from "./pin.js";
+export * from "./skeleton.js";
+export * from "./check.js";
+export * from "./recommend.js";
+export * from "./situation.js";
+export * from "./template.js";
+/**
+ * The planner tools: `knowledge_recommend` and `knowledge_check`, or an empty
+ * list with no client. The two share one pin: the first recommend answer
+ * fixes the release of the plan, and each later call carries it.
+ */
+export function createKnowledgeTools(deps) {
+    if (!deps.client)
+        return [];
+    const pin = createSnapshotPin();
+    return [
+        createKnowledgeRecommendTool({
+            client: deps.client,
+            pin,
+            ...(deps.farmLockFile ? { farmLockFile: deps.farmLockFile } : {}),
+            ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+            ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}),
+            ...(deps.onRecommend ? { onAnswer: deps.onRecommend } : {}),
+        }),
+        createKnowledgeCheckTool({ client: deps.client, pin }),
+    ];
+}
+/** A client that answers nothing: the definitions of the tools do not depend on the answers. */
+const NO_CLIENT = {
+    recommend: async () => ({ match: "unavailable", reason: "no service" }),
+    check: async () => ({ match: "unavailable", reason: "no service" }),
+    render: async () => ({ match: "unavailable", reason: "no service" }),
+    contract: async () => ({ match: "unavailable", reason: "no service" }),
+};
+/** A mutator that writes nothing: the definition of the template tool does not depend on the workspace. */
+const NO_MUTATOR = {
+    writeFile: async ({ path }) => ({ status: "out_of_scope", path }),
+    recordWrite: () => undefined,
+};
+/**
+ * The digest of the three tool definitions as this host registers them: the
+ * id, the description, and the input schema of each, in id order. The
+ * snapshot of the service pins its wire contract under its own tool
+ * definition hash; this one names what the model saw, and a run records it,
+ * thus a changed description or schema is a visible change of the run and
+ * not a silent one.
+ */
+export function knowledgeToolDefinitionHash() {
+    const tools = [...createKnowledgeTools({ client: NO_CLIENT }), createKnowledgeTemplateTool({ client: NO_CLIENT, mutator: NO_MUTATOR })];
+    const definitions = tools.map((tool) => ({ id: tool.id, description: tool.description, schema: tool.jsonSchema })).sort((a, b) => (a.id < b.id ? -1 : 1));
+    return `sha256:${createHash("sha256").update(JSON.stringify(definitions), "utf8").digest("hex")}`;
+}

package/dist/tools/knowledge/local-slots.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The local slots of a template: the slots whose value is a fact of the
+ * machine (a path, a column name, a level label, a design formula). The
+ * service renders such a slot as its marker `{{name}}` and never sees its
+ * value; the host binds the value here, after the render and before the
+ * write, thus the value never leaves the machine.
+ *
+ * `bindLocalSlots` is a copy of the reference implementation the knowledge
+ * service exports (`src/render/render.ts` of the service). The two must give
+ * the same bytes: a marked render bound here equals a full render of the
+ * service for the same values. Keep the literal rules in step with the
+ * service when a slot type is added.
+ */
+import type { TemplateParameter } from "./client.js";
+/** A slot value: a scalar, or a list of strings. */
+export type LocalSlotValue = string | number | boolean | readonly string[];
+/** One refusal of a local value, in the shape of a render rejection issue. */
+export interface LocalSlotIssue {
+    readonly slot: string;
+    readonly reason: string;
+    readonly permitted?: readonly string[];
+}
+/** One bound slot as the decision record keeps it: the value, its source, and the lines that carried its marker. */
+export interface BoundLocalSlot {
+    readonly name: string;
+    readonly value: LocalSlotValue;
+    readonly source: "caller" | "default";
+    readonly adaptable: true;
+    readonly default_source?: string;
+    readonly lines: readonly number[];
+    /** The `read` flag the service computed for the slot on the marked render, when it has a `when` condition. */
+    readonly read?: boolean;
+}
+export type BindLocalSlotsResult = {
+    readonly ok: false;
+    readonly issues: readonly LocalSlotIssue[];
+} | {
+    readonly ok: true;
+    readonly script: string;
+    readonly slots: readonly BoundLocalSlot[];
+};
+/** The local slots of a contract, in the order the template declares them. */
+export declare function localParameters(parameters: readonly TemplateParameter[]): TemplateParameter[];
+/** Check one caller value against the contract of its slot, as the renderer of the service does. */
+export declare function validateLocalSlot(parameter: TemplateParameter, value: unknown): LocalSlotIssue | undefined;
+/** The marker of a slot as the service leaves it in a marked render. */
+export declare function slotMarker(name: string): string;
+/**
+ * Bind the local values into a marked script. Each local marker takes the
+ * literal of its value, else of the default of the slot, else the absent
+ * literal when the slot is optional. A required local slot with no value
+ * and no default is an issue, and so is a value the contract refuses. The
+ * report names the source of each bound slot and keeps the `read` flag of
+ * the marked report of the service.
+ */
+export declare function bindLocalSlots(template: {
+    readonly language: string;
+    readonly parameters: readonly TemplateParameter[];
+}, script: string, localValues: Readonly<Record<string, unknown>>, marked?: readonly {
+    readonly name: string;
+    readonly read?: boolean;
+}[]): BindLocalSlotsResult;

package/dist/tools/knowledge/local-slots.js

@@ -0,0 +1,177 @@
+/**
+ * The local slots of a template: the slots whose value is a fact of the
+ * machine (a path, a column name, a level label, a design formula). The
+ * service renders such a slot as its marker `{{name}}` and never sees its
+ * value; the host binds the value here, after the render and before the
+ * write, thus the value never leaves the machine.
+ *
+ * `bindLocalSlots` is a copy of the reference implementation the knowledge
+ * service exports (`src/render/render.ts` of the service). The two must give
+ * the same bytes: a marked render bound here equals a full render of the
+ * service for the same values. Keep the literal rules in step with the
+ * service when a slot type is added.
+ */
+/** The local slots of a contract, in the order the template declares them. */
+export function localParameters(parameters) {
+    return parameters.filter((parameter) => parameter.local === true);
+}
+const FORMULA_PATTERN = /^~\s*[A-Za-z0-9_.+*:()\s-]+$/;
+/** Check one caller value against the contract of its slot, as the renderer of the service does. */
+export function validateLocalSlot(parameter, value) {
+    const slot = parameter.name;
+    const permitted = parameter.enum;
+    switch (parameter.type) {
+        case "string":
+        case "formula": {
+            if (typeof value !== "string" || value.length === 0)
+                return { slot, reason: "a non-empty string is required" };
+            if (parameter.type === "formula" && !FORMULA_PATTERN.test(value))
+                return { slot, reason: "a formula must start with ~ and hold only names, +, :, *, and parentheses" };
+            if (permitted && !permitted.includes(value))
+                return { slot, reason: `the value "${value}" is not permitted`, permitted };
+            if (parameter.pattern && !new RegExp(parameter.pattern).test(value))
+                return { slot, reason: `the value must match ${parameter.pattern}` };
+            return undefined;
+        }
+        case "number":
+        case "integer": {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return { slot, reason: "a number is required" };
+            if (parameter.type === "integer" && !Number.isInteger(value))
+                return { slot, reason: "an integer is required" };
+            if (parameter.minimum !== undefined && value < parameter.minimum)
+                return { slot, reason: `the value must be at least ${parameter.minimum}` };
+            if (parameter.maximum !== undefined && value > parameter.maximum)
+                return { slot, reason: `the value must be at most ${parameter.maximum}` };
+            return undefined;
+        }
+        case "boolean":
+            return typeof value === "boolean" ? undefined : { slot, reason: "a boolean is required" };
+        case "string_list": {
+            if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+                return { slot, reason: "a list of strings is required" };
+            if (permitted) {
+                const bad = value.find((item) => !permitted.includes(item));
+                if (bad !== undefined)
+                    return { slot, reason: `the value "${bad}" is not permitted`, permitted };
+            }
+            return undefined;
+        }
+        default:
+            // The contract is a loose object of the wire, thus a type this host does not know is possible. It is
+            // refused, never rendered as text, because a wrong literal is a wrong script.
+            return { slot, reason: `the slot type ${parameter.type} is not one this host renders` };
+    }
+}
+/** A slot value as a literal of the language: R gives `TRUE` and `c(...)`, Python gives `True` and `[...]`. */
+function literal(language, parameter, value) {
+    const python = language === "python";
+    switch (parameter.type) {
+        case "string":
+            return JSON.stringify(String(value));
+        case "formula":
+            return String(value);
+        case "number":
+        case "integer":
+            return String(value);
+        case "boolean":
+            return python ? (value ? "True" : "False") : value ? "TRUE" : "FALSE";
+        case "string_list": {
+            const items = Array.isArray(value) ? value : [String(value)];
+            const rendered = items.map((item) => JSON.stringify(String(item))).join(", ");
+            return python ? `[${rendered}]` : `c(${rendered})`;
+        }
+        default:
+            throw new Error(`unhandled slot type: ${parameter.type}`);
+    }
+}
+/** The literal of an optional slot that has no value: R keeps the type of the slot, Python has one absent scalar and an empty list. */
+function absentLiteral(language, type) {
+    if (language === "python")
+        return type === "string_list" ? "[]" : "None";
+    switch (type) {
+        case "string":
+            return "NA_character_";
+        case "integer":
+            return "NA_integer_";
+        case "number":
+            return "NA_real_";
+        case "boolean":
+            return "NA";
+        case "string_list":
+            return "character(0)";
+        default:
+            return "NULL";
+    }
+}
+/** The marker of a slot as the service leaves it in a marked render. */
+export function slotMarker(name) {
+    return `{{${name}}}`;
+}
+/**
+ * Bind the local values into a marked script. Each local marker takes the
+ * literal of its value, else of the default of the slot, else the absent
+ * literal when the slot is optional. A required local slot with no value
+ * and no default is an issue, and so is a value the contract refuses. The
+ * report names the source of each bound slot and keeps the `read` flag of
+ * the marked report of the service.
+ */
+export function bindLocalSlots(template, script, localValues, marked = []) {
+    const issues = [];
+    const locals = localParameters(template.parameters);
+    const byName = new Map(locals.map((parameter) => [parameter.name, parameter]));
+    for (const name of Object.keys(localValues)) {
+        if (!byName.has(name))
+            issues.push({ slot: name, reason: "the template has no such local slot", permitted: [...byName.keys()] });
+    }
+    const values = new Map();
+    const slots = [];
+    for (const parameter of locals) {
+        const given = localValues[parameter.name];
+        if (given !== undefined) {
+            const issue = validateLocalSlot(parameter, given);
+            if (issue) {
+                issues.push(issue);
+                continue;
+            }
+            // Validated above: a string, a finite number, a boolean, or a list of strings.
+            const value = given;
+            values.set(parameter.name, value);
+            slots.push({ name: parameter.name, value, source: "caller", adaptable: true, lines: [] });
+        }
+        else if (parameter.default !== undefined) {
+            // The contract is loose on the wire; a default is a scalar or a list of strings by the contract of the service,
+            // and the service renders whatever it holds, thus only an absent default is absent here too.
+            const value = parameter.default;
+            values.set(parameter.name, value);
+            slots.push({
+                name: parameter.name,
+                value,
+                source: "default",
+                adaptable: true,
+                ...(parameter.default_source ? { default_source: parameter.default_source } : {}),
+                lines: [],
+            });
+        }
+        else if (parameter.required !== false) {
+            issues.push({ slot: parameter.name, reason: "the local slot is required and has no value" });
+        }
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    const bound = script.replace(/\{\{([a-z][a-z0-9_]*)\}\}/g, (whole, name) => {
+        const parameter = byName.get(name);
+        if (!parameter)
+            return whole;
+        const value = values.get(name);
+        return value === undefined ? absentLiteral(template.language, parameter.type) : literal(template.language, parameter, value);
+    });
+    const lines = bound.split("\n");
+    const readByName = new Map(marked.flatMap((entry) => (entry.read === undefined ? [] : [[entry.name, entry.read]])));
+    const located = slots.map((entry) => ({
+        ...entry,
+        lines: script.split("\n").flatMap((line, index) => (line.includes(slotMarker(entry.name)) && index < lines.length ? [index + 1] : [])),
+        ...(readByName.has(entry.name) ? { read: readByName.get(entry.name) } : {}),
+    }));
+    return { ok: true, script: bound, slots: located };
+}

package/dist/tools/knowledge/pin.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The release a plan pins. The planner tools of one plan generation share
+ * one pin: the first recommend answer sets it, and every later call of the
+ * service inside that plan carries it as `expected_snapshot`. A service that
+ * moved to another release between two calls then refuses the call, and the
+ * plan never mixes two releases in silence.
+ */
+export interface SnapshotPin {
+    /** The pinned release digest, or `undefined` before the first answer. */
+    get(): string | undefined;
+    /** Pin the release of the first answer. A later call with another digest changes nothing: the first release is the plan's. */
+    set(digest: string): void;
+}
+export declare function createSnapshotPin(): SnapshotPin;

package/dist/tools/knowledge/pin.js

@@ -0,0 +1,17 @@
+/**
+ * The release a plan pins. The planner tools of one plan generation share
+ * one pin: the first recommend answer sets it, and every later call of the
+ * service inside that plan carries it as `expected_snapshot`. A service that
+ * moved to another release between two calls then refuses the call, and the
+ * plan never mixes two releases in silence.
+ */
+export function createSnapshotPin() {
+    let pinned;
+    return {
+        get: () => pinned,
+        set: (digest) => {
+            if (pinned === undefined)
+                pinned = digest;
+        },
+    };
+}