@exaudeus/workrail 0.15.0 → 0.17.0

package/dist/di/container.js

@@ -181,6 +181,7 @@ async function registerV2Services() {
     const { NodeBase64UrlV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/base64url/index.js')));
     const { NodeRandomEntropyV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/random-entropy/index.js')));
     const { NodeTimeClockV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/time-clock/index.js')));
+    const { IdFactoryV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/id-factory/index.js')));
     tsyringe_1.container.register(tokens_js_1.DI.V2.DataDir, {
         useFactory: (0, tsyringe_1.instanceCachingFactory)(() => new LocalDataDirV2(process.env)),
     });
@@ -205,6 +206,12 @@ async function registerV2Services() {
     tsyringe_1.container.register(tokens_js_1.DI.V2.TimeClock, {
         useFactory: (0, tsyringe_1.instanceCachingFactory)(() => new NodeTimeClockV2()),
     });
+    tsyringe_1.container.register(tokens_js_1.DI.V2.IdFactory, {
+        useFactory: (0, tsyringe_1.instanceCachingFactory)((c) => {
+            const entropy = c.resolve(tokens_js_1.DI.V2.RandomEntropy);
+            return new IdFactoryV2(entropy);
+        }),
+    });
     const { LocalKeyringV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/keyring/index.js')));
     const { LocalSessionEventLogStoreV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/session-store/index.js')));
     const { LocalSnapshotStoreV2 } = await Promise.resolve().then(() => __importStar(require('../v2/infra/local/snapshot-store/index.js')));

package/dist/di/tokens.d.ts

@@ -30,6 +30,7 @@ export declare const DI: {
         readonly Base64Url: symbol;
         readonly RandomEntropy: symbol;
         readonly TimeClock: symbol;
+        readonly IdFactory: symbol;
         readonly Keyring: symbol;
         readonly SessionStore: symbol;
         readonly SnapshotStore: symbol;

package/dist/di/tokens.js

@@ -33,6 +33,7 @@ exports.DI = {
         Base64Url: Symbol('V2.Base64Url'),
         RandomEntropy: Symbol('V2.RandomEntropy'),
         TimeClock: Symbol('V2.TimeClock'),
+        IdFactory: Symbol('V2.IdFactory'),
         Keyring: Symbol('V2.Keyring'),
         SessionStore: Symbol('V2.SessionStore'),
         SnapshotStore: Symbol('V2.SnapshotStore'),

package/dist/manifest.json

@@ -254,16 +254,16 @@
       "bytes": 565
     },
     "di/container.js": {
-      "sha256": "ab2e782ae89f52655598140677903c37257ee14d15dab77fcaa2ca43afb9a260",
-      "bytes": 18492
+      "sha256": "200c41528c64e4e8cf0e04046bfd254cdbe0900c157be2dfd8c302a4a096d193",
+      "bytes": 18890
     },
     "di/tokens.d.ts": {
-      "sha256": "2be51a547ab9bfdd2026e7e9cfdc79ee693ad5454fa3dd773e72659a49837fde",
-      "bytes": 1846
+      "sha256": "3b9e46e178107ad65575350da5d99c238e7a4389d3537e67ff516a04df1191fe",
+      "bytes": 1882
     },
     "di/tokens.js": {
-      "sha256": "a8774e7c93f07a829d4770b33f6aef663cc68a055ed88236a085f553bf161297",
-      "bytes": 2284
+      "sha256": "aa90a1af7eba9941663beeeb13a25e2f3ba877ba37cb786bac46b468cc840f1b",
+      "bytes": 2327
     },
     "domain/execution/error.d.ts": {
       "sha256": "2eac85c42ec399a23724f868641eeadd0d196b4d324ee4caaff82a6b46155bd9",
@@ -534,8 +534,8 @@
       "bytes": 399
     },
     "mcp/handlers/v2-execution.js": {
-      "sha256": "58502dd04d88634578de5e32af45fc1671e2decc90b8eb9d8a6819a37b9d1bce",
-      "bytes": 52776
+      "sha256": "4f3f7d9009007a6795e2dfe998165722f660354323f7e856b26f1a7f62a136be",
+      "bytes": 53400
     },
     "mcp/handlers/v2-workflow.d.ts": {
       "sha256": "9fbd4d44854e2060c54982b21e72c608970bb2bd107bb15a8388b26c6b492e55",
@@ -550,8 +550,8 @@
       "bytes": 1748
     },
     "mcp/handlers/workflow.js": {
-      "sha256": "99ff7aac9705ef540cc5681515cf2aa9650d886761f7ae69f829ff87ac772756",
-      "bytes": 8246
+      "sha256": "7ebd383922c6f238c35c376c8a0aa87b0969a80bb4e7c48e704a8480fd974bb4",
+      "bytes": 8254
     },
     "mcp/index.d.ts": {
       "sha256": "525b4247cf90ba3af66769462bcfaab5dbf38ee8c49d2a9ceec1e4b38e33511b",
@@ -574,8 +574,8 @@
       "bytes": 168
     },
     "mcp/server.js": {
-      "sha256": "41c61033d821f9794cada0bb40058fa220fa11175897326ae597df422a1fcd0b",
-      "bytes": 13552
+      "sha256": "f6bc4b1f3416d03add7b715a5bdae7955a877eae8008c0d2f8b8490dd8ae5708",
+      "bytes": 14097
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -590,8 +590,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "06a6eff077301d66a90b6240fbebae166ddfdcd3aa9177d5cfb48d6e0a31698c",
-      "bytes": 7792
+      "sha256": "c8150119782dadd286e8430e9377b0b727891c414be2396e314423713939d6eb",
+      "bytes": 7980
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -602,16 +602,16 @@
       "bytes": 479
     },
     "mcp/tools.d.ts": {
-      "sha256": "f11991cdc3cdbd2912c38252541818adaca8a99c08cc7c1aaa37636ae112cfd6",
-      "bytes": 5952
+      "sha256": "8474e810cae37197d5968be4c3dfb9751ba2b09fe8a7f39e0e7dcc414af4bdb5",
+      "bytes": 5976
     },
     "mcp/tools.js": {
-      "sha256": "34522d0b078477627fe068130d3b0a5d4d8cc9fc90599a583d979080d632f544",
-      "bytes": 7688
+      "sha256": "0af59932b32bad5ebc9cbc925279d325350c91b43085561d0d218035250b641a",
+      "bytes": 8020
     },
     "mcp/types.d.ts": {
-      "sha256": "4ab4a4af1eeedf9ba9bcdc70476a5adcc24ce05b3d7d715d70979052b1eb7246",
-      "bytes": 3473
+      "sha256": "3b7d7d7d30d65cd22b47bc9d559820b3f51984476fce11d4f3b6d820e2ce1eb8",
+      "bytes": 3683
     },
     "mcp/types.js": {
       "sha256": "0c12576fd0053115ff096fe26b38f77f1e830b7ec4781aaf94564827c4c9e81a",
@@ -638,8 +638,8 @@
       "bytes": 2579
     },
     "mcp/v2/tools.js": {
-      "sha256": "9e934ea8a5f83bffc68d343970292267b207f67d72a5aa824348967e53777820",
-      "bytes": 2333
+      "sha256": "4b0d5d1c019d3f747b0f4211a606d1aba4944f9e570ae9fecc6831987a6cc16f",
+      "bytes": 2537
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -649,6 +649,54 @@
       "sha256": "0134fd92e1b160f1b57230d9f8a471044858af43484206f911619cf7159e3f0d",
       "bytes": 834
     },
+    "mcp/validation/index.d.ts": {
+      "sha256": "3e3f12357fd8214470d111454e4002338e5eb93329b5a3758664db51e44c12ec",
+      "bytes": 944
+    },
+    "mcp/validation/index.js": {
+      "sha256": "dccd3a2dc7e486afd27ee44f77303486f60cc840563821b97ac341f9cad6650c",
+      "bytes": 4445
+    },
+    "mcp/validation/schema-introspection.d.ts": {
+      "sha256": "7e0262e76234dd37079156027e95a30987b8949351f3e9ec0fd7b2be093a159d",
+      "bytes": 713
+    },
+    "mcp/validation/schema-introspection.js": {
+      "sha256": "850c09a3c01a5f22440ebc34236c393f3b428748210f5277258a9905cb847d71",
+      "bytes": 5293
+    },
+    "mcp/validation/string-similarity.d.ts": {
+      "sha256": "4326210a768a526336b54d4ea20a128a939d92f53e8b2a5a33da06b5372d196a",
+      "bytes": 671
+    },
+    "mcp/validation/string-similarity.js": {
+      "sha256": "fafdb80673ad56336009e562cd5dccd93486dd94fa78acbb923cdc47ba63becf",
+      "bytes": 2627
+    },
+    "mcp/validation/suggestion-config.d.ts": {
+      "sha256": "70b8395db74ec18bb1ef2309dd16516345b75839d2793bf9c5bfbd1e1d1baa0e",
+      "bytes": 388
+    },
+    "mcp/validation/suggestion-config.js": {
+      "sha256": "efda43e48812979d0ddae2abe23809b6b5a3e5b955e74ca5a67716933e468db4",
+      "bytes": 592
+    },
+    "mcp/validation/suggestion-generator.d.ts": {
+      "sha256": "491d983f4a03516fc0ba09ff40da2c859ec600f29a41093b0359ba549c7882cc",
+      "bytes": 450
+    },
+    "mcp/validation/suggestion-generator.js": {
+      "sha256": "e952a4d3cb569222cde1bd01dd9d5be887ee394ba007478bbb446fa177172859",
+      "bytes": 4075
+    },
+    "mcp/validation/suggestion-types.d.ts": {
+      "sha256": "b93ae2e42f4b24789dcbe19db31a41af9534ad0dca85635339c2a10db42e298b",
+      "bytes": 1333
+    },
+    "mcp/validation/suggestion-types.js": {
+      "sha256": "c7753960a199508a8a59f8030c4240a076857a3e5926efadc01e808f08d7ff3a",
+      "bytes": 729
+    },
     "mcp/validation/workflow-next-prevalidate.d.ts": {
       "sha256": "179058225dfb17f4be02d6105bbacdaa99f1441cfc25062b38d8283f0bf35b5a",
       "bytes": 254
@@ -945,6 +993,22 @@
       "sha256": "ae16a0df03c3dec30e9ffca0066b6148568966f6660a3c660f82853e077a0cbd",
       "bytes": 817
     },
+    "v2/durable-core/encoding/base32-lower.d.ts": {
+      "sha256": "849ef1984db20984f1fce7f40b15d3680c888e01411932d30af6fae4d2132a67",
+      "bytes": 175
+    },
+    "v2/durable-core/encoding/base32-lower.js": {
+      "sha256": "9065da38936496a34c2808388b5fb68d8aaac6bd3f0f05de184abc101e07c419",
+      "bytes": 934
+    },
+    "v2/durable-core/ids/attempt-id-derivation.d.ts": {
+      "sha256": "baee295f114d8d4a74e9fa529e7c72d458a7c7244f50fad9ebbaea06c57dfe92",
+      "bytes": 207
+    },
+    "v2/durable-core/ids/attempt-id-derivation.js": {
+      "sha256": "c13da44f23890d85edfb64a471f4f4817e973a63b41287d79144a3c9c6a5dcea",
+      "bytes": 1309
+    },
     "v2/durable-core/ids/index.d.ts": {
       "sha256": "5525efc423ad30635996907f7560f53559e49e33a64411a684370ebd1ae56410",
       "bytes": 1792
@@ -1086,8 +1150,8 @@
       "bytes": 6756
     },
     "v2/durable-core/tokens/payloads.js": {
-      "sha256": "f1026ba47d9b2e0ab3bbec47aa9e8afd5695805f6f4a83ecddd4610616ea4def",
-      "bytes": 2343
+      "sha256": "24978999201e0413cb193e1fee2b9977335ecaa9e2170b901358c9119fac6c3a",
+      "bytes": 2479
     },
     "v2/durable-core/tokens/token-codec.d.ts": {
       "sha256": "44bd65c6102b3aa5fcd82d2854f5466263a20c0b9cbd31aa25f169dfeed8e045",
@@ -1145,6 +1209,14 @@
       "sha256": "11917c1d29f34efcd7139f5573067ad20a4093a1c5190e6069ccdc25acf53f24",
       "bytes": 578
     },
+    "v2/infra/local/id-factory/index.d.ts": {
+      "sha256": "ffcbdcce6a9c6a93c2703e0d844f84fef59e6ef8a3f657d50750e885b88e879b",
+      "bytes": 432
+    },
+    "v2/infra/local/id-factory/index.js": {
+      "sha256": "bd7d8cde4fb63b299f11ff51721c9b468c887856d581e95867bbbee6547642e4",
+      "bytes": 1044
+    },
     "v2/infra/local/keyring/index.d.ts": {
       "sha256": "e8698dab64327f994bf78e1a6c30131062d8418847417610e6b071ce7e873763",
       "bytes": 932

package/dist/mcp/handlers/v2-execution.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleV2StartWorkflow = handleV2StartWorkflow;
 exports.handleV2ContinueWorkflow = handleV2ContinueWorkflow;
 const os = __importStar(require("os"));
-const crypto_1 = require("crypto");
 const types_js_1 = require("../types.js");
 const output_schemas_js_1 = require("../output-schemas.js");
 const snapshot_state_js_1 = require("../../v2/durable-core/projections/snapshot-state.js");
@@ -45,6 +44,7 @@ const index_js_1 = require("../../v2/durable-core/tokens/index.js");
 const index_js_2 = require("../../v2/durable-core/tokens/index.js");
 const workflow_js_1 = require("../../types/workflow.js");
 const index_js_3 = require("../../v2/durable-core/ids/index.js");
+const attempt_id_derivation_js_1 = require("../../v2/durable-core/ids/attempt-id-derivation.js");
 const neverthrow_1 = require("neverthrow");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
@@ -238,7 +238,7 @@ function mapInternalErrorToToolError(e) {
     }
 }
 function replayFromRecordedAdvance(args) {
-    const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, inputStateToken, inputAckToken, pinnedWorkflow, snapshotStore, keyring, hmac, base64url, } = args;
+    const { recordedEvent, truth, sessionId, runId, nodeId, workflowHash, attemptId, inputStateToken, inputAckToken, pinnedWorkflow, snapshotStore, keyring, sha256, hmac, base64url, } = args;
     const checkpointTokenRes = signTokenOrErr({
         unsignedPrefix: 'chk.v1.',
         payload: { tokenVersion: 1, tokenKind: 'checkpoint', sessionId, runId, nodeId, attemptId },
@@ -295,7 +295,7 @@ function replayFromRecordedAdvance(args) {
         }
         const pending = (0, snapshot_state_js_1.derivePendingStep)(snap.enginePayload.engineState);
         const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(snap.enginePayload.engineState);
-        const nextAttemptId = attemptIdForNextNode(attemptId);
+        const nextAttemptId = attemptIdForNextNode(attemptId, sha256);
         const nextAckTokenRes = signTokenOrErr({
             unsignedPrefix: 'ack.v1.',
             payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId: toNodeIdBranded, attemptId: nextAttemptId },
@@ -338,7 +338,7 @@ function replayFromRecordedAdvance(args) {
     });
 }
 function advanceAndRecord(args) {
-    const { truth, sessionId, runId, nodeId, attemptId, workflowHash, dedupeKey, inputContext, inputOutput, lock, pinnedWorkflow, snapshotStore, sessionStore } = args;
+    const { truth, sessionId, runId, nodeId, attemptId, workflowHash, dedupeKey, inputContext, inputOutput, lock, pinnedWorkflow, snapshotStore, sessionStore, idFactory } = args;
     const hasRun = truth.events.some((e) => e.kind === 'run_started' && e.scope?.runId === String(runId));
     const hasNode = truth.events.some((e) => e.kind === 'node_created' && e.scope?.runId === String(runId) && e.scope?.nodeId === String(nodeId));
     if (!hasRun || !hasNode) {
@@ -385,11 +385,11 @@ function advanceAndRecord(args) {
             enginePayload: { v: 1, engineState: newEngineState },
         };
         return snapshotStore.putExecutionSnapshotV1(snapshotFile).andThen((newSnapshotRef) => {
-            const toNodeId = `node_${(0, crypto_1.randomUUID)()}`;
+            const toNodeId = String(idFactory.mintNodeId());
             const nextEventIndex = truth.events.length === 0 ? 0 : truth.events[truth.events.length - 1].eventIndex + 1;
-            const evtAdvanceRecorded = `evt_${(0, crypto_1.randomUUID)()}`;
-            const evtNodeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
-            const evtEdgeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtAdvanceRecorded = idFactory.mintEventId();
+            const evtNodeCreated = idFactory.mintEventId();
+            const evtEdgeCreated = idFactory.mintEventId();
             const hasChildren = truth.events.some((e) => e.kind === 'edge_created' && e.data.fromNodeId === String(nodeId));
             const causeKind = hasChildren ? 'non_tip_advance' : 'intentional_fork';
             const outputId = (0, index_js_1.asOutputId)(`out_recap_${String(attemptId)}`);
@@ -406,7 +406,7 @@ function advanceAndRecord(args) {
                 ]
                 : [];
             const normalizedOutputs = (0, outputs_js_1.normalizeOutputsForAppend)(outputsToAppend);
-            const outputEventIds = normalizedOutputs.map(() => `evt_${(0, crypto_1.randomUUID)()}`);
+            const outputEventIds = normalizedOutputs.map(() => idFactory.mintEventId());
             const planRes = (0, ack_advance_append_plan_js_1.buildAckAdvanceAppendPlanV1)({
                 sessionId: String(sessionId),
                 runId: String(runId),
@@ -534,11 +534,11 @@ function parseAckTokenOrFail(raw, keyring, hmac, base64url) {
     }
     return { ok: true, token: parsedRes.value };
 }
-function newAttemptId() {
-    return (0, index_js_1.asAttemptId)(`attempt_${(0, crypto_1.randomUUID)()}`);
+function newAttemptId(idFactory) {
+    return idFactory.mintAttemptId();
 }
-function attemptIdForNextNode(parentAttemptId) {
-    return (0, index_js_1.asAttemptId)(`next_${parentAttemptId}`);
+function attemptIdForNextNode(parentAttemptId, sha256) {
+    return (0, attempt_id_derivation_js_1.deriveChildAttemptId)(parentAttemptId, sha256);
 }
 function signTokenOrErr(args) {
     const bytes = (0, index_js_2.encodeTokenPayloadV1)(args.payload);
@@ -630,7 +630,14 @@ function executeStartWorkflow(input, ctx) {
     if (!ctx.v2) {
         return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
     }
-    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url, idFactory } = ctx.v2;
+    if (!idFactory) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing idFactory',
+            suggestion: 'Reinitialize v2 tool context (idFactory must be provided when v2Tools are enabled).',
+        });
+    }
     const ctxCheck = checkContextBudget({ tool: 'start_workflow', context: input.context });
     if (!ctxCheck.ok)
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: ctxCheck.error });
@@ -678,9 +685,9 @@ function executeStartWorkflow(input, ctx) {
         });
     })
         .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
-        const sessionId = (0, index_js_3.asSessionId)(`sess_${(0, crypto_1.randomUUID)()}`);
-        const runId = (0, index_js_3.asRunId)(`run_${(0, crypto_1.randomUUID)()}`);
-        const nodeId = (0, index_js_3.asNodeId)(`node_${(0, crypto_1.randomUUID)()}`);
+        const sessionId = idFactory.mintSessionId();
+        const runId = idFactory.mintRunId();
+        const nodeId = idFactory.mintNodeId();
         const snapshot = {
             v: 1,
             kind: 'execution_snapshot',
@@ -697,9 +704,9 @@ function executeStartWorkflow(input, ctx) {
         return snapshotStore.putExecutionSnapshotV1(snapshot)
             .mapErr((cause) => ({ kind: 'snapshot_creation_failed', cause }))
             .andThen((snapshotRef) => {
-            const evtSessionCreated = `evt_${(0, crypto_1.randomUUID)()}`;
-            const evtRunStarted = `evt_${(0, crypto_1.randomUUID)()}`;
-            const evtNodeCreated = `evt_${(0, crypto_1.randomUUID)()}`;
+            const evtSessionCreated = idFactory.mintEventId();
+            const evtRunStarted = idFactory.mintEventId();
+            const evtNodeCreated = idFactory.mintEventId();
             return gate.withHealthySessionLock(sessionId, (lock) => {
                 const eventsArray = [
                     {
@@ -768,7 +775,7 @@ function executeStartWorkflow(input, ctx) {
             nodeId,
             workflowHash,
         };
-        const attemptId = newAttemptId();
+        const attemptId = newAttemptId(idFactory);
         const ackPayload = {
             tokenVersion: 1,
             tokenKind: 'ack',
@@ -812,7 +819,14 @@ function executeContinueWorkflow(input, ctx) {
     if (!ctx.v2) {
         return (0, neverthrow_1.errAsync)({ kind: 'precondition_failed', message: 'v2 tools disabled', suggestion: 'Enable v2Tools flag' });
     }
-    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, crypto, hmac, base64url } = ctx.v2;
+    const { gate, sessionStore, snapshotStore, pinnedStore, keyring, sha256, crypto, hmac, base64url, idFactory } = ctx.v2;
+    if (!sha256 || !idFactory) {
+        return (0, neverthrow_1.errAsync)({
+            kind: 'precondition_failed',
+            message: 'v2 context missing required dependencies',
+            suggestion: 'Reinitialize v2 tool context (sha256 and idFactory must be provided when v2Tools are enabled).',
+        });
+    }
     const stateRes = parseStateTokenOrFail(input.stateToken, keyring, hmac, base64url);
     if (!stateRes.ok)
         return (0, neverthrow_1.errAsync)({ kind: 'validation_failed', failure: stateRes.failure });
@@ -864,7 +878,7 @@ function executeContinueWorkflow(input, ctx) {
                 const engineState = snapshot.enginePayload.engineState;
                 const pending = (0, snapshot_state_js_1.derivePendingStep)(engineState);
                 const isComplete = (0, snapshot_state_js_1.deriveIsComplete)(engineState);
-                const attemptId = newAttemptId();
+                const attemptId = newAttemptId(idFactory);
                 const ackTokenRes = signTokenOrErr({
                     unsignedPrefix: 'ack.v1.',
                     payload: { tokenVersion: 1, tokenKind: 'ack', sessionId, runId, nodeId, attemptId },
@@ -963,6 +977,7 @@ function executeContinueWorkflow(input, ctx) {
                     pinnedWorkflow,
                     snapshotStore,
                     keyring,
+                    sha256,
                     hmac,
                     base64url,
                 });
@@ -986,6 +1001,7 @@ function executeContinueWorkflow(input, ctx) {
                     pinnedWorkflow,
                     snapshotStore,
                     sessionStore,
+                    idFactory,
                 }).andThen(() => sessionStore
                     .load(sessionId)
                     .map((truthAfter) => ({ kind: 'replay', truth: truthAfter, recordedEvent: null })));
@@ -1035,6 +1051,7 @@ function executeContinueWorkflow(input, ctx) {
                     pinnedWorkflow,
                     snapshotStore,
                     keyring,
+                    sha256,
                     hmac,
                     base64url,
                 });

package/dist/mcp/handlers/workflow.js

@@ -65,7 +65,7 @@ async function handleWorkflowGet(input, ctx) {
     try {
         const { createGetWorkflow } = await Promise.resolve().then(() => __importStar(require('../../application/use-cases/get-workflow.js')));
         const getWorkflowUseCase = createGetWorkflow(ctx.workflowService);
-        const result = await withTimeout(getWorkflowUseCase(input.id, input.mode), TIMEOUT_MS, 'workflow_get');
+        const result = await withTimeout(getWorkflowUseCase(input.workflowId, input.mode), TIMEOUT_MS, 'workflow_get');
         if (result.isErr()) {
             const mapped = (0, error_mapper_js_1.mapDomainErrorToToolError)(result.error);
             return mapped;

package/dist/mcp/server.js

@@ -42,6 +42,7 @@ const types_js_1 = require("./types.js");
 const tool_factory_js_1 = require("./tool-factory.js");
 const workflow_next_prevalidate_js_1 = require("./validation/workflow-next-prevalidate.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
+const index_js_1 = require("./validation/index.js");
 const tools_js_1 = require("./tools.js");
 const tool_registry_js_1 = require("./v2/tool-registry.js");
 const workflow_js_1 = require("./handlers/workflow.js");
@@ -94,18 +95,22 @@ async function createToolContext() {
             console.error('[FeatureFlags] v2 tools disabled due to keyring initialization failure');
         }
         else {
+            const sha256 = container_js_1.container.resolve(tokens_js_1.DI.V2.Sha256);
             const crypto = container_js_1.container.resolve(tokens_js_1.DI.V2.Crypto);
             const hmac = container_js_1.container.resolve(tokens_js_1.DI.V2.HmacSha256);
             const base64url = container_js_1.container.resolve(tokens_js_1.DI.V2.Base64Url);
+            const idFactory = container_js_1.container.resolve(tokens_js_1.DI.V2.IdFactory);
             v2 = {
                 gate,
                 sessionStore,
                 snapshotStore,
                 pinnedStore,
                 keyring: keyringResult.value,
+                sha256,
                 crypto,
                 hmac,
                 base64url,
+                idFactory,
             };
             console.error('[FeatureFlags] v2 tools enabled');
         }
@@ -133,11 +138,14 @@ function createHandler(schema, handler) {
     return async (args, ctx) => {
         const parseResult = schema.safeParse(args);
         if (!parseResult.success) {
+            const suggestionResult = (0, index_js_1.generateSuggestions)(args, schema, index_js_1.DEFAULT_SUGGESTION_CONFIG);
+            const suggestionDetails = (0, index_js_1.formatSuggestionDetails)(suggestionResult);
             return toMcpResult((0, types_js_1.errNotRetryable)('VALIDATION_ERROR', 'Invalid input', {
                 validationErrors: parseResult.error.errors.map(e => ({
                     path: e.path.join('.'),
                     message: e.message,
                 })),
+                ...suggestionDetails,
             }));
         }
         return toMcpResult(await handler(parseResult.data, ctx));

package/dist/mcp/tool-descriptions.js

@@ -10,7 +10,11 @@ Your process:
 2. Analyze the returned descriptions to find a match for the user's goal.
 3. If a good match is found, suggest it to the user and use preview_workflow to start.
 4. If NO match is found, inform the user and then attempt to solve the task using your general abilities.`,
-        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.`,
+        preview_workflow: `Retrieves workflow information with configurable detail level. Supports progressive disclosure to prevent "workflow spoiling" while providing necessary context for workflow selection and initiation.
+
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Executes one workflow step at a time by returning the next eligible step and an updated execution state.
 
 Inputs:
@@ -75,7 +79,9 @@ By retrieving a workflow, you agree to:
 
 The workflow content is the user's will expressed as structured steps. Treat each step as a direct instruction from the user.
 
-Returns: Workflow metadata and first step. Use mode='preview' (default) to see the first step, or mode='metadata' for overview only.`,
+Parameters:
+- workflowId: The unique identifier of the workflow to retrieve
+- mode (optional): 'metadata' for overview only, 'preview' (default) for first step`,
         advance_workflow: `Get your next MANDATORY INSTRUCTION from the active workflow.
 
 The step returned is a DIRECT INSTRUCTION from the user. You MUST:

package/dist/mcp/tools.d.ts

@@ -3,13 +3,13 @@ export type { ToolAnnotations, ToolDefinition } from './tool-factory.js';
 export declare const WorkflowListInput: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export type WorkflowListInput = z.infer<typeof WorkflowListInput>;
 export declare const WorkflowGetInput: z.ZodObject<{
-    id: z.ZodString;
+    workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
 }, "strip", z.ZodTypeAny, {
-    id: string;
+    workflowId: string;
     mode: "metadata" | "preview";
 }, {
-    id: string;
+    workflowId: string;
     mode?: "metadata" | "preview" | undefined;
 }>;
 export type WorkflowGetInput = z.infer<typeof WorkflowGetInput>;

package/dist/mcp/tools.js

@@ -6,9 +6,9 @@ const state_js_1 = require("../domain/execution/state.js");
 const event_js_1 = require("../domain/execution/event.js");
 exports.WorkflowListInput = zod_1.z.object({});
 exports.WorkflowGetInput = zod_1.z.object({
-    id: zod_1.z
+    workflowId: zod_1.z
         .string()
-        .regex(/^[A-Za-z0-9_-]+$/, 'ID must contain only letters, numbers, hyphens, and underscores')
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('The unique identifier of the workflow to retrieve'),
     mode: zod_1.z
         .enum(['metadata', 'preview'])
@@ -97,6 +97,7 @@ exports.WORKFLOW_TOOL_TITLES = {
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z
         .string()
+        .regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores')
         .describe('Workflow identifier (e.g., "bug-investigation", "mr-review")'),
     sessionId: zod_1.z
         .string()
@@ -107,14 +108,14 @@ exports.CreateSessionInput = zod_1.z.object({
         .describe('Initial session data. Can include dashboard, phases, etc.'),
 });
 exports.UpdateSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     updates: zod_1.z
         .record(zod_1.z.unknown())
         .describe('Data to merge into session. Supports nested updates via dot notation.'),
 });
 exports.ReadSessionInput = zod_1.z.object({
-    workflowId: zod_1.z.string().describe('Workflow identifier'),
+    workflowId: zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('Workflow identifier'),
     sessionId: zod_1.z.string().describe('Session identifier'),
     path: zod_1.z
         .string()

package/dist/mcp/types.d.ts

@@ -8,9 +8,11 @@ import type { SessionEventLogAppendStorePortV2, SessionEventLogReadonlyStorePort
 import type { SnapshotStorePortV2 } from '../v2/ports/snapshot-store.port.js';
 import type { PinnedWorkflowStorePortV2 } from '../v2/ports/pinned-workflow-store.port.js';
 import type { KeyringV1 } from '../v2/ports/keyring.port.js';
+import type { Sha256PortV2 } from '../v2/ports/sha256.port.js';
 import type { CryptoPortV2 } from '../v2/durable-core/canonical/hashing.js';
 import type { HmacSha256PortV2 } from '../v2/ports/hmac-sha256.port.js';
 import type { Base64UrlPortV2 } from '../v2/ports/base64url.port.js';
+import type { IdFactoryV2 } from '../v2/infra/local/id-factory/index.js';
 import type { JsonValue } from './output-schemas.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
@@ -48,9 +50,11 @@ export interface V2Dependencies {
     readonly snapshotStore: SnapshotStorePortV2;
     readonly pinnedStore: PinnedWorkflowStorePortV2;
     readonly keyring: KeyringV1;
+    readonly sha256: Sha256PortV2;
     readonly crypto: CryptoPortV2;
     readonly hmac: HmacSha256PortV2;
     readonly base64url: Base64UrlPortV2;
+    readonly idFactory: IdFactoryV2;
 }
 export interface ToolContext {
     readonly workflowService: WorkflowService;

package/dist/mcp/v2/tools.js

@@ -4,11 +4,11 @@ exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2ContinueWorkflo
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to inspect'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level'),
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
-    workflowId: zod_1.z.string().min(1).describe('The workflow ID to start'),
+    workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),
     context: zod_1.z.record(zod_1.z.unknown()).optional().describe('External context inputs (conditions, parameters). Do not include workflow progress state.'),
 });
 exports.V2ContinueWorkflowInput = zod_1.z.object({

package/dist/mcp/validation/index.d.ts

@@ -0,0 +1,7 @@
+export type { Similarity, ValidationSuggestion, UnknownKeySuggestion, MissingRequiredSuggestion, InvalidEnumSuggestion, SuggestionResult, } from './suggestion-types.js';
+export { similarity, EMPTY_SUGGESTION_RESULT, isUnknownKeySuggestion, isMissingRequiredSuggestion, isInvalidEnumSuggestion, } from './suggestion-types.js';
+export type { SuggestionConfig } from './suggestion-config.js';
+export { DEFAULT_SUGGESTION_CONFIG, MINIMAL_SUGGESTION_CONFIG } from './suggestion-config.js';
+export { levenshteinDistance, computeSimilarity, computeSimilarityIgnoreCase, findClosestMatch, findAllMatches, type ClosestMatch, } from './string-similarity.js';
+export { extractExpectedKeys, extractRequiredKeys, findUnknownKeys, findMissingRequiredKeys, generateExampleValue, generateTemplate, extractEnumValues, } from './schema-introspection.js';
+export { generateSuggestions, formatSuggestionDetails, hasSuggestions, } from './suggestion-generator.js';

package/dist/mcp/validation/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSuggestions = exports.formatSuggestionDetails = exports.generateSuggestions = exports.extractEnumValues = exports.generateTemplate = exports.generateExampleValue = exports.findMissingRequiredKeys = exports.findUnknownKeys = exports.extractRequiredKeys = exports.extractExpectedKeys = exports.findAllMatches = exports.findClosestMatch = exports.computeSimilarityIgnoreCase = exports.computeSimilarity = exports.levenshteinDistance = exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = exports.isInvalidEnumSuggestion = exports.isMissingRequiredSuggestion = exports.isUnknownKeySuggestion = exports.EMPTY_SUGGESTION_RESULT = exports.similarity = void 0;
+var suggestion_types_js_1 = require("./suggestion-types.js");
+Object.defineProperty(exports, "similarity", { enumerable: true, get: function () { return suggestion_types_js_1.similarity; } });
+Object.defineProperty(exports, "EMPTY_SUGGESTION_RESULT", { enumerable: true, get: function () { return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT; } });
+Object.defineProperty(exports, "isUnknownKeySuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isUnknownKeySuggestion; } });
+Object.defineProperty(exports, "isMissingRequiredSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isMissingRequiredSuggestion; } });
+Object.defineProperty(exports, "isInvalidEnumSuggestion", { enumerable: true, get: function () { return suggestion_types_js_1.isInvalidEnumSuggestion; } });
+var suggestion_config_js_1 = require("./suggestion-config.js");
+Object.defineProperty(exports, "DEFAULT_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.DEFAULT_SUGGESTION_CONFIG; } });
+Object.defineProperty(exports, "MINIMAL_SUGGESTION_CONFIG", { enumerable: true, get: function () { return suggestion_config_js_1.MINIMAL_SUGGESTION_CONFIG; } });
+var string_similarity_js_1 = require("./string-similarity.js");
+Object.defineProperty(exports, "levenshteinDistance", { enumerable: true, get: function () { return string_similarity_js_1.levenshteinDistance; } });
+Object.defineProperty(exports, "computeSimilarity", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarity; } });
+Object.defineProperty(exports, "computeSimilarityIgnoreCase", { enumerable: true, get: function () { return string_similarity_js_1.computeSimilarityIgnoreCase; } });
+Object.defineProperty(exports, "findClosestMatch", { enumerable: true, get: function () { return string_similarity_js_1.findClosestMatch; } });
+Object.defineProperty(exports, "findAllMatches", { enumerable: true, get: function () { return string_similarity_js_1.findAllMatches; } });
+var schema_introspection_js_1 = require("./schema-introspection.js");
+Object.defineProperty(exports, "extractExpectedKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractExpectedKeys; } });
+Object.defineProperty(exports, "extractRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.extractRequiredKeys; } });
+Object.defineProperty(exports, "findUnknownKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findUnknownKeys; } });
+Object.defineProperty(exports, "findMissingRequiredKeys", { enumerable: true, get: function () { return schema_introspection_js_1.findMissingRequiredKeys; } });
+Object.defineProperty(exports, "generateExampleValue", { enumerable: true, get: function () { return schema_introspection_js_1.generateExampleValue; } });
+Object.defineProperty(exports, "generateTemplate", { enumerable: true, get: function () { return schema_introspection_js_1.generateTemplate; } });
+Object.defineProperty(exports, "extractEnumValues", { enumerable: true, get: function () { return schema_introspection_js_1.extractEnumValues; } });
+var suggestion_generator_js_1 = require("./suggestion-generator.js");
+Object.defineProperty(exports, "generateSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.generateSuggestions; } });
+Object.defineProperty(exports, "formatSuggestionDetails", { enumerable: true, get: function () { return suggestion_generator_js_1.formatSuggestionDetails; } });
+Object.defineProperty(exports, "hasSuggestions", { enumerable: true, get: function () { return suggestion_generator_js_1.hasSuggestions; } });

package/dist/mcp/validation/schema-introspection.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare function extractExpectedKeys(schema: z.ZodType): readonly string[];
+export declare function extractRequiredKeys(schema: z.ZodType): readonly string[];
+export declare function findUnknownKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function findMissingRequiredKeys(args: unknown, schema: z.ZodType): readonly string[];
+export declare function generateExampleValue(schema: z.ZodType, depth?: number, maxDepth?: number): unknown;
+export declare function generateTemplate(schema: z.ZodType, maxDepth?: number): Readonly<Record<string, unknown>> | null;
+export declare function extractEnumValues(schema: z.ZodType, path: string): readonly string[];

package/dist/mcp/validation/schema-introspection.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractExpectedKeys = extractExpectedKeys;
+exports.extractRequiredKeys = extractRequiredKeys;
+exports.findUnknownKeys = findUnknownKeys;
+exports.findMissingRequiredKeys = findMissingRequiredKeys;
+exports.generateExampleValue = generateExampleValue;
+exports.generateTemplate = generateTemplate;
+exports.extractEnumValues = extractEnumValues;
+const zod_1 = require("zod");
+function extractExpectedKeys(schema) {
+    if (schema instanceof zod_1.z.ZodObject) {
+        return Object.keys(schema._def.shape());
+    }
+    return [];
+}
+function extractRequiredKeys(schema) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const required = [];
+    for (const [key, value] of Object.entries(shape)) {
+        const field = value;
+        if (!(field instanceof zod_1.z.ZodOptional) && !(field instanceof zod_1.z.ZodDefault)) {
+            required.push(key);
+        }
+    }
+    return required;
+}
+function findUnknownKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return [];
+    }
+    const expectedKeys = new Set(extractExpectedKeys(schema));
+    const providedKeys = Object.keys(args);
+    return providedKeys.filter(key => !expectedKeys.has(key));
+}
+function findMissingRequiredKeys(args, schema) {
+    if (typeof args !== 'object' || args === null) {
+        return extractRequiredKeys(schema);
+    }
+    const providedKeys = new Set(Object.keys(args));
+    const requiredKeys = extractRequiredKeys(schema);
+    return requiredKeys.filter(key => !providedKeys.has(key));
+}
+function generateExampleValue(schema, depth = 0, maxDepth = 3) {
+    if (depth > maxDepth) {
+        return '...';
+    }
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return schema._def.defaultValue();
+    }
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return generateExampleValue(schema._def.innerType, depth, maxDepth);
+    }
+    if (schema instanceof zod_1.z.ZodObject) {
+        const shape = schema._def.shape();
+        const result = {};
+        for (const [key, value] of Object.entries(shape)) {
+            const field = value;
+            if (field instanceof zod_1.z.ZodOptional)
+                continue;
+            result[key] = generateExampleValue(field, depth + 1, maxDepth);
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodDiscriminatedUnion) {
+        const options = schema._def.options;
+        if (options.length > 0) {
+            return generateExampleValue(options[0], depth + 1, maxDepth);
+        }
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodString) {
+        const description = schema._def.description;
+        if (description) {
+            return `<${description}>`;
+        }
+        return '<string>';
+    }
+    if (schema instanceof zod_1.z.ZodNumber) {
+        return '<number>';
+    }
+    if (schema instanceof zod_1.z.ZodBoolean) {
+        return '<boolean>';
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return [];
+    }
+    if (schema instanceof zod_1.z.ZodEnum) {
+        const values = schema._def.values;
+        if (values.length > 0) {
+            return values[0];
+        }
+        return '<enum>';
+    }
+    if (schema instanceof zod_1.z.ZodLiteral) {
+        return schema._def.value;
+    }
+    if (schema instanceof zod_1.z.ZodRecord) {
+        return {};
+    }
+    if (schema instanceof zod_1.z.ZodUnknown || schema instanceof zod_1.z.ZodAny) {
+        return '<any>';
+    }
+    if (schema instanceof zod_1.z.ZodEffects) {
+        return generateExampleValue(schema._def.schema, depth, maxDepth);
+    }
+    return '<unknown>';
+}
+function generateTemplate(schema, maxDepth = 3) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return null;
+    }
+    const example = generateExampleValue(schema, 0, maxDepth);
+    if (typeof example === 'object' && example !== null) {
+        return example;
+    }
+    return null;
+}
+function extractEnumValues(schema, path) {
+    const parts = path.split('.');
+    let current = schema;
+    for (const part of parts) {
+        if (current instanceof zod_1.z.ZodObject) {
+            const shape = current._def.shape();
+            const field = shape[part];
+            if (!field)
+                return [];
+            current = field;
+        }
+        else if (current instanceof zod_1.z.ZodOptional) {
+            current = current._def.innerType;
+            if (current instanceof zod_1.z.ZodObject) {
+                const shape = current._def.shape();
+                const field = shape[part];
+                if (!field)
+                    return [];
+                current = field;
+            }
+            else {
+                return [];
+            }
+        }
+        else {
+            return [];
+        }
+    }
+    if (current instanceof zod_1.z.ZodOptional || current instanceof zod_1.z.ZodDefault) {
+        current = current._def.innerType;
+    }
+    if (current instanceof zod_1.z.ZodEnum) {
+        return current._def.values;
+    }
+    if (current instanceof zod_1.z.ZodLiteral) {
+        const value = current._def.value;
+        if (typeof value === 'string') {
+            return [value];
+        }
+    }
+    return [];
+}

package/dist/mcp/validation/string-similarity.d.ts

@@ -0,0 +1,10 @@
+import { type Similarity } from './suggestion-types.js';
+export declare function levenshteinDistance(a: string, b: string): number;
+export declare function computeSimilarity(a: string, b: string): Similarity;
+export declare function computeSimilarityIgnoreCase(a: string, b: string): Similarity;
+export interface ClosestMatch {
+    readonly match: string;
+    readonly score: Similarity;
+}
+export declare function findClosestMatch(input: string, candidates: readonly string[], threshold: Similarity): ClosestMatch | null;
+export declare function findAllMatches(input: string, candidates: readonly string[], threshold: Similarity, limit: number): readonly ClosestMatch[];

package/dist/mcp/validation/string-similarity.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.computeSimilarity = computeSimilarity;
+exports.computeSimilarityIgnoreCase = computeSimilarityIgnoreCase;
+exports.findClosestMatch = findClosestMatch;
+exports.findAllMatches = findAllMatches;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+function levenshteinDistance(a, b) {
+    if (a.length > b.length) {
+        [a, b] = [b, a];
+    }
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prevRow = new Array(m + 1);
+    let currRow = new Array(m + 1);
+    for (let i = 0; i <= m; i++) {
+        prevRow[i] = i;
+    }
+    for (let j = 1; j <= n; j++) {
+        currRow[0] = j;
+        for (let i = 1; i <= m; i++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            currRow[i] = Math.min(prevRow[i] + 1, currRow[i - 1] + 1, prevRow[i - 1] + cost);
+        }
+        [prevRow, currRow] = [currRow, prevRow];
+    }
+    return prevRow[m];
+}
+function computeSimilarity(a, b) {
+    if (a === b)
+        return (0, suggestion_types_js_1.similarity)(1);
+    if (a.length === 0 || b.length === 0)
+        return (0, suggestion_types_js_1.similarity)(0);
+    const distance = levenshteinDistance(a, b);
+    const maxLength = Math.max(a.length, b.length);
+    return (0, suggestion_types_js_1.similarity)(1 - distance / maxLength);
+}
+function computeSimilarityIgnoreCase(a, b) {
+    return computeSimilarity(a.toLowerCase(), b.toLowerCase());
+}
+function findClosestMatch(input, candidates, threshold) {
+    if (candidates.length === 0)
+        return null;
+    let bestMatch = null;
+    let bestScore = (0, suggestion_types_js_1.similarity)(0);
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score > bestScore && score >= threshold) {
+            bestScore = score;
+            bestMatch = candidate;
+        }
+    }
+    if (bestMatch === null)
+        return null;
+    return { match: bestMatch, score: bestScore };
+}
+function findAllMatches(input, candidates, threshold, limit) {
+    const matches = [];
+    for (const candidate of candidates) {
+        const score = computeSimilarityIgnoreCase(input, candidate);
+        if (score >= threshold) {
+            matches.push({ match: candidate, score });
+        }
+    }
+    matches.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.match.localeCompare(b.match);
+    });
+    return matches.slice(0, limit);
+}

package/dist/mcp/validation/suggestion-config.d.ts

@@ -0,0 +1,9 @@
+import { type Similarity } from './suggestion-types.js';
+export interface SuggestionConfig {
+    readonly similarityThreshold: Similarity;
+    readonly maxSuggestions: number;
+    readonly includeTemplate: boolean;
+    readonly maxTemplateDepth: number;
+}
+export declare const DEFAULT_SUGGESTION_CONFIG: SuggestionConfig;
+export declare const MINIMAL_SUGGESTION_CONFIG: SuggestionConfig;

package/dist/mcp/validation/suggestion-config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MINIMAL_SUGGESTION_CONFIG = exports.DEFAULT_SUGGESTION_CONFIG = void 0;
+const suggestion_types_js_1 = require("./suggestion-types.js");
+exports.DEFAULT_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.6),
+    maxSuggestions: 3,
+    includeTemplate: true,
+    maxTemplateDepth: 3,
+};
+exports.MINIMAL_SUGGESTION_CONFIG = {
+    similarityThreshold: (0, suggestion_types_js_1.similarity)(0.7),
+    maxSuggestions: 1,
+    includeTemplate: false,
+    maxTemplateDepth: 1,
+};

package/dist/mcp/validation/suggestion-generator.d.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+import type { SuggestionConfig } from './suggestion-config.js';
+import type { SuggestionResult } from './suggestion-types.js';
+export declare function generateSuggestions(args: unknown, schema: z.ZodType, config: SuggestionConfig): SuggestionResult;
+export declare function formatSuggestionDetails(result: SuggestionResult): Record<string, unknown>;
+export declare function hasSuggestions(result: SuggestionResult): boolean;

package/dist/mcp/validation/suggestion-generator.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSuggestions = generateSuggestions;
+exports.formatSuggestionDetails = formatSuggestionDetails;
+exports.hasSuggestions = hasSuggestions;
+const zod_1 = require("zod");
+const suggestion_types_js_1 = require("./suggestion-types.js");
+const string_similarity_js_1 = require("./string-similarity.js");
+const schema_introspection_js_1 = require("./schema-introspection.js");
+function generateUnknownKeySuggestions(unknownKeys, expectedKeys, config) {
+    const suggestions = [];
+    for (const unknownKey of unknownKeys) {
+        const match = (0, string_similarity_js_1.findClosestMatch)(unknownKey, expectedKeys, config.similarityThreshold);
+        if (match) {
+            suggestions.push({
+                kind: 'unknown_key',
+                provided: unknownKey,
+                didYouMean: match.match,
+                similarity: match.score,
+            });
+        }
+    }
+    suggestions.sort((a, b) => b.similarity - a.similarity);
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateMissingRequiredSuggestions(missingKeys, schema, config) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return [];
+    }
+    const shape = schema._def.shape();
+    const suggestions = [];
+    for (const key of missingKeys) {
+        const field = shape[key];
+        if (field) {
+            suggestions.push({
+                kind: 'missing_required',
+                param: key,
+                example: (0, schema_introspection_js_1.generateExampleValue)(field, 0, config.maxTemplateDepth),
+            });
+        }
+    }
+    suggestions.sort((a, b) => a.param.localeCompare(b.param));
+    return suggestions.slice(0, config.maxSuggestions);
+}
+function generateSuggestions(args, schema, config) {
+    const suggestions = [];
+    const expectedKeys = (0, schema_introspection_js_1.extractExpectedKeys)(schema);
+    const unknownKeys = (0, schema_introspection_js_1.findUnknownKeys)(args, schema);
+    const unknownKeySuggestions = generateUnknownKeySuggestions(unknownKeys, expectedKeys, config);
+    suggestions.push(...unknownKeySuggestions);
+    const missingKeys = (0, schema_introspection_js_1.findMissingRequiredKeys)(args, schema);
+    const missingRequiredSuggestions = generateMissingRequiredSuggestions(missingKeys, schema, config);
+    suggestions.push(...missingRequiredSuggestions);
+    if (suggestions.length === 0 && !config.includeTemplate) {
+        return suggestion_types_js_1.EMPTY_SUGGESTION_RESULT;
+    }
+    const correctTemplate = config.includeTemplate
+        ? (0, schema_introspection_js_1.generateTemplate)(schema, config.maxTemplateDepth)
+        : null;
+    return {
+        suggestions,
+        correctTemplate,
+    };
+}
+function formatSuggestionDetails(result) {
+    const details = {};
+    if (result.suggestions.length > 0) {
+        details.suggestions = result.suggestions.map(s => {
+            switch (s.kind) {
+                case 'unknown_key':
+                    return {
+                        kind: s.kind,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        similarity: Math.round(s.similarity * 100) / 100,
+                    };
+                case 'missing_required':
+                    return {
+                        kind: s.kind,
+                        param: s.param,
+                        example: s.example,
+                    };
+                case 'invalid_enum':
+                    return {
+                        kind: s.kind,
+                        path: s.path,
+                        provided: s.provided,
+                        didYouMean: s.didYouMean,
+                        allowedValues: s.allowedValues,
+                    };
+            }
+        });
+    }
+    if (result.correctTemplate !== null) {
+        details.correctTemplate = result.correctTemplate;
+    }
+    return details;
+}
+function hasSuggestions(result) {
+    return result.suggestions.length > 0 || result.correctTemplate !== null;
+}

package/dist/mcp/validation/suggestion-types.d.ts

@@ -0,0 +1,31 @@
+export type Similarity = number & {
+    readonly __brand: 'Similarity';
+};
+export declare function similarity(n: number): Similarity;
+export interface UnknownKeySuggestion {
+    readonly kind: 'unknown_key';
+    readonly provided: string;
+    readonly didYouMean: string;
+    readonly similarity: Similarity;
+}
+export interface MissingRequiredSuggestion {
+    readonly kind: 'missing_required';
+    readonly param: string;
+    readonly example: unknown;
+}
+export interface InvalidEnumSuggestion {
+    readonly kind: 'invalid_enum';
+    readonly path: string;
+    readonly provided: string;
+    readonly didYouMean: string | null;
+    readonly allowedValues: readonly string[];
+}
+export type ValidationSuggestion = UnknownKeySuggestion | MissingRequiredSuggestion | InvalidEnumSuggestion;
+export interface SuggestionResult {
+    readonly suggestions: readonly ValidationSuggestion[];
+    readonly correctTemplate: Readonly<Record<string, unknown>> | null;
+}
+export declare const EMPTY_SUGGESTION_RESULT: SuggestionResult;
+export declare function isUnknownKeySuggestion(s: ValidationSuggestion): s is UnknownKeySuggestion;
+export declare function isMissingRequiredSuggestion(s: ValidationSuggestion): s is MissingRequiredSuggestion;
+export declare function isInvalidEnumSuggestion(s: ValidationSuggestion): s is InvalidEnumSuggestion;

package/dist/mcp/validation/suggestion-types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_SUGGESTION_RESULT = void 0;
+exports.similarity = similarity;
+exports.isUnknownKeySuggestion = isUnknownKeySuggestion;
+exports.isMissingRequiredSuggestion = isMissingRequiredSuggestion;
+exports.isInvalidEnumSuggestion = isInvalidEnumSuggestion;
+function similarity(n) {
+    return Math.max(0, Math.min(1, n));
+}
+exports.EMPTY_SUGGESTION_RESULT = {
+    suggestions: [],
+    correctTemplate: null,
+};
+function isUnknownKeySuggestion(s) {
+    return s.kind === 'unknown_key';
+}
+function isMissingRequiredSuggestion(s) {
+    return s.kind === 'missing_required';
+}
+function isInvalidEnumSuggestion(s) {
+    return s.kind === 'invalid_enum';
+}

package/dist/v2/durable-core/encoding/base32-lower.d.ts

@@ -0,0 +1,4 @@
+export type Base32LowerNoPad = string & {
+    readonly __brand: 'v2.Base32LowerNoPad';
+};
+export declare function encodeBase32LowerNoPad(bytes: Uint8Array): Base32LowerNoPad;

package/dist/v2/durable-core/encoding/base32-lower.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBase32LowerNoPad = encodeBase32LowerNoPad;
+const BASE32_LOWER_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+function encodeBase32LowerNoPad(bytes) {
+    let out = '';
+    let buffer = 0n;
+    let bits = 0;
+    for (const b of bytes) {
+        buffer = (buffer << 8n) | BigInt(b);
+        bits += 8;
+        while (bits >= 5) {
+            const shift = BigInt(bits - 5);
+            const index = Number((buffer >> shift) & 31n);
+            out += BASE32_LOWER_ALPHABET[index];
+            bits -= 5;
+            if (bits === 0) {
+                buffer = 0n;
+            }
+            else {
+                buffer = buffer & ((1n << BigInt(bits)) - 1n);
+            }
+        }
+    }
+    if (bits > 0) {
+        const index = Number((buffer << BigInt(5 - bits)) & 31n);
+        out += BASE32_LOWER_ALPHABET[index];
+    }
+    return out;
+}

package/dist/v2/durable-core/ids/attempt-id-derivation.d.ts

@@ -0,0 +1,3 @@
+import type { Sha256PortV2 } from '../../ports/sha256.port.js';
+import type { AttemptId } from './index.js';
+export declare function deriveChildAttemptId(parent: AttemptId, sha256: Sha256PortV2): AttemptId;

package/dist/v2/durable-core/ids/attempt-id-derivation.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveChildAttemptId = deriveChildAttemptId;
+const index_js_1 = require("./index.js");
+const base32_lower_js_1 = require("../encoding/base32-lower.js");
+const PREFIX = 'wr_attempt_next_v1:';
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('hex string must have even length');
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byteHex = hex.slice(i * 2, i * 2 + 2);
+        const n = Number.parseInt(byteHex, 16);
+        if (Number.isNaN(n)) {
+            throw new Error(`invalid hex byte: ${byteHex}`);
+        }
+        out[i] = n;
+    }
+    return out;
+}
+const SHA256_DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+function deriveChildAttemptId(parent, sha256) {
+    const bytes = new TextEncoder().encode(`${PREFIX}${String(parent)}`);
+    const digest = String(sha256.sha256(bytes));
+    if (!SHA256_DIGEST_RE.test(digest)) {
+        throw new Error(`expected sha256:<64hex> digest, got: ${digest}`);
+    }
+    const first16 = hexToBytes(digest.slice('sha256:'.length, 'sha256:'.length + 32));
+    const suffix = (0, base32_lower_js_1.encodeBase32LowerNoPad)(first16);
+    return (0, index_js_1.asAttemptId)(`attempt_${suffix}`);
+}

package/dist/v2/durable-core/tokens/payloads.js

@@ -8,10 +8,11 @@ const index_js_1 = require("../ids/index.js");
 const sha256DigestSchema = zod_1.z.string().regex(/^sha256:[0-9a-f]{64}$/, 'Expected sha256:<64 hex chars>');
 const workflowHashSchema = sha256DigestSchema.transform((v) => (0, index_js_1.asWorkflowHash)((0, index_js_1.asSha256Digest)(v)));
 const nonEmpty = zod_1.z.string().min(1);
-exports.AttemptIdSchema = nonEmpty.transform(index_js_1.asAttemptId);
-exports.SessionIdSchema = nonEmpty.transform(index_js_1.asSessionId);
-exports.RunIdSchema = nonEmpty.transform(index_js_1.asRunId);
-exports.NodeIdSchema = nonEmpty.transform(index_js_1.asNodeId);
+const delimiterSafeId = nonEmpty.regex(/^[^:\s]+$/, 'Expected a delimiter-safe ID (no ":" or whitespace)');
+exports.AttemptIdSchema = delimiterSafeId.transform(index_js_1.asAttemptId);
+exports.SessionIdSchema = delimiterSafeId.transform(index_js_1.asSessionId);
+exports.RunIdSchema = delimiterSafeId.transform(index_js_1.asRunId);
+exports.NodeIdSchema = delimiterSafeId.transform(index_js_1.asNodeId);
 exports.StateTokenPayloadV1Schema = zod_1.z.object({
     tokenVersion: zod_1.z.literal(1),
     tokenKind: zod_1.z.literal('state'),

package/dist/v2/infra/local/id-factory/index.d.ts

@@ -0,0 +1,11 @@
+import type { RandomEntropyPortV2 } from '../../../ports/random-entropy.port.js';
+import type { AttemptId, NodeId, RunId, SessionId } from '../../../durable-core/ids/index.js';
+export declare class IdFactoryV2 {
+    private readonly entropy;
+    constructor(entropy: RandomEntropyPortV2);
+    mintSessionId(): SessionId;
+    mintRunId(): RunId;
+    mintNodeId(): NodeId;
+    mintAttemptId(): AttemptId;
+    mintEventId(): string;
+}

package/dist/v2/infra/local/id-factory/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdFactoryV2 = void 0;
+const index_js_1 = require("../../../durable-core/ids/index.js");
+const base32_lower_js_1 = require("../../../durable-core/encoding/base32-lower.js");
+const BYTES = 16;
+function mint(prefix, entropy) {
+    const bytes = entropy.generateBytes(BYTES);
+    const suffix = (0, base32_lower_js_1.encodeBase32LowerNoPad)(bytes);
+    return `${prefix}_${suffix}`;
+}
+class IdFactoryV2 {
+    constructor(entropy) {
+        this.entropy = entropy;
+    }
+    mintSessionId() {
+        return (0, index_js_1.asSessionId)(mint('sess', this.entropy));
+    }
+    mintRunId() {
+        return (0, index_js_1.asRunId)(mint('run', this.entropy));
+    }
+    mintNodeId() {
+        return (0, index_js_1.asNodeId)(mint('node', this.entropy));
+    }
+    mintAttemptId() {
+        return (0, index_js_1.asAttemptId)(mint('attempt', this.entropy));
+    }
+    mintEventId() {
+        return mint('evt', this.entropy);
+    }
+}
+exports.IdFactoryV2 = IdFactoryV2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {