@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/knowledge/situation.js

@@ -0,0 +1,157 @@
+/**
+ * The situation fields as a flat tool input. Each `.describe()` is the whole
+ * of what the model knows about a field, thus the descriptions carry the
+ * definitions of the terms, and they tell the planner where in the Data
+ * Context each value comes from.
+ */
+import { z } from "zod";
+export const SituationFieldsSchema = z.object({
+    question: z
+        .enum([
+        "differential_expression",
+        "enrichment",
+        "qc",
+        "full_plan",
+        "tf_activity",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "signature_scoring",
+    ])
+        .describe("What the plan needs a procedure for. `full_plan` returns QC, filtering, the model, the test, shrinkage, multiple testing, enrichment, and the report in one answer. " +
+        "Use `differential_expression` when the research question does not ask for pathways or gene sets; an enrichment step the user did not ask for is unasked scope. " +
+        "Use `enrichment` when a results table is the input and no new test is fitted, and `qc` when the question stops at the sample structure. " +
+        "Use `tf_activity` for regulator or pathway activity, `deconvolution` for cell type proportions, `coexpression` for modules, `clustering` for sample subgroups, `survival` for an outcome association, " +
+        "and `signature_scoring` for a per-sample score, or with `classifier: true` for a classifier of the samples."),
+    modality: z.literal("bulk_rna_seq").describe("The assay. Phase 0 serves bulk RNA-seq only."),
+    data_state: z
+        .enum(["fastq", "counts", "tpm_or_fpkm", "log_normalized"])
+        .describe("The state of the expression data in the inputs: raw reads, a raw integer count matrix, TPM/FPKM/RPKM abundances, or log-scale normalized values (log-CPM, microarray)."),
+    count_source: z
+        .enum(["salmon", "kallisto", "star_featurecounts", "rsem", "unknown"])
+        .optional()
+        .describe("The quantifier that produced the counts, when the profile names one. The quantifier does not establish the length correction; `import_state` does."),
+    import_state: z
+        .enum(["quantifications", "estimated_counts_with_lengths", "corrected_counts", "integer_counts", "unknown"])
+        .optional()
+        .describe("The import state of a count table from a transcript quantifier (Salmon, kallisto, RSEM): whether the length correction occurred. Read it from the profile. " +
+        "`quantifications`: per-sample quantification files (quant.sf or abundance.h5) or a quantification directory, plus a transcript-to-gene map. " +
+        "`estimated_counts_with_lengths`: a fractional gene-by-sample matrix plus a table of average transcript lengths per gene and sample. " +
+        "`corrected_counts`: a table described as lengthScaledTPM or scaledTPM counts. " +
+        "`integer_counts`: integer counts from an aligner and a counter (STAR, featureCounts) or from a 3' protocol, with no length data. " +
+        "`unknown`: a count table from a quantifier with no statement of the correction. Omit when `data_state` is not `counts`."),
+    organism: z.enum(["human", "mouse", "other"]).describe("The organism of the samples."),
+    n_groups: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The number of levels of the condition of interest (2 for a two-group comparison; 4 for a 2x2 design; 1 when `continuous_predictor` names the variable of interest)."),
+    n_per_group_min: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The smallest number of biological samples in any group, after technical replicates are summed. 1 means a group has no replication. In a time course, the smallest number in one group at one time point. With a nested block, the smallest number of blocks (for example animals) in one group. With a continuous predictor, the number of samples."),
+    n_per_group_max: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The largest number of biological samples in any group. In a time course, the largest number in one group at one time point. With a nested block, the largest number of blocks in one group. With a continuous predictor, the number of samples."),
+    n_samples: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("The total number of biological samples in the analysis, after technical replicates are summed. Give it whenever the profile states it: the per-group extrema do not give the total for three or more groups, and the rules on a small cohort read it."),
+    n_events: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("For a survival question, the number of samples with an observed event (event indicator 1) in the outcome column. Omit when the question is not survival or the count is not in the profile."),
+    paired: z.boolean().describe("True when each subject contributes a sample to more than one condition (paired or repeated measures)."),
+    blocking_factor: z
+        .enum(["individual", "cell_line", "litter", "site", "pair", "other"])
+        .nullable()
+        .optional()
+        .describe("The role of the blocking factor that is not the condition, never its column name: `individual` when the same subject, donor, or animal gives more than one sample; `cell_line`; `litter`; `site` for a center or a lab of a multi-site study; `pair` for matched pairs of different individuals; `other`. Omit when there is none. The column name stays in the step."),
+    block_structure: z
+        .enum(["crossed", "nested"])
+        .optional()
+        .describe("How the blocking factor relates to the condition: `crossed` when each block holds samples of more than one condition (a donor with a treated and a control sample); `nested` when each block lies inside one condition (several samples from one animal of one genotype), thus the block is the unit of replication. Omit when there is no blocking factor."),
+    batch: z
+        .enum(["none", "known_balanced", "known_confounded", "known_unbalanced", "suspected"])
+        .describe("The batch structure: none; a known batch whose levels each hold every condition; a known batch whose levels coincide with the conditions; a known batch whose levels do not each hold every condition but at least one level holds two conditions (estimable, unbalanced); or a suspected structure (dates, lanes, plates) the metadata does not name."),
+    covariates: z
+        .array(z.enum(["sex", "age", "clinical", "technical", "other"]))
+        .optional()
+        .describe('The role of each other sample covariate the design must hold, one entry per covariate and never a column name, for example ["sex", "age"]: `clinical` for a stage, a grade, or a diagnosis; `technical` for a variable that is not the batch, for example the RNA integrity. Omit when there are none. The column names stay in the step.'),
+    n_timepoints: z.number().int().min(1).nullable().optional().describe("The number of time points when the design is a time course. Omit otherwise."),
+    continuous_predictor: z
+        .enum(["dose", "time", "age", "score", "other"])
+        .nullable()
+        .optional()
+        .describe("The role of the numeric variable of interest, never its column name, when the research question is a trend over that value and not a comparison of groups: `dose`, `time`, `age`, `score`, or `other`. Then set `n_groups` to 1 and the per-group counts to the number of samples. Omit when the variable of interest is a factor. The column name stays in the step."),
+    technical_replicates: z
+        .boolean()
+        .optional()
+        .describe("Set true when some columns of the count table are technical replicates of one biological sample, for example one library sequenced on two lanes or two runs. Omit when each column is one biological sample."),
+    sample_exclusions: z
+        .boolean()
+        .optional()
+        .describe("Set true when the plan drops some delivered samples before the analysis, for example an on-treatment biopsy in a pre-treatment cohort or a failed library. The service then adds a cohort assembly step that counts the units per group after the drop, so the plan states no count before that step. Omit when every delivered sample enters the analysis."),
+    feature_level: z
+        .enum(["gene", "exon", "transcript"])
+        .optional()
+        .describe("The row unit of the count table: `gene` for one row per gene; `exon` for one row per exon or counting bin with the gene of each row, as featureCounts at the feature level writes it; `transcript` for one row per transcript, as tximport writes with txOut or a quantifier table delivers. Omit for a gene-level table or when `data_state` is not counts."),
+    library_type: z.enum(["polyA", "total", "three_prime", "unknown"]).optional().describe("The library preparation, when known."),
+    strandedness: z
+        .enum(["verified", "declared_unverified", "unknown"])
+        .optional()
+        .describe("Whether the strandedness was verified against the quantification, declared but not verified, or unknown."),
+    interaction: z.boolean().optional().describe("True when the question is the interaction of two factors (for example genotype by treatment)."),
+    classifier: z
+        .boolean()
+        .optional()
+        .describe("Set true when the question is a classifier of the samples into classes (a model that predicts the class of a sample from its expression, with cross-validation). Omit for a per-sample score."),
+    extra_analyses: z
+        .array(z.enum([
+        "variance_partition",
+        "tf_activity",
+        "pathway_activity",
+        "signature_scoring",
+        "deconvolution",
+        "coexpression",
+        "clustering",
+        "survival",
+        "transcript_level",
+        "annotation",
+    ]))
+        .optional()
+        .describe("Analyses the research question asks for beside the question kind, for example a regulator activity beside a differential expression. Each joins the procedure at its place. " +
+        "Add `annotation` when the rows of the count table are not gene symbols (Ensembl or Entrez identifiers) and a later step needs symbols: the identifier map is then a vetted step with its own template, and no other step rebuilds it. Omit when none."),
+    preferred_language: z
+        .enum(["R", "python"])
+        .optional()
+        .describe("The script language the user asked for, when the user constraints name one. The answer then names the template in that language when the method has one. Omit otherwise."),
+    enrichment_input: z
+        .enum(["ranked_list", "gene_list", "sample_scores"])
+        .optional()
+        .describe("What the enrichment step takes: `ranked_list` for every tested gene ranked by a statistic (the default), `gene_list` for a discrete list such as the significant genes, `sample_scores` for a pathway score per sample. Omit when the question has no enrichment."),
+    quality_flags: z
+        .array(z.enum(["low_depth_sample", "outlier_sample", "sample_identity_doubt", "high_duplication", "degraded_rna"]))
+        .optional()
+        .describe("The quality concerns of the profile as typed flags: a sample with a library size far below the median; a sample that does not cluster with its group; a doubt about the identity of a sample; high duplication; degraded RNA (a low RNA integrity number, a 3' coverage bias, or formalin-fixed material)."),
+});
+/** The situation as the client sends it: the fields as given, with the caller preference held out of the situation fields. */
+export function toSituation(fields) {
+    const { preferred_language: _omitted, ...situation } = fields;
+    return situation;
+}
+/** The preferences of the caller, beside the situation: the language of the template. */
+export function toPreferences(fields) {
+    return fields.preferred_language ? { language: fields.preferred_language } : undefined;
+}
+/** One worked example, in the descriptions of the two planner tools. Examples raise complex-parameter accuracy. */
+export const SITUATION_EXAMPLE = '{"question":"differential_expression","modality":"bulk_rna_seq","data_state":"counts","count_source":"salmon","import_state":"unknown","organism":"human",' +
+    '"n_groups":2,"n_per_group_min":6,"n_per_group_max":6,"paired":false,"batch":"none","quality_flags":["low_depth_sample"]}';

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

@@ -0,0 +1,69 @@
+/**
+ * The plan skeleton: the procedure of the service folded into the steps of a
+ * plan, with the agent, the packages, the dependencies, the caveats, the
+ * alternatives, the disputed sides, the forbidden methods, the environment,
+ * and the grounding of each step filled from the answer. It is
+ * the one representation the planner receives: the procedure itself never
+ * reaches the model, thus nothing the procedure holds may be lost here. A
+ * small model edits a skeleton where it fails to compose a plan from a
+ * procedure; a frontier model pays nothing for it. The skeleton carries only
+ * the fields the answer can fill. The question, the acceptance criteria, the
+ * resources, and the step budget come from the data profile, and the planner
+ * adds them.
+ *
+ * The fold is fixed: one cohort assembly step when the procedure holds one
+ * (the sample exclusions and the sum of technical replicates, before any
+ * other step reads the counts), one QC step, one differential expression
+ * step that holds the filter, the normalization, the design, the test, the
+ * shrinkage, and the multiple testing (the templates cover the same span),
+ * one enrichment step on its own track, and one report step. A group with
+ * no step in the procedure is absent from the skeleton.
+ *
+ * The central step of a group names the method of the skeleton step, and it
+ * gives the alternatives, the template, and the environment: an alternative
+ * of a folded step (a normalization in the differential expression group)
+ * is not a permitted replacement of the step method, and it stays out. The
+ * settings, the caveats, and the forbidden methods come from every step of
+ * the group, each setting with the step it belongs to. A parameter is a
+ * setting of the grounding, never a constraint of the step: the value is the
+ * vetted default, and the agent can state another value with its reason.
+ */
+import type { GroundingSetting } from "../../schemas/workflow-state.js";
+import type { RecommendWithEnvironment, StepEnvironment } from "./environment.js";
+export type SkeletonAlternative = {
+    readonly method: string;
+    readonly label: string;
+    readonly when: string;
+    readonly rules: readonly string[];
+};
+export type SkeletonStep = {
+    readonly id: string;
+    readonly name: string;
+    readonly track: string;
+    readonly step_type: string;
+    readonly agent: string;
+    readonly packages: readonly string[];
+    readonly depends_on: readonly string[];
+    readonly caveats: readonly string[];
+    /** The other permitted methods of the step, from the central procedure step. */
+    readonly alternatives: readonly SkeletonAlternative[];
+    /** A disputed rule of the group with its sides. The planner chooses one side and states the choice. */
+    readonly disputed?: {
+        readonly rule: string;
+        readonly sides: readonly string[];
+    };
+    /** The method ids the rules forbid in the steps of the group. */
+    readonly forbids: readonly string[];
+    /** The environment of the central step, when the host bound the stores: the package in the farm and the collection in the reference store. */
+    readonly environment?: StepEnvironment;
+    readonly grounding: {
+        readonly status: "grounded" | "ungrounded" | "flagged";
+        readonly snapshot: string;
+        readonly claims: readonly string[];
+        readonly template?: string;
+        /** One entry per parameter of the procedure steps of the group, with the step it belongs to. */
+        readonly settings: readonly GroundingSetting[];
+        readonly reason: string;
+    };
+};
+export declare function buildPlanSkeleton(answer: RecommendWithEnvironment): SkeletonStep[];

package/dist/tools/knowledge/skeleton.js

@@ -0,0 +1,201 @@
+/**
+ * The plan skeleton: the procedure of the service folded into the steps of a
+ * plan, with the agent, the packages, the dependencies, the caveats, the
+ * alternatives, the disputed sides, the forbidden methods, the environment,
+ * and the grounding of each step filled from the answer. It is
+ * the one representation the planner receives: the procedure itself never
+ * reaches the model, thus nothing the procedure holds may be lost here. A
+ * small model edits a skeleton where it fails to compose a plan from a
+ * procedure; a frontier model pays nothing for it. The skeleton carries only
+ * the fields the answer can fill. The question, the acceptance criteria, the
+ * resources, and the step budget come from the data profile, and the planner
+ * adds them.
+ *
+ * The fold is fixed: one cohort assembly step when the procedure holds one
+ * (the sample exclusions and the sum of technical replicates, before any
+ * other step reads the counts), one QC step, one differential expression
+ * step that holds the filter, the normalization, the design, the test, the
+ * shrinkage, and the multiple testing (the templates cover the same span),
+ * one enrichment step on its own track, and one report step. A group with
+ * no step in the procedure is absent from the skeleton.
+ *
+ * The central step of a group names the method of the skeleton step, and it
+ * gives the alternatives, the template, and the environment: an alternative
+ * of a folded step (a normalization in the differential expression group)
+ * is not a permitted replacement of the step method, and it stays out. The
+ * settings, the caveats, and the forbidden methods come from every step of
+ * the group, each setting with the step it belongs to. A parameter is a
+ * setting of the grounding, never a constraint of the step: the value is the
+ * vetted default, and the agent can state another value with its reason.
+ */
+import { textOf } from "../../lib/unknown-text.js";
+const GROUPS = [
+    { id: "T0S1", track: "T1", step_type: "data_preparation", agent: "bulk-transcriptomics-agent", steps: ["cohort_assembly"], name: "Cohort assembly" },
+    { id: "T1S1", track: "T1", step_type: "qc", agent: "bulk-transcriptomics-agent", steps: ["qc_sample_structure"], name: "Sample structure QC" },
+    {
+        id: "T1S2",
+        track: "T1",
+        step_type: "analysis",
+        agent: "bulk-transcriptomics-agent",
+        steps: ["filter_low_counts", "normalize", "model_design", "differential_expression", "shrink_lfc", "multiple_testing"],
+        name: "Differential expression",
+    },
+    { id: "T2S1", track: "T2", step_type: "enrichment", agent: "enrichment-agent", steps: ["enrichment"], name: "Gene set enrichment" },
+    {
+        id: "T2S2",
+        track: "T2",
+        step_type: "activity",
+        agent: "enrichment-agent",
+        steps: ["tf_activity", "pathway_activity"],
+        name: "Regulator and pathway activity",
+    },
+    { id: "T1S4", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["variance_partition"], name: "Variance partition" },
+    { id: "T3S1", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["signature_scoring"], name: "Signature scoring" },
+    { id: "T3S2", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["deconvolution"], name: "Cell type deconvolution" },
+    { id: "T3S3", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["coexpression"], name: "Co-expression modules" },
+    { id: "T3S4", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["clustering"], name: "Sample clustering" },
+    { id: "T3S5", track: "T3", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["survival"], name: "Outcome association" },
+    { id: "T1S5", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["transcript_level"], name: "Transcript-level analysis" },
+    { id: "T1S6", track: "T1", step_type: "analysis", agent: "bulk-transcriptomics-agent", steps: ["annotation"], name: "Identifier annotation" },
+    { id: "T1S3", track: "T1", step_type: "report", agent: "bulk-transcriptomics-agent", steps: ["report"], name: "Report" },
+];
+/**
+ * The dependencies of each group. The QC depends on the cohort assembly when
+ * one is present, a group depends on the QC, on the differential expression
+ * when its input is a results table, and the report depends on every group
+ * that is present.
+ */
+const DEPENDS = {
+    T0S1: [],
+    T1S1: ["T0S1"],
+    T1S2: ["T1S1"],
+    T2S1: ["T1S2"],
+    T2S2: ["T1S2", "T1S1"],
+    T1S4: ["T1S1"],
+    T3S1: ["T1S1"],
+    T3S2: ["T1S1"],
+    T3S3: ["T1S1"],
+    T3S4: ["T1S1"],
+    T3S5: ["T3S1", "T1S1"],
+    T1S5: ["T1S1"],
+    T1S6: ["T1S1"],
+    T1S3: ["T1S2", "T2S1", "T2S2", "T1S4", "T3S1", "T3S2", "T3S3", "T3S4", "T3S5", "T1S5", "T1S6"],
+};
+/** A parameter value as a setting: a scalar stays, a list becomes a list of strings, anything else its text. */
+function settingValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map(String);
+    return textOf(value);
+}
+/** The settings of the steps of a group: one entry per parameter, with the step it belongs to. */
+function stepSettings(steps) {
+    return steps.flatMap((step) => (step.parameters ?? []).map((parameter) => ({
+        step: step.step,
+        name: parameter.name,
+        value: settingValue(parameter.value),
+        source: parameter.default_source,
+    })));
+}
+/** The forbidden method ids of a step. The client schema reads the field through the loose object. */
+function forbidsOf(step) {
+    const forbids = step.forbids;
+    return Array.isArray(forbids) ? forbids.flatMap((method) => (typeof method === "string" ? [method] : [])) : [];
+}
+/** `a and b`, or `a, b and c` for a longer list. */
+function joinWithAnd(items) {
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${String(items[items.length - 1])}`;
+}
+/**
+ * The caveats a step carries beside its warn flags. A parameter conflict, a
+ * substitution, and a language limit each render as a caveat, never as a
+ * setting: a setting is a value, and none of the three is a value.
+ */
+function stepCaveats(step) {
+    const caveats = [];
+    for (const conflict of step.conflicts ?? []) {
+        caveats.push(`${step.step}: ${conflict.parameter} conflicts between ${joinWithAnd(conflict.entries.map((entry) => entry.rule))}`);
+    }
+    if (step.substitution && step.method) {
+        caveats.push(`${step.method.label} stands in for ${step.substitution.label}`);
+    }
+    if (step.limit) {
+        // Only two languages exist, thus the named template is in the other one. A slot that refuses a value of the
+        // rules is not a fact of the design, thus with a refusal the caveat names the cause of each skipped template.
+        const named = step.limit.requested_language === "python" ? "R" : "Python";
+        const refused = step.limit.skipped.some((entry) => entry.refused !== undefined);
+        const causes = step.limit.skipped.map((entry) => entry.refused !== undefined ? `${entry.template}: ${entry.refused}` : `${entry.template} does not honor ${entry.missing.join(", ")}`);
+        const cause = refused ? `because ${causes.join("; ")}` : "for this design";
+        caveats.push(`the requested language has no template that realizes ${step.method?.label ?? step.step} ${cause}; the ${named} template is named`);
+    }
+    if (step.unrealized) {
+        // The knowledge covers the step and no vetted script does: the plan says so, and it invents no template.
+        const why = step.unrealized.templates.map((entry) => `${entry.template}: ${entry.why}`).join("; ");
+        caveats.push(`no vetted template realizes ${step.method?.label ?? step.step} for this design (${why || "the method lists no template for the step"}); the step runs without a template of the service`);
+    }
+    return caveats;
+}
+/** The present dependencies of a group; a group whose own dependency is absent falls back to the QC, and the two first groups to nothing. */
+function dependsOn(id, kept) {
+    const present = (DEPENDS[id] ?? []).filter((dependency) => kept.has(dependency));
+    if (present.length > 0)
+        return [...new Set(present)];
+    return id !== "T0S1" && id !== "T1S1" && kept.has("T1S1") ? ["T1S1"] : [];
+}
+export function buildPlanSkeleton(answer) {
+    const byStep = new Map(answer.procedure.map((step) => [step.step, step]));
+    const present = new Set(answer.procedure.map((step) => step.step));
+    const kept = GROUPS.filter((group) => group.steps.some((step) => present.has(step)));
+    const keptIds = new Set(kept.map((group) => group.id));
+    return kept.map((group) => {
+        const steps = group.steps.map((step) => byStep.get(step)).filter((step) => step !== undefined);
+        const central = steps.find((step) => step.step === "differential_expression") ?? steps.find((step) => step.method !== undefined) ?? steps[0];
+        const flags = steps.flatMap((step) => step.flags ?? []);
+        const hardFlag = flags.find((flag) => flag.severity === "flag");
+        const claims = [...new Set(steps.flatMap((step) => step.rules))];
+        const packages = [...new Set(steps.map((step) => step.package?.name).flatMap((name) => (name !== undefined ? [name] : [])))];
+        const caveats = [...flags.filter((flag) => flag.severity === "warn").map((flag) => flag.message), ...steps.flatMap(stepCaveats)];
+        const method = central?.method;
+        // A rule covers the group when a step of the group carries one. A method
+        // is not necessary: the report step carries the reporting rules and no
+        // method, and it is grounded by those rules.
+        const covered = method !== undefined || claims.length > 0;
+        const status = hardFlag ? "flagged" : covered ? "grounded" : "ungrounded";
+        const name = method && group.id !== "T1S1" && group.id !== "T1S3" ? method.label : group.name;
+        const alternatives = (central?.alternatives ?? []).map(({ method: id, label, when, rules }) => ({ method: id, label, when, rules }));
+        // One dispute per skeleton step: the central step first, else the first folded step that carries one.
+        const disputed = central?.disputed ?? steps.find((step) => step.disputed !== undefined)?.disputed;
+        const forbids = [...new Set(steps.flatMap(forbidsOf))];
+        return {
+            id: group.id,
+            name,
+            track: group.track,
+            step_type: group.step_type,
+            agent: group.agent,
+            packages,
+            depends_on: dependsOn(group.id, keptIds),
+            caveats: hardFlag ? [hardFlag.message, ...caveats] : caveats,
+            alternatives,
+            disputed: disputed === undefined ? undefined : { rule: disputed.rule, sides: disputed.sides },
+            forbids,
+            environment: central?.environment,
+            grounding: {
+                status,
+                snapshot: answer.snapshot.digest,
+                claims,
+                template: central?.template,
+                settings: stepSettings(steps),
+                reason: hardFlag
+                    ? `flagged by ${hardFlag.rule}`
+                    : method
+                        ? `${method.label} per ${claims[0] ?? "the procedure"}`
+                        : covered
+                            ? `${group.name} per ${String(claims[0])}`
+                            : "no rule covers this step",
+            },
+        };
+    });
+}

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

@@ -0,0 +1,139 @@
+/**
+ * `knowledge_template` — the model emits slot values, and the tool writes the
+ * rendered script and the decision record into the step workspace through
+ * the same `WorkspaceMutator` as `write_file`. The script is never output tokens.
+ *
+ * The installed versions ride from the tool, not from the model: the tool
+ * reads the `inflexa.lock` of the farm and the `image-packages.json` of the
+ * store when the host names them (`installedPackages`), and the service
+ * answers with the environment match, which the decision record keeps.
+ *
+ * The plan settings ride from the host, not from the model: the step input
+ * carries a `TemplateBinding` when the plan step grounds on a template, and
+ * the tool merges the bound slots under the model values. A model value that
+ * differs from a bound value is refused before the service call unless an
+ * `overrides` entry names the slot with a reason, and the decision record
+ * keeps the bound slots and the overrides beside the script path.
+ *
+ * The facts of the machine never ride at all: a local slot of the template
+ * (a path, a column name, a level label, a design formula) is split off the
+ * request, the service renders it as its marker, and the tool binds the
+ * value on the machine before it writes the file. The request carries the
+ * step, its claims, and the release digest the plan pinned, thus the record
+ * binds the cited decision to the bytes, and a service on another release
+ * refuses the render instead of moving the plan in silence. The call runs as
+ * one durable step, thus a replay returns the cached result and renders
+ * nothing again.
+ */
+import { z } from "zod";
+import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
+import type { WorkspaceMutator, WriteFileResult, WriteRecord } from "../workspace/mutator.js";
+import type { KnowledgeClient, KnowledgeRejected, KnowledgeSnapshotMismatch, KnowledgeUnavailable, TemplateParameter } from "./client.js";
+/** A slot value the plan binds: a scalar, or a list of strings. JSON-serialisable, as the durable step input needs. */
+export type TemplateBindingValue = string | number | boolean | readonly string[];
+/**
+ * The plan settings bound to the template of one step, composed by the host
+ * at dispatch and carried on the durable step input. `slots` holds the bound
+ * value per slot name, and `sources` the source of each value (a doi, a
+ * document, or the plan) under the same name. The rest binds the render to
+ * the plan step: its id, its claims, the release the plan pinned, and the
+ * local slots of the contract that the tool binds on the machine.
+ */
+export type TemplateBinding = {
+    /** The template reference of the plan step, with its version, for example `tpl-deseq2-two-group@1.0.0`. */
+    readonly template: string;
+    readonly slots: Readonly<Record<string, TemplateBindingValue>>;
+    readonly sources: Readonly<Record<string, string>>;
+    /** The id of the plan step. */
+    readonly step?: string;
+    /** The claims of the plan step, as `knowledge_recommend` returned them. */
+    readonly claims?: readonly string[];
+    /** The release digest the plan pinned. Absent when the step is ungrounded. */
+    readonly snapshot?: string;
+    /** The local slots of the served contract. Absent on a binding made before the contract carried the flag. */
+    readonly local?: readonly TemplateParameter[];
+    /** The names of every adaptable slot of the served contract, thus the tool refuses an unknown name before anything leaves the machine. */
+    readonly adaptable?: readonly string[];
+};
+export type KnowledgeTemplateDeps = {
+    readonly client: KnowledgeClient;
+    readonly mutator: WorkspaceMutator;
+    /** Host path of the farm `inflexa.lock`, or its resolver for each analysis. Absent with no image record, the environment match reads as unknown. */
+    readonly farmLockFile?: EnvironmentStorePaths["farmLockFile"];
+    /** Host path of the `image-packages.json` of the store: the packages the sandbox image ships, among them the R packages of the R runtime. */
+    readonly imagePackagesFile?: string;
+    /** The plan settings bound to the template of the step. Absent, the model values ride alone. */
+    readonly binding?: TemplateBinding;
+};
+/** One bound slot as the decision record keeps it. */
+export type BoundSlotRecord = {
+    readonly slot: string;
+    readonly value: TemplateBindingValue;
+    readonly source: string;
+};
+/** One change of a bound value that an `overrides` entry declared, as the decision record keeps it. */
+export type SettingsOverrideRecord = {
+    readonly slot: string;
+    readonly plan_value: TemplateBindingValue;
+    readonly new_value: unknown;
+    readonly reason: string;
+};
+export type KnowledgeTemplateOutput = {
+    readonly status: "ok";
+    readonly script_path: string;
+    readonly decision_record_path: string;
+    readonly template: {
+        readonly id: string;
+        readonly version: string;
+        readonly label: string;
+        readonly method: {
+            readonly id: string;
+            readonly label: string;
+        };
+        readonly substitute_for?: {
+            readonly id: string;
+            readonly label: string;
+        };
+    };
+    readonly snapshot: {
+        readonly date: string;
+        readonly digest: string;
+    };
+    readonly slots: readonly {
+        readonly name: string;
+        readonly value?: unknown;
+        readonly source: string;
+        readonly adaptable: boolean;
+        readonly lines: readonly number[];
+    }[];
+    /** The local slots the tool bound on this machine. */
+    readonly local_slots: readonly string[];
+    /** The digest of the script as written. */
+    readonly written_sha256: string;
+    readonly environment_match: string;
+    readonly syntax: string;
+    readonly expected_outputs: readonly {
+        readonly name: string;
+        readonly path: string;
+        readonly description?: string;
+    }[];
+    readonly run_with: string;
+} | {
+    readonly status: "write_refused";
+    readonly path: string;
+    readonly reason: Exclude<WriteFileResult["status"], "ok">;
+} | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch;
+/** The result of a `knowledge_template` call: each landed write rides as the call record, for the fold. */
+type KnowledgeTemplateResult = KnowledgeTemplateOutput | WithToolCallRecord<KnowledgeTemplateOutput, readonly WriteRecord[]>;
+declare const KnowledgeTemplateInputSchema: z.ZodObject<{
+    template: z.ZodString;
+    slots: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    overrides: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slot: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    script_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function createKnowledgeTemplateTool(deps: KnowledgeTemplateDeps): Tool<z.infer<typeof KnowledgeTemplateInputSchema>, KnowledgeTemplateResult>;
+export {};