@petepetrash/circuit 0.1.0

package/dist/flows/registries/shape-hints/from-zod.js

@@ -0,0 +1,354 @@
+// Render a one-line JSON-shape skeleton from a Zod schema.
+//
+// Used by flow `relay-hints.ts` authors so the shape portion of a relay
+// instruction is derived from the report's Zod schema rather than typed
+// out by hand. Authors keep the task-specific guidance and the
+// mechanical tail (no code fences, JSON.parse, validation) as authored
+// prose — only the literal `{ "field": "<placeholder>", ... }` part is
+// generated here.
+//
+// Field-level placeholders default to `<string>`, `<number>`, etc. An
+// author can override the placeholder for any leaf field by calling
+// `.describe('what the field carries')` on the Zod schema; the renderer
+// renders that description as the placeholder text. A `.describe()` carried
+// on an OBJECT or ARRAY shape (including one attached through a transparent
+// wrapper like `.optional()`) is not a leaf placeholder, so it renders as a
+// leading `<...>` annotation in front of the recursed shape rather than being
+// dropped — that is how the context-pull channel's "when to ask" guidance
+// reaches the worker.
+//
+// Limitations the renderer degrades on intentionally:
+//   - ZodUnion (non-discriminated) renders each option separated by ` |
+//     `. Authors usually want a more guided prose explanation for
+//     unions, so this is a deliberately-bare default.
+//   - ZodDiscriminatedUnion collapses to a single shape when every
+//     branch is a ZodObject with the same key set; the discriminator
+//     field becomes an enum-like placeholder. Heterogeneous-shape
+//     unions fall back to `a | b | c`.
+//   - ZodAny / ZodUnknown render as `<any>` / `<unknown>` placeholders
+//     and rely on authored guidance.
+//   - `.superRefine`-only invariants that the structural type can't
+//     express (e.g. value-conditional minimums) stay in authored prose.
+//   - ZodLazy / recursive schemas are guarded against infinite
+//     recursion: a node visited again at deeper depth renders as
+//     `<recursive>` rather than blowing the stack.
+function defOf(node) {
+    return node._zod.def;
+}
+function objectShape(def) {
+    const shape = def.shape;
+    return typeof shape === 'function' ? shape() : shape;
+}
+function literalValues(def) {
+    if (Array.isArray(def.values))
+        return def.values;
+    if ('value' in def)
+        return [def.value];
+    return [];
+}
+function enumValues(def) {
+    const raw = def.entries ?? def.values;
+    if (Array.isArray(raw))
+        return raw;
+    if (raw === undefined || raw === null || typeof raw !== 'object')
+        return [];
+    // `z.enum()` over numeric TS enums (formerly `z.nativeEnum()`) carries
+    // TypeScript's reverse-mapped form
+    // ({0:'Low',1:'High',Low:0,High:1}); Zod accepts the numeric value side.
+    const values = Object.values(raw);
+    const isReverseMapped = values.some((value) => typeof value === 'number' &&
+        Object.hasOwn(raw, String(value)));
+    const accepted = isReverseMapped
+        ? values.filter((value) => typeof value === 'number')
+        : values;
+    return Array.from(new Set(accepted));
+}
+function renderEnumValues(values) {
+    return values
+        .map((value) => (typeof value === 'string' ? escapeJsonInner(value) : String(value)))
+        .join('|');
+}
+// JSON-escape a string for inline use inside a double-quoted JSON-shape
+// placeholder. The renderer emits inline JSON-ish prose, not strict JSON,
+// but unescaped quotes/backslashes in a `.describe()` text or in an object
+// key can break the visual shape (and confuse a worker that tries to
+// JSON.parse the literal example). Reuse JSON.stringify and strip the
+// surrounding quotes so the escape rules stay in lockstep with the
+// language standard.
+function escapeJsonInner(value) {
+    const serialized = JSON.stringify(value);
+    return serialized.slice(1, serialized.length - 1);
+}
+// The non-empty `.describe()` text carried directly on a node, checking the
+// instance-level description first (where `.describe()` writes in Zod v4) and
+// falling back to the def. Returns undefined when no description is present.
+function carriedDescription(node) {
+    const nodeDescription = node.description;
+    if (typeof nodeDescription === 'string' && nodeDescription.length > 0) {
+        return nodeDescription;
+    }
+    const defDescription = defOf(node).description;
+    if (typeof defDescription === 'string' && defDescription.length > 0) {
+        return defDescription;
+    }
+    return undefined;
+}
+function leafDescriptionOr(node, fallback) {
+    const description = carriedDescription(node);
+    if (description !== undefined) {
+        return `"<${escapeJsonInner(description)}>"`;
+    }
+    return fallback;
+}
+// Base Zod types whose `.describe()` is structural guidance about a shape, not
+// a leaf placeholder. A description carried on (or wrapping) one of these is
+// surfaced as a `<...>` annotation rather than dropped.
+const NON_LEAF_BASE_TYPES = new Set(['object', 'array', 'tuple', 'record', 'map']);
+// Peel transparent wrappers (`.optional()`, `.default()`, `.pipe()`, etc.) to
+// find the base type a node ultimately stands for, so a description attached to
+// a wrapper is attributed to the object/array it wraps. Used only to decide
+// whether a carried description annotates a non-leaf shape — leaves fold their
+// own describe into the placeholder via `leafDescriptionOr`, so they must not
+// also be annotated here.
+function annotatesAsNonLeaf(node) {
+    let current = node;
+    for (let depth = 0; depth <= MAX_RECURSION_DEPTH; depth += 1) {
+        const def = defOf(current);
+        switch (def.type) {
+            case 'optional':
+            case 'nullable':
+            case 'default':
+            case 'readonly':
+            case 'catch':
+            case 'nonoptional':
+            case 'success':
+                current = def.innerType;
+                continue;
+            case 'pipe':
+                current = (def.in ?? def.out);
+                continue;
+            default:
+                return NON_LEAF_BASE_TYPES.has(def.type);
+        }
+    }
+    return false;
+}
+// Prepend a non-leaf node's carried `.describe()` text as a leading `<...>`
+// annotation in front of its rendered shape. The text is left unescaped on
+// purpose: unlike a leaf placeholder it sits OUTSIDE any JSON string literal,
+// so it reads as inline guidance, not as a parseable value. Returns the
+// rendered shape unchanged when there is no description or the node is a leaf.
+function withCarriedAnnotation(node, rendered) {
+    const description = carriedDescription(node);
+    if (description === undefined || !annotatesAsNonLeaf(node)) {
+        return rendered;
+    }
+    return `<${description}> ${rendered}`;
+}
+// Render-time recursion guard. The visited set captures Zod nodes already
+// on the render stack so a `z.lazy(() => Node)` self-reference is detected
+// at the second visit and short-circuited. The set is render-call-scoped,
+// not module-global, so independent schemas don't share state.
+const MAX_RECURSION_DEPTH = 32;
+export function renderShapeSkeleton(schema) {
+    return renderNode(schema, new Set(), 0);
+}
+// Collect every string value the schema admits for its top-level `verdict`
+// field. Handles plain objects (verdict as enum or literal) and unions —
+// including discriminated unions over `verdict` — by walking each branch.
+// Returns [] when the schema has no introspectable verdict field, so
+// callers can degrade to the step's check.pass list alone.
+export function verdictValuesFromSchema(schema) {
+    const out = [];
+    collectVerdictValues(schema, out, 0);
+    return [...new Set(out)];
+}
+function collectVerdictValues(node, out, depth) {
+    if (depth > MAX_RECURSION_DEPTH)
+        return;
+    const def = defOf(node);
+    switch (def.type) {
+        case 'object': {
+            const verdict = objectShape(def).verdict;
+            if (verdict === undefined)
+                return;
+            const verdictDef = defOf(verdict);
+            const values = verdictDef.type === 'enum'
+                ? enumValues(verdictDef)
+                : verdictDef.type === 'literal'
+                    ? literalValues(verdictDef)
+                    : [];
+            for (const value of values) {
+                if (typeof value === 'string')
+                    out.push(value);
+            }
+            return;
+        }
+        case 'union': {
+            for (const option of def.options) {
+                collectVerdictValues(option, out, depth + 1);
+            }
+            return;
+        }
+        case 'lazy': {
+            const getter = def.getter;
+            collectVerdictValues(getter(), out, depth + 1);
+            return;
+        }
+        default:
+            return;
+    }
+}
+function renderNode(node, visited, depth) {
+    if (visited.has(node) || depth > MAX_RECURSION_DEPTH) {
+        return '<recursive>';
+    }
+    visited.add(node);
+    try {
+        const rendered = renderNodeInner(node, visited, depth + 1);
+        return withCarriedAnnotation(node, rendered);
+    }
+    finally {
+        visited.delete(node);
+    }
+}
+function renderNodeInner(node, visited, depth) {
+    const def = defOf(node);
+    switch (def.type) {
+        case 'object': {
+            const shape = objectShape(def);
+            const entries = Object.entries(shape).map(([key, child]) => `"${escapeJsonInner(key)}": ${renderNode(child, visited, depth)}`);
+            return `{ ${entries.join(', ')} }`;
+        }
+        case 'array': {
+            const inner = renderNode(def.element, visited, depth);
+            return `[${inner}]`;
+        }
+        case 'optional':
+        case 'nullable':
+        case 'default':
+        case 'readonly':
+        case 'catch':
+        case 'nonoptional':
+        case 'success':
+            return renderNode(def.innerType, visited, depth);
+        case 'pipe':
+            return renderNode((def.in ?? def.out), visited, depth);
+        case 'transform':
+            return '<transform>';
+        case 'literal': {
+            const [value] = literalValues(def);
+            return typeof value === 'string' ? JSON.stringify(value) : JSON.stringify(value);
+        }
+        case 'enum': {
+            const values = enumValues(def);
+            return `"<${renderEnumValues(values)}>"`;
+        }
+        case 'string':
+            return leafDescriptionOr(node, '"<string>"');
+        case 'number':
+            return leafDescriptionOr(node, '<number>');
+        case 'bigint':
+            return leafDescriptionOr(node, '<bigint>');
+        case 'boolean':
+            return leafDescriptionOr(node, '<true|false>');
+        case 'date':
+            return leafDescriptionOr(node, '"<iso-date>"');
+        case 'null':
+            return 'null';
+        case 'undefined':
+            return '<undefined>';
+        case 'any':
+            return leafDescriptionOr(node, '<any>');
+        case 'unknown':
+            return leafDescriptionOr(node, '<unknown>');
+        case 'never':
+            return '<never>';
+        case 'record':
+        case 'map':
+            return `{ "<key>": ${renderNode(def.valueType, visited, depth)} }`;
+        case 'tuple': {
+            const items = def.items.map((item) => renderNode(item, visited, depth));
+            const rest = def.rest;
+            if (rest !== undefined && rest !== null) {
+                items.push(`...${renderNode(rest, visited, depth)}`);
+            }
+            return `[${items.join(', ')}]`;
+        }
+        case 'union': {
+            const options = def.options;
+            const discriminator = def.discriminator;
+            if (typeof discriminator === 'string') {
+                const collapsed = collapseDiscriminatedUnion(discriminator, options, visited, depth);
+                if (collapsed !== undefined)
+                    return collapsed;
+            }
+            return options.map((opt) => renderNode(opt, visited, depth)).join(' | ');
+        }
+        case 'lazy': {
+            const getter = def.getter;
+            return renderNode(getter(), visited, depth);
+        }
+        case 'intersection': {
+            const left = renderNode(def.left, visited, depth);
+            const right = renderNode(def.right, visited, depth);
+            return `${left} & ${right}`;
+        }
+        default:
+            return `<${def.type}>`;
+    }
+}
+// Collapse a discriminated union of ZodObject branches into a single shape
+// when every branch has the same key set. The discriminator field renders
+// as an enum-style placeholder listing the literal values across branches;
+// other fields render from the first branch (they're expected to match in
+// shape, even if their value constraints differ). Returns undefined when
+// branches diverge structurally, in which case the caller falls back to
+// `a | b | c` rendering.
+function collapseDiscriminatedUnion(discriminator, options, visited, depth) {
+    if (options.length === 0)
+        return undefined;
+    const objectShapes = [];
+    const discriminatorValues = [];
+    for (const option of options) {
+        const optDef = defOf(option);
+        if (optDef.type !== 'object')
+            return undefined;
+        const shape = objectShape(optDef);
+        objectShapes.push(shape);
+        const discriminatorNode = shape[discriminator];
+        if (discriminatorNode === undefined)
+            return undefined;
+        const discriminatorDef = defOf(discriminatorNode);
+        if (discriminatorDef.type !== 'literal')
+            return undefined;
+        const [value] = literalValues(discriminatorDef);
+        discriminatorValues.push(value);
+    }
+    const firstShape = objectShapes[0];
+    if (firstShape === undefined)
+        return undefined;
+    const keyList = Object.keys(firstShape);
+    const keyListSorted = keyList.slice().sort();
+    for (const shape of objectShapes) {
+        const shapeKeys = Object.keys(shape).slice().sort();
+        if (shapeKeys.length !== keyListSorted.length)
+            return undefined;
+        for (let idx = 0; idx < shapeKeys.length; idx += 1) {
+            if (shapeKeys[idx] !== keyListSorted[idx])
+                return undefined;
+        }
+    }
+    const entries = keyList.map((key) => {
+        if (key === discriminator) {
+            const rendered = discriminatorValues.map((value) => typeof value === 'string' ? escapeJsonInner(value) : String(value));
+            return `"${escapeJsonInner(key)}": "<${rendered.join('|')}>"`;
+        }
+        const child = firstShape[key];
+        if (child === undefined)
+            return `"${escapeJsonInner(key)}": <missing>`;
+        return `"${escapeJsonInner(key)}": ${renderNode(child, visited, depth)}`;
+    });
+    return `{ ${entries.join(', ')} }`;
+}
+//# sourceMappingURL=from-zod.js.map

package/dist/flows/registries/shape-hints/from-zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-zod.js","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/from-zod.ts"],"names":[],"mappings":"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"}

package/dist/flows/registries/shape-hints/instruction-helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function shapeInstruction(skeleton: string): string;
+export declare function mechanicalTail(schema: string, reportPath?: string): string;
+//# sourceMappingURL=instruction-helpers.d.ts.map

package/dist/flows/registries/shape-hints/instruction-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-helpers.d.ts","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/instruction-helpers.ts"],"names":[],"mappings":"AAcA,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAW1E"}

package/dist/flows/registries/shape-hints/instruction-helpers.js

@@ -0,0 +1,28 @@
+// Shared assembly helpers for relay shape-hint instructions.
+//
+// `shapeInstruction` prefixes a rendered JSON skeleton with the canonical
+// opening line; `mechanicalTail` appends the parse/validate contract every
+// schema hint must carry. The `relay-prompt-hygiene` test enforces three of
+// those clauses (no code fences, no surrounding prose, JSON.parse) across
+// every registered hint, so flow authors reach for these bookends and keep
+// only their task-specific guidance as authored prose. Keeping the contract
+// text in one place is what lets it stay identical across flows.
+//
+// `reportPath` is optional: pass it when a step writes to a single stable
+// path (most flows) and omit it when the path is step-numbered or otherwise
+// ambiguous, so the tail never cites a path the worker can't trust.
+export function shapeInstruction(skeleton) {
+    return `Respond with a single raw JSON object whose top-level shape is exactly: ${skeleton}`;
+}
+export function mechanicalTail(schema, reportPath) {
+    const validation = reportPath === undefined
+        ? `The runtime parses your response with JSON.parse, rejects verdicts the schema does not allow, and validates the full report body against ${schema}.`
+        : `The runtime parses your response with JSON.parse, rejects verdicts the schema does not allow, and validates the full report body against ${schema} before writing ${reportPath}.`;
+    return [
+        'Do not include extra top-level keys.',
+        'Do not wrap the JSON in Markdown code fences.',
+        'Do not include any prose before or after the JSON object.',
+        validation,
+    ].join(' ');
+}
+//# sourceMappingURL=instruction-helpers.js.map

package/dist/flows/registries/shape-hints/instruction-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-helpers.js","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/instruction-helpers.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,iEAAiE;AACjE,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,oEAAoE;AAEpE,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,2EAA2E,QAAQ,EAAE,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,UAAmB;IAChE,MAAM,UAAU,GACd,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,4IAA4I,MAAM,GAAG;QACvJ,CAAC,CAAC,4IAA4I,MAAM,mBAAmB,UAAU,GAAG,CAAC;IACzL,OAAO;QACL,sCAAsC;QACtC,+CAA+C;QAC/C,2DAA2D;QAC3D,UAAU;KACX,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC"}

package/dist/flows/registries/shape-hints/registry.d.ts

@@ -0,0 +1,5 @@
+import type { RelayStep, SchemaShapeHint, StructuralShapeHint } from './types.js';
+export declare function findRelayShapeHint(step: RelayStep): string | undefined;
+export declare function listRegisteredSchemaHints(): readonly SchemaShapeHint[];
+export declare function listRegisteredStructuralHints(): readonly StructuralShapeHint[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/flows/registries/shape-hints/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/registry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAKlF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAUtE;AAED,wBAAgB,yBAAyB,IAAI,SAAS,eAAe,EAAE,CAMtE;AAED,wBAAgB,6BAA6B,IAAI,SAAS,mBAAmB,EAAE,CAE9E"}

package/dist/flows/registries/shape-hints/registry.js

@@ -0,0 +1,33 @@
+// Registry of relay shape hints, keyed by output schema name.
+//
+// Hints come from src/flows/catalog.ts via buildSchemaHintMap and
+// buildStructuralHintList. Schema lookup runs first; structural hints
+// are tried in registration order only when the schema lookup misses.
+import { buildSchemaHintMap, buildStructuralHintList } from '../../catalog-derivations.js';
+import { flowPackages } from '../../catalog.js';
+const SCHEMA_HINTS = buildSchemaHintMap(flowPackages);
+const STRUCTURAL_HINTS = buildStructuralHintList(flowPackages);
+export function findRelayShapeHint(step) {
+    const schema = step.writes.report?.schema;
+    if (schema !== undefined) {
+        const bySchema = SCHEMA_HINTS.get(schema);
+        if (bySchema !== undefined)
+            return bySchema;
+    }
+    for (const hint of STRUCTURAL_HINTS) {
+        if (hint.match(step))
+            return hint.instruction;
+    }
+    return undefined;
+}
+export function listRegisteredSchemaHints() {
+    const out = [];
+    for (const [schema, instruction] of SCHEMA_HINTS) {
+        out.push({ kind: 'schema', schema, instruction });
+    }
+    return out;
+}
+export function listRegisteredStructuralHints() {
+    return STRUCTURAL_HINTS;
+}
+//# sourceMappingURL=registry.js.map

package/dist/flows/registries/shape-hints/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/registry.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,sEAAsE;AAEtE,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,MAAM,YAAY,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;AACtD,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,YAAY,CAAC,CAAC;AAE/D,MAAM,UAAU,kBAAkB,CAAC,IAAe;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC1C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAC;IAC9C,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,YAAY,EAAE,CAAC;QACjD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO,gBAAgB,CAAC;AAC1B,CAAC"}

package/dist/flows/registries/shape-hints/types.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeIndexedRelayStep } from '../runtime-index.js';
+export type RelayStep = RuntimeIndexedRelayStep;
+export interface SchemaShapeHint {
+    readonly kind: 'schema';
+    readonly schema: string;
+    readonly instruction: string;
+}
+export interface StructuralShapeHint {
+    readonly kind: 'structural';
+    readonly id: string;
+    match(step: RelayStep): boolean;
+    readonly instruction: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/flows/registries/shape-hints/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/types.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B"}

package/dist/flows/registries/shape-hints/types.js

@@ -0,0 +1,25 @@
+// Shape-hint registry types.
+//
+// A shape hint tells a worker what JSON shape its relay response
+// must produce so the runner can parse + validate the result against
+// the step's typed report schema. Without a hint, workers receive
+// only a generic "respond with a verdict" instruction and produce
+// acknowledgment-style responses that fail schema validation at the
+// step check.
+//
+// Two hint kinds live in the registry:
+//   - 'schema'     — keyed by `step.writes.report.schema`. The
+//                    common case: each per-flow relay step
+//                    that writes a typed report contributes one.
+//   - 'structural' — keyed by a step-shape predicate (role + check).
+//                    For relay steps that emit a structured result
+//                    body but do not register a typed report under
+//                    `writes.report` (e.g. the standalone review
+//                    flow's audit step).
+//
+// To add a new flow's relay shape hint, an author writes:
+//   1. The schema for the report body in src/flows/<wf>/reports.ts
+//   2. A SchemaShapeHint or StructuralShapeHint export in src/flows/<wf>/relay-hints.ts
+//   3. Register it on the package's `relayReports[].relayHint`
+export {};
+//# sourceMappingURL=types.js.map

package/dist/flows/registries/shape-hints/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/flows/registries/shape-hints/types.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,EAAE;AACF,iEAAiE;AACjE,qEAAqE;AACrE,kEAAkE;AAClE,kEAAkE;AAClE,oEAAoE;AACpE,cAAc;AACd,EAAE;AACF,uCAAuC;AACvC,+DAA+D;AAC/D,2DAA2D;AAC3D,iEAAiE;AACjE,qEAAqE;AACrE,mEAAmE;AACnE,mEAAmE;AACnE,iEAAiE;AACjE,yCAAyC;AACzC,EAAE;AACF,0DAA0D;AAC1D,mEAAmE;AACnE,wFAAwF;AACxF,+DAA+D"}

package/dist/flows/registries/verification-writers/registry.d.ts

@@ -0,0 +1,6 @@
+import { type RuntimeIndexedFlow } from '../runtime-index.js';
+import type { VerificationBuilder, VerificationStep } from './types.js';
+export declare function findVerificationWriter(resultSchemaName: string): VerificationBuilder | undefined;
+export declare function listVerificationWriters(): readonly (readonly [string, VerificationBuilder])[];
+export declare function resolveVerificationReadPaths(builder: VerificationBuilder, flow: RuntimeIndexedFlow, step: VerificationStep): Record<string, string>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/flows/registries/verification-writers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/flows/registries/verification-writers/registry.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,kBAAkB,EAAoC,MAAM,qBAAqB,CAAC;AAChG,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAIxE,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAEhG;AAKD,wBAAgB,uBAAuB,IAAI,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAE7F;AASD,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,gBAAgB,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}

package/dist/flows/registries/verification-writers/registry.js

@@ -0,0 +1,37 @@
+// Registry of verification writers, keyed by output schema name.
+//
+// Builders come from src/flows/catalog.ts via buildVerificationRegistry.
+import { buildVerificationRegistry } from '../../catalog-derivations.js';
+import { flowPackages } from '../../catalog.js';
+import { reportPathForSchemaInRuntimeFlow } from '../runtime-index.js';
+const REGISTRY = buildVerificationRegistry(flowPackages);
+export function findVerificationWriter(resultSchemaName) {
+    return REGISTRY.get(resultSchemaName);
+}
+// Every registered verification writer, as [resultSchemaName, builder] pairs. The
+// source-coverage test enumerates this so a newly-added writer cannot slip in
+// without declaring its source reads (or being explicitly marked uncoupled).
+export function listVerificationWriters() {
+    return [...REGISTRY.entries()];
+}
+// Resolve a verification builder's declared reads against a specific runtime flow
+// + step, the same way loadCommands enforces them: each REQUIRED read's report
+// path must be produced by some step AND listed in the verification step's reads,
+// or it throws with the writer's own "requires step '<id>' to read <path>"
+// phrasing. Builders that declare no reads resolve to an empty map (nothing to
+// check). This is the offline mirror the runnability floor uses so a composed
+// verification step whose source is unwired is caught before it runs, not after.
+export function resolveVerificationReadPaths(builder, flow, step) {
+    const paths = {};
+    for (const descriptor of builder.reads ?? []) {
+        if (!descriptor.required)
+            continue;
+        const path = reportPathForSchemaInRuntimeFlow(flow, descriptor.schema);
+        if (!step.reads.includes(path)) {
+            throw new Error(`${builder.resultSchemaName} requires step '${step.id}' to read ${path}`);
+        }
+        paths[descriptor.name] = path;
+    }
+    return paths;
+}
+//# sourceMappingURL=registry.js.map

package/dist/flows/registries/verification-writers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/flows/registries/verification-writers/registry.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,yEAAyE;AAEzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAA2B,gCAAgC,EAAE,MAAM,qBAAqB,CAAC;AAGhG,MAAM,QAAQ,GAAG,yBAAyB,CAAC,YAAY,CAAC,CAAC;AAEzD,MAAM,UAAU,sBAAsB,CAAC,gBAAwB;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACxC,CAAC;AAED,kFAAkF;AAClF,8EAA8E;AAC9E,6EAA6E;AAC7E,MAAM,UAAU,uBAAuB;IACrC,OAAO,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,kFAAkF;AAClF,+EAA+E;AAC/E,kFAAkF;AAClF,2EAA2E;AAC3E,+EAA+E;AAC/E,8EAA8E;AAC9E,iFAAiF;AACjF,MAAM,UAAU,4BAA4B,CAC1C,OAA4B,EAC5B,IAAwB,EACxB,IAAsB;IAEtB,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,UAAU,CAAC,QAAQ;YAAE,SAAS;QACnC,MAAM,IAAI,GAAG,gCAAgC,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAa,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,gBAAgB,mBAAmB,IAAI,CAAC,EAAE,aAAa,IAAI,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/flows/registries/verification-writers/types.d.ts

@@ -0,0 +1,37 @@
+import type { RuntimeIndexedFlow, RuntimeIndexedVerificationStep } from '../runtime-index.js';
+export type VerificationStep = RuntimeIndexedVerificationStep;
+export interface VerificationCommand {
+    readonly id: string;
+    readonly cwd: string;
+    readonly argv: readonly string[];
+    readonly timeout_ms: number;
+    readonly max_output_bytes: number;
+    readonly env: Readonly<Record<string, string>>;
+}
+export interface VerificationCommandObservation {
+    readonly command: VerificationCommand;
+    readonly exit_code: number;
+    readonly status: 'passed' | 'failed';
+    readonly duration_ms: number;
+    readonly stdout_summary: string;
+    readonly stderr_summary: string;
+    readonly timed_out: boolean;
+}
+export interface VerificationBuildContext {
+    readonly runFolder: string;
+    readonly projectRoot?: string;
+    readonly flow: RuntimeIndexedFlow;
+    readonly step: VerificationStep;
+}
+export interface VerificationReadDescriptor {
+    readonly name: string;
+    readonly schema: string;
+    readonly required: boolean;
+}
+export interface VerificationBuilder {
+    readonly resultSchemaName: string;
+    readonly reads?: readonly VerificationReadDescriptor[];
+    loadCommands(context: VerificationBuildContext): readonly VerificationCommand[];
+    buildResult(observations: readonly VerificationCommandObservation[], context: VerificationBuildContext): unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/flows/registries/verification-writers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/flows/registries/verification-writers/types.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAE9F,MAAM,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AAK9D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD;AAMD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAGhC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC;AAUD,MAAM,WAAW,0BAA0B;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAIlC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IASlC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAIvD,YAAY,CAAC,OAAO,EAAE,wBAAwB,GAAG,SAAS,mBAAmB,EAAE,CAAC;IAShF,WAAW,CACT,YAAY,EAAE,SAAS,8BAA8B,EAAE,EACvD,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC;CACZ"}

package/dist/flows/registries/verification-writers/types.js

@@ -0,0 +1,22 @@
+// Verification writer registry types.
+//
+// A verification step has three pieces of flow-specific logic:
+//
+//   1. Where do the commands come from? (Build sources from
+//      build.plan@v1; Fix sources from fix.brief@v1.)
+//   2. What's the output report's shape? (BuildVerification vs.
+//      FixVerification — Fix's wider schema carries timeout/env per
+//      command result.)
+//   3. What's the output schema name?
+//
+// The runner's spawnSync loop, output summarization, and trace_entry-writing
+// stay universal. Each VerificationBuilder fills the flow-specific
+// holes.
+//
+// To add a new flow's verification step:
+//   1. Define the result schema in src/flows/<wf>/reports.ts
+//   2. Implement a VerificationBuilder in
+//      src/flows/<wf>/writers/<schema>.ts
+//   3. Register it on the flow package's `writers.verification`
+export {};
+//# sourceMappingURL=types.js.map

package/dist/flows/registries/verification-writers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/flows/registries/verification-writers/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,+DAA+D;AAC/D,EAAE;AACF,4DAA4D;AAC5D,sDAAsD;AACtD,gEAAgE;AAChE,oEAAoE;AACpE,wBAAwB;AACxB,sCAAsC;AACtC,EAAE;AACF,6EAA6E;AAC7E,mEAAmE;AACnE,SAAS;AACT,EAAE;AACF,yCAAyC;AACzC,6DAA6D;AAC7D,0CAA0C;AAC1C,0CAA0C;AAC1C,gEAAgE"}