@archmax-ai/harness 1.0.1 → 1.1.0

package/skills/archmax-harness/references/backend-integration.md

@@ -82,7 +82,7 @@ From `@archmax-ai/harness` (`src/index.ts`):
 | `workflowStateSchema`, `workflowPaths`, `sessionPaths`, `runArtifactPaths` | schema/fn | State schema + path helpers |
 | `runTests`, `RunTestsOptions`, `CaseResult` | fn/type | Run a workflow's cases — [against your own agent](#cases-against-your-agent) |
 | `toolsFromMap`, `AgentToolDescriptor`, `ToolContext`, `ToolPaths`, `PathAccess`, `ToolPathsError` | fn/type/class | Host tools: a `name → descriptor` map, each descriptor's declared `paths` and a handler handed the turn's workspace — [host tools](#host-tools) |
-| `SIGNATURE_TYPES`, `normalizeSignature`, `signatureForTrigger`, `signatureJsonSchema`, `signatureValueIssues` | const/fn | A trigger's typed signature as JSON Schema and its conformance rule — [exposing a workflow](#exposing-a-workflow-to-outside-callers); also on `@archmax-ai/harness/spec` |
+| `SIGNATURE_TYPES`, `SIGNATURE_FORMATS`, `SIGNATURE_CONTENTS`, `normalizeSignature`, `signatureForTrigger`, `signatureJsonSchema`, `signatureValueIssues` | const/fn | A trigger's typed signature, rules included, as JSON Schema and its conformance rule — [exposing a workflow](#exposing-a-workflow-to-outside-callers); also on `@archmax-ai/harness/spec` |
 
 ## createAgent options
 
@@ -399,12 +399,22 @@ const outcome = await agent.workflow!.send(sessionId, { message: "Refund the ord
 - `signatureJsonSchema(entries)` → `{ type: "object", properties, required }`:
   one property per entry in declaration order, every name required,
   `date`/`date-time`/`file` as `{ type: "string", format }`, an untyped entry as `{}`,
-  an entry's `description` carried over. It adds no `additionalProperties`; set
-  it for your own ingress.
-- `signatureValueIssues(entries, values)` → one issue per missing name and per
-  non-conforming value; `[]` means the turn boundary will not refuse the map for
-  its signature. It **never coerces**: a form that collects text converts
-  `"4"` to `4` before it validates or seeds.
+  an entry's `description` carried over. Rules map to their JSON Schema keywords:
+  `format: email` → `format: "email"`, `format: url` → `format: "uri"` plus
+  `pattern: "^https?://"`, `format: phone` → the E.164 `pattern`; `pattern`,
+  `minLength`/`maxLength`, `enum`, numeric `minimum`/`maximum` and
+  `minItems`/`maxItems` as themselves; `content` → `contentMediaType`. Date
+  bounds, `accept` and `maxSize` are not mapped (the runtime still enforces
+  them). It adds no `additionalProperties`; set it for your own ingress.
+- `signatureValueIssues(entries, values, options?)` → one issue per missing name
+  and per non-conforming value; `[]` means the turn boundary will not refuse the
+  map for its signature. A value breaking a rule is an `invalid` issue carrying
+  `rule` (one per entry, the first rule broken), so code that filters
+  `kind === "invalid"` enforces rules unchanged. `options.now` pins the clock
+  for `today`/`now` (tests, a host's own clock). It is synchronous, pure and
+  browser-safe, and a `pattern` runs in RE2, so it is safe in a request path on
+  input from anyone. It **never coerces or trims**: a form that collects text
+  converts `"4"` to `4` before it validates or seeds.
 - A trigger's `description` is written for the caller. Use it as the MCP tool
   or operation description. The session's own model never sees it.
 - **A `file` entry** (`format: "file"` in the schema) takes a workspace path. To
@@ -417,13 +427,15 @@ const outcome = await agent.workflow!.send(sessionId, { message: "Refund the ord
   `InvalidTurnFileError`, before anything is written, for a bad variable or file
   name, a variable also given in `variables`, a session parked at a human state, or
   bytes the store cannot hold exactly (a non-text file needs a store with
-  `uploadFiles`). `signatureValueIssues` checks only a `file` value's shape, so a
-  start form validates the path the upload will produce, or skips the entry and
-  lets `files` supply it.
+  `uploadFiles`). `signatureValueIssues` checks only a `file` value's shape and its
+  `accept` extensions, so a start form validates the path the upload will
+  produce, or skips the entry and lets `files` supply it; `maxSize` is checked by
+  the runtime at the turn boundary, against the placed file.
 - A host that reads specs itself must read `requires`/`returns` through
-  `normalizeSignature` (both spellings → `{ name, type?, description? }[]`),
-  never as `string[]`: an entry may be an object. Hosts must be on the release
-  that introduced typed entries before any workspace they read uses them.
+  `normalizeSignature` (both spellings → `{ name, type?, description?, …rules }[]`,
+  `maxSize` in bytes, `today`/`now` kept symbolic), never as `string[]`: an entry
+  may be an object. Hosts must be on the release that introduced typed entries
+  (and, for rules, 1.1.0) before any workspace they read uses them.
 
 ## Lifecycle events
 

package/skills/archmax-harness/references/workflow-schema.md

@@ -606,7 +606,8 @@ states:
         description: Enrich one order and say whether it is late.  # for callers only
         requires:                            # a firing must supply these to start
           - order_id                         # bare name = untyped
-          - { name: due, type: date, description: The day the order is due. }
+          - { name: due, type: date, minimum: today, description: The day the order is due. }
+          - { name: priority, type: string, enum: [low, normal, high] }   # a rule
         returns:                             # the run guarantees these when it completes
           - enrichment_file
           - { name: delayed, type: boolean }
@@ -635,10 +636,11 @@ states:
   state through a code state that checks the returns and sends the work back
   with what is missing. Each entry is a bare
   run-variable name (**untyped**: any value, `null` included) or a strict object
-  `{ name, type?, description? }` naming one; the spellings mix in one list and
+  `{ name, type?, description?, …rules }` naming one; the spellings mix in one list and
   names are distinct across both. What the agent must *do* to produce a
   variable still belongs in the `instructions` that set it. The names — with
-  type and description when declared, as `name (type) — description` — are
+  type, rules and description when declared, as
+  `name (type; rule; rule) — description` — are
   rendered into the prompt under the trigger's entry state, so the agent is told
   what to produce before it can be failed for omitting it. A trigger's
   `requires:` also **guarantees** the variable for `${{…}}` guards, so `validate`
@@ -654,9 +656,37 @@ states:
   refused before any model call), **at the write** (`archmax_set_variables` of a
   mistyped typed return of the current trigger is a correctable refusal,
   nothing written) and **at completion** (a mistyped typed return rejects the
-  run — in practice a code state's write). There are no enums, item or
-  property schemas, ranges or optional inputs. An unknown `type`, an unknown
-  entry key (`default:`) or an empty `description` fails load.
+  run — in practice a code state's write). There are no item or property
+  schemas and no optional inputs. An unknown `type`, an unknown entry key
+  (`default:`) or an empty `description` fails load.
+- **Rules** say what a typed value must look like beyond its type, spelled as
+  JSON Schema keywords, and are held wherever the type is (start, write,
+  completion, a delegation call and its settle):
+
+  | Rule | On | Value |
+  | --- | --- | --- |
+  | `format` | `string` | `email` (WHATWG grammar, a domain with a TLD), `url` (absolute `http(s)://`, no credentials), `phone` (E.164, `+4930123456`) |
+  | `pattern` | `string` | a regex found anywhere in the value (anchor with `^…$`), ≤ 1,000 characters |
+  | `minLength`, `maxLength` | `string` | non-negative integers, counted in code points |
+  | `enum` | `string` | a non-empty list of distinct strings, matched exactly |
+  | `content` | `string` | `text`, `markdown` or `html`: a **declaration** for the host, never checked or sanitised |
+  | `minimum`, `maximum` | `integer`, `number` | numbers, inclusive |
+  | `minimum`, `maximum` | `date` | `YYYY-MM-DD` or `today` (UTC), inclusive |
+  | `minimum`, `maximum` | `date-time` | an RFC 3339 instant or `now`, inclusive |
+  | `minItems`, `maxItems` | `array` | non-negative integers |
+  | `accept` | `file` | extensions like `.pdf`, matched on the last extension, case-insensitively |
+  | `maxSize` | `file` | bytes, or `<n>KB` / `<n>MB` (1,000-based); checked where the file crosses a boundary |
+
+  Nothing is coerced or trimmed; a mistyped value reports its type, not a rule;
+  each entry reports only the first rule it breaks (`'quantity' must be at most
+  100`). Load fails, naming the entry and key, for a rule on a type that does not
+  take it or on an untyped entry, `format` with `pattern`, a pattern that does not
+  compile or uses a lookaround or backreference, and inconsistent bounds (`min…`
+  above `max…`, an empty or repeated `enum`). A `pattern` runs in RE2 (linear
+  time, so no input can make it slow) and must also compile as an ECMA-262 `u`
+  regex, so RE2-only syntax like `(?i)` or `\pL` is refused. Add rules where a
+  caller outside the session supplies the value (a form, an MCP client), or where
+  the agent must produce a value of a set shape; the agent sees them in its prompt.
 - **A `file` value must name a readable file.** The pure rule checks only the
   path's shape (a host runs it in a browser). At the start, at the write, at
   completion and at a delegation call the runtime also requires a **file** (not a

package/skills/archmax-harness/references/workflow-yaml.md

@@ -59,9 +59,12 @@ states:
         requires:                #   variables a firing must supply (a caller's required params):
           - order_id             #     a bare name is untyped (any value, null included)
           - { name: due, type: date, description: The day it is due. }  # typed: held at the boundary
+          - { name: contact, type: string, format: email }  # a rule beside the type: held wherever the type is
         returns: [result_file]   #   variables the run guarantees on completion (a caller's result);
                                  #   short of them: a child returns what it set + a `note`; a top-level run is rejected
                                  #   entry types: string integer number boolean date date-time object array file
+                                 #   rules: format pattern minLength maxLength enum content (string); minimum maximum
+                                 #   (integer number date date-time); minItems maxItems (array); accept maxSize (file)
     instructions: >-
       Record the decision in scratchpad/refund.json, then archmax_advance to
       check-policy; never close the case yourself. If a note sends the case