@archmax-ai/harness 0.1.0 → 0.2.1

package/dist/machine/signature.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A trigger's signature, typed: what each `requires`/`returns` entry declares,
+ * the one mapping from a signature to JSON Schema, and the one conformance rule.
+ *
+ * Pure and browser-safe — it depends on nothing but the spec's types — so a host
+ * builds an MCP tool schema, a start form or request validation from exactly the
+ * mapping and rule the runtime enforces. Every runtime check (the turn boundary,
+ * `archmax_set_variables`, the completion check, a delegation and its settle)
+ * decides by {@link signatureValueIssues}; nothing else judges a value's type.
+ */
+import type { MachineSpec, SignatureEntryDeclaration } from "./types.js";
+/**
+ * The types a signature entry may declare: JSON Schema's own type words, plus its
+ * two string formats `date` and `date-time`, promoted because a host renders and
+ * validates them differently from free text.
+ */
+export declare const SIGNATURE_TYPES: readonly ["string", "integer", "number", "boolean", "date", "date-time", "object", "array"];
+/** One of {@link SIGNATURE_TYPES}. */
+export type SignatureType = (typeof SIGNATURE_TYPES)[number];
+/**
+ * One signature entry, normalized: the variable's name, and optionally what kind
+ * of value it holds and what it is for. An entry without `type` is untyped — any
+ * value satisfies it, `null` included.
+ */
+export interface SignatureEntry {
+    name: string;
+    type?: SignatureType;
+    description?: string;
+}
+/** A trigger's whole signature, normalized: its caller-facing `description` and both lists. */
+export interface TriggerSignature {
+    /** What calling this entry does, written for a caller; never disclosed to the session's own model. */
+    description?: string;
+    /** What a firing must supply, in declaration order; empty when undeclared. */
+    requires: SignatureEntry[];
+    /** What a completed session guarantees is set, in declaration order; empty when undeclared. */
+    returns: SignatureEntry[];
+}
+/**
+ * One reason a value map does not satisfy a signature: a name that is not set,
+ * or a value that does not conform to its entry's type. `found` is the JSON kind
+ * of what arrived; `message` is a phrase naming the variable, worded for whoever
+ * has to correct it, which each site wraps in its own refusal.
+ */
+export type SignatureValueIssue = {
+    kind: "missing";
+    name: string;
+    message: string;
+} | {
+    kind: "invalid";
+    name: string;
+    type: SignatureType;
+    found: SignatureValueKind;
+    message: string;
+};
+/** The JSON kind of a value, as an issue reports what arrived. */
+export type SignatureValueKind = "string" | "number" | "boolean" | "null" | "object" | "array";
+/**
+ * A `requires`/`returns` list as `{ name, type?, description? }` entries, in
+ * declaration order: a bare name and `{ name }` are the same untyped entry.
+ * Total — a list the schema refused (a scalar, an entry naming nothing) yields
+ * what it can read, so `validate` can read a spec whose shape failed.
+ */
+export declare function normalizeSignature(list: readonly (string | SignatureEntryDeclaration)[] | undefined | null): SignatureEntry[];
+/** Whether a value is one of {@link SIGNATURE_TYPES}. */
+export declare function isSignatureType(value: unknown): value is SignatureType;
+/**
+ * A trigger's normalized signature read from a parsed spec, or `undefined` when no
+ * state declares the id. The same reading `WorkflowMachine.signatureForTrigger`
+ * gives, for a host that holds only a spec. Two states declaring one id is a
+ * document error; here the later one wins, as in `triggerBindings`.
+ */
+export declare function signatureForTrigger(spec: MachineSpec, triggerId: string): TriggerSignature | undefined;
+/** One property of {@link signatureJsonSchema}'s output. An untyped entry has no `type`. */
+export interface SignaturePropertySchema {
+    type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
+    format?: "date" | "date-time";
+    description?: string;
+}
+/** What {@link signatureJsonSchema} yields: a JSON Schema object over the signature's names. */
+export interface SignatureJsonSchema {
+    type: "object";
+    properties: Record<string, SignaturePropertySchema>;
+    required: string[];
+}
+/**
+ * The one mapping from signature entries to a JSON Schema object: one property
+ * per entry in declaration order, the six JSON Schema type words as themselves,
+ * `date`/`date-time` as a string with that `format`, an untyped entry as `{}`,
+ * and every name `required` — each `requires` entry is mandatory, and the
+ * completion check guarantees each `returns` entry is set. The delegation tool's
+ * input schema is built by it, so a host building an MCP tool, a form or an API
+ * body from the same signature describes exactly what the runtime enforces.
+ */
+export declare function signatureJsonSchema(entries: readonly SignatureEntry[]): SignatureJsonSchema;
+/**
+ * The one conformance rule: one issue per entry whose name is not set in
+ * `values`, and one per typed entry whose value does not conform, in declaration
+ * order; an empty list when the map satisfies the signature. A name is set when
+ * `values` holds it with any value but `undefined`. An untyped entry takes any
+ * value, `null` included; a typed one never takes `null`. Nothing is coerced —
+ * the string `"4"` is not an `integer`.
+ */
+export declare function signatureValueIssues(entries: readonly SignatureEntry[], values: Readonly<Record<string, unknown>>): SignatureValueIssue[];

package/dist/machine/signature.js

@@ -0,0 +1,210 @@
+/**
+ * The types a signature entry may declare: JSON Schema's own type words, plus its
+ * two string formats `date` and `date-time`, promoted because a host renders and
+ * validates them differently from free text.
+ */
+export const SIGNATURE_TYPES = [
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "date",
+    "date-time",
+    "object",
+    "array",
+];
+// --- Normalizing -----------------------------------------------------------------
+/**
+ * A `requires`/`returns` list as `{ name, type?, description? }` entries, in
+ * declaration order: a bare name and `{ name }` are the same untyped entry.
+ * Total — a list the schema refused (a scalar, an entry naming nothing) yields
+ * what it can read, so `validate` can read a spec whose shape failed.
+ */
+export function normalizeSignature(list) {
+    if (!Array.isArray(list))
+        return [];
+    const entries = [];
+    for (const item of list) {
+        if (typeof item === "string") {
+            entries.push({ name: item });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const { name, type, description } = item;
+        if (typeof name !== "string")
+            continue;
+        const entry = { name };
+        if (isSignatureType(type))
+            entry.type = type;
+        if (typeof description === "string" && description.trim() !== "")
+            entry.description = description.trim();
+        entries.push(entry);
+    }
+    return entries;
+}
+/** Whether a value is one of {@link SIGNATURE_TYPES}. */
+export function isSignatureType(value) {
+    return typeof value === "string" && SIGNATURE_TYPES.includes(value);
+}
+/**
+ * A trigger's normalized signature read from a parsed spec, or `undefined` when no
+ * state declares the id. The same reading `WorkflowMachine.signatureForTrigger`
+ * gives, for a host that holds only a spec. Two states declaring one id is a
+ * document error; here the later one wins, as in `triggerBindings`.
+ */
+export function signatureForTrigger(spec, triggerId) {
+    let found;
+    for (const state of Object.values(spec.states ?? {})) {
+        const triggers = state?.triggers;
+        if (!triggers || !Object.hasOwn(triggers, triggerId))
+            continue;
+        const decl = triggers[triggerId];
+        const description = typeof decl?.description === "string" ? decl.description.trim() : "";
+        found = {
+            ...(description ? { description } : {}),
+            requires: normalizeSignature(decl?.requires),
+            returns: normalizeSignature(decl?.returns),
+        };
+    }
+    return found;
+}
+/**
+ * The one mapping from signature entries to a JSON Schema object: one property
+ * per entry in declaration order, the six JSON Schema type words as themselves,
+ * `date`/`date-time` as a string with that `format`, an untyped entry as `{}`,
+ * and every name `required` — each `requires` entry is mandatory, and the
+ * completion check guarantees each `returns` entry is set. The delegation tool's
+ * input schema is built by it, so a host building an MCP tool, a form or an API
+ * body from the same signature describes exactly what the runtime enforces.
+ */
+export function signatureJsonSchema(entries) {
+    const properties = {};
+    for (const entry of entries) {
+        const property = entry.type === "date" || entry.type === "date-time"
+            ? { type: "string", format: entry.type }
+            : entry.type
+                ? { type: entry.type }
+                : {};
+        if (entry.description)
+            property.description = entry.description;
+        properties[entry.name] = property;
+    }
+    return { type: "object", properties, required: entries.map((entry) => entry.name) };
+}
+// --- Conformance --------------------------------------------------------------------
+/**
+ * The one conformance rule: one issue per entry whose name is not set in
+ * `values`, and one per typed entry whose value does not conform, in declaration
+ * order; an empty list when the map satisfies the signature. A name is set when
+ * `values` holds it with any value but `undefined`. An untyped entry takes any
+ * value, `null` included; a typed one never takes `null`. Nothing is coerced —
+ * the string `"4"` is not an `integer`.
+ */
+export function signatureValueIssues(entries, values) {
+    const issues = [];
+    for (const entry of entries) {
+        const value = Object.hasOwn(values, entry.name) ? values[entry.name] : undefined;
+        if (value === undefined) {
+            issues.push({ kind: "missing", name: entry.name, message: `'${entry.name}' is not set` });
+            continue;
+        }
+        if (!entry.type || conforms(entry.type, value))
+            continue;
+        const found = valueKind(value);
+        issues.push({
+            kind: "invalid",
+            name: entry.name,
+            type: entry.type,
+            found,
+            message: `'${entry.name}' must be ${TYPE_PHRASES[entry.type]}, but ${arrived(found, value)} arrived`,
+        });
+    }
+    return issues;
+}
+/** Whether one value conforms to one signature type. */
+function conforms(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "date":
+            return typeof value === "string" && isFullDate(value);
+        case "date-time":
+            return typeof value === "string" && isDateTime(value);
+        case "object":
+            return value !== null && typeof value === "object" && !Array.isArray(value);
+        case "array":
+            return Array.isArray(value);
+    }
+}
+/** What each type means, as a refusal states it. */
+const TYPE_PHRASES = {
+    string: "a string",
+    integer: "an integer (a number with no fractional part)",
+    number: "a number",
+    boolean: "a boolean (true or false)",
+    date: "a date (an RFC 3339 full-date, YYYY-MM-DD, naming a real calendar day)",
+    "date-time": "a date-time (an RFC 3339 date-time with an offset, e.g. 2026-03-01T09:30:00Z)",
+    object: "an object",
+    array: "an array",
+};
+function valueKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    const kind = typeof value;
+    return kind === "string" || kind === "number" || kind === "boolean" ? kind : "object";
+}
+/** The arrival, worded: a short scalar is quoted so a malformed date or a fraction is visible. */
+function arrived(found, value) {
+    if (found === "null")
+        return "null";
+    const article = found === "array" || found === "object" ? "an" : "a";
+    if (found === "string" && value.length <= 40)
+        return `${article} string (${JSON.stringify(value)})`;
+    if (found === "number")
+        return `${article} number (${String(value)})`;
+    return `${article} ${found}`;
+}
+// --- RFC 3339 -----------------------------------------------------------------------
+//
+// Hand-written rather than `Date.parse`, which accepts implementation-specific
+// strings and rolls `2026-02-30` over into March.
+const FULL_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME = /^(\d{4}-\d{2}-\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/;
+/** An RFC 3339 `full-date` naming a real calendar day. */
+function isFullDate(value) {
+    const match = FULL_DATE.exec(value);
+    if (!match)
+        return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth(year, month);
+}
+/** An RFC 3339 `date-time`: a real day, a valid time, and a mandatory offset. */
+function isDateTime(value) {
+    const match = DATE_TIME.exec(value);
+    if (!match || !isFullDate(match[1]))
+        return false;
+    const [hour, minute, second] = [match[2], match[3], match[4]].map(Number);
+    // 60 admits a leap second, as RFC 3339 does.
+    if (hour > 23 || minute > 59 || second > 60)
+        return false;
+    if (match[5] !== undefined && (Number(match[5]) > 23 || Number(match[6]) > 59))
+        return false;
+    return true;
+}
+function daysInMonth(year, month) {
+    if (month === 2)
+        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+//# sourceMappingURL=signature.js.map

package/dist/machine/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/machine/signature.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,SAAS;IACT,MAAM;IACN,WAAW;IACX,QAAQ;IACR,OAAO;CACC,CAAC;AAuCX,oFAAoF;AAEpF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAwE;IAExE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,IAAiB,EAAE,CAAC;QACrC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC7B,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,SAAS;QACvE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,IAA+B,CAAC;QACpE,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAS;QACvC,MAAM,KAAK,GAAmB,EAAE,IAAI,EAAE,CAAC;QACvC,IAAI,eAAe,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QAC7C,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;QACzG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAqC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiB,EAAE,SAAiB;IACtE,IAAI,KAAmC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAQ,CAAC;QACjC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACjC,MAAM,WAAW,GAAG,OAAO,IAAI,EAAE,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,KAAK,GAAG;YACN,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,QAAQ,EAAE,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC;YAC5C,OAAO,EAAE,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC;SAC3C,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAkBD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAkC;IACpE,MAAM,UAAU,GAA4C,EAAE,CAAC;IAC/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GACZ,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;YACjD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE;YACxC,CAAC,CAAC,KAAK,CAAC,IAAI;gBACV,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;gBACtB,CAAC,CAAC,EAAE,CAAC;QACX,IAAI,KAAK,CAAC,WAAW;YAAE,QAAQ,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QAChE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IACpC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AACtF,CAAC;AAED,uFAAuF;AAEvF;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAkC,EAClC,MAAyC;IAEzC,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,KAAK,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;YAC1F,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;YAAE,SAAS;QACzD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK;YACL,OAAO,EAAE,IAAI,KAAK,CAAC,IAAI,aAAa,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU;SACrG,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,SAAS,QAAQ,CAAC,IAAmB,EAAE,KAAc;IACnD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;QACnC,KAAK,SAAS;YACZ,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC9D,KAAK,QAAQ;YACX,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7D,KAAK,SAAS;YACZ,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;QACpC,KAAK,MAAM;YACT,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QACxD,KAAK,WAAW;YACd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9E,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED,oDAAoD;AACpD,MAAM,YAAY,GAAkC;IAClD,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,+CAA+C;IACxD,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,2BAA2B;IACpC,IAAI,EAAE,wEAAwE;IAC9E,WAAW,EAAE,+EAA+E;IAC5F,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,UAAU;CAClB,CAAC;AAEF,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC;IAC1B,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AACxF,CAAC;AAED,kGAAkG;AAClG,SAAS,OAAO,CAAC,KAAyB,EAAE,KAAc;IACxD,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IACrE,IAAI,KAAK,KAAK,QAAQ,IAAK,KAAgB,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,GAAG,OAAO,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC;IAChH,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,GAAG,OAAO,YAAY,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;IACtE,OAAO,GAAG,OAAO,IAAI,KAAK,EAAE,CAAC;AAC/B,CAAC;AAED,uFAAuF;AACvF,EAAE;AACF,+EAA+E;AAC/E,kDAAkD;AAElD,MAAM,SAAS,GAAG,2BAA2B,CAAC;AAC9C,MAAM,SAAS,GACb,wFAAwF,CAAC;AAE3F,0DAA0D;AAC1D,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAClF,CAAC;AAED,iFAAiF;AACjF,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAA6B,CAAC;IACtG,6CAA6C;IAC7C,IAAI,IAAI,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE,IAAI,MAAM,GAAG,EAAE;QAAE,OAAO,KAAK,CAAC;IAC1D,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3F,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACjD,CAAC"}

package/dist/machine/spec-schema.d.ts

@@ -218,6 +218,48 @@ export declare const stateTypeSchema: z.ZodEnum<{
     human: "human";
     agent: "agent";
 }>;
+/**
+ * @see SignatureEntryDeclaration
+ *
+ * The object spelling of a signature entry. Strict, unlike the loose declaration
+ * around it: an unknown key here is most likely a misspelled `type` or
+ * `description`, and read loosely it would silently mean "untyped".
+ */
+export declare const signatureEntryObjectSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        date: "date";
+        array: "array";
+        integer: "integer";
+        "date-time": "date-time";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * @see SignatureEntryDeclaration
+ *
+ * One signature entry: a bare run-variable name (untyped), or the object
+ * spelling. A failure is reported in the terms of the spelling the author used,
+ * so a mistyped bare name reads exactly as it did before objects were accepted.
+ */
+export declare const signatureEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        date: "date";
+        array: "array";
+        integer: "integer";
+        "date-time": "date-time";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
 /**
  * @see TriggerDeclaration
  *
@@ -229,8 +271,35 @@ export declare const triggerDeclarationSchema: z.ZodObject<{
     session: z.ZodOptional<z.ZodString>;
     message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodString]>>;
     connection: z.ZodOptional<z.ZodString>;
-    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    returns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            date: "date";
+            array: "array";
+            integer: "integer";
+            "date-time": "date-time";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
+    returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            date: "date";
+            array: "array";
+            integer: "integer";
+            "date-time": "date-time";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
 }, z.core.$loose>;
 /**
  * A state's `triggers:` — the one place a trigger is declared. The key is the
@@ -242,8 +311,35 @@ export declare const stateTriggersSchema: z.ZodRecord<z.ZodString, z.ZodNullable
     session: z.ZodOptional<z.ZodString>;
     message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodString]>>;
     connection: z.ZodOptional<z.ZodString>;
-    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    returns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            date: "date";
+            array: "array";
+            integer: "integer";
+            "date-time": "date-time";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
+    returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            date: "date";
+            array: "array";
+            integer: "integer";
+            "date-time": "date-time";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>>;
 }, z.core.$loose>>>;
 /** @see MachineState */
 export declare const machineStateSchema: z.ZodObject<{
@@ -260,8 +356,35 @@ export declare const machineStateSchema: z.ZodObject<{
         session: z.ZodOptional<z.ZodString>;
         message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodString]>>;
         connection: z.ZodOptional<z.ZodString>;
-        requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        returns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        description: z.ZodOptional<z.ZodString>;
+        requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                object: "object";
+                date: "date";
+                array: "array";
+                integer: "integer";
+                "date-time": "date-time";
+            }>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>>;
+        returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                object: "object";
+                date: "date";
+                array: "array";
+                integer: "integer";
+                "date-time": "date-time";
+            }>>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>>;
     }, z.core.$loose>>>>;
     before: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
         script: z.ZodString;
@@ -531,8 +654,35 @@ export declare const machineSpecSchema: z.ZodObject<{
             session: z.ZodOptional<z.ZodString>;
             message: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodString]>>;
             connection: z.ZodOptional<z.ZodString>;
-            requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            returns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            description: z.ZodOptional<z.ZodString>;
+            requires: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodOptional<z.ZodEnum<{
+                    string: "string";
+                    number: "number";
+                    boolean: "boolean";
+                    object: "object";
+                    date: "date";
+                    array: "array";
+                    integer: "integer";
+                    "date-time": "date-time";
+                }>>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
+            returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodOptional<z.ZodEnum<{
+                    string: "string";
+                    number: "number";
+                    boolean: "boolean";
+                    object: "object";
+                    date: "date";
+                    array: "array";
+                    integer: "integer";
+                    "date-time": "date-time";
+                }>>;
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
         }, z.core.$loose>>>>;
         before: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
             script: z.ZodString;

package/dist/machine/spec-schema.js

@@ -10,6 +10,7 @@ import { z } from "zod";
 import { normalizeAllowEntry } from "./allow.js";
 import { normalizeHooks } from "../lifecycle/hook-shape.js";
 import { isSlug } from "./slug.js";
+import { SIGNATURE_TYPES } from "./signature.js";
 import { MANUAL_TRIGGER, parseSessionPath, stateTriggerIds } from "./triggers.js";
 import { parseReferences, referenceError, TITLE_VARIABLE, TRIGGER_VARIABLE, VARIABLE_NAME_PATTERN, } from "./variables.js";
 // --- Shared scalars ------------------------------------------------------------
@@ -332,16 +333,81 @@ export const stateTypeSchema = z.enum(["agent", "human"], {
     error: (issue) => `unknown state type '${String(issue.input)}' (expected 'agent' or 'human')`,
 });
 // --- Triggers ------------------------------------------------------------------
-/** One half of a trigger's signature: a list of distinct run-variable names. */
+/** The keys a signature entry object may carry, as a refusal lists them. */
+const SIGNATURE_ENTRY_KEYS = "'name', 'type' and 'description'";
+/** The accepted type words, as a refusal lists them. */
+const SIGNATURE_TYPE_LIST = `${SIGNATURE_TYPES.slice(0, -1).join(", ")} or ${SIGNATURE_TYPES.at(-1)}`;
+/**
+ * @see SignatureEntryDeclaration
+ *
+ * The object spelling of a signature entry. Strict, unlike the loose declaration
+ * around it: an unknown key here is most likely a misspelled `type` or
+ * `description`, and read loosely it would silently mean "untyped".
+ */
+export const signatureEntryObjectSchema = z.strictObject({
+    name: z
+        .string({
+        error: "a signature entry needs a 'name' naming its variable (e.g. '{ name: order_id, type: string }')",
+    })
+        .regex(VARIABLE_NAME_PATTERN, {
+        error: (issue) => `'${String(issue.input)}' is not a valid run-variable name. Use lowercase letters, ` +
+            `digits and underscores, starting with a letter (e.g. 'order_id').`,
+    }),
+    type: z
+        .enum(SIGNATURE_TYPES, {
+        error: (issue) => `'type' must be one of ${SIGNATURE_TYPE_LIST}; got ${JSON.stringify(issue.input)}`,
+    })
+        .optional(),
+    description: z
+        .string({ error: `'description' ${NON_EMPTY}` })
+        .refine((value) => value.trim() !== "", `'description' ${NON_EMPTY}`)
+        .optional(),
+}, {
+    error: (issue) => issue.code === "unrecognized_keys"
+        ? `${entryLabel(issue.input)} declares ${issue.keys.map((k) => `'${k}'`).join(", ")}, which a ` +
+            `signature entry does not take: it has ${SIGNATURE_ENTRY_KEYS} only.`
+        : undefined,
+});
+/** An entry as a message names it: by its `name` when it has a readable one. */
+function entryLabel(input) {
+    const name = input?.name;
+    return typeof name === "string" && name !== "" ? `Entry '${name}'` : "The entry";
+}
+/**
+ * @see SignatureEntryDeclaration
+ *
+ * One signature entry: a bare run-variable name (untyped), or the object
+ * spelling. A failure is reported in the terms of the spelling the author used,
+ * so a mistyped bare name reads exactly as it did before objects were accepted.
+ */
+export const signatureEntrySchema = z.union([variableName, signatureEntryObjectSchema], {
+    error: (issue) => {
+        if (issue.code !== "invalid_union")
+            return undefined;
+        const input = issue.input;
+        const isObject = input !== null && typeof input === "object" && !Array.isArray(input);
+        const branch = issue.errors[isObject ? 1 : 0] ?? [];
+        const messages = branch.map((inner) => inner.message);
+        if (!isObject)
+            return messages[0] ?? `'${String(input)}' is not a valid run-variable name`;
+        return `${entryLabel(input)}: ${messages.join("; ")}`;
+    },
+});
+/**
+ * One half of a trigger's signature: a list of entries with distinct names —
+ * each a bare name or `{ name, type?, description? }`, distinct by name across
+ * both spellings.
+ */
 function signatureSchema(key) {
     return z
-        .array(variableName, {
-        error: `must be a list of run-variable names (e.g. '${key}: [order_id]'). A signature names ` +
-            `the contract only — what a variable holds belongs in the state instructions that set it.`,
+        .array(signatureEntrySchema, {
+        error: `must be a list of run-variable names, each a bare name or '{ name, type?, description? }' ` +
+            `(e.g. '${key}: [order_id, { name: due, type: date }]').`,
     })
-        .superRefine((names, ctx) => {
+        .superRefine((entries, ctx) => {
         const seen = new Set();
-        names.forEach((name, index) => {
+        entries.forEach((entry, index) => {
+            const name = typeof entry === "string" ? entry : entry.name;
             if (seen.has(name)) {
                 ctx.addIssue({ code: "custom", path: [index], message: `'${name}' is listed more than once.` });
             }
@@ -403,6 +469,12 @@ export const triggerDeclarationSchema = z
     })
         .refine((value) => value.trim() !== "", "must be a non-empty string naming an access connection in the host's environment.")
         .optional(),
+    // For whoever calls the entry — a delegating model, a host's MCP client, a
+    // form's reader. The session's own brief is its `instructions`; this never reaches it.
+    description: z
+        .string({ error: "must be a non-empty string saying, for a caller, what calling this entry does." })
+        .refine((value) => value.trim() !== "", "must be a non-empty string saying, for a caller, what calling this entry does.")
+        .optional(),
     requires: signatureSchema("requires").optional(),
     returns: signatureSchema("returns").optional(),
 })