@sensigo/realm 0.41.0 → 0.43.0

package/dist/types/workflow-definition.js

@@ -1,3 +1,228 @@
+// issue #508 (final correction): a `types/ -> workflow/` edge, added for `buildTrustRefusal`
+// below — audit-verified to create no cycle (`diagnostics.ts` imports only from its own
+// directory's `source-positions.ts`, which imports only `js-yaml`'s types; neither imports
+// anything from this file).
+import { closestKey } from '../workflow/diagnostics.js';
+/**
+ * Every value `TrustLevel` declares — the step-level vocabulary. Single-sourced (issue #508):
+ * before this, the two-literal gate test (`=== 'human_confirmed' || === 'human_reviewed'`) was
+ * copied by hand at FOUR call sites (the engine's gate mint, the protocol generator ×2, the
+ * loader's gate-choices check), and NO site validated the value at all — `human_confrimed`,
+ * `Human_Confirmed`, `engine_delivered`, `""`, `123`, `null` all loaded clean and ran with no
+ * gate. See `classifyStepTrust`/`isGateTrust` below, and `docs/reference/yaml-schema.md`'s
+ * `## Trust levels` section for the authoring contract.
+ *
+ * **`as const satisfies readonly TrustLevel[]` is NORMATIVE, not stylistic.** An explicit
+ * `readonly TrustLevel[]` type annotation WIDENS the array's member type to the full `TrustLevel`
+ * union regardless of which literals are actually listed — under that annotation, the
+ * `Exclude<>`-based drift guards below type-check even with members missing, shipping dead.
+ * `as const` preserves the literal tuple type the guards need to see a real difference. This is
+ * the house pattern (`KNOWN_STEP_KEYS`/`KNOWN_RETRY_KEYS` above), and verified here by actually
+ * deleting a member and confirming a real compile error results (not merely asserted).
+ */
+export const TRUST_LEVELS = [
+    'auto',
+    'human_confirmed',
+    'human_reviewed',
+];
+/** The subset of `TRUST_LEVELS` that actually opens a human gate — `'auto'` is the sole
+ *  non-gating member of `TrustLevel`. Kept as its OWN array (not derived by filtering
+ *  `TRUST_LEVELS` at the type level) so a single hardcoded `TRUST_LEVELS` collapse at the mint
+ *  can never silently widen who gets gated — see `classifyStepTrust`'s arm-order comment for why
+ *  the drift this guards against is a real, previously-considered mutant shape. */
+export const GATE_TRUST_LEVELS = [
+    'human_confirmed',
+    'human_reviewed',
+];
+/** Every value `ServiceTrust` declares — the `services: <name>: trust:` vocabulary. A DIFFERENT
+ *  key from a step's own `trust:` (the dominant real-world confusion this PR's L1 refusal names
+ *  directly — six of realm's nine shipped examples carried a `ServiceTrust` literal on a step).
+ *  Minted here, single-sourced, so the loader's own Ajv enum (`yaml-loader.ts`) and this PR's
+ *  service-trust-confusion refusal can never drift apart into a THIRD hardcoded copy. */
+export const SERVICE_TRUST_LEVELS = [
+    'engine_delivered',
+    'engine_managed',
+    'agent_provided',
+];
+const _trustLevelsMissingCheck = true;
+const _trustLevelsExtraCheck = true;
+const _gateTrustSubsetCheck = true;
+const _serviceTrustLevelsMissingCheck = true;
+const _serviceTrustLevelsExtraCheck = true;
+/**
+ * Classifies a step's declared `trust` value against its execution kind. `kind` is
+ * `ExecutionMode | undefined` because one real call site (`yaml-loader.ts`'s per-step walk) sees
+ * this before `execution` has been validated — a step with `execution: bogus` (or a missing
+ * `execution` at all) reaches trust classification before the malformed-kind error is the whole
+ * verdict, and `undefined` here must classify as harmlessly as an absent trust value: covered by
+ * the FIRST arm below.
+ *
+ * **Arm order is normative** (issue #508 design review, mutant (iii)): `GATE_TRUST_LEVELS`
+ * membership is tested BEFORE the `'auto'` shortcut on auto/agent. With the shortcut checked
+ * first, collapsing `GATE_TRUST_LEVELS` into `TRUST_LEVELS` (a plausible single-sourcing
+ * shortcut) would change NOTHING observable — 'auto' is caught by its own branch either way,
+ * and `TRUST_LEVELS` membership alone can never distinguish 'human_confirmed' from 'auto' when
+ * the shortcut already resolved it — making that mutation a GUARANTEED EQUIVALENT MUTANT rather
+ * than a real regression test. Testing `GATE_TRUST_LEVELS` first means the collapse is
+ * observable: `classifyStepTrust('auto', 'auto')` would flip from `'lawful_no_gate'` to
+ * `'gates'`, since `TRUST_LEVELS` (unlike `GATE_TRUST_LEVELS`) contains `'auto'`.
+ */
+export function classifyStepTrust(kind, value) {
+    if (value === undefined)
+        return 'lawful_no_gate';
+    if (kind === 'auto' || kind === 'agent') {
+        if (GATE_TRUST_LEVELS.includes(value))
+            return 'gates';
+        if (value === 'auto')
+            return 'lawful_no_gate';
+        return 'refuse';
+    }
+    if (kind === 'finalizer') {
+        return value === 'auto' ? 'lawful_no_gate' : 'refuse';
+    }
+    // guard, and any kind outside the four (undefined, or a value the loader would itself refuse
+    // as an invalid `execution`) — trust is never meaningful there, declared or not.
+    return 'refuse';
+}
+/**
+ * Pure VALUE question — "is this a gate-opening literal" — for the two call sites that have no
+ * kind in scope at all: the engine's gate mint (`execution-loop.ts`, which only ever reaches a
+ * step whose kind already passed L1/L2, so the kind conjunct `classifyStepTrust` would add is
+ * inert there) and the loader's gate-choices-empty check (`yaml-loader.ts`, evaluated on a raw
+ * step object before this file's own kind-narrowing block). `classifyStepTrust` CONSUMES this
+ * function for its own 'gates' arm, so there remains exactly one membership fact — passing a
+ * fabricated kind to reach a single call site would not be single-sourcing, it would be lying to
+ * a parameter to get there.
+ */
+export function isGateTrust(value) {
+    return GATE_TRUST_LEVELS.includes(value);
+}
+/**
+ * Renders a `trust` value into prose — the ONE rendering rule every trust-value message shares,
+ * exported so a NON-refusal disclosure (the protocol generator's guard/finalizer inert-trust
+ * note) can consume it too, rather than hand-rolling its own renderer that could drift from this
+ * one. `JSON.stringify`, unconditionally, no exceptions: `String()` makes `''` print as the
+ * unreadable `'trust: '` (reads as MISSING, not empty), `null` print as `'trust: null'`
+ * (indistinguishable from the three-character string `"null"`), and — worst — an ARRAY print as
+ * its own first element (`String(['a','b'])` is `'a,b'`; a value the author declared as a list is
+ * shown as if it were a scalar, with no sign anything was ever dropped).
+ */
+export function renderTrustValue(value) {
+    return JSON.stringify(value);
+}
+function selectTrustRefusalArm(value) {
+    if (SERVICE_TRUST_LEVELS.includes(value))
+        return 'service';
+    if (value === 'human_notified')
+        return 'removed';
+    return 'generic';
+}
+function trustRefusalConsequence(surface) {
+    switch (surface) {
+        case 'load':
+            // No error-code mention: L1's throw carries `VALIDATION_WORKFLOW_SCHEMA` (yaml-loader.ts
+            // joins every load-time error into one `WorkflowError` under that single code) — never
+            // `VALIDATION_TRUST_VALUE`, which is exclusively L2's (execution-loop.ts's) code. Naming
+            // it here would be a claim this surface cannot back.
+            return ('refused at load: this workflow cannot create a run while the value is wrong, so no ' +
+                'step of it — gated or not — ever executes under it');
+        case 'dispatch':
+            // No inline code mention either, but for the OPPOSITE reason: `error_code` is a real,
+            // separate, structured field on the envelope here (`VALIDATION_TRUST_VALUE`, set on the
+            // `WorkflowError` this text becomes the message of) — a reader with programmatic access
+            // already has it without parsing prose for it.
+            return ('refused at dispatch: no gate opens and this step does not run; this run is now ' +
+                'parked, non-terminal, until the value is corrected, and any step depending on this ' +
+                "one returns 'blocked' in the meantime");
+        case 'finding':
+            // `RunHealthFinding` has no separate code field the way `dispatch`'s envelope does — the
+            // code is only ever visible if it is IN this string.
+            return 'the engine will refuse this step at dispatch (VALIDATION_TRUST_VALUE)';
+        case 'briefing':
+            // Same reasoning as `finding`: `ProtocolStep.agent_involvement` is a bare string, and this
+            // is a genuinely true prediction of what L2 will throw if the agent calls execute_step
+            // anyway — the code is real information, not decoration.
+            return ('calling execute_step here will be refused (VALIDATION_TRUST_VALUE): no gate opens ' +
+                'and this step does not run; the run would then park, non-terminal, until the value ' +
+                "is corrected, with any step depending on this one returning 'blocked'");
+    }
+}
+/**
+ * The accepted-set / did-you-mean / remedy tail. `kind: 'finalizer'` is the ONE case that
+ * replaces this entirely with the finalizer's own kind clause — reachable only on
+ * `surface: 'load'` (see `buildTrustRefusal`'s own doc for why `dispatch`/`finding`/`briefing`
+ * never see a finalizer step at all): the generic accepted-set-plus-live-run-remedy text would
+ * wrongly imply the two human-gate literals are meaningful on a kind that can never gate.
+ */
+function trustRefusalTail(kind, surface, didYouMean) {
+    if (kind === 'finalizer') {
+        return (`'trust' accepts ${TRUST_LEVELS.join(', ')}, and only 'auto' is meaningful on ` +
+            `execution: finalizer steps.`);
+    }
+    switch (surface) {
+        case 'load':
+            return (`A step's 'trust' accepts ${TRUST_LEVELS.join(', ')}.` +
+                (didYouMean !== undefined ? ` Did you mean '${didYouMean}'?` : '') +
+                ` Correct the value, then 'realm workflow register <path>' — any run of this ` +
+                `workflow picks up the corrected definition on its next attempt at this step.`);
+        case 'dispatch':
+            return (`A step's 'trust' accepts ${TRUST_LEVELS.join(', ')}.` +
+                (didYouMean !== undefined ? ` Did you mean '${didYouMean}'?` : '') +
+                ` Correct the value, then 'realm workflow register <path>' and retry this step — ` +
+                `this run picks up the corrected definition.`);
+        case 'finding':
+            return (`Accepts ${TRUST_LEVELS.join(', ')}` +
+                (didYouMean !== undefined ? `; did you mean '${didYouMean}'?` : '') +
+                ` — correct the value and 'realm workflow register <path>'.`);
+        case 'briefing':
+            return (`A step's 'trust' accepts ${TRUST_LEVELS.join(', ')}.` +
+                (didYouMean !== undefined ? ` Did you mean '${didYouMean}'?` : '') +
+                ` Do NOT call execute_step for it; report this to the user, who must correct the ` +
+                `workflow definition and re-register it.`);
+    }
+}
+/**
+ * The ONE trust-refusal message composer (issue #508 final correction). Four consumers —
+ * `yaml-loader.ts`'s load-time refusal (auto/agent, and the finalizer's own non-gate-literal
+ * branch), `execution-loop.ts`'s dispatch-time refusal, `run-health.ts`'s `trust_value_invalid`
+ * finding, and the protocol generator's pre-dispatch agent briefing — used to hand-compose this
+ * text independently, and every defect this issue's prior rounds found (arm divergence across
+ * surfaces, mixed bare/quoted value rendering, an array printing as its own first element, a
+ * grammar seam where a sentence-ending clause met a lowercase continuation) fell out of that
+ * duplication, not out of four separate bugs. This function is the single point where value
+ * rendering, arm selection, and the per-surface consequence sentence are assembled — no call site
+ * chooses an arm or renders a value on its own again.
+ *
+ * `kind` only changes the output when `kind === 'finalizer'` — and even then, only reachable on
+ * `surface: 'load'`. `dispatch`/`finding`/`briefing` are all scoped, structurally, to
+ * `findEligibleSteps`'s auto/agent-only population (see each call site's own comment for why),
+ * so a finalizer step's trust value can only ever reach this function through `yaml-loader.ts`'s
+ * load-time check. `kind: 'guard'` must never reach this function at all: a guard's blanket
+ * `trust` prohibition is a KIND prohibition (the key is the offense, the value is irrelevant),
+ * minted by the #517 registry walk, and structurally never routes through a value-refusal
+ * composer.
+ */
+export function buildTrustRefusal(args) {
+    const { kind, value, step, surface } = args;
+    const arm = selectTrustRefusalArm(value);
+    // `closestKey` throws a TypeError on `null` — guarded by the `typeof` check, which also
+    // correctly excludes every other non-string value (123, [], {}) from the suggestion without a
+    // special case for each. Only the generic arm ever suggests: a service-trust value or the
+    // retired tombstone are exact membership matches, not near-misses.
+    const didYouMean = arm === 'generic' && typeof value === 'string' ? closestKey(value, TRUST_LEVELS) : undefined;
+    const rendered = renderTrustValue(value);
+    const armClause = arm === 'service'
+        ? `'trust: ${rendered}' is a SERVICE's trust level (declared under 'services: <name>: ` +
+            `trust:'), not a step's`
+        : arm === 'removed'
+            ? `'trust: ${rendered}' was removed (issue #508): it never triggered a notification, ` +
+                `it never opened a gate, and most workflows should simply delete the key`
+            : `'trust: ${rendered}' is not a recognized value`;
+    const prefix = surface === 'load' || surface === 'dispatch' ? `Step '${step}': ` : '';
+    const consequence = trustRefusalConsequence(surface);
+    const tail = trustRefusalTail(kind, surface, didYouMean);
+    return `${prefix}${armClause} — ${consequence}. ${tail}`;
+}
 /**
  * Every key RetryConfig declares. Used by the YAML loader (issue #140) to warn when a `retry:`
  * block declares a key that isn't recognized (misspelling, or a stale field) — same non-breaking

package/dist/types/workflow-definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-definition.js","sourceRoot":"","sources":["../../src/types/workflow-definition.ts"],"names":[],"mappings":"AAuHA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,cAAc;IACd,SAAS;IACT,eAAe;IACf,cAAc;IACd,YAAY;IACZ,uBAAuB;CACf,CAAC;AAMX,MAAM,sBAAsB,GAE+C,IAAI,CAAC;AAChF,MAAM,oBAAoB,GAEyD,IAAI,CAAC;AAmFxF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS;IACT,OAAO;IACP,SAAS;IACT,qBAAqB;IACrB,iBAAiB;IACjB,WAAW;IACX,gBAAgB;IAChB,kBAAkB;IAClB,cAAc;CACN,CAAC;AAMX,MAAM,qBAAqB,GAE6C,IAAI,CAAC;AAC7E,MAAM,mBAAmB,GAEuD,IAAI,CAAC;AAmQrF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa;IACb,WAAW;IACX,YAAY;IACZ,cAAc;IACd,MAAM;IACN,cAAc;IACd,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,WAAW;IACX,SAAS;IACT,QAAQ;IACR,cAAc;IACd,eAAe;IACf,cAAc;IACd,uBAAuB;IACvB,eAAe;IACf,OAAO;IACP,iBAAiB;IACjB,OAAO;IACP,uBAAuB;IACvB,cAAc;IACd,QAAQ;IACR,SAAS;IACT,cAAc;IACd,MAAM;IACN,eAAe;IACf,OAAO;IACP,gBAAgB;IAChB,aAAa;IACb,cAAc;IACd,mBAAmB;IACnB,qBAAqB;CACb,CAAC;AAQX,MAAM,qBAAqB,GAEiD,IAAI,CAAC;AACjF,MAAM,mBAAmB,GAE2D,IAAI,CAAC;AAoGzF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI;IACJ,MAAM;IACN,aAAa;IACb,SAAS;IACT,eAAe;IACf,UAAU;IACV,UAAU;IACV,aAAa;IACb,WAAW;IACX,OAAO;IACP,cAAc;IACd,YAAY;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,SAAS;CACD,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,YAAY;IACZ,YAAY;IACZ,mBAAmB;IACnB,gBAAgB;IAChB,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC;AAWX,MAAM,yBAAyB,GAKvB,IAAI,CAAC;AACb,MAAM,uBAAuB,GAKrB,IAAI,CAAC;AACb,MAAM,yBAAyB,GAE4D,IAAI,CAAC"}
+{"version":3,"file":"workflow-definition.js","sourceRoot":"","sources":["../../src/types/workflow-definition.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,wFAAwF;AACxF,2FAA2F;AAC3F,4BAA4B;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAiCxD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,MAAM;IACN,iBAAiB;IACjB,gBAAgB;CACwB,CAAC;AAE3C;;;;mFAImF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,iBAAiB;IACjB,gBAAgB;CACwB,CAAC;AAE3C;;;;yFAIyF;AACzF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;CAC0B,CAAC;AAY7C,MAAM,wBAAwB,GAE6C,IAAI,CAAC;AAChF,MAAM,sBAAsB,GAEuD,IAAI,CAAC;AAMxF,MAAM,qBAAqB,GAIuD,IAAI,CAAC;AAIvF,MAAM,+BAA+B,GAEuD,IAAI,CAAC;AACjG,MAAM,6BAA6B,GAGjC,IAAI,CAAC;AAmBP;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA+B,EAAE,KAAc;IAC/E,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAC;IACjD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACxC,IAAK,iBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,OAAO,CAAC;QAC9E,IAAI,KAAK,KAAK,MAAM;YAAE,OAAO,gBAAgB,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC;IACxD,CAAC;IACD,6FAA6F;IAC7F,iFAAiF;IACjF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAQ,iBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAWD,SAAS,qBAAqB,CAAC,KAAc;IAC3C,IAAK,oBAA2C,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACnF,IAAI,KAAK,KAAK,gBAAgB;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,SAAS,CAAC;AACnB,CAAC;AAiBD,SAAS,uBAAuB,CAAC,OAA4B;IAC3D,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,yFAAyF;YACzF,uFAAuF;YACvF,yFAAyF;YACzF,qDAAqD;YACrD,OAAO,CACL,qFAAqF;gBACrF,oDAAoD,CACrD,CAAC;QACJ,KAAK,UAAU;YACb,sFAAsF;YACtF,wFAAwF;YACxF,wFAAwF;YACxF,+CAA+C;YAC/C,OAAO,CACL,iFAAiF;gBACjF,qFAAqF;gBACrF,uCAAuC,CACxC,CAAC;QACJ,KAAK,SAAS;YACZ,yFAAyF;YACzF,qDAAqD;YACrD,OAAO,uEAAuE,CAAC;QACjF,KAAK,UAAU;YACb,2FAA2F;YAC3F,uFAAuF;YACvF,yDAAyD;YACzD,OAAO,CACL,oFAAoF;gBACpF,qFAAqF;gBACrF,uEAAuE,CACxE,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CACvB,IAAmB,EACnB,OAA4B,EAC5B,UAA8B;IAE9B,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,CACL,mBAAmB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,qCAAqC;YAC/E,6BAA6B,CAC9B,CAAC;IACJ,CAAC;IACD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,CACL,4BAA4B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACtD,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,8EAA8E;gBAC9E,8EAA8E,CAC/E,CAAC;QACJ,KAAK,UAAU;YACb,OAAO,CACL,4BAA4B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACtD,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,kFAAkF;gBAClF,6CAA6C,CAC9C,CAAC;QACJ,KAAK,SAAS;YACZ,OAAO,CACL,WAAW,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACpC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnE,4DAA4D,CAC7D,CAAC;QACJ,KAAK,UAAU;YACb,OAAO,CACL,4BAA4B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACtD,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,kFAAkF;gBAClF,yCAAyC,CAC1C,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAKjC;IACC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,MAAM,GAAG,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACzC,wFAAwF;IACxF,8FAA8F;IAC9F,0FAA0F;IAC1F,mEAAmE;IACnE,MAAM,UAAU,GACd,GAAG,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/F,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAEzC,MAAM,SAAS,GACb,GAAG,KAAK,SAAS;QACf,CAAC,CAAC,WAAW,QAAQ,kEAAkE;YACrF,wBAAwB;QAC1B,CAAC,CAAC,GAAG,KAAK,SAAS;YACjB,CAAC,CAAC,WAAW,QAAQ,iEAAiE;gBACpF,yEAAyE;YAC3E,CAAC,CAAC,WAAW,QAAQ,6BAA6B,CAAC;IAEzD,MAAM,MAAM,GAAG,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,MAAM,WAAW,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAEzD,OAAO,GAAG,MAAM,GAAG,SAAS,MAAM,WAAW,KAAK,IAAI,EAAE,CAAC;AAC3D,CAAC;AAkGD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,cAAc;IACd,SAAS;IACT,eAAe;IACf,cAAc;IACd,YAAY;IACZ,uBAAuB;CACf,CAAC;AAMX,MAAM,sBAAsB,GAE+C,IAAI,CAAC;AAChF,MAAM,oBAAoB,GAEyD,IAAI,CAAC;AAmFxF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,SAAS;IACT,OAAO;IACP,SAAS;IACT,qBAAqB;IACrB,iBAAiB;IACjB,WAAW;IACX,gBAAgB;IAChB,kBAAkB;IAClB,cAAc;CACN,CAAC;AAMX,MAAM,qBAAqB,GAE6C,IAAI,CAAC;AAC7E,MAAM,mBAAmB,GAEuD,IAAI,CAAC;AAsQrF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,aAAa;IACb,WAAW;IACX,YAAY;IACZ,cAAc;IACd,MAAM;IACN,cAAc;IACd,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,gBAAgB;IAChB,WAAW;IACX,WAAW;IACX,SAAS;IACT,QAAQ;IACR,cAAc;IACd,eAAe;IACf,cAAc;IACd,uBAAuB;IACvB,eAAe;IACf,OAAO;IACP,iBAAiB;IACjB,OAAO;IACP,uBAAuB;IACvB,cAAc;IACd,QAAQ;IACR,SAAS;IACT,cAAc;IACd,MAAM;IACN,eAAe;IACf,OAAO;IACP,gBAAgB;IAChB,aAAa;IACb,cAAc;IACd,mBAAmB;IACnB,qBAAqB;CACb,CAAC;AAQX,MAAM,qBAAqB,GAEiD,IAAI,CAAC;AACjF,MAAM,mBAAmB,GAE2D,IAAI,CAAC;AAoGzF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI;IACJ,MAAM;IACN,aAAa;IACb,SAAS;IACT,eAAe;IACf,UAAU;IACV,UAAU;IACV,aAAa;IACb,WAAW;IACX,OAAO;IACP,cAAc;IACd,YAAY;IACZ,kBAAkB;IAClB,iBAAiB;IACjB,SAAS;CACD,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,YAAY;IACZ,YAAY;IACZ,mBAAmB;IACnB,gBAAgB;IAChB,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC;AAWX,MAAM,yBAAyB,GAKvB,IAAI,CAAC;AACb,MAAM,uBAAuB,GAKrB,IAAI,CAAC;AACb,MAAM,yBAAyB,GAE4D,IAAI,CAAC"}

package/dist/types/workflow-error.d.ts

@@ -1,7 +1,7 @@
 import type { LoaderWarning } from '../workflow/diagnostics.js';
 export type ErrorCategory = 'NETWORK' | 'SERVICE' | 'STATE' | 'VALIDATION' | 'ENGINE' | 'RESOURCE';
 export type AgentAction = 'report_to_user' | 'provide_input' | 'resolve_precondition' | 'stop' | 'wait_for_human' | 'wait_and_proceed';
-export type ErrorCode = 'NETWORK_TIMEOUT' | 'NETWORK_UNREACHABLE' | 'NETWORK_DNS_FAILED' | 'NETWORK_CONNECTION_RESET' | 'SERVICE_HTTP_4XX' | 'SERVICE_HTTP_5XX' | 'SERVICE_RATE_LIMITED' | 'SERVICE_AUTH_FAILED' | 'SERVICE_NOT_FOUND' | 'SERVICE_RESPONSE_INVALID' | 'SERVICE_UNEXPECTED_REDIRECT' | 'STATE_BLOCKED' | 'STATE_PRECONDITION_FAILED' | 'STATE_RUN_NOT_FOUND' | 'STATE_WORKFLOW_NOT_FOUND' | 'STATE_RUN_TERMINAL' | 'STATE_SNAPSHOT_MISMATCH' | 'STATE_RUN_LOCKED' | 'STATE_RUN_BUSY' | 'STATE_TRANSITION_DENIED' | 'STATE_RUN_RESURRECTED' | 'STATE_LEGACY_FORMAT' | 'STATE_STEP_ALREADY_CLAIMED' | 'STATE_STEP_NOT_ELIGIBLE' | 'STATE_STEP_ALREADY_SETTLED' | 'STATE_CLAIM_LOST' | 'STATE_RUN_DIVERGED' | 'STATE_RUN_ALREADY_ACTIVE' | 'STATE_IDEMPOTENCY_KEY_USED' | 'RUN_ABORTING' | 'VALIDATION_INPUT_SCHEMA' | 'VALIDATION_OUTPUT_SCHEMA' | 'VALIDATION_TRACE_SCHEMA' | 'VALIDATION_EXHAUSTED' | 'VALIDATION_WORKFLOW_SCHEMA' | 'VALIDATION_HASH_MISMATCH' | 'VALIDATION_QUOTE_NOT_FOUND' | 'VALIDATION_FIELD_UNKNOWN' | 'VALIDATION_FIELD_EXCLUDED' | 'VALIDATION_EMPTY_VALUE' | 'VALIDATION_BATCH_TOO_LARGE' | 'VALIDATION_BATCH_ITEMS' | 'STEP_HANDLER_ERROR' | 'ENGINE_INTERNAL' | 'ENGINE_STORE_FAILED' | 'ENGINE_ARTIFACT_DELETE_FAILED' | 'ENGINE_ADAPTER_FAILED' | 'ENGINE_ADAPTER_NOT_REGISTERED' | 'ENGINE_PROCESSOR_FAILED' | 'ENGINE_HANDLER_FAILED' | 'ENGINE_HANDLER_NOT_REGISTERED' | 'ENGINE_STEP_FAILED' | 'ENGINE_GATE_OPEN_FAILED' | 'GATE_MESSAGE_UNRESOLVABLE' | 'FILTER_UNKNOWN' | 'ADAPTER_OP_UNSUPPORTED' | 'ADAPTER_VALIDATION_FAILED' | 'ADAPTER_REQUEST_FAILED' | 'STEP_TIMEOUT' | 'STEP_ABORTED' | 'STEP_RETRY_EXHAUSTED' | 'STATE_STEP_PENDING' | 'STATE_SEAL_UNSTAMPED' | 'STATE_SEAL_ORPHANED' | 'STATE_SEAL_ERASED' | 'STATE_SEAL_UNKNOWN_ARM' | 'STATE_SEAL_INCOHERENT' | 'STATE_SEAL_REWRITTEN' | 'STEP_NOT_FOUND' | 'GUARD_RESOLUTION_ERROR' | 'INPUT_MAP_DEPTH_EXCEEDED' | 'INPUT_MAP_UNKNOWN_DIRECTIVE' | 'RESOURCE_FETCH_FAILED' | 'RESOURCE_TOO_LARGE' | 'RESOURCE_FORMAT_INVALID' | 'RESOURCE_NOT_ACCESSIBLE' | 'BUFFER_FULL' | 'TRACE_CAPABILITY_INCONSISTENT' | 'MCP_CONNECTION_FAILED' | 'MCP_TOOL_NOT_FOUND' | 'MCP_TOOL_NAME_COLLISION';
+export type ErrorCode = 'NETWORK_TIMEOUT' | 'NETWORK_UNREACHABLE' | 'NETWORK_DNS_FAILED' | 'NETWORK_CONNECTION_RESET' | 'SERVICE_HTTP_4XX' | 'SERVICE_HTTP_5XX' | 'SERVICE_RATE_LIMITED' | 'SERVICE_AUTH_FAILED' | 'SERVICE_NOT_FOUND' | 'SERVICE_RESPONSE_INVALID' | 'SERVICE_UNEXPECTED_REDIRECT' | 'STATE_BLOCKED' | 'STATE_PRECONDITION_FAILED' | 'STATE_RUN_NOT_FOUND' | 'STATE_WORKFLOW_NOT_FOUND' | 'STATE_RUN_TERMINAL' | 'STATE_SNAPSHOT_MISMATCH' | 'STATE_RUN_LOCKED' | 'STATE_RUN_BUSY' | 'STATE_TRANSITION_DENIED' | 'STATE_RUN_RESURRECTED' | 'STATE_LEGACY_FORMAT' | 'STATE_STEP_ALREADY_CLAIMED' | 'STATE_STEP_NOT_ELIGIBLE' | 'STATE_STEP_ALREADY_SETTLED' | 'STATE_CLAIM_LOST' | 'STATE_RUN_DIVERGED' | 'STATE_RUN_ALREADY_ACTIVE' | 'STATE_IDEMPOTENCY_KEY_USED' | 'RUN_ABORTING' | 'VALIDATION_INPUT_SCHEMA' | 'VALIDATION_OUTPUT_SCHEMA' | 'VALIDATION_TRACE_SCHEMA' | 'VALIDATION_EXHAUSTED' | 'VALIDATION_WORKFLOW_SCHEMA' | 'VALIDATION_HASH_MISMATCH' | 'VALIDATION_QUOTE_NOT_FOUND' | 'VALIDATION_FIELD_UNKNOWN' | 'VALIDATION_FIELD_EXCLUDED' | 'VALIDATION_EMPTY_VALUE' | 'VALIDATION_BATCH_TOO_LARGE' | 'VALIDATION_BATCH_ITEMS' | 'VALIDATION_TRUST_VALUE' | 'STEP_HANDLER_ERROR' | 'ENGINE_INTERNAL' | 'ENGINE_STORE_FAILED' | 'ENGINE_ARTIFACT_DELETE_FAILED' | 'ENGINE_ADAPTER_FAILED' | 'ENGINE_ADAPTER_NOT_REGISTERED' | 'ENGINE_PROCESSOR_FAILED' | 'ENGINE_HANDLER_FAILED' | 'ENGINE_HANDLER_NOT_REGISTERED' | 'ENGINE_STEP_FAILED' | 'ENGINE_GATE_OPEN_FAILED' | 'GATE_MESSAGE_UNRESOLVABLE' | 'FILTER_UNKNOWN' | 'ADAPTER_OP_UNSUPPORTED' | 'ADAPTER_VALIDATION_FAILED' | 'ADAPTER_REQUEST_FAILED' | 'STEP_TIMEOUT' | 'STEP_ABORTED' | 'STEP_RETRY_EXHAUSTED' | 'STATE_STEP_PENDING' | 'STATE_SEAL_UNSTAMPED' | 'STATE_SEAL_ORPHANED' | 'STATE_SEAL_ERASED' | 'STATE_SEAL_UNKNOWN_ARM' | 'STATE_SEAL_INCOHERENT' | 'STATE_SEAL_REWRITTEN' | 'STEP_NOT_FOUND' | 'GUARD_RESOLUTION_ERROR' | 'INPUT_MAP_DEPTH_EXCEEDED' | 'INPUT_MAP_UNKNOWN_DIRECTIVE' | 'RESOURCE_FETCH_FAILED' | 'RESOURCE_TOO_LARGE' | 'RESOURCE_FORMAT_INVALID' | 'RESOURCE_NOT_ACCESSIBLE' | 'BUFFER_FULL' | 'TRACE_CAPABILITY_INCONSISTENT' | 'MCP_CONNECTION_FAILED' | 'MCP_TOOL_NOT_FOUND' | 'MCP_TOOL_NAME_COLLISION';
 export interface WorkflowErrorOptions {
     code: ErrorCode;
     category: ErrorCategory;

package/dist/types/workflow-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-error.d.ts","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow-error.d.ts","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"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"}

package/dist/types/workflow-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-error.js","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"AAsMA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAY;IAChB,QAAQ,CAAgB;IACxB,WAAW,CAAc;IACzB,SAAS,CAAU;IACnB,OAAO,CAA0B;IACjC,MAAM,CAAU;IAChB,SAAS,CAAS;IAClB,OAAO,CAAS;IAChB,WAAW,CAAU;IAC9B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAA4B;IACpC;;;;;;;;;OASG;IACH,MAAM,CAAqB;IAE3B,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAC9E,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACjE,CAAC;CACF"}
+{"version":3,"file":"workflow-error.js","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"AA6MA,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAY;IAChB,QAAQ,CAAgB;IACxB,WAAW,CAAc;IACzB,SAAS,CAAU;IACnB,OAAO,CAA0B;IACjC,MAAM,CAAU;IAChB,SAAS,CAAS;IAClB,OAAO,CAAS;IAChB,WAAW,CAAU;IAC9B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAA4B;IACpC;;;;;;;;;OASG;IACH,MAAM,CAAqB;IAE3B,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QAC9E,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrE,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACjE,CAAC;CACF"}

package/dist/workflow/diagnostics.d.ts

@@ -6,11 +6,13 @@
 import type { SourcePosition } from './source-positions.js';
 export type WarningCode = 'UNKNOWN_WORKFLOW_KEY' | 'UNKNOWN_STEP_KEY' | 'UNKNOWN_CREATE_WORKFLOW_KEY' | 'IDEMPOTENT_INERT_IN_FINALIZER' | 'DUAL_SCHEMA_DECLARED' | 'RETRY_NO_TIMEOUT' | 'EXTENSION_SENTINEL' | 'UNKNOWN_RETRY_KEY' | 'ON_TIMEOUT_SINGLE_ATTEMPT' | 'TOTAL_TIMEOUT_BELOW_ATTEMPT' | 'TOTAL_TIMEOUT_NON_AUTO' | 'RETRY_INERT_NON_AUTO' | 'UNKNOWN_VALIDATION_EXHAUSTION_KEY' | 'DEAD_VALIDATION_EXHAUSTION_CONFIG' | 'UNKNOWN_GATE_KEY' | 'DEAD_GATE_CONFIG';
 /**
- * A single structured diagnostic. `message` is the full human-readable text (matching, for every
- * unknown-key code, exactly what `renderLoaderWarning` would independently reconstruct from the
- * structured fields — kept in sync by construction, not by convention: see `findUnknownKeys`
- * below). `scope`/`id`/`step`/`key`/`did_you_mean` are populated only by the unknown-key family;
- * other codes carry just `code`/`severity`/`message`.
+ * A single structured diagnostic. `message` is the full human-readable text, minted once at the
+ * source (`findUnknownKeys` below, for the unknown-key family) — `renderLoaderWarning` never
+ * reconstructs it from the structured fields; it only ECHOES `message` verbatim, prefixed with
+ * `⚠ `. `scope`/`id`/`step`/`key`/`did_you_mean` are populated only by the unknown-key family and
+ * exist for consumers that want the PARTS (a machine reader, a different renderer), not for
+ * `renderLoaderWarning` to recompose from — that would risk a second, drifting copy of the same
+ * prose. Other codes carry just `code`/`severity`/`message`.
  */
 export interface LoaderWarning {
     code: WarningCode;
@@ -71,6 +73,30 @@ export declare function resolveSeverity(code: WarningCode, policy?: Record<Warni
  * deterministic, not alphabetical.
  */
 export declare function closestKey(key: string, allowList: readonly string[]): string | undefined;
+/**
+ * The author-extension namespace (issue #559). A top-level key beginning `x-` is the AUTHOR's:
+ * realm carries it verbatim into the registered copy and never reads it — a place for YAML
+ * anchor hosts (e.g. a shared enum) and tooling notes. Docker Compose's `^x-` is the same
+ * mechanism, and its own docs direct anchors into it.
+ *
+ * `x-realm-` is reserved for realm's own future extension keys from the day the namespace
+ * opens — so a key in it is NOT an extension key and still refuses, with a message naming the
+ * reservation (OpenAPI reserved `x-oai-`/`x-oas-` only retroactively; realm does it up front).
+ *
+ * The reserved sub-namespace is matched in EVERY capitalization — `x-Realm-foo` and `x-REALM-foo`
+ * are NOT the author's keys (issue #582): the reservation exists so no case-variant can sit
+ * beside a future realm key, so it must not depend on the author's Shift key. The reservation is
+ * the PREFIX `x-realm-` (OpenAPI reserves `x-oai-` the same way): the dash-less word `x-realm` is
+ * the author's.
+ *
+ * Case-sensitive: `X-Foo` is not an extension key (OpenAPI's and Compose's `^x-` are lowercase).
+ * The dash is load-bearing: `xtra` is not one. A bare `x-` IS one — an empty extension name is
+ * still the author's; it renders as `x-` in the disclosure clause.
+ */
+export declare const EXTENSION_KEY_PREFIX: "x-";
+export declare const RESERVED_EXTENSION_PREFIX: "x-realm-";
+/** True when `key` is the author's own extension key (see `EXTENSION_KEY_PREFIX`). */
+export declare function isExtensionKey(key: string): boolean;
 /**
  * Finds every own-key of `obj` not present in `allowList` and returns one LoaderWarning per
  * offender. Pure — no printing, no throwing. Severity is resolved against DEFAULT_POLICY at
@@ -99,6 +125,16 @@ export declare function findUnknownKeys(obj: Record<string, unknown>, allowList:
      * position map declined to place) and produces exactly the pre-#392 warning.
      */
     positionOf?: (key: string) => SourcePosition | undefined;
+    /**
+     * Skips a key entirely (issue #559) — no allow-list check, no warning. Passed by the ONE
+     * top-level workflow-key site in yaml-loader.ts, where `x-` keys are the author's namespace.
+     * The step site deliberately does NOT pass it: step keys are the #417 consumption registry, a
+     * closed set where an inert key is a load error by ratified policy — there is no namespace at
+     * step level.
+     *
+     * Optional, so every existing caller compiles and behaves byte-identically.
+     */
+    isExtension?: (key: string) => boolean;
 }): LoaderWarning[];
 /**
  * The SINGLE source of the `⚠ ` line format — every printer (the core plain wrappers in

package/dist/workflow/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/workflow/diagnostics.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,kBAAkB,GAClB,6BAA6B,GAC7B,+BAA+B,GAC/B,sBAAsB,GACtB,kBAAkB,GAClB,oBAAoB,GAEpB,mBAAmB,GACnB,2BAA2B,GAC3B,6BAA6B,GAC7B,wBAAwB,GAGxB,sBAAsB,GAEtB,mCAAmC,GACnC,mCAAmC,GAInC,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiBhE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,MAAM,GAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAkB,GAC7D,MAAM,GAAG,OAAO,CAElB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAYxF;AAgCD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,GAAG,EAAE;IACH,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;CAC1D,GACA,aAAa,EAAE,CA6BjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAE5D"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/workflow/diagnostics.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,kBAAkB,GAClB,6BAA6B,GAC7B,+BAA+B,GAC/B,sBAAsB,GACtB,kBAAkB,GAClB,oBAAoB,GAEpB,mBAAmB,GACnB,2BAA2B,GAC3B,6BAA6B,GAC7B,wBAAwB,GAGxB,sBAAsB,GAEtB,mCAAmC,GACnC,mCAAmC,GAInC,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiBhE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,MAAM,GAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAkB,GAC7D,MAAM,GAAG,OAAO,CAElB;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAYxF;AAgCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,EAAG,IAAa,CAAC;AAClD,eAAO,MAAM,yBAAyB,EAAG,UAAmB,CAAC;AAE7D,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAInD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,GAAG,EAAE;IACH,KAAK,EAAE,UAAU,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IACzD;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC,GACA,aAAa,EAAE,CA8BjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAE5D"}

package/dist/workflow/diagnostics.js

@@ -91,12 +91,12 @@ export function closestKey(key, allowList) {
 /**
  * Builds the templated "unknown key" message text (everything after the `⚠ ` prefix).
  *
- * The position is spliced in HERE, at the mint, rather than at any render site (issue #392). Two
- * reasons. `renderLoaderWarning` is the single source of the `⚠ ` line format and stays
- * byte-untouched, so nothing downstream has to learn about positions. And the CLI's #170
- * substitution rewrites `— ignored` at print time for a refusing boundary — inserting before that
- * anchor leaves it intact, whereas inserting after it would leave the two edits fighting over the
- * same span.
+ * The position is spliced in HERE, at the mint, rather than at any render site (issue #392):
+ * `renderLoaderWarning` is the single source of the `⚠ ` line format and stays byte-untouched, so
+ * nothing downstream has to learn about positions. (Issue #540 removed the one other reason this
+ * comment used to give — a CLI print-time substitution that rewrote `— ignored` for a refusing
+ * boundary, and whose anchor this splice point had to land before. That substitution is gone;
+ * `— ignored` now renders unmodified everywhere. See `plans/issue-540/design-d2.md`.)
  *
  * The prose carries the START line only. A human reading an error wants somewhere to look, not a
  * range; the range lives on the structured channel where a span-editing agent can use it.
@@ -111,6 +111,32 @@ function renderUnknownKeyMessage(target, key, didYouMean, noun, line) {
     }
     return `${target}: unknown key '${key}'${at} — ignored (not a recognized ${noun} field).`;
 }
+/**
+ * The author-extension namespace (issue #559). A top-level key beginning `x-` is the AUTHOR's:
+ * realm carries it verbatim into the registered copy and never reads it — a place for YAML
+ * anchor hosts (e.g. a shared enum) and tooling notes. Docker Compose's `^x-` is the same
+ * mechanism, and its own docs direct anchors into it.
+ *
+ * `x-realm-` is reserved for realm's own future extension keys from the day the namespace
+ * opens — so a key in it is NOT an extension key and still refuses, with a message naming the
+ * reservation (OpenAPI reserved `x-oai-`/`x-oas-` only retroactively; realm does it up front).
+ *
+ * The reserved sub-namespace is matched in EVERY capitalization — `x-Realm-foo` and `x-REALM-foo`
+ * are NOT the author's keys (issue #582): the reservation exists so no case-variant can sit
+ * beside a future realm key, so it must not depend on the author's Shift key. The reservation is
+ * the PREFIX `x-realm-` (OpenAPI reserves `x-oai-` the same way): the dash-less word `x-realm` is
+ * the author's.
+ *
+ * Case-sensitive: `X-Foo` is not an extension key (OpenAPI's and Compose's `^x-` are lowercase).
+ * The dash is load-bearing: `xtra` is not one. A bare `x-` IS one — an empty extension name is
+ * still the author's; it renders as `x-` in the disclosure clause.
+ */
+export const EXTENSION_KEY_PREFIX = 'x-';
+export const RESERVED_EXTENSION_PREFIX = 'x-realm-';
+/** True when `key` is the author's own extension key (see `EXTENSION_KEY_PREFIX`). */
+export function isExtensionKey(key) {
+    return (key.startsWith(EXTENSION_KEY_PREFIX) && !key.toLowerCase().startsWith(RESERVED_EXTENSION_PREFIX));
+}
 /**
  * Finds every own-key of `obj` not present in `allowList` and returns one LoaderWarning per
  * offender. Pure — no printing, no throwing. Severity is resolved against DEFAULT_POLICY at
@@ -122,6 +148,8 @@ export function findUnknownKeys(obj, allowList, ctx) {
     const target = ctx.scope === 'workflow' ? `workflow '${ctx.id ?? '<unknown>'}'` : `step '${ctx.step}'`;
     const noun = ctx.noun ?? ctx.scope;
     for (const key of Object.keys(obj)) {
+        if (ctx.isExtension?.(key) === true)
+            continue;
         if (allowList.includes(key))
             continue;
         const did_you_mean = closestKey(key, allowList);

package/dist/workflow/diagnostics.js.map

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

package/dist/workflow/registrar.d.ts

@@ -1,4 +1,5 @@
 import type { WorkflowDefinition } from '../types/workflow-definition.js';
+import type { RunRecord } from '../types/run-record.js';
 export interface WorkflowRegistrar {
     /** Persist a WorkflowDefinition under its id, overwriting any previous registration. */
     register(definition: WorkflowDefinition): Promise<void>;
@@ -43,4 +44,45 @@ export declare class JsonWorkflowStore implements WorkflowRegistrar {
         }>;
     }>;
 }
+/**
+ * Fetches the workflow definition a run-context resolution needs, wrapping a
+ * `STATE_WORKFLOW_NOT_FOUND` throw with the one-time-register remedy (issue #456) — the ONE
+ * chokepoint every run-context site (`respond`, `resume`, `replay`, `drain`, `agent --run-id`,
+ * and the MCP `submit_human_response`/`execute_step`/`append_trace` tools) calls, instead of each
+ * hand-wrapping its own raw `store.get(run.workflow_id)`.
+ *
+ * The `store` and `run` parameters are narrowed to exactly what this function uses
+ * (`Pick<WorkflowRegistrar, 'get'>` / `Pick<RunRecord, 'workflow_id'>`) — by necessity, not taste:
+ * `resolveRunAttach`'s own dependency type IS that narrower `Pick` (its test doubles are get-only,
+ * and a full `WorkflowRegistrar` parameter here would not compile at that call site). Every other
+ * caller passes a full registrar and a full run record, both structurally assignable to the
+ * narrower type.
+ *
+ * HEDGED reasoning, moved here from `run-attach.ts`'s inline comment (its call site now just
+ * points back here): this function genuinely cannot know WHY the workflow is missing. A wiped
+ * store, a different `$HOME`, and a run created from a file without `--register` all mint the
+ * identical `STATE_WORKFLOW_NOT_FOUND` from the registrar — so the remedy says "most often",
+ * never "because". Keyed on the stable error CODE, never on message text.
+ *
+ * PRECONDITION — run-context resolution ONLY. A by-id lookup with no run behind it (`start_run`,
+ * `start_run_batch`, `get_workflow_protocol`) must never call this: there the hedge would be
+ * false — "this run was created from a file without --register" presumes a run that does not
+ * exist yet.
+ *
+ * Every OTHER `WorkflowError` (e.g. `STATE_LEGACY_FORMAT`, which already carries its own correct
+ * "Re-register it with: …" remedy) passes through completely untouched, by identity — wrapping it
+ * would double-remedy. A non-`WorkflowError` throw also passes through untouched.
+ *
+ * issue #493 seam: if definition snapshots ever land on the run record, the snapshot-wins
+ * resolution order belongs INSIDE this function — every run-context caller updates for free.
+ *
+ * @param store Anything that can `.get()` a workflow by id.
+ * @param run   The run whose `workflow_id` to resolve.
+ * @param opts  `retryVerb` — the verb this call site's remedy should recommend retrying with
+ *              (e.g. `'re-attach'`, `'respond again'`, `'resume again'`, `'replay again'`,
+ *              `'drain again'`, or the MCP-neutral `'retry'`).
+ */
+export declare function getWorkflowForRun(store: Pick<WorkflowRegistrar, 'get'>, run: Pick<RunRecord, 'workflow_id'>, opts: {
+    retryVerb: string;
+}): Promise<WorkflowDefinition>;
 //# sourceMappingURL=registrar.d.ts.map

package/dist/workflow/registrar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/workflow/registrar.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAK1E,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,8EAA8E;IAC9E,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrD,qCAAqC;IACrC,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,CAAC,EAAE,MAAM;IAKtB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCpD,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAQ3C;;;;;;;;;;;;;;OAcG;IACG,mBAAmB,IAAI,OAAO,CAAC;QACnC,SAAS,EAAE,kBAAkB,EAAE,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpD,UAAU,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACjD,CAAC;CAqBH"}
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/workflow/registrar.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAKxD,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,8EAA8E;IAC9E,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrD,qCAAqC;IACrC,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,CAAC,EAAE,MAAM;IAKtB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCpD,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAQ3C;;;;;;;;;;;;;;OAcG;IACG,mBAAmB,IAAI,OAAO,CAAC;QACnC,SAAS,EAAE,kBAAkB,EAAE,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpD,UAAU,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACjD,CAAC;CAqBH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,EACrC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EACnC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAoB7B"}

package/dist/workflow/registrar.js

@@ -89,4 +89,61 @@ export class JsonWorkflowStore {
         return { workflows, unreadable, mismatched };
     }
 }
+/**
+ * Fetches the workflow definition a run-context resolution needs, wrapping a
+ * `STATE_WORKFLOW_NOT_FOUND` throw with the one-time-register remedy (issue #456) — the ONE
+ * chokepoint every run-context site (`respond`, `resume`, `replay`, `drain`, `agent --run-id`,
+ * and the MCP `submit_human_response`/`execute_step`/`append_trace` tools) calls, instead of each
+ * hand-wrapping its own raw `store.get(run.workflow_id)`.
+ *
+ * The `store` and `run` parameters are narrowed to exactly what this function uses
+ * (`Pick<WorkflowRegistrar, 'get'>` / `Pick<RunRecord, 'workflow_id'>`) — by necessity, not taste:
+ * `resolveRunAttach`'s own dependency type IS that narrower `Pick` (its test doubles are get-only,
+ * and a full `WorkflowRegistrar` parameter here would not compile at that call site). Every other
+ * caller passes a full registrar and a full run record, both structurally assignable to the
+ * narrower type.
+ *
+ * HEDGED reasoning, moved here from `run-attach.ts`'s inline comment (its call site now just
+ * points back here): this function genuinely cannot know WHY the workflow is missing. A wiped
+ * store, a different `$HOME`, and a run created from a file without `--register` all mint the
+ * identical `STATE_WORKFLOW_NOT_FOUND` from the registrar — so the remedy says "most often",
+ * never "because". Keyed on the stable error CODE, never on message text.
+ *
+ * PRECONDITION — run-context resolution ONLY. A by-id lookup with no run behind it (`start_run`,
+ * `start_run_batch`, `get_workflow_protocol`) must never call this: there the hedge would be
+ * false — "this run was created from a file without --register" presumes a run that does not
+ * exist yet.
+ *
+ * Every OTHER `WorkflowError` (e.g. `STATE_LEGACY_FORMAT`, which already carries its own correct
+ * "Re-register it with: …" remedy) passes through completely untouched, by identity — wrapping it
+ * would double-remedy. A non-`WorkflowError` throw also passes through untouched.
+ *
+ * issue #493 seam: if definition snapshots ever land on the run record, the snapshot-wins
+ * resolution order belongs INSIDE this function — every run-context caller updates for free.
+ *
+ * @param store Anything that can `.get()` a workflow by id.
+ * @param run   The run whose `workflow_id` to resolve.
+ * @param opts  `retryVerb` — the verb this call site's remedy should recommend retrying with
+ *              (e.g. `'re-attach'`, `'respond again'`, `'resume again'`, `'replay again'`,
+ *              `'drain again'`, or the MCP-neutral `'retry'`).
+ */
+export async function getWorkflowForRun(store, run, opts) {
+    try {
+        return await store.get(run.workflow_id);
+    }
+    catch (err) {
+        if (err instanceof WorkflowError && err.code === 'STATE_WORKFLOW_NOT_FOUND') {
+            throw new WorkflowError(`${err.message} — most often this run was created from a file without --register. ` +
+                `Register the workflow (realm workflow register <file>) and ${opts.retryVerb}.`, {
+                code: err.code,
+                category: err.category,
+                agentAction: err.agentAction,
+                retryable: err.retryable,
+                details: err.details,
+                ...(err.warnings !== undefined ? { warnings: err.warnings } : {}),
+            });
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=registrar.js.map

package/dist/workflow/registrar.js.map

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