@archmax-ai/harness 1.0.1 → 2.0.0

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

@@ -57,13 +57,12 @@ export declare const machineTransitionSchema: z.ZodObject<{
         none: "none";
     }>>;
 }, z.core.$strict>;
-/** Whether an edge carries no description the agent could route on: absent, empty or blank. */
+/** Whether an edge carries no description: absent, empty or blank. */
 export declare function isUndescribed(transition: {
     description?: string;
 }): boolean;
 /** @see StateBudget */
 export declare const stateBudgetSchema: z.ZodObject<{
-    maxTurns: z.ZodOptional<z.ZodNumber>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     maxParks: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
@@ -173,7 +172,8 @@ export declare const stateTypeSchema: z.ZodEnum<{
  *
  * 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".
+ * `description`, and read loosely it would silently mean "untyped". A rule key
+ * is shape-checked here and held to its entry's type by {@link refineRules}.
  */
 export declare const signatureEntryObjectSchema: z.ZodObject<{
     name: z.ZodString;
@@ -189,6 +189,26 @@ export declare const signatureEntryObjectSchema: z.ZodObject<{
         array: "array";
     }>>;
     description: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<{
+        email: "email";
+        url: "url";
+        phone: "phone";
+    }>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content: z.ZodOptional<z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>>;
+    minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
 }, z.core.$strict>;
 /**
  * @see SignatureEntryDeclaration
@@ -211,6 +231,26 @@ export declare const signatureEntrySchema: z.ZodUnion<readonly [z.ZodString, z.Z
         array: "array";
     }>>;
     description: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<{
+        email: "email";
+        url: "url";
+        phone: "phone";
+    }>>;
+    pattern: z.ZodOptional<z.ZodString>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content: z.ZodOptional<z.ZodEnum<{
+        text: "text";
+        markdown: "markdown";
+        html: "html";
+    }>>;
+    minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
 }, z.core.$strict>]>;
 /**
  * @see TriggerDeclaration
@@ -238,6 +278,26 @@ export declare const triggerDeclarationSchema: z.ZodObject<{
             array: "array";
         }>>;
         description: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+            email: "email";
+            url: "url";
+            phone: "phone";
+        }>>;
+        pattern: z.ZodOptional<z.ZodString>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>>;
+        minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     }, z.core.$strict>]>>>;
     returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         name: z.ZodString;
@@ -253,6 +313,26 @@ export declare const triggerDeclarationSchema: z.ZodObject<{
             array: "array";
         }>>;
         description: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+            email: "email";
+            url: "url";
+            phone: "phone";
+        }>>;
+        pattern: z.ZodOptional<z.ZodString>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>>;
+        minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     }, z.core.$strict>]>>>;
 }, z.core.$loose>;
 /**
@@ -280,6 +360,26 @@ export declare const stateTriggersSchema: z.ZodRecord<z.ZodString, z.ZodNullable
             array: "array";
         }>>;
         description: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+            email: "email";
+            url: "url";
+            phone: "phone";
+        }>>;
+        pattern: z.ZodOptional<z.ZodString>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>>;
+        minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     }, z.core.$strict>]>>>;
     returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
         name: z.ZodString;
@@ -295,6 +395,26 @@ export declare const stateTriggersSchema: z.ZodRecord<z.ZodString, z.ZodNullable
             array: "array";
         }>>;
         description: z.ZodOptional<z.ZodString>;
+        format: z.ZodOptional<z.ZodEnum<{
+            email: "email";
+            url: "url";
+            phone: "phone";
+        }>>;
+        pattern: z.ZodOptional<z.ZodString>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            markdown: "markdown";
+            html: "html";
+        }>>;
+        minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     }, z.core.$strict>]>>>;
 }, z.core.$loose>>>;
 /** @see MachineState */
@@ -329,6 +449,26 @@ export declare const machineStateSchema: z.ZodObject<{
                 array: "array";
             }>>;
             description: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodEnum<{
+                email: "email";
+                url: "url";
+                phone: "phone";
+            }>>;
+            pattern: z.ZodOptional<z.ZodString>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            content: z.ZodOptional<z.ZodEnum<{
+                text: "text";
+                markdown: "markdown";
+                html: "html";
+            }>>;
+            minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            minItems: z.ZodOptional<z.ZodNumber>;
+            maxItems: z.ZodOptional<z.ZodNumber>;
+            accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         }, z.core.$strict>]>>>;
         returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
             name: z.ZodString;
@@ -344,11 +484,30 @@ export declare const machineStateSchema: z.ZodObject<{
                 array: "array";
             }>>;
             description: z.ZodOptional<z.ZodString>;
+            format: z.ZodOptional<z.ZodEnum<{
+                email: "email";
+                url: "url";
+                phone: "phone";
+            }>>;
+            pattern: z.ZodOptional<z.ZodString>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            content: z.ZodOptional<z.ZodEnum<{
+                text: "text";
+                markdown: "markdown";
+                html: "html";
+            }>>;
+            minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            minItems: z.ZodOptional<z.ZodNumber>;
+            maxItems: z.ZodOptional<z.ZodNumber>;
+            accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         }, z.core.$strict>]>>>;
     }, z.core.$loose>>>>;
     script: z.ZodOptional<z.ZodString>;
     budget: z.ZodOptional<z.ZodObject<{
-        maxTurns: z.ZodOptional<z.ZodNumber>;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         maxParks: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
@@ -586,6 +745,26 @@ export declare const machineSpecSchema: z.ZodObject<{
                     array: "array";
                 }>>;
                 description: z.ZodOptional<z.ZodString>;
+                format: z.ZodOptional<z.ZodEnum<{
+                    email: "email";
+                    url: "url";
+                    phone: "phone";
+                }>>;
+                pattern: z.ZodOptional<z.ZodString>;
+                minLength: z.ZodOptional<z.ZodNumber>;
+                maxLength: z.ZodOptional<z.ZodNumber>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                content: z.ZodOptional<z.ZodEnum<{
+                    text: "text";
+                    markdown: "markdown";
+                    html: "html";
+                }>>;
+                minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                minItems: z.ZodOptional<z.ZodNumber>;
+                maxItems: z.ZodOptional<z.ZodNumber>;
+                accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             }, z.core.$strict>]>>>;
             returns: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
                 name: z.ZodString;
@@ -601,11 +780,30 @@ export declare const machineSpecSchema: z.ZodObject<{
                     array: "array";
                 }>>;
                 description: z.ZodOptional<z.ZodString>;
+                format: z.ZodOptional<z.ZodEnum<{
+                    email: "email";
+                    url: "url";
+                    phone: "phone";
+                }>>;
+                pattern: z.ZodOptional<z.ZodString>;
+                minLength: z.ZodOptional<z.ZodNumber>;
+                maxLength: z.ZodOptional<z.ZodNumber>;
+                enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                content: z.ZodOptional<z.ZodEnum<{
+                    text: "text";
+                    markdown: "markdown";
+                    html: "html";
+                }>>;
+                minimum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                maximum: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+                minItems: z.ZodOptional<z.ZodNumber>;
+                maxItems: z.ZodOptional<z.ZodNumber>;
+                accept: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
             }, z.core.$strict>]>>>;
         }, z.core.$loose>>>>;
         script: z.ZodOptional<z.ZodString>;
         budget: z.ZodOptional<z.ZodObject<{
-            maxTurns: z.ZodOptional<z.ZodNumber>;
             timeoutMs: z.ZodOptional<z.ZodNumber>;
             maxParks: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;

package/dist/machine/spec-schema.js

@@ -9,7 +9,8 @@
 import { z } from "zod";
 import { normalizeAllowEntry } from "./allow.js";
 import { isSlug } from "./slug.js";
-import { SIGNATURE_TYPES } from "./signature.js";
+import { boundsInOrder, isBound, isCount, parseSize, RULE_TYPES, SIGNATURE_CONTENTS, SIGNATURE_FORMATS, SIGNATURE_RULE_NAMES, SIGNATURE_TYPES, } from "./signature.js";
+import { compilePattern, jsonSchemaPatternError } from "./signature-pattern.js";
 import { MANUAL_TRIGGER, parseSessionPath, stateTriggerIds } from "./triggers.js";
 import { parseReferences, referenceError, TITLE_VARIABLE, TRIGGER_VARIABLE, VARIABLE_NAME_PATTERN, } from "./variables.js";
 /**
@@ -156,41 +157,16 @@ export const transitionTypeSchema = z.enum(["approve", "reject", "refine", "none
 });
 /**
  * The agent is disclosed the active state's edges and nothing else of the graph,
- * so an edge must give it something to route on: its `description`, or — for an
- * **undescribed** edge (absent, empty or blank) — the target state's own
- * `instructions`, which the edge then discloses in its place. An edge with
- * neither hands the agent a bare slug and asks it to route: an unnavigable graph,
- * which is worse to warn about than to refuse, so {@link refineSpec} refuses it.
- * It refuses an undescribed transition of a human state, where the description
- * is the person's button label, and an undescribed edge into a grader or a code
- * state: a grader's instructions are its criteria, which the work it judges is
- * never shown, and a code state has none. A code state's own edges are exempt —
- * its script routes, and nothing reads their descriptions. A non-string is a
- * typo and refused here. The issue path
+ * so an edge's `description` is the only thing it is told about the edge — no
+ * attribute of the target state is disclosed — and at a human state it is also
+ * the decision's button label. A non-string is a typo and refused here; an
+ * absent or blank one is an **undescribed** edge, which {@link refineSpec}
+ * accepts only where there is nothing to choose and no condition to say (see
+ * {@link undescribedEdgeIssue}). The issue path
  * (`states.<slug>.transitions.<index>.description`) names the edge.
  */
-const TRANSITION_DESCRIPTION = `must be a string: what the agent routes on when it considers this edge. Say when to take it ` +
-    `(e.g. 'Refunds over $50'), not where it goes — or omit it to route on the target state's ` +
-    `instructions instead.`;
-/** An undescribed edge whose target has no instructions: nothing to route on. */
-function undescribedEdgeMessage(target) {
-    return (`must be a non-empty string here: the agent routes on an edge's description, or, when it has ` +
-        `none, on the target state's instructions — and '${target}' declares none. Say when to take ` +
-        `this edge (e.g. 'Refunds over $50'), or give '${target}' instructions.`);
-}
-/** An undescribed edge into an automated state: there are no instructions the agent may be shown. */
-function undescribedAutomatedEdgeMessage(target, type) {
-    const why = type === "grader"
-        ? `'${target}' is a grader, whose instructions are its criteria and never shown to the work it judges`
-        : `'${target}' is a code state, which has none`;
-    return (`must be a non-empty string here: the agent routes on an edge's description, or, when it has ` +
-        `none, on the target state's instructions — and ${why}. Say when to take this edge ` +
-        `(e.g. 'The reply is drafted').`);
-}
-/** An undescribed transition on a human state: the decision's button has no label. */
-const HUMAN_TRANSITION_DESCRIPTION = `must be a non-empty string on a human state's transition: it is the label of the decision's ` +
-    `button for the person deciding, and a target's instructions do not tell them what choosing it ` +
-    `means. Say what the choice is (e.g. 'Approve the refund').`;
+const TRANSITION_DESCRIPTION = `must be a string: it is the only thing the agent is told about this edge, so say when to ` +
+    `take it (e.g. 'Refunds over $50'), not where it goes.`;
 /** @see MachineTransition */
 export const machineTransitionSchema = z
     .object({
@@ -199,14 +175,13 @@ export const machineTransitionSchema = z
     type: transitionTypeSchema.optional(),
 })
     .strict();
-/** Whether an edge carries no description the agent could route on: absent, empty or blank. */
+/** Whether an edge carries no description: absent, empty or blank. */
 export function isUndescribed(transition) {
     return !transition.description?.trim();
 }
 /** @see StateBudget */
 export const stateBudgetSchema = z
     .object({
-    maxTurns: positiveInt.optional(),
     timeoutMs: positiveInt.optional(),
     maxParks: positiveInt.optional(),
 })
@@ -300,15 +275,39 @@ export const stateTypeSchema = z.enum(["agent", "human", "grader", "code"], {
 });
 // --- Triggers ------------------------------------------------------------------
 /** The keys a signature entry object may carry, as a refusal lists them. */
-const SIGNATURE_ENTRY_KEYS = "'name', 'type' and 'description'";
+const SIGNATURE_ENTRY_KEYS = `'name', 'type', 'description' and the rules ` +
+    `${SIGNATURE_RULE_NAMES.slice(0, -1).map((rule) => `'${rule}'`).join(", ")} and '${SIGNATURE_RULE_NAMES.at(-1)}'`;
 /** The accepted type words, as a refusal lists them. */
 const SIGNATURE_TYPE_LIST = `${SIGNATURE_TYPES.slice(0, -1).join(", ")} or ${SIGNATURE_TYPES.at(-1)}`;
+/** What a `maxSize` must look like, as a refusal says it. */
+const SIZE_SHAPE = "a size in bytes: an integer, or '<n>KB' / '<n>MB' (e.g. 10MB)";
+/** One file extension as `accept` lists it: a dot and a name holding no further dot or separator. */
+const EXTENSION = /^\.[^./\\]+$/;
+/** A length or count rule's shape; that it is a non-negative integer is the refinement's. */
+function countRule(rule) {
+    return z.number({ error: `'${rule}' must be a non-negative integer` }).optional();
+}
+/** A `minimum`/`maximum` rule's shape; which of the two kinds the entry's type takes is the refinement's. */
+function boundRule(rule) {
+    return z
+        .union([z.number(), z.string()], {
+        error: `'${rule}' must be a number, a date (YYYY-MM-DD or 'today') or a date-time (RFC 3339 or 'now')`,
+    })
+        .optional();
+}
+/** A list rule's shape: strings, with emptiness and repeats left to the refinement. */
+function listRule(rule) {
+    return z
+        .array(z.string({ error: `'${rule}' must list strings` }), { error: `'${rule}' must be a list of strings` })
+        .optional();
+}
 /**
  * @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".
+ * `description`, and read loosely it would silently mean "untyped". A rule key
+ * is shape-checked here and held to its entry's type by {@link refineRules}.
  */
 export const signatureEntryObjectSchema = z.strictObject({
     name: z
@@ -328,12 +327,126 @@ export const signatureEntryObjectSchema = z.strictObject({
         .string({ error: `'description' ${NON_EMPTY}` })
         .refine((value) => value.trim() !== "", `'description' ${NON_EMPTY}`)
         .optional(),
+    format: z
+        .enum(SIGNATURE_FORMATS, {
+        error: (issue) => `'format' must be one of email, url or phone; got ${JSON.stringify(issue.input)}`,
+    })
+        .optional(),
+    pattern: z.string({ error: "'pattern' must be a string (a regular expression)" }).optional(),
+    minLength: countRule("minLength"),
+    maxLength: countRule("maxLength"),
+    enum: listRule("enum"),
+    content: z
+        .enum(SIGNATURE_CONTENTS, {
+        error: (issue) => `'content' must be one of text, markdown or html; got ${JSON.stringify(issue.input)}`,
+    })
+        .optional(),
+    minimum: boundRule("minimum"),
+    maximum: boundRule("maximum"),
+    minItems: countRule("minItems"),
+    maxItems: countRule("maxItems"),
+    accept: listRule("accept"),
+    maxSize: z.union([z.number(), z.string()], { error: `'maxSize' must be ${SIZE_SHAPE}` }).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,
-});
+}).superRefine(refineRules);
+/** `string`, `integer, number, date and date-time`. */
+function typeList(types) {
+    return types.length === 1 ? types[0] : `${types.slice(0, -1).join(", ")} and ${types.at(-1)}`;
+}
+/**
+ * Hold an entry's rules to its type and to each other. Each issue sits at the
+ * rule's key and names the entry itself: the union around the entry hands a
+ * refinement's issues on unwrapped.
+ */
+function refineRules(entry, ctx) {
+    const declared = SIGNATURE_RULE_NAMES.filter((rule) => entry[rule] !== undefined);
+    if (declared.length === 0)
+        return;
+    const label = entryLabel(entry);
+    const issue = (rule, message) => ctx.addIssue({ code: "custom", path: [rule], message: `${label} ${message}` });
+    const { type } = entry;
+    const applicable = [];
+    for (const rule of declared) {
+        const types = RULE_TYPES[rule];
+        if (!type)
+            issue(rule, `declares '${rule}', but has no 'type': it applies to ${typeList(types)} entries only.`);
+        else if (!types.includes(type))
+            issue(rule, `declares '${rule}', which applies to ${typeList(types)} entries only.`);
+        else
+            applicable.push(rule);
+    }
+    if (!type)
+        return;
+    const has = (rule) => applicable.includes(rule);
+    for (const rule of ["minLength", "maxLength", "minItems", "maxItems"]) {
+        if (has(rule) && !isCount(entry[rule])) {
+            issue(rule, `declares '${rule}' as ${String(entry[rule])}, which is not a non-negative integer.`);
+            applicable.splice(applicable.indexOf(rule), 1);
+        }
+    }
+    if (has("format") && has("pattern")) {
+        issue("pattern", `declares both 'format' and 'pattern': an entry declares one or the other.`);
+    }
+    if (has("pattern")) {
+        const pattern = entry.pattern;
+        const compiled = compilePattern(pattern);
+        const error = compiled.ok ? jsonSchemaPatternError(pattern) : compiled.error;
+        if (error)
+            issue("pattern", `declares a 'pattern' that cannot be used: ${error}.`);
+    }
+    for (const rule of ["minimum", "maximum"]) {
+        if (!has(rule) || isBound(type, entry[rule]))
+            continue;
+        const shape = type === "date"
+            ? "a date (YYYY-MM-DD, a real calendar day) or 'today'"
+            : type === "date-time"
+                ? "an RFC 3339 date-time with an offset (e.g. 2026-11-01T09:00:00Z) or 'now'"
+                : "a number";
+        issue(rule, `declares '${rule}' as ${JSON.stringify(entry[rule])}, but on a ${type} entry it must be ${shape}.`);
+    }
+    for (const [low, high] of [
+        ["minLength", "maxLength"],
+        ["minimum", "maximum"],
+        ["minItems", "maxItems"],
+    ]) {
+        if (!has(low) || !has(high))
+            continue;
+        const ordered = low === "minimum"
+            ? boundsInOrder(type, entry[low], entry[high])
+            : entry[low] <= entry[high];
+        if (!ordered) {
+            issue(low, `declares '${low}' ${JSON.stringify(entry[low])} above '${high}' ${JSON.stringify(entry[high])}, ` +
+                `so no value could conform.`);
+        }
+    }
+    for (const rule of ["enum", "accept"]) {
+        if (!has(rule))
+            continue;
+        const list = entry[rule];
+        if (list.length === 0) {
+            issue(rule, `declares an empty '${rule}', so no value could conform.`);
+            continue;
+        }
+        const malformed = rule === "accept" ? list.find((extension) => !EXTENSION.test(extension)) : undefined;
+        if (malformed !== undefined) {
+            issue(rule, `lists ${JSON.stringify(malformed)} in 'accept', which is not a file extension: write a dot and ` +
+                `a name with no further dot, e.g. '.pdf'.`);
+            continue;
+        }
+        // Extensions compare case-insensitively, as `accept` is checked.
+        const keys = list.map((item) => (rule === "accept" ? item.toLowerCase() : item));
+        const repeated = list.find((_, index) => keys.indexOf(keys[index]) !== index);
+        if (repeated !== undefined)
+            issue(rule, `lists ${JSON.stringify(repeated)} more than once in '${rule}'.`);
+    }
+    if (has("maxSize") && parseSize(entry.maxSize) === undefined) {
+        issue("maxSize", `declares 'maxSize' as ${JSON.stringify(entry.maxSize)}, which is not ${SIZE_SHAPE}.`);
+    }
+}
 /** An entry as a message names it: by its `name` when it has a readable one. */
 function entryLabel(input) {
     const name = input?.name;
@@ -659,6 +772,59 @@ function lockIssues(states) {
     }
     return issues;
 }
+/** The type a state declares, `agent` when it declares none. */
+function stateTypeOf(state) {
+    return state?.type ?? "agent";
+}
+/** Why an edge of a state that is not an agent state needs a description, and what to write. */
+const NON_AGENT_EDGE = {
+    human: (slug) => `'${slug}' is a human state, where an edge's description is the label of the person's ` +
+        `button. Say what choosing it means (e.g. 'Approve the refund').`,
+    grader: (slug) => `'${slug}' is a grader state, which chooses its edge by the descriptions. Say when to take ` +
+        `it (e.g. 'The email is ready to send').`,
+    code: (slug) => `'${slug}' is a code state: its script routes, and the description is what a reader of the ` +
+        `spec and the trail goes by. Say when the script takes it (e.g. 'The decision matches the policy').`,
+};
+/** What an edge into a state that is not an agent state hands the session to. */
+const HANDED_TO = {
+    human: "a person's decision",
+    grader: "a grader's check",
+    code: "a code state's check",
+};
+/**
+ * Why `slug`'s undescribed edge at `index` is refused, or `undefined` when it
+ * stands. An edge may go undescribed only where the agent has nothing to choose
+ * and nothing to wait for beyond the state's own work: it is the **only** edge
+ * of an **agent** state that has `instructions`, and it leads into **another
+ * agent** state. The agent takes it as soon as those instructions are done, and
+ * is told so in the edge's place. Every refusal says what to write instead.
+ */
+function undescribedEdgeIssue(states, slug, index) {
+    const state = states[slug];
+    const transitions = state.transitions ?? [];
+    const to = transitions[index].to;
+    const type = stateTypeOf(state);
+    const target = stateTypeOf(states[to]);
+    const refuse = (why) => `must be a non-empty string here: ${why}`;
+    const say = `Say when to take it (e.g. 'The customer confirmed the address').`;
+    if (type !== "agent")
+        return refuse(NON_AGENT_EDGE[type](slug));
+    if (transitions.length > 1) {
+        return refuse(`'${slug}' has ${transitions.length} transitions, and the agent chooses between them by their ` +
+            `descriptions; only a state's single transition may go without one. ${say}`);
+    }
+    if (to === slug)
+        return refuse(`this edge leads back into '${slug}' itself, so it needs a condition. ${say}`);
+    if (target !== "agent") {
+        return refuse(`'${to}' is a ${target} state, so this edge hands the session to ${HANDED_TO[target]}. Say ` +
+            `what must be ready for it (e.g. 'The reply is drafted').`);
+    }
+    if (!state.instructions?.trim()) {
+        return refuse(`'${slug}' declares no instructions, and an undescribed edge is taken once they are done. ` +
+            `Give '${slug}' instructions, or say when to take this edge.`);
+    }
+    return undefined;
+}
 export function refineSpec(spec) {
     const issues = [];
     const issue = (path, message) => issues.push({ path, message });
@@ -675,19 +841,11 @@ export function refineSpec(spec) {
                 issue(`${at}.transitions.${index}.to`, `State '${slug}' transitions to undefined state '${transition.to}'`);
                 return;
             }
-            // A code state's script routes: nothing reads its edges' descriptions.
-            if (!isUndescribed(transition) || state.type === "code")
+            if (!isUndescribed(transition))
                 return;
-            const target = states[transition.to];
-            if (state.type === "human") {
-                issue(`${at}.transitions.${index}.description`, HUMAN_TRANSITION_DESCRIPTION);
-            }
-            else if (target?.type === "grader" || target?.type === "code") {
-                issue(`${at}.transitions.${index}.description`, undescribedAutomatedEdgeMessage(transition.to, target.type));
-            }
-            else if (!target?.instructions?.trim()) {
-                issue(`${at}.transitions.${index}.description`, undescribedEdgeMessage(transition.to));
-            }
+            const refusal = undescribedEdgeIssue(states, slug, index);
+            if (refusal)
+                issue(`${at}.transitions.${index}.description`, refusal);
         });
         if (state.on_error !== undefined && !(state.on_error in states)) {
             issue(`${at}.on_error`, `State '${slug}' on_error routes to undefined state '${state.on_error}'`);