@archmax-ai/harness 1.0.1 → 1.1.0

package/dist/machine/signature-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-pattern.js","sourceRoot":"","sources":["../../src/machine/signature-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAE9B,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAKvC,0GAA0G;AAC1G,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;AACjD,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,IAAI,IAAI,WAAW;QAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;IACxE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,OAAO,CAAC,OAAe;IAC9B,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,OAAO,CAAC,MAAM,uCAAuC,kBAAkB,EAAE,EAAE,CAAC;IAClH,CAAC;IACD,IAAI,GAAU,CAAC;IACf,IAAI,CAAC;QACH,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,IAAI,CAAC;QACH,IAAI,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,2CAA4C,GAAa,CAAC,OAAO,EAAE,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/machine/signature.d.ts

@@ -1,13 +1,3 @@
-/**
- * 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
@@ -19,12 +9,61 @@ import type { MachineSpec, SignatureEntryDeclaration } from "./types.js";
 export declare const SIGNATURE_TYPES: readonly ["string", "integer", "number", "boolean", "date", "date-time", "object", "array", "file"];
 /** One of {@link SIGNATURE_TYPES}. */
 export type SignatureType = (typeof SIGNATURE_TYPES)[number];
+/** The formats a `string` entry's `format` rule names. */
+export declare const SIGNATURE_FORMATS: readonly ["email", "url", "phone"];
+/** One of {@link SIGNATURE_FORMATS}. */
+export type SignatureFormat = (typeof SIGNATURE_FORMATS)[number];
+/**
+ * The kinds of text a `string` entry's `content` rule declares. A declaration
+ * only: carried and mapped, never checked — what a kind permits is a host's call.
+ */
+export declare const SIGNATURE_CONTENTS: readonly ["text", "markdown", "html"];
+/** One of {@link SIGNATURE_CONTENTS}. */
+export type SignatureContent = (typeof SIGNATURE_CONTENTS)[number];
+/**
+ * The rules an entry declares on its value beyond its type, each spelled as the
+ * JSON Schema keyword it maps to where one exists, and each only on the types
+ * {@link RULE_TYPES} allows.
+ */
+export interface SignatureRules {
+    /** `string`: an email address, an http(s) URL, or an E.164 phone number. */
+    format?: SignatureFormat;
+    /** `string`: a regular expression (RE2 syntax) found anywhere in the value. */
+    pattern?: string;
+    /** `string`: the fewest code points. */
+    minLength?: number;
+    /** `string`: the most code points. */
+    maxLength?: number;
+    /** `string`: the values allowed, compared exactly. */
+    enum?: string[];
+    /** `string`: what kind of text the value holds. Declared, not checked. */
+    content?: SignatureContent;
+    /** `integer`/`number`: a number; `date`: `YYYY-MM-DD` or `today`; `date-time`: an RFC 3339 instant or `now`. Inclusive. */
+    minimum?: number | string;
+    /** As {@link SignatureRules.minimum}, from above. */
+    maximum?: number | string;
+    /** `array`: the fewest entries. */
+    minItems?: number;
+    /** `array`: the most entries. */
+    maxItems?: number;
+    /** `file`: the extensions allowed, each with its leading `.`, compared case-insensitively. */
+    accept?: string[];
+    /** `file`: the largest file, in bytes. Checked where a `file` value crosses a boundary. */
+    maxSize?: number;
+}
+/** Which rule an issue is about. */
+export type SignatureRuleName = keyof SignatureRules;
+/** The types each rule applies to. A rule on any other type, or on an untyped entry, is a load error. */
+export declare const RULE_TYPES: Readonly<Record<SignatureRuleName, readonly SignatureType[]>>;
+/** Every rule name, in the order an entry's rules are read and listed. */
+export declare const SIGNATURE_RULE_NAMES: SignatureRuleName[];
 /**
  * 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.
+ * of value it holds, the rules that value must meet, and what it is for. An
+ * entry without `type` is untyped — any value satisfies it, `null` included —
+ * and declares no rules.
  */
-export interface SignatureEntry {
+export interface SignatureEntry extends SignatureRules {
     name: string;
     type?: SignatureType;
     description?: string;
@@ -40,9 +79,10 @@ export interface TriggerSignature {
 }
 /**
  * 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.
+ * or a value that does not conform to its entry's type or breaks one of its
+ * rules (`rule` names which). `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";
@@ -53,19 +93,46 @@ export type SignatureValueIssue = {
     name: string;
     type: SignatureType;
     found: SignatureValueKind;
+    rule?: SignatureRuleName;
     message: string;
 };
+/** How {@link signatureValueIssues} reads its clock. */
+export interface SignatureValueOptions {
+    /** The instant `now` is, and whose UTC date `today` is; the current time when omitted. */
+    now?: Date;
+}
 /** 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.
+ * A `requires`/`returns` list as `{ name, type?, description?, …rules }`
+ * entries, in declaration order: a bare name and `{ name }` are the same
+ * untyped entry. A rule is carried as written, except `maxSize`, read as bytes;
+ * `today` and `now` stay symbolic. Total — a list the schema refused (a scalar,
+ * an entry naming nothing, a rule its type does not take) 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 length or count: a non-negative integer. */
+export declare function isCount(value: unknown): value is number;
+/**
+ * Whether `value` is a well-formed `minimum`/`maximum` for `type`: a finite
+ * number for `integer`/`number`, a real `YYYY-MM-DD` or `today` for `date`, an
+ * RFC 3339 date-time or `now` for `date-time`.
+ */
+export declare function isBound(type: SignatureType, value: unknown): value is number | string;
+/**
+ * Whether a `minimum` and a `maximum` for `type` leave room for a value: `true`
+ * unless both are literal and the minimum is above the maximum. `today` and
+ * `now` move, so a bound naming one is never out of order here.
+ */
+export declare function boundsInOrder(type: SignatureType, minimum: unknown, maximum: unknown): boolean;
+/**
+ * A `maxSize` in bytes: a non-negative integer as itself, `<n>KB` as n × 1,000,
+ * `<n>MB` as n × 1,000,000; `undefined` for anything else.
+ */
+export declare function parseSize(value: unknown): number | undefined;
 /**
  * A trigger's normalized signature read from a parsed spec, or `undefined` when no
  * state declares the id. The same reading `WorkflowMachine.signatureForTrigger`
@@ -73,10 +140,22 @@ export declare function isSignatureType(value: unknown): value is SignatureType;
  * 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`. */
+/**
+ * One property of {@link signatureJsonSchema}'s output. An untyped entry has no
+ * `type`; a rule JSON Schema can express adds its keyword.
+ */
 export interface SignaturePropertySchema {
     type?: "string" | "integer" | "number" | "boolean" | "object" | "array";
-    format?: "date" | "date-time" | "file";
+    format?: "date" | "date-time" | "file" | "email" | "uri";
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    contentMediaType?: "text/plain" | "text/markdown" | "text/html";
     description?: string;
 }
 /** What {@link signatureJsonSchema} yields: a JSON Schema object over the signature's names. */
@@ -89,23 +168,46 @@ export interface SignatureJsonSchema {
  * 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`/`file` 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.
+ * each rule JSON Schema can express as its keyword, 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 what the runtime enforces. Date bounds, `accept` and `maxSize` have
+ * no JSON Schema keyword and are left out; the runtime still enforces them.
  */
 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`. A `file` value is judged by its shape
- * alone: whether a file is there, and whether the session may read it, is the
- * runtime's check where the value crosses a boundary.
- */
-export declare function signatureValueIssues(entries: readonly SignatureEntry[], values: Readonly<Record<string, unknown>>): SignatureValueIssue[];
+ * `values`, and one per typed entry whose value does not conform to its type
+ * or, conforming, breaks one of its rules, 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 or trimmed —
+ * the string `"4"` is not an `integer`, and `" a@b.co"` is not an email address.
+ *
+ * Rules are checked only on a value of the right type, and an entry reports
+ * only the first rule it breaks, in this order: `format`/`pattern`, `enum`,
+ * `minLength`/`maxLength`, `minimum`/`maximum`, `minItems`/`maxItems`,
+ * `accept`. `today` and `now` read `options.now`, the current time by default.
+ * Every check is synchronous and linear in the value's length; an authored
+ * `pattern` runs in RE2, never in `RegExp`. A `file` value is judged by its
+ * path alone: whether a file is there, whether the session may read it and
+ * how large it is, is the runtime's check where the value crosses a boundary.
+ */
+export declare function signatureValueIssues(entries: readonly SignatureEntry[], values: Readonly<Record<string, unknown>>, options?: SignatureValueOptions): SignatureValueIssue[];
+/**
+ * The rules an entry declares, as short phrases in declaration-table order
+ * (`an email address`, `at most 80 characters`, `not before today`): what the
+ * prompt lists beside the entry's type, in the words a refusal of each uses.
+ */
+export declare function signatureRulePhrases(entry: SignatureEntry): string[];
+/**
+ * A `file` path's last extension, lower-cased with its leading `.`, or `""`
+ * when its file name has none (`notes`, `.env`).
+ */
+export declare function lastExtension(path: string): string;
+/** A byte count as a refusal states it, 1,000-based: `10 MB`, `512 KB`, `1500 bytes`. */
+export declare function formatSize(bytes: number): string;
 /**
  * A workspace path from the root, as a `file` value spells it: at most one
  * leading `/`, then one or more segments, none empty, `.` or `..`, with no