@exaudeus/workrail 1.0.0 → 1.1.0

package/dist/v2/durable-core/domain/reason-model.d.ts

@@ -0,0 +1,94 @@
+import type { AutonomyV2 } from '../schemas/session/preferences.js';
+import { type Result } from 'neverthrow';
+export type CapabilityV2 = 'delegation' | 'web_browsing';
+export type GapSeverityV1 = 'info' | 'warning' | 'critical';
+export type UserOnlyDependencyReasonV1 = 'needs_user_secret_or_token' | 'needs_user_account_access' | 'needs_user_artifact' | 'needs_user_choice' | 'needs_user_approval' | 'needs_user_environment_action';
+export type GapReasonV1 = {
+    readonly category: 'user_only_dependency';
+    readonly detail: UserOnlyDependencyReasonV1;
+} | {
+    readonly category: 'contract_violation';
+    readonly detail: 'missing_required_output' | 'invalid_required_output';
+} | {
+    readonly category: 'capability_missing';
+    readonly detail: 'required_capability_unavailable' | 'required_capability_unknown';
+} | {
+    readonly category: 'unexpected';
+    readonly detail: 'invariant_violation' | 'storage_corruption_detected';
+};
+export type BlockerCodeV1 = 'USER_ONLY_DEPENDENCY' | 'MISSING_REQUIRED_OUTPUT' | 'INVALID_REQUIRED_OUTPUT' | 'REQUIRED_CAPABILITY_UNKNOWN' | 'REQUIRED_CAPABILITY_UNAVAILABLE' | 'INVARIANT_VIOLATION' | 'STORAGE_CORRUPTION_DETECTED';
+export type BlockerPointerV1 = {
+    readonly kind: 'context_key';
+    readonly key: string;
+} | {
+    readonly kind: 'context_budget';
+} | {
+    readonly kind: 'output_contract';
+    readonly contractRef: string;
+} | {
+    readonly kind: 'capability';
+    readonly capability: CapabilityV2;
+} | {
+    readonly kind: 'workflow_step';
+    readonly stepId: string;
+};
+export type BlockerV1 = {
+    readonly code: BlockerCodeV1;
+    readonly pointer: BlockerPointerV1;
+    readonly message: string;
+    readonly suggestedFix?: string;
+};
+export type BlockerReportV1 = {
+    blockers: BlockerV1[];
+};
+export type ReasonV1 = {
+    readonly kind: 'missing_context_key';
+    readonly key: string;
+} | {
+    readonly kind: 'context_budget_exceeded';
+} | {
+    readonly kind: 'missing_required_output';
+    readonly contractRef: string;
+} | {
+    readonly kind: 'invalid_required_output';
+    readonly contractRef: string;
+} | {
+    readonly kind: 'required_capability_unknown';
+    readonly capability: CapabilityV2;
+} | {
+    readonly kind: 'required_capability_unavailable';
+    readonly capability: CapabilityV2;
+} | {
+    readonly kind: 'user_only_dependency';
+    readonly detail: UserOnlyDependencyReasonV1;
+    readonly stepId: string;
+} | {
+    readonly kind: 'invariant_violation';
+} | {
+    readonly kind: 'storage_corruption_detected';
+};
+export type ReasonModelError = {
+    readonly code: 'INVALID_DELIMITER_SAFE_ID';
+    readonly message: string;
+} | {
+    readonly code: 'INVALID_CONTRACT_REF';
+    readonly message: string;
+} | {
+    readonly code: 'BLOCKER_MESSAGE_TOO_LARGE';
+    readonly message: string;
+} | {
+    readonly code: 'BLOCKER_SUGGESTED_FIX_TOO_LARGE';
+    readonly message: string;
+} | {
+    readonly code: 'INVARIANT_VIOLATION';
+    readonly message: string;
+};
+export declare function reasonToGap(reason: ReasonV1): {
+    readonly severity: GapSeverityV1;
+    readonly reason: GapReasonV1;
+    readonly summary: string;
+};
+export declare function blockerSortKey(b: BlockerV1): string;
+export declare function reasonToBlocker(reason: ReasonV1): Result<BlockerV1, ReasonModelError>;
+export declare function buildBlockerReport(reasons: readonly ReasonV1[]): Result<BlockerReportV1, ReasonModelError>;
+export declare function shouldBlock(autonomy: AutonomyV2, reasons: readonly ReasonV1[]): boolean;

package/dist/v2/durable-core/domain/reason-model.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reasonToGap = reasonToGap;
+exports.blockerSortKey = blockerSortKey;
+exports.reasonToBlocker = reasonToBlocker;
+exports.buildBlockerReport = buildBlockerReport;
+exports.shouldBlock = shouldBlock;
+const constants_js_1 = require("../constants.js");
+const neverthrow_1 = require("neverthrow");
+function utf8ByteLength(s) {
+    return new TextEncoder().encode(s).length;
+}
+function ensureDelimiterSafeId(label, value) {
+    if (!constants_js_1.DELIMITER_SAFE_ID_PATTERN.test(value)) {
+        return (0, neverthrow_1.err)({
+            code: 'INVALID_DELIMITER_SAFE_ID',
+            message: `${label} must be delimiter-safe: [a-z0-9_-]+`,
+        });
+    }
+    return (0, neverthrow_1.ok)(value);
+}
+function ensureContractRef(contractRef) {
+    if (contractRef.trim().length === 0) {
+        return (0, neverthrow_1.err)({ code: 'INVALID_CONTRACT_REF', message: 'contractRef must be non-empty' });
+    }
+    return (0, neverthrow_1.ok)(contractRef);
+}
+function ensureBlockerTextBudgets(blocker) {
+    if (utf8ByteLength(blocker.message) > constants_js_1.MAX_BLOCKER_MESSAGE_BYTES) {
+        return (0, neverthrow_1.err)({
+            code: 'BLOCKER_MESSAGE_TOO_LARGE',
+            message: `blocker.message exceeds ${constants_js_1.MAX_BLOCKER_MESSAGE_BYTES} UTF-8 bytes`,
+        });
+    }
+    if (blocker.suggestedFix && utf8ByteLength(blocker.suggestedFix) > constants_js_1.MAX_BLOCKER_SUGGESTED_FIX_BYTES) {
+        return (0, neverthrow_1.err)({
+            code: 'BLOCKER_SUGGESTED_FIX_TOO_LARGE',
+            message: `blocker.suggestedFix exceeds ${constants_js_1.MAX_BLOCKER_SUGGESTED_FIX_BYTES} UTF-8 bytes`,
+        });
+    }
+    return (0, neverthrow_1.ok)(blocker);
+}
+function reasonToGap(reason) {
+    switch (reason.kind) {
+        case 'user_only_dependency':
+            return {
+                severity: 'critical',
+                reason: { category: 'user_only_dependency', detail: reason.detail },
+                summary: `User-only dependency: ${reason.detail} (stepId=${reason.stepId})`,
+            };
+        case 'missing_required_output':
+            return {
+                severity: 'critical',
+                reason: { category: 'contract_violation', detail: 'missing_required_output' },
+                summary: `Missing required output for contractRef=${reason.contractRef}`,
+            };
+        case 'invalid_required_output':
+            return {
+                severity: 'critical',
+                reason: { category: 'contract_violation', detail: 'invalid_required_output' },
+                summary: `Invalid required output for contractRef=${reason.contractRef}`,
+            };
+        case 'required_capability_unknown':
+            return {
+                severity: 'critical',
+                reason: { category: 'capability_missing', detail: 'required_capability_unknown' },
+                summary: `Required capability status unknown: ${reason.capability}`,
+            };
+        case 'required_capability_unavailable':
+            return {
+                severity: 'critical',
+                reason: { category: 'capability_missing', detail: 'required_capability_unavailable' },
+                summary: `Required capability unavailable: ${reason.capability}`,
+            };
+        case 'storage_corruption_detected':
+            return {
+                severity: 'critical',
+                reason: { category: 'unexpected', detail: 'storage_corruption_detected' },
+                summary: 'Storage corruption detected',
+            };
+        case 'missing_context_key':
+            return {
+                severity: 'critical',
+                reason: { category: 'unexpected', detail: 'invariant_violation' },
+                summary: `Missing required context key: ${reason.key}`,
+            };
+        case 'context_budget_exceeded':
+            return {
+                severity: 'critical',
+                reason: { category: 'unexpected', detail: 'invariant_violation' },
+                summary: 'Context budget exceeded',
+            };
+        case 'invariant_violation':
+            return {
+                severity: 'critical',
+                reason: { category: 'unexpected', detail: 'invariant_violation' },
+                summary: 'Invariant violation',
+            };
+        default: {
+            const _exhaustive = reason;
+            return _exhaustive;
+        }
+    }
+}
+function blockerSortKey(b) {
+    const p = b.pointer;
+    let ptrStable;
+    switch (p.kind) {
+        case 'context_key':
+            ptrStable = p.key;
+            break;
+        case 'output_contract':
+            ptrStable = p.contractRef;
+            break;
+        case 'capability':
+            ptrStable = p.capability;
+            break;
+        case 'workflow_step':
+            ptrStable = p.stepId;
+            break;
+        case 'context_budget':
+            ptrStable = '';
+            break;
+        default: {
+            const _exhaustive = p;
+            ptrStable = _exhaustive;
+        }
+    }
+    return `${b.code}|${p.kind}|${ptrStable}`;
+}
+function reasonToBlocker(reason) {
+    switch (reason.kind) {
+        case 'missing_context_key':
+            return ensureDelimiterSafeId('context_key.key', reason.key)
+                .map((key) => ({
+                code: 'INVARIANT_VIOLATION',
+                pointer: { kind: 'context_key', key },
+                message: `Missing required context key: ${key}`,
+                suggestedFix: `Include context.${key} (delimiter-safe key) in the next continue_workflow call.`,
+            }))
+                .andThen(ensureBlockerTextBudgets);
+        case 'context_budget_exceeded':
+            return ensureBlockerTextBudgets({
+                code: 'INVARIANT_VIOLATION',
+                pointer: { kind: 'context_budget' },
+                message: 'Context exceeded the allowed budget or was non-serializable.',
+                suggestedFix: 'Remove large blobs from context and pass only small external inputs (IDs, paths, parameters).',
+            });
+        case 'missing_required_output':
+            return ensureContractRef(reason.contractRef)
+                .map((contractRef) => ({
+                code: 'MISSING_REQUIRED_OUTPUT',
+                pointer: { kind: 'output_contract', contractRef },
+                message: `Missing required output (contractRef=${contractRef}).`,
+                suggestedFix: 'Provide output.notesMarkdown that satisfies the step output requirements.',
+            }))
+                .andThen(ensureBlockerTextBudgets);
+        case 'invalid_required_output':
+            return ensureContractRef(reason.contractRef)
+                .map((contractRef) => ({
+                code: 'INVALID_REQUIRED_OUTPUT',
+                pointer: { kind: 'output_contract', contractRef },
+                message: `Invalid output for contractRef=${contractRef}.`,
+                suggestedFix: 'Adjust output.notesMarkdown to satisfy validation and retry continue_workflow with the same ackToken.',
+            }))
+                .andThen(ensureBlockerTextBudgets);
+        case 'required_capability_unknown':
+            return ensureBlockerTextBudgets({
+                code: 'REQUIRED_CAPABILITY_UNKNOWN',
+                pointer: { kind: 'capability', capability: reason.capability },
+                message: `Required capability status is unknown: ${reason.capability}.`,
+                suggestedFix: 'Probe the capability (or run the required tool) and retry.',
+            });
+        case 'required_capability_unavailable':
+            return ensureBlockerTextBudgets({
+                code: 'REQUIRED_CAPABILITY_UNAVAILABLE',
+                pointer: { kind: 'capability', capability: reason.capability },
+                message: `Required capability is unavailable: ${reason.capability}.`,
+                suggestedFix: 'Enable the capability or choose an alternate approach that does not require it.',
+            });
+        case 'user_only_dependency':
+            return ensureDelimiterSafeId('workflow_step.stepId', reason.stepId)
+                .map((stepId) => ({
+                code: 'USER_ONLY_DEPENDENCY',
+                pointer: { kind: 'workflow_step', stepId },
+                message: `Step requires user input: ${reason.detail}.`,
+                suggestedFix: 'Ask the user for the required input/approval and retry.',
+            }))
+                .andThen(ensureBlockerTextBudgets);
+        case 'invariant_violation':
+            return ensureBlockerTextBudgets({
+                code: 'INVARIANT_VIOLATION',
+                pointer: { kind: 'context_budget' },
+                message: 'Invariant violation: execution cannot safely proceed.',
+                suggestedFix: 'Inspect the durable event log and pinned workflow snapshot for mismatches.',
+            });
+        case 'storage_corruption_detected':
+            return ensureBlockerTextBudgets({
+                code: 'STORAGE_CORRUPTION_DETECTED',
+                pointer: { kind: 'context_budget' },
+                message: 'Storage corruption detected: durable session data failed validation.',
+                suggestedFix: 'Stop and investigate the session store; do not continue advancing this session.',
+            });
+        default: {
+            const _exhaustive = reason;
+            return _exhaustive;
+        }
+    }
+}
+function buildBlockerReport(reasons) {
+    if (reasons.length === 0) {
+        return (0, neverthrow_1.err)({ code: 'INVARIANT_VIOLATION', message: 'buildBlockerReport requires at least one reason' });
+    }
+    const blockers = [];
+    for (const reason of reasons) {
+        const b = reasonToBlocker(reason);
+        if (b.isErr())
+            return (0, neverthrow_1.err)(b.error);
+        blockers.push(b.value);
+    }
+    blockers.sort((a, b) => blockerSortKey(a).localeCompare(blockerSortKey(b)));
+    return (0, neverthrow_1.ok)({ blockers: blockers.slice(0, constants_js_1.MAX_BLOCKERS) });
+}
+function shouldBlock(autonomy, reasons) {
+    if (reasons.length === 0)
+        return false;
+    return autonomy !== 'full_auto_never_stop';
+}

package/dist/v2/durable-core/domain/recap-recovery.d.ts

@@ -0,0 +1,24 @@
+import type { Result } from 'neverthrow';
+import type { RunDagRunV2 } from '../../../v2/projections/run-dag.js';
+import type { NodeOutputsProjectionV2 } from '../../../v2/projections/node-outputs.js';
+import type { NodeId } from '../ids/index.js';
+export type RecapRecoveryError = {
+    readonly code: 'RECAP_RECOVERY_FAILED';
+    readonly message: string;
+};
+export declare function collectAncestryRecap(args: {
+    readonly nodeId: NodeId;
+    readonly dag: RunDagRunV2;
+    readonly outputs: NodeOutputsProjectionV2;
+    readonly includeCurrentNode: boolean;
+}): Result<readonly string[], RecapRecoveryError>;
+export declare function collectDownstreamRecap(args: {
+    readonly fromNodeId: NodeId;
+    readonly toNodeId: NodeId;
+    readonly dag: RunDagRunV2;
+    readonly outputs: NodeOutputsProjectionV2;
+}): Result<readonly string[], RecapRecoveryError>;
+export declare function buildChildSummary(args: {
+    readonly nodeId: NodeId;
+    readonly dag: RunDagRunV2;
+}): string;

package/dist/v2/durable-core/domain/recap-recovery.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectAncestryRecap = collectAncestryRecap;
+exports.collectDownstreamRecap = collectDownstreamRecap;
+exports.buildChildSummary = buildChildSummary;
+const neverthrow_1 = require("neverthrow");
+function collectAncestryRecap(args) {
+    const buildChain = (cur, visited) => {
+        if (!cur || visited.has(cur))
+            return [];
+        const nodeData = args.dag.nodesById[cur];
+        const parent = nodeData?.parentNodeId ?? null;
+        const newVisited = new Set([...visited, cur]);
+        return [cur, ...buildChain(parent, newVisited)];
+    };
+    const startNode = args.includeCurrentNode
+        ? String(args.nodeId)
+        : args.dag.nodesById[String(args.nodeId)]?.parentNodeId ?? null;
+    const chain = buildChain(startNode, new Set());
+    const recaps = chain.flatMap((nodeId) => {
+        const nodeOutputs = args.outputs.nodesById[nodeId];
+        if (!nodeOutputs)
+            return [];
+        return nodeOutputs.currentByChannel.recap
+            .filter(r => r.payload.payloadKind === 'notes')
+            .map(r => {
+            if (r.payload.payloadKind === 'notes') {
+                return r.payload.notesMarkdown;
+            }
+            return '';
+        })
+            .filter(s => s.length > 0);
+    });
+    return (0, neverthrow_1.ok)([...recaps].reverse());
+}
+function collectDownstreamRecap(args) {
+    const buildPathBackward = (cur, visited) => {
+        if (!cur || cur === String(args.fromNodeId) || visited.has(cur))
+            return [];
+        const nodeData = args.dag.nodesById[cur];
+        const parent = nodeData?.parentNodeId ?? null;
+        const newVisited = new Set([...visited, cur]);
+        return [cur, ...buildPathBackward(parent, newVisited)];
+    };
+    const pathBackward = buildPathBackward(String(args.toNodeId), new Set());
+    const recaps = [...pathBackward].reverse().flatMap((nodeId) => {
+        const nodeOutputs = args.outputs.nodesById[nodeId];
+        if (!nodeOutputs)
+            return [];
+        return nodeOutputs.currentByChannel.recap
+            .filter(r => r.payload.payloadKind === 'notes')
+            .map(r => {
+            if (r.payload.payloadKind === 'notes') {
+                return r.payload.notesMarkdown;
+            }
+            return '';
+        })
+            .filter(s => s.length > 0);
+    });
+    return (0, neverthrow_1.ok)(recaps);
+}
+function buildChildSummary(args) {
+    const children = args.dag.edges.filter((e) => e.fromNodeId === args.nodeId);
+    const count = children.length;
+    if (count === 0)
+        return '';
+    if (count === 1) {
+        return `This node has 1 child. Preferred branch tip: ${args.dag.preferredTipNodeId ?? 'unknown'}`;
+    }
+    return `This node has ${count} children. Preferred branch tip: ${args.dag.preferredTipNodeId ?? 'unknown'}`;
+}

package/dist/v2/durable-core/domain/validation-criteria-validator.d.ts

@@ -0,0 +1,8 @@
+import type { ValidationCriteria, ValidationResult } from '../../../types/validation.js';
+import type { OutputRequirementStatus } from './blocking-decision.js';
+export declare const VALIDATION_CRITERIA_CONTRACT_REF: "wr.validationCriteria";
+export declare function getOutputRequirementStatusV1(args: {
+    readonly validationCriteria: ValidationCriteria | undefined;
+    readonly notesMarkdown: string | undefined;
+    readonly validation: ValidationResult | undefined;
+}): OutputRequirementStatus;

package/dist/v2/durable-core/domain/validation-criteria-validator.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALIDATION_CRITERIA_CONTRACT_REF = void 0;
+exports.getOutputRequirementStatusV1 = getOutputRequirementStatusV1;
+exports.VALIDATION_CRITERIA_CONTRACT_REF = 'wr.validationCriteria';
+function getOutputRequirementStatusV1(args) {
+    if (!args.validationCriteria)
+        return { kind: 'not_required' };
+    if (!args.notesMarkdown) {
+        return { kind: 'missing', contractRef: exports.VALIDATION_CRITERIA_CONTRACT_REF };
+    }
+    if (args.validation && !args.validation.valid) {
+        return { kind: 'invalid', contractRef: exports.VALIDATION_CRITERIA_CONTRACT_REF, validation: args.validation };
+    }
+    return { kind: 'not_required' };
+}

package/dist/v2/durable-core/domain/validation-requirements-extractor.d.ts

@@ -0,0 +1,2 @@
+import type { ValidationCriteria } from '../../../types/validation.js';
+export declare function extractValidationRequirements(criteria: ValidationCriteria | undefined): readonly string[];

package/dist/v2/durable-core/domain/validation-requirements-extractor.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractValidationRequirements = extractValidationRequirements;
+const validation_js_1 = require("../../../types/validation.js");
+function extractValidationRequirements(criteria) {
+    if (!criteria)
+        return [];
+    try {
+        const requirements = extractRequirementsRecursive(criteria);
+        return requirements.slice(0, 5);
+    }
+    catch {
+        return [];
+    }
+}
+function extractRequirementsRecursive(criteria) {
+    const requirements = [];
+    if ((0, validation_js_1.isValidationRule)(criteria)) {
+        const formatted = formatRule(criteria);
+        if (formatted)
+            requirements.push(formatted);
+        return requirements;
+    }
+    if ((0, validation_js_1.isValidationComposition)(criteria)) {
+        if (criteria.and) {
+            for (const sub of criteria.and) {
+                requirements.push(...extractRequirementsRecursive(sub));
+            }
+        }
+    }
+    return requirements;
+}
+function formatRule(rule) {
+    switch (rule.type) {
+        case 'contains':
+            if (!rule.value)
+                return null;
+            return `Must contain: "${rule.value}"`;
+        case 'regex':
+            if (!rule.pattern)
+                return null;
+            const flags = rule.flags ? ` (flags: ${rule.flags})` : '';
+            return `Must match pattern: ${rule.pattern}${flags}`;
+        case 'length':
+            const parts = [];
+            if (rule.min !== undefined)
+                parts.push(`≥${rule.min} chars`);
+            if (rule.max !== undefined)
+                parts.push(`≤${rule.max} chars`);
+            if (parts.length === 0)
+                return null;
+            return `Length: ${parts.join(', ')}`;
+        case 'schema':
+            return null;
+        default:
+            return null;
+    }
+}