@inflexa-ai/harness 0.45.1 → 0.46.2

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

@@ -18,6 +18,7 @@
  * parses.
  */
 import { z } from "zod";
+import type { SituationFieldsSchema } from "./situation.js";
 /** The role of the blocking factor. A role and never a column name, because the situation leaves the machine. */
 export type BlockingRole = "individual" | "cell_line" | "litter" | "site" | "pair" | "other";
 /** The role of a covariate of the design. A role and never a column name. */
@@ -25,48 +26,12 @@ export type CovariateRole = "sex" | "age" | "clinical" | "technical" | "other";
 /** The role of the numeric variable of interest when the question is a trend, not a comparison of groups. */
 export type PredictorRole = "dose" | "time" | "age" | "score" | "other";
 /** The typed description of one analysis situation. Never a sample row, never an identifier, and never a column name. */
-export interface KnowledgeSituation {
-    readonly question: "differential_expression" | "enrichment" | "qc" | "full_plan";
-    readonly modality: "bulk_rna_seq";
-    readonly data_state: "fastq" | "counts" | "tpm_or_fpkm" | "log_normalized";
-    readonly count_source?: "salmon" | "kallisto" | "star_featurecounts" | "rsem" | "unknown";
-    /** Whether the length correction of a quantifier occurred. Never required: the service sets `unknown` on counts. */
-    readonly import_state?: "quantifications" | "estimated_counts_with_lengths" | "corrected_counts" | "integer_counts" | "unknown";
-    readonly organism: "human" | "mouse" | "other";
-    readonly n_groups: number;
-    readonly n_per_group_min: number;
-    readonly n_per_group_max: number;
-    /** The total number of biological samples. Never required. */
-    readonly n_samples?: number;
-    /** The number of samples with an observed event, for a survival question. Never required. */
-    readonly n_events?: number;
-    readonly paired: boolean;
-    /** The role of the blocking factor, or null. The column name stays on the machine. */
-    readonly blocking_factor?: BlockingRole | null;
-    /** How the blocking factor relates to the condition: crossed, or nested inside one condition. */
-    readonly block_structure?: "crossed" | "nested";
-    readonly batch: "none" | "known_balanced" | "known_confounded" | "known_unbalanced" | "suspected";
-    /** The role of each covariate of the design, one entry per covariate. The column names stay on the machine. */
-    readonly covariates?: readonly CovariateRole[];
-    readonly n_timepoints?: number | null;
-    /** The role of the numeric variable of interest when the question is a trend over it; then `n_groups` is 1. The column name stays on the machine. */
-    readonly continuous_predictor?: PredictorRole | null;
-    /** True when some columns of the count table are technical replicates of one biological sample. */
-    readonly technical_replicates?: boolean;
-    /** The row unit of the count table. Absent for a gene-level table. */
-    readonly feature_level?: "gene" | "exon" | "transcript";
-    readonly library_type?: "polyA" | "total" | "three_prime" | "unknown";
-    readonly strandedness?: "verified" | "declared_unverified" | "unknown";
-    readonly interaction?: boolean;
-    /** True for a classifier of the samples into classes; absent for a per-sample score. */
-    readonly classifier?: boolean;
-    readonly quality_flags?: readonly ("low_depth_sample" | "outlier_sample" | "sample_identity_doubt" | "high_duplication" | "degraded_rna")[];
-}
+export type KnowledgeSituation = z.infer<typeof SituationFieldsSchema>;
 export declare const RecommendResponseSchema: z.ZodObject<{
     match: z.ZodEnum<{
-        none: "none";
         applicable: "applicable";
         flag: "flag";
+        none: "none";
     }>;
     snapshot: z.ZodObject<{
         date: z.ZodString;
@@ -98,14 +63,14 @@ export declare const RecommendResponseSchema: z.ZodObject<{
         }, z.core.$loose>>;
         parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
-            value: z.ZodUnknown;
+            value: z.ZodJSONSchema;
             default_source: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>>;
         conflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
             parameter: z.ZodString;
             entries: z.ZodArray<z.ZodObject<{
                 rule: z.ZodString;
-                value: z.ZodUnknown;
+                value: z.ZodJSONSchema;
             }, z.core.$loose>>;
         }, z.core.$loose>>>;
         substitution: z.ZodOptional<z.ZodObject<{
@@ -132,6 +97,10 @@ export declare const RecommendResponseSchema: z.ZodObject<{
                 why: z.ZodString;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
+        package: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$loose>>;
+        forbids: z.ZodOptional<z.ZodJSONSchema>;
     }, z.core.$loose>>;
     uncovered: z.ZodArray<z.ZodString>;
     unrealized: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -211,7 +180,7 @@ export declare const RenderResponseSchema: z.ZodObject<{
     script: z.ZodString;
     slots: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        value: z.ZodOptional<z.ZodUnknown>;
+        value: z.ZodOptional<z.ZodJSONSchema>;
         source: z.ZodString;
         adaptable: z.ZodBoolean;
         lines: z.ZodArray<z.ZodNumber>;
@@ -229,7 +198,7 @@ export declare const RenderResponseSchema: z.ZodObject<{
         path: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
-    decision_record: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    decision_record: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
 }, z.core.$loose>;
 export type RenderResponse = z.infer<typeof RenderResponseSchema>;
 /**
@@ -245,7 +214,7 @@ declare const TemplateParameterSchema: z.ZodObject<{
     adaptable: z.ZodBoolean;
     local: z.ZodOptional<z.ZodBoolean>;
     required: z.ZodOptional<z.ZodBoolean>;
-    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+    default: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodString>]>>>, z.ZodTransform<string | number | boolean | string[] | undefined, string | number | boolean | string[] | null | undefined>>>;
     default_source: z.ZodOptional<z.ZodString>;
     enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
     pattern: z.ZodOptional<z.ZodString>;
@@ -274,7 +243,7 @@ export declare const TemplateContractSchema: z.ZodObject<{
         adaptable: z.ZodBoolean;
         local: z.ZodOptional<z.ZodBoolean>;
         required: z.ZodOptional<z.ZodBoolean>;
-        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>>;
+        default: z.ZodOptional<z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodString>]>>>, z.ZodTransform<string | number | boolean | string[] | undefined, string | number | boolean | string[] | null | undefined>>>;
         default_source: z.ZodOptional<z.ZodString>;
         enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
         pattern: z.ZodOptional<z.ZodString>;
@@ -295,11 +264,11 @@ export declare const TemplateContractSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type TemplateContract = z.infer<typeof TemplateContractSchema>;
 /** The preferences of the caller: the language of the template the answer names. */
-export interface KnowledgePreferences {
+export type KnowledgePreferences = {
     readonly language?: "R" | "python";
-}
+};
 /** What a drafted step carries into the check. */
-export interface DraftedStep {
+export type DraftedStep = {
     readonly step_type: string;
     readonly method: string;
     /** The catalog id of the method (`M-dddd`), copied from the recommendation. An exact match wins over the wording. */
@@ -311,22 +280,22 @@ export interface DraftedStep {
     }[];
     /** The outcome the step states when the design forbids inference, for example `descriptive_only`. */
     readonly outcome?: string;
-}
-export interface FarmPackage {
+};
+export type FarmPackage = {
     readonly name: string;
     readonly version: string;
-}
+};
 /** The service could not answer after the retry policy. The run continues from the prose skills. */
-export interface KnowledgeUnavailable {
+export type KnowledgeUnavailable = {
     readonly match: "unavailable";
     readonly reason: string;
-}
+};
 /**
  * The service serves another release than the one the plan pinned, and it
  * did no work. A plan is not moved to a new release in silence: the caller
  * proceeds as with an unavailable service, and it states the two digests.
  */
-export interface KnowledgeSnapshotMismatch {
+export type KnowledgeSnapshotMismatch = {
     readonly match: "snapshot_mismatch";
     readonly message: string;
     readonly expected: string;
@@ -334,9 +303,9 @@ export interface KnowledgeSnapshotMismatch {
         readonly date: string;
         readonly digest: string;
     };
-}
+};
 /** The service refused the request and named the field or the slot and the permitted values. */
-export interface KnowledgeRejected {
+export type KnowledgeRejected = {
     readonly match: "rejected";
     readonly message: string;
     readonly issues: readonly {
@@ -346,17 +315,17 @@ export interface KnowledgeRejected {
         readonly reason?: string;
         readonly permitted?: readonly string[];
     }[];
-}
+};
 /** What a render call carries beside the template and the slots. */
-export interface RenderCallOptions {
+export type RenderCallOptions = {
     /** The id of the plan step that runs the script. */
     readonly step?: string;
     /** The claims of the plan step that selected the template. Each must resolve in the served snapshot. */
     readonly claims?: readonly string[];
     /** The release digest the plan pinned. The service refuses another release with `snapshot_mismatch`. */
     readonly expectedSnapshot?: string;
-}
-export interface KnowledgeClient {
+};
+export type KnowledgeClient = {
     /** `expectedSnapshot` pins the release of an earlier answer of the same plan; the first call of a plan has none. */
     recommend(situation: KnowledgeSituation, responseFormat?: "concise" | "detailed", preferences?: KnowledgePreferences, expectedSnapshot?: string): Promise<RecommendResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch>;
     check(situation: KnowledgeSituation, steps: readonly DraftedStep[], expectedSnapshot?: string): Promise<CheckResponse | KnowledgeUnavailable | KnowledgeRejected | KnowledgeSnapshotMismatch>;
@@ -369,14 +338,14 @@ export interface KnowledgeClient {
      * unknown template is `rejected` with the field `template`.
      */
     contract(template: string): Promise<TemplateContract | KnowledgeUnavailable | KnowledgeRejected>;
-}
-export interface HttpKnowledgeClientConfig {
+};
+export type HttpKnowledgeClientConfig = {
     /** The service origin, for example `https://knowledge.inflexa.ai`. */
     readonly baseUrl: string;
     /** The bearer key. The license of the service. */
     readonly apiKey: string;
     readonly timeoutMs?: number;
     readonly maxRetries?: number;
-}
+};
 export declare function createHttpKnowledgeClient(config: HttpKnowledgeClientConfig): KnowledgeClient;
 export {};

package/dist/tools/knowledge/client.js

@@ -19,6 +19,8 @@
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { parseJsonAs, safeParseJsonAs } from "../../lib/parse-json.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 // ── The answers, as the harness reads them ──────────────────────────
 const SnapshotRefSchema = z.object({ date: z.string(), digest: z.string() });
 /** A method of the catalog by id and label. */
@@ -26,7 +28,7 @@ const MethodRefSchema = z.looseObject({ id: z.string(), label: z.string() });
 /** Two rules of equal specificity and strength disagree on a parameter. The step omits the parameter and names both. */
 const ProcedureConflictSchema = z.looseObject({
     parameter: z.string(),
-    entries: z.array(z.looseObject({ rule: z.string(), value: z.unknown() })),
+    entries: z.array(z.looseObject({ rule: z.string(), value: z.json() })),
 });
 /** The step method is a declared substitute: `for` names the method of record it stands in for. */
 const ProcedureSubstitutionSchema = z.looseObject({ for: z.string(), label: z.string(), template: z.string() });
@@ -52,11 +54,15 @@ const ProcedureStepSchema = z.looseObject({
     flags: z.array(z.looseObject({ rule: z.string(), severity: z.string(), message: z.string(), outcome: z.string().optional() })).optional(),
     alternatives: z.array(z.looseObject({ method: z.string(), label: z.string(), when: z.string(), rules: z.array(z.string()) })).optional(),
     disputed: z.looseObject({ rule: z.string(), sides: z.array(z.string()) }).optional(),
-    parameters: z.array(z.looseObject({ name: z.string(), value: z.unknown(), default_source: z.string().optional() })).optional(),
+    parameters: z.array(z.looseObject({ name: z.string(), value: z.json(), default_source: z.string().optional() })).optional(),
     conflicts: z.array(ProcedureConflictSchema).optional(),
     substitution: ProcedureSubstitutionSchema.optional(),
     limit: ProcedureLimitSchema.optional(),
     unrealized: ProcedureUnrealizedSchema.optional(),
+    /** The runtime package the step installs, when the service names one. */
+    package: z.looseObject({ name: z.string() }).optional(),
+    /** The forbidden method ids, read defensively by the grounding report. */
+    forbids: z.json().optional(),
 });
 const ClaimSchema = z.looseObject({
     id: z.string(),
@@ -111,7 +117,7 @@ export const RenderResponseSchema = z.looseObject({
     /** A local slot entry has no value: the host binds it. */
     slots: z.array(z.looseObject({
         name: z.string(),
-        value: z.unknown().optional(),
+        value: z.json().optional(),
         source: z.string(),
         adaptable: z.boolean(),
         lines: z.array(z.number()),
@@ -122,12 +128,13 @@ export const RenderResponseSchema = z.looseObject({
     environment: z.looseObject({ match: z.string() }),
     syntax: z.looseObject({ status: z.string() }),
     outputs: z.array(z.looseObject({ name: z.string(), path: z.string(), description: z.string().optional() })),
-    decision_record: z.record(z.string(), z.unknown()),
+    decision_record: z.record(z.string(), z.json()),
 });
 // ── The template contract ───────────────────────────────────────────
-const SlotScalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
-/** A slot value on the wire: a scalar, or a list of scalars. */
-const SlotValueSchema = z.union([SlotScalarSchema, z.array(SlotScalarSchema)]);
+/** A scalar on the wire. */
+const SlotScalarSchema = z.union([z.string(), z.number(), z.boolean()]);
+/** A slot value on the wire: a scalar, or a list of strings — the contract the service states for a default. */
+const SlotValueSchema = z.union([SlotScalarSchema, z.array(z.string())]);
 /**
  * One slot of a template with the constraint a caller value must obey.
  * `adaptable: false` marks a pinned slot: the render refuses a caller value
@@ -142,7 +149,10 @@ const TemplateParameterSchema = z.looseObject({
     /** True for a slot whose value is a fact of the machine (a path, a column name, a level label, a formula): the host binds it, and the service never sees it. */
     local: z.boolean().optional(),
     required: z.boolean().optional(),
-    default: SlotValueSchema.optional(),
+    /** A `null` default is a slot with no default: it parses to an absent value. */
+    default: SlotValueSchema.nullish()
+        .transform((value) => value ?? undefined)
+        .optional(),
     default_source: z.string().optional(),
     enum: z.array(z.string()).optional(),
     pattern: z.string().optional(),
@@ -185,12 +195,21 @@ const ValidationFailureSchema = z.looseObject({
         permitted: z.array(z.string()).optional(),
     })),
 });
+/** The runtime shape of that answer, for the paths whose type says it cannot arrive. */
+const SnapshotMismatchAnswerSchema = z.looseObject({
+    match: z.literal("snapshot_mismatch"),
+    message: z.string(),
+});
+/** True when `call` answered a mismatch envelope on a route whose type says it cannot carry one. */
+function isSnapshotMismatchAnswer(answer) {
+    return SnapshotMismatchAnswerSchema.safeParse(answer).success;
+}
 /** The `message` of an error envelope, or the body itself when it is not one. */
 function messageOf(body) {
     try {
-        const raw = JSON.parse(body);
-        if (raw !== null && typeof raw === "object" && "message" in raw && typeof raw.message === "string")
-            return raw.message;
+        const message = parseUnknownRecord(parseJsonAs(body, z.json()))?.["message"];
+        if (typeof message === "string")
+            return message;
     }
     catch {
         // Not JSON: the body is the message.
@@ -223,28 +242,26 @@ function refusalOf(error, notFoundField) {
         return { match: "rejected", message, issues: [{ field: notFoundField, message }] };
     }
     if (error.status === 409) {
-        let raw;
+        let parsed;
         try {
-            raw = JSON.parse(error.body);
+            parsed = safeParseJsonAs(error.body, SnapshotMismatchSchema);
         }
         catch {
             return undefined;
         }
-        const parsed = SnapshotMismatchSchema.safeParse(raw);
         if (!parsed.success)
             return undefined;
         return { match: "snapshot_mismatch", message: parsed.data.message, expected: parsed.data.expected, served: parsed.data.served };
     }
     if (error.status !== 400)
         return undefined;
-    let raw;
+    let parsed;
     try {
-        raw = JSON.parse(error.body);
+        parsed = safeParseJsonAs(error.body, ValidationFailureSchema);
     }
     catch {
         return { match: "rejected", message: error.body || "the service refused the request", issues: [] };
     }
-    const parsed = ValidationFailureSchema.safeParse(raw);
     if (!parsed.success)
         return { match: "rejected", message: error.body, issues: [] };
     return { match: "rejected", message: parsed.data.message, issues: parsed.data.issues };
@@ -263,7 +280,7 @@ export function createHttpKnowledgeClient(config) {
             ...policy,
             method,
             headers,
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            body: JSON.stringify(body),
         });
         if (result.isOk())
             return result.value;
@@ -276,7 +293,7 @@ export function createHttpKnowledgeClient(config) {
     async function lookup(path, schema, notFoundField) {
         const answer = await call("GET", path, undefined, schema, notFoundField);
         // A GET without a body has no pin, thus a 409 is not among its answers; the guard keeps the type honest.
-        if (typeof answer === "object" && answer !== null && "match" in answer && answer.match === "snapshot_mismatch") {
+        if (isSnapshotMismatchAnswer(answer)) {
             return { match: "unavailable", reason: answer.message };
         }
         return answer;
@@ -284,18 +301,18 @@ export function createHttpKnowledgeClient(config) {
     return {
         recommend: (situation, responseFormat, preferences, expectedSnapshot) => call("POST", "/v1/recommend", {
             situation,
-            ...(responseFormat ? { response_format: responseFormat } : {}),
-            ...(preferences ? { preferences } : {}),
-            ...(expectedSnapshot ? { expected_snapshot: expectedSnapshot } : {}),
+            response_format: responseFormat,
+            preferences,
+            expected_snapshot: expectedSnapshot,
         }, RecommendResponseSchema),
-        check: (situation, steps, expectedSnapshot) => call("POST", "/v1/check", { situation, steps, ...(expectedSnapshot ? { expected_snapshot: expectedSnapshot } : {}) }, CheckResponseSchema),
+        check: (situation, steps, expectedSnapshot) => call("POST", "/v1/check", { situation, steps, expected_snapshot: expectedSnapshot }, CheckResponseSchema),
         render: (template, slots, farm, options) => call("POST", "/v1/template/render", {
             template,
             slots,
-            ...(farm ? { farm } : {}),
-            ...(options?.step ? { step: options.step } : {}),
-            ...(options?.claims ? { claims: options.claims } : {}),
-            ...(options?.expectedSnapshot ? { expected_snapshot: options.expectedSnapshot } : {}),
+            farm,
+            step: options?.step,
+            claims: options?.claims,
+            expected_snapshot: options?.expectedSnapshot,
         }, RenderResponseSchema),
         contract: (template) => lookup(`/v1/templates/${encodeURIComponent(templateIdOf(template))}`, TemplateContractSchema, "template"),
     };

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

@@ -20,15 +20,15 @@
  * fills a gap and never names a path it did not read.
  */
 import type { FarmPackage, RecommendResponse } from "./client.js";
-export interface EnvironmentPaths {
+export type 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 {
+};
+export type StepEnvironment = {
     readonly package?: {
         readonly name: string;
         readonly present: boolean;
@@ -40,14 +40,14 @@ export interface StepEnvironment {
         readonly path?: string;
         readonly title?: string;
     };
-}
+};
 /** Where each fact of the environment came from: a record the host read, or nothing. */
-export interface EnvironmentSource {
+export type 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;

package/dist/tools/knowledge/environment.js

@@ -54,10 +54,21 @@ export function installedPackages(paths) {
     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);
+    const tokens = [];
+    let token = "";
+    const flush = () => {
+        if (token.length > 1)
+            tokens.push(token);
+        token = "";
+    };
+    for (const char of text.toLowerCase()) {
+        if ((char >= "a" && char <= "z") || (char >= "0" && char <= "9"))
+            token += char;
+        else
+            flush();
+    }
+    flush();
+    return tokens;
 }
 /** A collection term of the tree (`msigdb_hallmark_human`) matches an entry whose labels hold every token of the term. */
 function findCollection(term, entries) {
@@ -83,7 +94,7 @@ export async function joinEnvironment(answer, paths) {
         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 } : {}) };
+            environment.package = { name: pkg.name, present: version !== undefined, version };
         }
         const collection = step.parameters?.find((parameter) => parameter.name === "gene_set_collection");
         if (collection && typeof collection.value === "string" && entries) {
@@ -91,8 +102,8 @@ export async function joinEnvironment(answer, paths) {
             environment.collection = {
                 name: collection.value,
                 present: found !== undefined,
-                ...(found ? { path: found.path } : {}),
-                ...(found?.metadata?.title ? { title: found.metadata.title } : {}),
+                path: found?.path,
+                title: found?.metadata?.title,
             };
         }
         return Object.keys(environment).length > 0 ? { ...step, environment } : step;

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

@@ -21,7 +21,7 @@ export * from "./check.js";
 export * from "./recommend.js";
 export * from "./situation.js";
 export * from "./template.js";
-export interface KnowledgeToolsDeps {
+export type 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"];
@@ -31,7 +31,7 @@ export interface KnowledgeToolsDeps {
     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

package/dist/tools/knowledge/index.js

@@ -35,24 +35,24 @@ export function createKnowledgeTools(deps) {
         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 } : {}),
+            farmLockFile: deps.farmLockFile,
+            imagePackagesFile: deps.imagePackagesFile,
+            refStorePath: deps.refStorePath,
+            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" }),
+    recommend: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    check: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    render: () => Promise.resolve({ match: "unavailable", reason: "no service" }),
+    contract: () => Promise.resolve({ 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 }),
+    writeFile: ({ path }) => Promise.resolve({ status: "out_of_scope", path }),
     recordWrite: () => undefined,
 };
 /**

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

@@ -15,13 +15,13 @@ 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 {
+export type 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 {
+export type BoundLocalSlot = {
     readonly name: string;
     readonly value: LocalSlotValue;
     readonly source: "caller" | "default";
@@ -30,7 +30,7 @@ export interface BoundLocalSlot {
     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[];

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

@@ -11,10 +11,14 @@
  * service for the same values. Keep the literal rules in step with the
  * service when a slot type is added.
  */
+import { z } from "zod";
+/** The contract of a validated local slot value, as `validateLocalSlot` accepts it. */
+const LocalSlotValueSchema = z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]);
 /** The local slots of a contract, in the order the template declares them. */
 export function localParameters(parameters) {
     return parameters.filter((parameter) => parameter.local === true);
 }
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a formula starts with ~ and holds only formula name characters; the shape is the slot contract.
 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) {
@@ -29,6 +33,7 @@ export function validateLocalSlot(parameter, 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 };
+            // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the pattern arrives as contract data from the template author, not from this module.
             if (parameter.pattern && !new RegExp(parameter.pattern).test(value))
                 return { slot, reason: `the value must match ${parameter.pattern}` };
             return undefined;
@@ -135,7 +140,7 @@ export function bindLocalSlots(template, script, localValues, marked = []) {
                 continue;
             }
             // Validated above: a string, a finite number, a boolean, or a list of strings.
-            const value = given;
+            const value = LocalSlotValueSchema.parse(given);
             values.set(parameter.name, value);
             slots.push({ name: parameter.name, value, source: "caller", adaptable: true, lines: [] });
         }
@@ -149,7 +154,7 @@ export function bindLocalSlots(template, script, localValues, marked = []) {
                 value,
                 source: "default",
                 adaptable: true,
-                ...(parameter.default_source ? { default_source: parameter.default_source } : {}),
+                default_source: parameter.default_source,
                 lines: [],
             });
         }
@@ -159,7 +164,9 @@ export function bindLocalSlots(template, script, localValues, marked = []) {
     }
     if (issues.length > 0)
         return { ok: false, issues };
-    const bound = script.replace(/\{\{([a-z][a-z0-9_]*)\}\}/g, (whole, name) => {
+    const bound = 
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the {{name}} placeholders are the template grammar of the contract; the capture names the slot to bind.
+    script.replace(/\{\{([a-z][a-z0-9_]*)\}\}/g, (whole, name) => {
         const parameter = byName.get(name);
         if (!parameter)
             return whole;
@@ -171,7 +178,7 @@ export function bindLocalSlots(template, script, localValues, marked = []) {
     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) } : {}),
+        read: readByName.get(entry.name),
     }));
     return { ok: true, script: bound, slots: located };
 }

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

@@ -5,10 +5,10 @@
  * moved to another release between two calls then refuses the call, and the
  * plan never mixes two releases in silence.
  */
-export interface SnapshotPin {
+export type 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;