@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/workflow-compiler-rules.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Graph rules of the authoring-time workflow compiler.
+ * Each rule reports diagnostics; the compiler decides whether an error stops compilation.
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+export type WorkflowDiagnosticCode = 'AUTHORING_INVALID' | 'MISSING_REFERENCE' | 'MISSING_BINDING' | 'HOST_PROFILE_MISMATCH' | 'BINDING_UNAVAILABLE' | 'UNREACHABLE_STEP' | 'UNBOUNDED_LOOP' | 'WHOLE_CAPTURE' | 'ACTIONS_BURIED' | 'HOST_PROFILE_UNDECLARED' | 'APPROVAL_MISSING';
+export type WorkflowCompileDiagnostic = Readonly<{
+    level: 'error' | 'warning';
+    code: WorkflowDiagnosticCode;
+    message: string;
+    step_id?: string;
+    path?: string;
+}>;
+export type DiagnosticSink = (diagnostic: WorkflowCompileDiagnostic) => void;
+/** Route targets that end the step sequence instead of naming a step. */
+export declare const VERDICT_ROUTE_TARGETS: Set<string>;
+export declare function checkWorkflowGraph(definition: WorkflowDefinition, report: DiagnosticSink): void;
+/**
+ * Predicate parameters by kind: a missing required parameter is an error, an unknown one a
+ * warning, and a kind that needs a subject without `target` is an error for json-path-equals and
+ * a warning otherwise, because the subject then is the step's receipt status.
+ */
+export declare function checkPredicateParameters(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-rules.d.ts.map

package/dist/core/workflow-compiler-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-rules.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAKvG,MAAM,MAAM,sBAAsB,GAC9B,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,uBAAuB,GACvB,qBAAqB,GACrB,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,GACf,gBAAgB,GAChB,yBAAyB,GACzB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,yBAAyB,KAAK,IAAI,CAAC;AAE7E,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,aAShC,CAAC;AAoMH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAU/F;AA4BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,cAAc,GACrB,IAAI,CAkCN"}

package/dist/core/workflow-compiler-rules.js

@@ -0,0 +1,284 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Graph rules of the authoring-time workflow compiler.
+ * Each rule reports diagnostics; the compiler decides whether an error stops compilation.
+ */
+import { checkLoopBounds } from './workflow-compiler-loop-rules.js';
+import { checkOptionalSteps } from './workflow-compiler-optional-rules.js';
+import { checkOperatorTexts } from './workflow-compiler-text-rules.js';
+/** Route targets that end the step sequence instead of naming a step. */
+export const VERDICT_ROUTE_TARGETS = new Set([
+    'PASS',
+    'FAIL',
+    'BLOCKED',
+    'CANCELLED',
+    'INCONCLUSIVE',
+    'stop',
+    'pause',
+    'repair',
+]);
+function checkUniqueIds(definition, report) {
+    const stepIds = new Set();
+    for (const step of definition.steps) {
+        if (stepIds.has(step.id)) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                message: `Duplicate workflow step: ${step.id}`,
+            });
+        }
+        stepIds.add(step.id);
+    }
+    const predicateIds = new Set();
+    for (const predicate of definition.predicates) {
+        if (predicateIds.has(predicate.id)) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                message: `Duplicate workflow predicate: ${predicate.id}`,
+            });
+        }
+        predicateIds.add(predicate.id);
+    }
+}
+function checkStepReferences(definition, report) {
+    const stepIds = new Set(definition.steps.map((step) => step.id));
+    const predicateIds = new Set(definition.predicates.map((predicate) => predicate.id));
+    const evidenceIds = new Set(definition.evidence.map((entry) => entry.id));
+    const missing = (step_id, path, message) => report({ level: 'error', code: 'MISSING_REFERENCE', step_id, path, message });
+    for (const step of definition.steps) {
+        for (const dependency of step.depends_on) {
+            if (!stepIds.has(dependency)) {
+                missing(step.id, 'depends_on', `Unknown workflow dependency: ${dependency}`);
+            }
+        }
+        const predicates = [...step.expected_results, ...(step.human?.prevalidate ?? [])];
+        for (const predicate of predicates) {
+            if (!predicateIds.has(predicate)) {
+                missing(step.id, 'expected_results', `Unknown workflow predicate: ${predicate}`);
+            }
+        }
+        for (const evidenceId of [...step.evidence_ids, ...(step.human?.evidence_ids ?? [])]) {
+            if (!evidenceIds.has(evidenceId)) {
+                missing(step.id, 'evidence_ids', `Unknown workflow evidence: ${evidenceId}`);
+            }
+        }
+        if (step.reconciliation_step && !stepIds.has(step.reconciliation_step)) {
+            missing(step.id, 'reconciliation_step', `Unknown reconciliation step: ${step.reconciliation_step}`);
+        }
+        for (const [slot, target] of Object.entries(step.on)) {
+            if (!VERDICT_ROUTE_TARGETS.has(target) && !stepIds.has(target)) {
+                missing(step.id, `on.${slot}`, `Unknown workflow route: ${target}`);
+            }
+        }
+        if (step.retry.requires_idempotency && !step.idempotency_key) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'idempotency_key',
+                message: `Step ${step.id} requires an idempotency key for retry`,
+            });
+        }
+    }
+    for (const [index, route] of definition.error_routes.entries()) {
+        if (!VERDICT_ROUTE_TARGETS.has(route.target) && !stepIds.has(route.target)) {
+            report({
+                level: 'error',
+                code: 'MISSING_REFERENCE',
+                path: `error_routes.${index}.target`,
+                message: `Unknown workflow route: ${route.target}`,
+            });
+        }
+    }
+}
+function checkStepContracts(definition, report) {
+    for (const step of definition.steps) {
+        if ((step.kind === 'tool' || step.kind === 'script') && !step.binding) {
+            report({
+                level: 'error',
+                code: 'MISSING_BINDING',
+                step_id: step.id,
+                message: `Missing concrete binding for step: ${step.id}`,
+            });
+        }
+        if (step.kind === 'human' && !step.human) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                message: `Missing human contract for step: ${step.id}`,
+            });
+        }
+        // BUG-165: the runtime evaluates a predicate step itself and changes nothing. A human step
+        // may declare the effect of what the person does; that drives the approval gate.
+        if (step.kind === 'predicate' && step.side_effect !== 'read-only') {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'side_effect',
+                message: `Predicate step ${step.id} is evaluated by the runtime and changes nothing: declare side_effect "read-only", not "${step.side_effect}"`,
+            });
+        }
+        const options = new Set(step.human?.options ?? []);
+        for (const answer of Object.keys(step.human?.response_mapping ?? {})) {
+            if (!options.has(answer) && answer !== 'freeform') {
+                report({
+                    level: 'error',
+                    code: 'MISSING_REFERENCE',
+                    step_id: step.id,
+                    path: 'human.response_mapping',
+                    message: `Step ${step.id} maps "${answer}", which is not one of its options (or "freeform")`,
+                });
+            }
+        }
+        for (const option of options) {
+            if (step.human && !(option in step.human.response_mapping)) {
+                report({
+                    level: 'error',
+                    code: 'AUTHORING_INVALID',
+                    step_id: step.id,
+                    path: 'human.response_mapping',
+                    message: `Step ${step.id} offers "${option}" without a response_mapping verdict for it`,
+                });
+            }
+        }
+    }
+}
+function checkCycles(definition, report) {
+    const visiting = new Set();
+    const visited = new Set();
+    const byId = new Map(definition.steps.map((step) => [step.id, step]));
+    const visit = (stepId) => {
+        if (visiting.has(stepId)) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: stepId,
+                message: `Cyclic workflow dependency: ${stepId}`,
+            });
+            return false;
+        }
+        if (visited.has(stepId))
+            return true;
+        visiting.add(stepId);
+        for (const dependency of byId.get(stepId)?.depends_on ?? []) {
+            if (!visit(dependency))
+                return false;
+        }
+        visiting.delete(stepId);
+        visited.add(stepId);
+        return true;
+    };
+    for (const step of definition.steps) {
+        if (!visit(step.id))
+            return;
+    }
+}
+/** Steps no route reaches from the first step; cleanup steps run after a verdict and count as reached. */
+function checkReachability(definition, report) {
+    const byId = new Map(definition.steps.map((step) => [step.id, step]));
+    const reached = new Set();
+    const queue = [
+        definition.steps[0]?.id,
+        ...definition.error_routes.map((route) => route.target),
+        ...definition.steps.filter((step) => step.kind === 'cleanup').map((step) => step.id),
+    ];
+    while (queue.length > 0) {
+        const stepId = queue.shift();
+        const step = stepId ? byId.get(stepId) : undefined;
+        if (!step || reached.has(step.id))
+            continue;
+        reached.add(step.id);
+        queue.push(step.on.pass, step.on.fail, step.on.error);
+    }
+    for (const step of definition.steps) {
+        if (!reached.has(step.id)) {
+            report({
+                level: 'warning',
+                code: 'UNREACHABLE_STEP',
+                step_id: step.id,
+                message: `Step ${step.id} is not reached by any route from ${definition.steps[0]?.id}; a run never dispatches it`,
+            });
+        }
+    }
+}
+export function checkWorkflowGraph(definition, report) {
+    checkUniqueIds(definition, report);
+    checkStepReferences(definition, report);
+    checkStepContracts(definition, report);
+    checkCycles(definition, report);
+    checkReachability(definition, report);
+    checkPredicateParameters(definition, report);
+    checkOptionalSteps(definition, report);
+    checkLoopBounds(definition, report);
+    checkOperatorTexts(definition, report);
+}
+/** Parameters each predicate kind reads; `target` selects the subject for every kind. */
+const PREDICATE_PARAMETERS = {
+    equals: { required: ['expected'] },
+    'in-set': { required: ['values'] },
+    'number-compare': { required: ['operator', 'expected'] },
+    'text-normalized-equals': { required: ['expected'] },
+    'text-contains': { required: ['expected'] },
+    'text-regex': { required: ['pattern'], optional: ['flags'] },
+    'json-path-equals': { required: ['path', 'expected'] },
+    'artifact-count': { required: ['expected'] },
+    'schema-valid': { required: ['valid'] },
+    'file-check': { required: ['passed'] },
+    'origin-check': { required: ['passed'] },
+    'digest-check': { required: ['passed'] },
+    'playwright-assertion': { required: ['passed'] },
+};
+const TARGETED_KINDS = new Set([
+    'number-compare',
+    'json-path-equals',
+    'text-regex',
+    'text-contains',
+]);
+/**
+ * Predicate parameters by kind: a missing required parameter is an error, an unknown one a
+ * warning, and a kind that needs a subject without `target` is an error for json-path-equals and
+ * a warning otherwise, because the subject then is the step's receipt status.
+ */
+export function checkPredicateParameters(definition, report) {
+    for (const predicate of definition.predicates) {
+        const spec = PREDICATE_PARAMETERS[predicate.kind];
+        if (!spec)
+            continue;
+        const keys = Object.keys(predicate.parameters);
+        const allowed = ['target', ...spec.required, ...(spec.optional ?? [])];
+        const missing = spec.required.filter((key) => !keys.includes(key));
+        const path = `predicates.${predicate.id}.parameters`;
+        if (missing.length > 0) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                path,
+                message: `Predicate ${predicate.id} (${predicate.kind}) needs parameters ${missing.join(', ')}; it reads ${allowed.join(', ')}`,
+            });
+        }
+        const unknown = keys.filter((key) => !allowed.includes(key));
+        if (unknown.length > 0) {
+            report({
+                level: 'warning',
+                code: 'AUTHORING_INVALID',
+                path,
+                message: `Predicate ${predicate.id} (${predicate.kind}) ignores parameters ${unknown.join(', ')}; it reads ${allowed.join(', ')}`,
+            });
+        }
+        if (TARGETED_KINDS.has(predicate.kind) && typeof predicate.parameters.target !== 'string') {
+            report({
+                level: predicate.kind === 'json-path-equals' ? 'error' : 'warning',
+                code: 'AUTHORING_INVALID',
+                path: `${path}.target`,
+                message: `Predicate ${predicate.id} (${predicate.kind}) has no parameters.target, so it judges the step's receipt status; set target to the value to judge, for example "outputs.<step>.json" or "outputs.<step>.exit_code"`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-rules.js.map

package/dist/core/workflow-compiler-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-compiler-section-rules.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Section rules of the authoring-time workflow compiler (STORY-464). A section groups steps by
+ * place and phase, and its `remote` flag and platform decide whether the guide view runs a
+ * step's command or copies it (DEC-021). A step that names an unknown section is an error;
+ * an empty section and a section whose steps are not contiguous are warnings.
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+import type { DiagnosticSink } from './workflow-compiler-rules.js';
+export declare function checkSections(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-section-rules.d.ts.map

package/dist/core/workflow-compiler-section-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-section-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-section-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,wBAAgB,aAAa,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAgD1F"}

package/dist/core/workflow-compiler-section-rules.js

@@ -0,0 +1,57 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Section rules of the authoring-time workflow compiler (STORY-464). A section groups steps by
+ * place and phase, and its `remote` flag and platform decide whether the guide view runs a
+ * step's command or copies it (DEC-021). A step that names an unknown section is an error;
+ * an empty section and a section whose steps are not contiguous are warnings.
+ */
+export function checkSections(definition, report) {
+    const sections = definition.sections ?? [];
+    const known = new Set();
+    for (const [index, section] of sections.entries()) {
+        if (known.has(section.id)) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                path: `sections.${index}.id`,
+                message: `Duplicate section: ${section.id}`,
+            });
+        }
+        known.add(section.id);
+    }
+    for (const step of definition.steps) {
+        if (step.section !== undefined && !known.has(step.section)) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'section',
+                message: `Step ${step.id} names section ${step.section}, which the definition does not declare`,
+            });
+        }
+    }
+    for (const section of sections) {
+        const positions = definition.steps.flatMap((step, index) => step.section === section.id ? [index] : []);
+        if (positions.length === 0) {
+            report({
+                level: 'warning',
+                code: 'AUTHORING_INVALID',
+                path: 'sections',
+                message: `Section ${section.id} has no steps`,
+            });
+            continue;
+        }
+        const first = positions[0] ?? 0;
+        if (positions.some((position, offset) => position !== first + offset)) {
+            report({
+                level: 'warning',
+                code: 'AUTHORING_INVALID',
+                path: 'sections',
+                message: `The steps of section ${section.id} are not contiguous in authored order; the guide view groups them where they stand`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-section-rules.js.map

package/dist/core/workflow-compiler-section-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-section-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-section-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,UAAU,aAAa,CAAC,UAA8B,EAAE,MAAsB;IAClF,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC;gBACL,KAAK,EAAE,OAAO;gBACd,IAAI,EAAE,mBAAmB;gBACzB,IAAI,EAAE,YAAY,KAAK,KAAK;gBAC5B,OAAO,EAAE,sBAAsB,OAAO,CAAC,EAAE,EAAE;aAC5C,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3D,MAAM,CAAC;gBACL,KAAK,EAAE,OAAO;gBACd,IAAI,EAAE,mBAAmB;gBACzB,OAAO,EAAE,IAAI,CAAC,EAAE;gBAChB,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,QAAQ,IAAI,CAAC,EAAE,kBAAkB,IAAI,CAAC,OAAO,yCAAyC;aAChG,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACzD,IAAI,CAAC,OAAO,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAC3C,CAAC;QACF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC;gBACL,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,mBAAmB;gBACzB,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE,WAAW,OAAO,CAAC,EAAE,eAAe;aAC9C,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,QAAQ,KAAK,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC;YACtE,MAAM,CAAC;gBACL,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,mBAAmB;gBACzB,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE,wBAAwB,OAAO,CAAC,EAAE,oFAAoF;aAChI,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/workflow-compiler-text-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rules for the texts an operator reads (BUG-216). A whole stdout or stderr capture
+ * inserted into an operator's instruction buries the actions under a wall of output, so the
+ * compiler points to `script.extract` and a single value; and an instruction whose numbered
+ * actions start after more than three lines of lead text hides what to do.
+ * @see BUG-216
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+import type { DiagnosticSink } from './workflow-compiler-rules.js';
+/** Lead lines an instruction may carry before its first numbered action. */
+export declare const OPERATOR_LEAD_LINES = 3;
+/** Non-blank lines before the first numbered line outside a fence; undefined without one. */
+export declare function leadLinesBeforeActions(text: string): number | undefined;
+export declare function checkOperatorTexts(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-text-rules.d.ts.map

package/dist/core/workflow-compiler-text-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-text-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-text-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAKnE,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAerC,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAavE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAwC/F"}

package/dist/core/workflow-compiler-text-rules.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rules for the texts an operator reads (BUG-216). A whole stdout or stderr capture
+ * inserted into an operator's instruction buries the actions under a wall of output, so the
+ * compiler points to `script.extract` and a single value; and an instruction whose numbered
+ * actions start after more than three lines of lead text hides what to do.
+ * @see BUG-216
+ */
+import { OPERATOR_HOST_TOOL } from './workflow-host-profiles.js';
+/** Lead lines an instruction may carry before its first numbered action. */
+export const OPERATOR_LEAD_LINES = 3;
+const WHOLE_CAPTURE = /\$\{outputs\.([a-z][a-z0-9_-]*)\.(stdout|stderr)\}/g;
+const NUMBERED = /^\s*\d+[.)]\s+\S/;
+const FENCE = /^\s*(```|~~~)/;
+/** The operator reads the step: a question, a step bound to the operator, or one `who` gives them. */
+function operatorReads(step) {
+    return (step.kind === 'human' ||
+        step.binding?.host_tool_name === OPERATOR_HOST_TOOL ||
+        step.who === 'operator');
+}
+/** Non-blank lines before the first numbered line outside a fence; undefined without one. */
+export function leadLinesBeforeActions(text) {
+    let fenced = false;
+    let lead = 0;
+    for (const line of text.split('\n')) {
+        if (FENCE.test(line)) {
+            fenced = !fenced;
+            lead += 1;
+            continue;
+        }
+        if (!fenced && NUMBERED.test(line))
+            return lead;
+        if (line.trim())
+            lead += 1;
+    }
+    return undefined;
+}
+export function checkOperatorTexts(definition, report) {
+    for (const step of definition.steps) {
+        if (!operatorReads(step))
+            continue;
+        if (step.script?.extract && step.binding?.host_tool_name === OPERATOR_HOST_TOOL) {
+            report({
+                level: 'warning',
+                code: 'WHOLE_CAPTURE',
+                step_id: step.id,
+                path: 'script.extract',
+                message: `Step ${step.id} is reported by the operator, who sends no stdout, so its script.extract reads nothing; declare the extract on the agent step that runs the command`,
+            });
+        }
+        const texts = [
+            ['instruction', step.instruction],
+            ['human.instruction', step.human?.instruction],
+            ['expected_observation', step.expected_observation],
+            ['human.expected_observation', step.human?.expected_observation],
+        ];
+        for (const [path, text] of texts) {
+            for (const [, source, capture] of (text ?? '').matchAll(WHOLE_CAPTURE)) {
+                report({
+                    level: 'warning',
+                    code: 'WHOLE_CAPTURE',
+                    step_id: step.id,
+                    path,
+                    message: `Step ${step.id} inserts the whole ${capture} of step ${source} into a text the operator reads; declare script.extract on ${source} and insert one value with \${outputs.${source}.values.<name>}`,
+                });
+            }
+        }
+        const lead = step.instruction ? leadLinesBeforeActions(step.instruction) : undefined;
+        if (lead !== undefined && lead > OPERATOR_LEAD_LINES) {
+            report({
+                level: 'warning',
+                code: 'ACTIONS_BURIED',
+                step_id: step.id,
+                path: 'instruction',
+                message: `Step ${step.id} has ${lead} lines before its first numbered action; keep at most ${OPERATOR_LEAD_LINES}, so the operator sees what to do first`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-text-rules.js.map

package/dist/core/workflow-compiler-text-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-text-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-text-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-compiler.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring-time workflow compiler.
+ * Resolves exact tool bindings and validates the execution graph before a run starts.
+ */
+import { type WorkflowDefinitionV2 as WorkflowDefinition, type WorkflowHostProfile, type WorkflowHumanTransport } from '../schemas/workflow-definition-v2.js';
+import { type WorkflowCompileDiagnostic, type WorkflowDiagnosticCode } from './workflow-compiler-rules.js';
+import { type HostProfileSource, type ResolvedHostProfile } from './workflow-host-profiles.js';
+export type { WorkflowCompileDiagnostic, WorkflowDiagnosticCode, } from './workflow-compiler-rules.js';
+export type WorkflowCompilerErrorCode = WorkflowDiagnosticCode | 'MANIFEST_INTEGRITY';
+export declare class WorkflowCompilerError extends Error {
+    readonly code: WorkflowCompilerErrorCode;
+    readonly diagnostics: readonly WorkflowCompileDiagnostic[];
+    constructor(code: WorkflowCompilerErrorCode, message: string, diagnostics?: readonly WorkflowCompileDiagnostic[]);
+}
+export type WorkflowExecutionManifest = Readonly<{
+    schema_version: '1.0';
+    definition_schema_version: '2.0';
+    process_type: string;
+    definition_digest: string;
+    manifest_digest: string;
+    compiler_version: string;
+    host_profile: string;
+    /** Where the host profile was found; `undeclared` compiles without a tool list. */
+    host_profile_source?: HostProfileSource | 'undeclared';
+    host_profile_definition?: WorkflowHostProfile | null;
+    definition: WorkflowDefinition;
+    /** Human transport per human step, resolved for the host profile. */
+    human_transports?: Readonly<Record<string, WorkflowHumanTransport>>;
+    /** Authoring warnings; they are not part of either digest. */
+    warnings?: readonly WorkflowCompileDiagnostic[];
+}>;
+export declare function workflowDigest(value: unknown): string;
+export type WorkflowCompileOptions = Readonly<{
+    hostProfile: string;
+    compilerVersion?: string;
+    /** `workflow.host_profiles` of the project config; definition profiles take precedence. */
+    projectHostProfiles?: readonly WorkflowHostProfile[];
+}>;
+export type WorkflowDiagnosis = Readonly<{
+    definition?: WorkflowDefinition;
+    diagnostics: readonly WorkflowCompileDiagnostic[];
+    hostProfile?: ResolvedHostProfile;
+    humanTransports?: Readonly<Record<string, WorkflowHumanTransport>>;
+}>;
+/** Collect every authoring diagnostic for one host profile without throwing. */
+export declare function diagnoseWorkflowDefinitionV2(input: unknown, options: WorkflowCompileOptions): WorkflowDiagnosis;
+export declare function compileWorkflowDefinitionV2(input: unknown, options: WorkflowCompileOptions): WorkflowExecutionManifest;
+export declare function verifyWorkflowExecutionManifest(manifest: WorkflowExecutionManifest, options: WorkflowCompileOptions): void;
+//# sourceMappingURL=workflow-compiler.d.ts.map

package/dist/core/workflow-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,KAAK,oBAAoB,IAAI,kBAAkB,EAE/C,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC5B,MAAM,sCAAsC,CAAC;AAU9C,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAEzB,MAAM,6BAA6B,CAAC;AAErC,YAAY,EACV,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAEtF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAE,yBAAyB,CAAC;IAChD,SAAgB,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAElE,YACE,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,SAAS,yBAAyB,EAAO,EAMvD;CACF;AAED,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,cAAc,EAAE,KAAK,CAAC;IACtB,yBAAyB,EAAE,KAAK,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC;IACvD,uBAAuB,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACrD,UAAU,EAAE,kBAAkB,CAAC;IAC/B,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACpE,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACjD,CAAC,CAAC;AAcH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIrD;AAoBD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,mBAAmB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAClD,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACpE,CAAC,CAAC;AAEH,gFAAgF;AAChF,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,sBAAsB,GAC9B,iBAAiB,CAwCnB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,sBAAsB,GAC9B,yBAAyB,CAgC3B;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,yBAAyB,EACnC,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAYN"}