@astrasyncai/verification-gateway 3.12.0 → 4.1.0

package/dist/adapters/http-pdlss.d.mts

@@ -1,6 +1,6 @@
 /**
  * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —
- * vocabulary-unification round (Bug 14, adapter-spec §4.6).
+ * the vocabulary-unification layer.
  *
  * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,
  * `data`, custom nouns like `trading`); `action` = dotted verb
@@ -13,7 +13,7 @@
  * duplicated here and pinned strictly equal by a monorepo CI test
  * (vocab-equality.test.ts). Change them in BOTH places or that test fails.
  */
-/** Pinned method→action derivation table (§4.6). */
+/** Pinned method→action derivation table. */
 declare const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>>;
 /** Unknown methods are treated as mutating until proven otherwise. */
 declare const DEFAULT_HTTP_ACTION = "data.write";
@@ -63,7 +63,7 @@ declare function normalizePurposeHeader(value: string): {
 /**
  * Resolve the {purpose, action} pair for one HTTP request.
  *
- * Precedence (both axes; §4.6):
+ * Precedence (both axes):
  *   action:  route mapping → extractAction option → X-Astra-Action header →
  *            candidate from a dotted X-Astra-Purpose → pinned method table
  *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →

package/dist/adapters/http-pdlss.d.ts

@@ -1,6 +1,6 @@
 /**
  * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —
- * vocabulary-unification round (Bug 14, adapter-spec §4.6).
+ * the vocabulary-unification layer.
  *
  * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,
  * `data`, custom nouns like `trading`); `action` = dotted verb
@@ -13,7 +13,7 @@
  * duplicated here and pinned strictly equal by a monorepo CI test
  * (vocab-equality.test.ts). Change them in BOTH places or that test fails.
  */
-/** Pinned method→action derivation table (§4.6). */
+/** Pinned method→action derivation table. */
 declare const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>>;
 /** Unknown methods are treated as mutating until proven otherwise. */
 declare const DEFAULT_HTTP_ACTION = "data.write";
@@ -63,7 +63,7 @@ declare function normalizePurposeHeader(value: string): {
 /**
  * Resolve the {purpose, action} pair for one HTTP request.
  *
- * Precedence (both axes; §4.6):
+ * Precedence (both axes):
  *   action:  route mapping → extractAction option → X-Astra-Action header →
  *            candidate from a dotted X-Astra-Purpose → pinned method table
  *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →

package/dist/adapters/http-pdlss.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * vocabulary-unification round (Bug 14, adapter-spec §4.6).\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table (§4.6). */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes; §4.6):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}
+{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}

package/dist/adapters/http-pdlss.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * vocabulary-unification round (Bug 14, adapter-spec §4.6).\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table (§4.6). */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes; §4.6):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}
+{"version":3,"sources":["../../src/adapters/http-pdlss.ts"],"sourcesContent":["/**\n * Shared purpose/action resolver for the HTTP adapters (express + nextjs) —\n * the vocabulary-unification layer.\n *\n * The PDLSS two-axis contract: `purpose` = bare category noun (`shopping`,\n * `data`, custom nouns like `trading`); `action` = dotted verb\n * (`shopping.search`) or an enumerated transport token. Transport verbs\n * (GET/POST/...) NEVER travel as PDLSS actions — they map through the pinned\n * method table below.\n *\n * SELF-CONTAINED on purpose: this published package cannot depend on the\n * private @astrasyncai/pdlss-vocab workspace package, so the constants are\n * duplicated here and pinned strictly equal by a monorepo CI test\n * (vocab-equality.test.ts). Change them in BOTH places or that test fails.\n */\n\n/** Pinned method→action derivation table. */\nexport const HTTP_METHOD_ACTION_TABLE: Readonly<Record<string, string>> = {\n  GET: 'data.read',\n  HEAD: 'data.read',\n  OPTIONS: 'data.read',\n  POST: 'data.write',\n  PUT: 'data.write',\n  PATCH: 'data.write',\n  DELETE: 'data.delete',\n};\n\n/** Unknown methods are treated as mutating until proven otherwise. */\nexport const DEFAULT_HTTP_ACTION = 'data.write';\n\n/** Generic category emitted when nothing supplies a domain purpose. */\nexport const DEFAULT_HTTP_PURPOSE = 'data';\n\nexport function actionForHttpMethod(method: string): string {\n  return HTTP_METHOD_ACTION_TABLE[method.toUpperCase()] ?? DEFAULT_HTTP_ACTION;\n}\n\nexport type HttpPurposeSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'legacy_header'\n  | 'query'\n  | 'action_derived'\n  | 'transport_default';\n\nexport type HttpActionSource =\n  | 'route_config'\n  | 'custom_extractor'\n  | 'header'\n  | 'purpose_header_derived'\n  | 'method_table';\n\nexport interface HttpPdlssInput {\n  method: string;\n  /** `X-Astra-Purpose` header value (agent's declaration). */\n  astraPurpose?: string;\n  /** `X-Astra-Action` header value (agent's declaration, symmetric with MCP). */\n  astraAction?: string;\n  /** Legacy `x-purpose` header — deprecated, removal scheduled for 4.0.0. */\n  legacyPurpose?: string;\n  /** Legacy `?purpose` query param (express only) — deprecated, removal 4.0.0. */\n  queryPurpose?: string;\n  /** Dashboard route config send-mapping (RouteAccessConfig.purpose/.action). */\n  routePurpose?: string;\n  routeAction?: string;\n  /** Results of the merchant's extractPurpose/extractAction options. */\n  customPurpose?: string;\n  hasCustomPurposeExtractor?: boolean;\n  customAction?: string;\n  hasCustomActionExtractor?: boolean;\n}\n\nexport interface HttpPdlssResolution {\n  purpose: string;\n  action: string;\n  purposeSource: HttpPurposeSource;\n  actionSource: HttpActionSource;\n}\n\n/**\n * Normalize an `X-Astra-Purpose` header value.\n *  - colon form `\"category:action\"` (legacy wire shape): take the prefix; the\n *    remainder is free-text and exists in no vocabulary — discard it and let\n *    the method table supply the action (matches pre-3.1.0 discard behavior).\n *  - dotted form `\"shopping.purchase\"` (the shape older docs taught): prefix\n *    becomes the purpose, the WHOLE token becomes an action candidate.\n *  - bare token: purpose verbatim.\n */\nexport function normalizePurposeHeader(value: string): {\n  purpose: string;\n  actionCandidate?: string;\n} {\n  const colon = value.indexOf(':');\n  if (colon >= 0) {\n    return { purpose: value.slice(0, colon) };\n  }\n  const dot = value.indexOf('.');\n  if (dot > 0 && dot < value.length - 1) {\n    return { purpose: value.slice(0, dot), actionCandidate: value };\n  }\n  return { purpose: value };\n}\n\n/**\n * Resolve the {purpose, action} pair for one HTTP request.\n *\n * Precedence (both axes):\n *   action:  route mapping → extractAction option → X-Astra-Action header →\n *            candidate from a dotted X-Astra-Purpose → pinned method table\n *   purpose: route mapping → extractPurpose option → X-Astra-Purpose →\n *            legacy x-purpose / ?purpose → category prefix of the resolved\n *            action → 'data'\n *\n * A configured custom extractor masks the header/legacy/query steps of its\n * axis (it replaces the default chain, as extractPurpose always has); when it\n * returns undefined the axis falls through to the table/prefix fallback.\n * The route mapping is merchant policy fetched from the dashboard — it\n * outranks agent-supplied headers the way MCP toolGates do.\n */\nexport function resolveHttpPdlss(input: HttpPdlssInput): HttpPdlssResolution {\n  const fromHeader = input.astraPurpose ? normalizePurposeHeader(input.astraPurpose) : undefined;\n\n  // ── Action axis ──\n  let action: string;\n  let actionSource: HttpActionSource;\n  if (input.routeAction) {\n    action = input.routeAction;\n    actionSource = 'route_config';\n  } else if (input.hasCustomActionExtractor && input.customAction) {\n    action = input.customAction;\n    actionSource = 'custom_extractor';\n  } else if (!input.hasCustomActionExtractor && input.astraAction) {\n    action = input.astraAction;\n    actionSource = 'header';\n  } else if (!input.hasCustomActionExtractor && fromHeader?.actionCandidate) {\n    action = fromHeader.actionCandidate;\n    actionSource = 'purpose_header_derived';\n  } else {\n    action = actionForHttpMethod(input.method);\n    actionSource = 'method_table';\n  }\n\n  // ── Purpose axis ──\n  let purpose: string | undefined;\n  let purposeSource: HttpPurposeSource | undefined;\n  if (input.routePurpose) {\n    purpose = input.routePurpose;\n    purposeSource = 'route_config';\n  } else if (input.hasCustomPurposeExtractor) {\n    if (input.customPurpose) {\n      purpose = input.customPurpose;\n      purposeSource = 'custom_extractor';\n    }\n  } else if (fromHeader) {\n    purpose = fromHeader.purpose;\n    purposeSource = 'header';\n  } else if (input.legacyPurpose) {\n    purpose = input.legacyPurpose;\n    purposeSource = 'legacy_header';\n  } else if (input.queryPurpose) {\n    purpose = input.queryPurpose;\n    purposeSource = 'query';\n  }\n\n  if (!purpose) {\n    // Keep the pair coherent: an agent that sent only X-Astra-Action (or a\n    // route that mapped only the action) gets that action's own category.\n    const dot = action.indexOf('.');\n    if (dot > 0) {\n      purpose = action.slice(0, dot);\n      purposeSource = 'action_derived';\n    } else {\n      purpose = DEFAULT_HTTP_PURPOSE;\n      purposeSource = 'transport_default';\n    }\n  }\n\n  return { purpose, action, purposeSource: purposeSource!, actionSource };\n}\n"],"mappings":";AAiBO,IAAM,2BAA6D;AAAA,EACxE,KAAK;AAAA,EACL,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,KAAK;AAAA,EACL,OAAO;AAAA,EACP,QAAQ;AACV;AAGO,IAAM,sBAAsB;AAG5B,IAAM,uBAAuB;AAE7B,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,yBAAyB,OAAO,YAAY,CAAC,KAAK;AAC3D;AAsDO,SAAS,uBAAuB,OAGrC;AACA,QAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,MAAI,SAAS,GAAG;AACd,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,KAAK,EAAE;AAAA,EAC1C;AACA,QAAM,MAAM,MAAM,QAAQ,GAAG;AAC7B,MAAI,MAAM,KAAK,MAAM,MAAM,SAAS,GAAG;AACrC,WAAO,EAAE,SAAS,MAAM,MAAM,GAAG,GAAG,GAAG,iBAAiB,MAAM;AAAA,EAChE;AACA,SAAO,EAAE,SAAS,MAAM;AAC1B;AAkBO,SAAS,iBAAiB,OAA4C;AAC3E,QAAM,aAAa,MAAM,eAAe,uBAAuB,MAAM,YAAY,IAAI;AAGrF,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,aAAa;AACrB,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,MAAM,4BAA4B,MAAM,cAAc;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,MAAM,aAAa;AAC/D,aAAS,MAAM;AACf,mBAAe;AAAA,EACjB,WAAW,CAAC,MAAM,4BAA4B,YAAY,iBAAiB;AACzE,aAAS,WAAW;AACpB,mBAAe;AAAA,EACjB,OAAO;AACL,aAAS,oBAAoB,MAAM,MAAM;AACzC,mBAAe;AAAA,EACjB;AAGA,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,cAAc;AACtB,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,2BAA2B;AAC1C,QAAI,MAAM,eAAe;AACvB,gBAAU,MAAM;AAChB,sBAAgB;AAAA,IAClB;AAAA,EACF,WAAW,YAAY;AACrB,cAAU,WAAW;AACrB,oBAAgB;AAAA,EAClB,WAAW,MAAM,eAAe;AAC9B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB,WAAW,MAAM,cAAc;AAC7B,cAAU,MAAM;AAChB,oBAAgB;AAAA,EAClB;AAEA,MAAI,CAAC,SAAS;AAGZ,UAAM,MAAM,OAAO,QAAQ,GAAG;AAC9B,QAAI,MAAM,GAAG;AACX,gBAAU,OAAO,MAAM,GAAG,GAAG;AAC7B,sBAAgB;AAAA,IAClB,OAAO;AACL,gBAAU;AACV,sBAAgB;AAAA,IAClB;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,QAAQ,eAA+B,aAAa;AACxE;","names":[]}

package/dist/adapters/mcp.d.mts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { a as AccessLevel, G as GatewayConfig, w as VerificationResult } from '../types-BntuzEEn.mjs';
+import { a as AccessLevel, G as GatewayConfig, x as VerificationResult } from '../types-r850cOt0.mjs';
 import '../metadata-capture.mjs';
 
 /**
@@ -81,7 +81,7 @@ interface ParsedMcpRequest {
      */
     agentIdFromBody?: string;
     /**
-     * Round-12 (F19) + round-13 (R13-1): purpose extracted from the MCP body
+     * Purpose extracted from the MCP body
      * with the symmetric precedence chain. Sourced from `_meta.astrasync.purpose`
      * (canonical SDK location) OR `params.arguments.purpose` (legacy /
      * conventional callers). The discriminator is on `purposeSourceFromBody`.
@@ -92,7 +92,7 @@ interface ParsedMcpRequest {
     /** Which body location resolved `purposeFromBody`. */
     purposeSourceFromBody?: 'meta' | 'tool_argument';
     /**
-     * Round-13 (R13-2): action extracted from the MCP body with the same
+     * Action extracted from the MCP body with the same
      * symmetric chain as purpose. Sourced from `_meta.astrasync.action`
      * (canonical) OR `params.arguments.action` (legacy). Adapter combines
      * with the `X-Astra-Action` header (header wins) before mapping; final
@@ -130,15 +130,24 @@ declare function parseMcpJsonRpc(body: unknown): ParsedMcpRequest | null;
  *   - `purpose` defaults to `undefined` (backend evaluator applies
  *     skip-when-undefined). Per-tool overrides via `toolGates` config let
  *     merchants declare the semantic purpose each tool fulfils.
- *   - `action` is the bare tool name for `tools/call`, the JSON-RPC method
- *     otherwise. Header/body overrides available.
+ *   - `action` comes only from declarations (toolGate config, header, or
+ *     body). For `tools/call` with none declared it is `undefined` —
+ *     evaluation is purpose-only, because a raw tool name is a transport
+ *     token, not a PDLSS action, and sending it as one guarantees an
+ *     action-policy mismatch. For other JSON-RPC methods the method string
+ *     is used.
  */
 interface McpPdlssMapping {
     purpose: string | undefined;
-    action: string;
+    /**
+     * `undefined` when a `tools/call` request declared no action anywhere —
+     * the verify-access call then evaluates purpose-only. Tool names never
+     * travel as PDLSS actions.
+     */
+    action: string | undefined;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer' | undefined;
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -150,11 +159,13 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
- * symmetry with purpose):
+ * Action precedence (3.1.0 — toolGate override added for
+ * symmetry with purpose; 4.1.0 — the bare-tool-name fallback for
+ * `tools/call` was removed):
  *   - `toolGate.action` authoritative → header → body `_meta` → body
- *     `arguments` → bare tool name / method (transport_layer, unchanged —
- *     bare tool names are legitimate enumerated actions, never aliased).
+ *     `arguments` → then: `undefined` for `tools/call` (purpose-only
+ *     evaluation — tool names are transport tokens, never PDLSS actions),
+ *     or the JSON-RPC method string for other methods (transport_layer).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
@@ -167,7 +178,7 @@ declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, heade
 /**
  * Recommended minimum access level per method type. The MCP middleware uses
  * this to split low-risk handshake / introspection traffic from high-risk
- * tool execution — defect (a) from the cohort-3 review.
+ * tool execution.
  *
  *   - `initialize` / `notifications/initialized`        → `none`     (handshake must work for unregistered probes)
  *   - `tools/list` / `prompts/list` / `resources/list`  → `none`     (introspection is public-surface)
@@ -218,12 +229,16 @@ declare function mcpRiskTier(parsed: ParsedMcpRequest): AccessLevel;
  *   createMcpMiddleware({
  *     apiBaseUrl: 'https://astrasync.ai/api',
  *     apiKey: process.env.ASTRASYNC_API_KEY,
- *     // Optional per-tool overrides — tools not listed get the default tier
- *     // from `mcpRiskTier` (`tools/call` → 'standard').
+ *     // Per-tool gates — tools not listed get the default tier from
+ *     // `mcpRiskTier` (`tools/call` → 'standard'). Use the object form:
+ *     // gated tools need a PDLSS purpose (and ideally an action).
  *     toolGates: {
- *       start_checkout: 'standard',
- *       confirm_purchase: 'full',
- *       browse_catalog: 'read-only',
+ *       browse_catalog: { minAccessLevel: 'read-only', purpose: 'shopping' },
+ *       start_checkout: {
+ *         minAccessLevel: 'standard',
+ *         purpose: 'shopping',
+ *         action: 'shopping.purchase',
+ *       },
  *     },
  *   }),
  *   yourMcpServerHandler,
@@ -246,10 +261,11 @@ declare global {
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
- * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * When `action` is set (symmetric with `purpose`), it is
  * authoritative over `X-Astra-Action` / body declarations, letting the
  * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
- * whose callers would otherwise fall to the bare tool-name transport default.
+ * whose callers would otherwise leave the action undeclared (purpose-only
+ * evaluation — raw tool names never travel as PDLSS actions).
  *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
@@ -265,26 +281,31 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Per-tool gating for `tools/call` invocations. Tools not listed inherit
      * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
      *
-     * Accepts both the shorthand access-level string and the full object shape.
-     * NOTE (3.2.0): the access-level band no longer gates, and a gated `tools/call`
-     * must carry a resolvable PDLSS **purpose** (the backend requires it). So the
-     * bare string shorthand — which carries no purpose — only works if the caller
-     * supplies the purpose another way (an `X-Astra-Purpose` header, or
-     * `params._meta.astrasync.purpose`); otherwise the call fails fast with a
-     * `PDLSS_PURPOSE_REQUIRED` 400. Prefer the **object form with `purpose`**:
+     * Use the **object form** — it lets the merchant declare the PDLSS
+     * `purpose` (required for any gated tool: the backend rejects gated calls
+     * with no resolvable purpose) and pin a dotted-verb `action`:
      * ```typescript
      * toolGates: {
-     *   browse_catalog: 'read-only',                 // shorthand — purpose must come
-     *                                                // from a header / _meta, else 400
-     *   list_products:  { purpose: 'shopping',       // object form (recommended)
+     *   list_products:  { minAccessLevel: 'read-only',
+     *                     purpose: 'shopping',
      *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
-     *   start_checkout: { purpose: 'shopping',
+     *   start_checkout: { minAccessLevel: 'standard',
+     *                     purpose: 'shopping',
      *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }
      * ```
      *
+     * The bare access-level string shorthand (`browse_catalog: 'read-only'`)
+     * is a legacy form and a known footgun: it carries no purpose, so the call
+     * only succeeds when the AGENT declares one (an `X-Astra-Purpose` header
+     * or `params._meta.astrasync.purpose`) — otherwise it fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400. It also declares no action, so evaluation
+     * is purpose-only (the SDK never sends the raw tool name as the PDLSS
+     * action). `createMcpMiddleware` logs a warning at construction for every
+     * bare-string gate.
+     *
      * When `tools/call` arrives for a tool not declared in `toolGates`, the SDK
      * falls back to a risk-tier default based on the method classification
      * (`mcpRiskTier`). For `tools/call` the fallback is `'standard'`. Best
@@ -324,7 +345,7 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
      * verify-access when it carries a recent marker for the resolved agent.
      *
-     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13** (audit F-A1-01). The marker
+     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13.** The marker
      * is plaintext semicolon-delimited with no HMAC, so any client that sets
      * the header (with the right format + fresh timestamp + matching ASTRA-id)
      * skipped verify-access entirely. The per-process verify-access result
@@ -335,8 +356,8 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * the header AND you trust the network path between hops (mTLS, internal
      * VPC, etc.). For most installs, leave at the safe default.
      *
-     * Future SDK release will either remove this option entirely OR add HMAC
-     * signing to the marker. Tracked as round-19+ work.
+     * A future SDK release will either remove this option entirely OR add
+     * HMAC signing to the marker.
      */
     trustVerifiedHop?: boolean;
     /** Window for accepting an upstream verified-hop marker. Default 60_000ms. */
@@ -352,9 +373,8 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Posture when the MCP middleware itself throws an internal error.
      * Default `'open'` for backward compatibility in SDK 2.4.13. Shadow logs
      * record what WOULD be denied with `failOnError: 'closed'` so merchants
-     * can grep correlationId for impact analysis during the 1-week
-     * observation window. Default flips to `'closed'` in a follow-up release.
-     * Audit F-A1-06.
+     * can grep correlationId for impact analysis during the observation
+     * window. Default flips to `'closed'` in a follow-up release.
      */
     failOnError?: 'open' | 'closed';
 }

package/dist/adapters/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { a as AccessLevel, G as GatewayConfig, w as VerificationResult } from '../types-SDu4Llbe.js';
+import { a as AccessLevel, G as GatewayConfig, x as VerificationResult } from '../types-sMxBT-nM.js';
 import '../metadata-capture.js';
 
 /**
@@ -81,7 +81,7 @@ interface ParsedMcpRequest {
      */
     agentIdFromBody?: string;
     /**
-     * Round-12 (F19) + round-13 (R13-1): purpose extracted from the MCP body
+     * Purpose extracted from the MCP body
      * with the symmetric precedence chain. Sourced from `_meta.astrasync.purpose`
      * (canonical SDK location) OR `params.arguments.purpose` (legacy /
      * conventional callers). The discriminator is on `purposeSourceFromBody`.
@@ -92,7 +92,7 @@ interface ParsedMcpRequest {
     /** Which body location resolved `purposeFromBody`. */
     purposeSourceFromBody?: 'meta' | 'tool_argument';
     /**
-     * Round-13 (R13-2): action extracted from the MCP body with the same
+     * Action extracted from the MCP body with the same
      * symmetric chain as purpose. Sourced from `_meta.astrasync.action`
      * (canonical) OR `params.arguments.action` (legacy). Adapter combines
      * with the `X-Astra-Action` header (header wins) before mapping; final
@@ -130,15 +130,24 @@ declare function parseMcpJsonRpc(body: unknown): ParsedMcpRequest | null;
  *   - `purpose` defaults to `undefined` (backend evaluator applies
  *     skip-when-undefined). Per-tool overrides via `toolGates` config let
  *     merchants declare the semantic purpose each tool fulfils.
- *   - `action` is the bare tool name for `tools/call`, the JSON-RPC method
- *     otherwise. Header/body overrides available.
+ *   - `action` comes only from declarations (toolGate config, header, or
+ *     body). For `tools/call` with none declared it is `undefined` —
+ *     evaluation is purpose-only, because a raw tool name is a transport
+ *     token, not a PDLSS action, and sending it as one guarantees an
+ *     action-policy mismatch. For other JSON-RPC methods the method string
+ *     is used.
  */
 interface McpPdlssMapping {
     purpose: string | undefined;
-    action: string;
+    /**
+     * `undefined` when a `tools/call` request declared no action anywhere —
+     * the verify-access call then evaluates purpose-only. Tool names never
+     * travel as PDLSS actions.
+     */
+    action: string | undefined;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer' | undefined;
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -150,11 +159,13 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
- * symmetry with purpose):
+ * Action precedence (3.1.0 — toolGate override added for
+ * symmetry with purpose; 4.1.0 — the bare-tool-name fallback for
+ * `tools/call` was removed):
  *   - `toolGate.action` authoritative → header → body `_meta` → body
- *     `arguments` → bare tool name / method (transport_layer, unchanged —
- *     bare tool names are legitimate enumerated actions, never aliased).
+ *     `arguments` → then: `undefined` for `tools/call` (purpose-only
+ *     evaluation — tool names are transport tokens, never PDLSS actions),
+ *     or the JSON-RPC method string for other methods (transport_layer).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
@@ -167,7 +178,7 @@ declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, heade
 /**
  * Recommended minimum access level per method type. The MCP middleware uses
  * this to split low-risk handshake / introspection traffic from high-risk
- * tool execution — defect (a) from the cohort-3 review.
+ * tool execution.
  *
  *   - `initialize` / `notifications/initialized`        → `none`     (handshake must work for unregistered probes)
  *   - `tools/list` / `prompts/list` / `resources/list`  → `none`     (introspection is public-surface)
@@ -218,12 +229,16 @@ declare function mcpRiskTier(parsed: ParsedMcpRequest): AccessLevel;
  *   createMcpMiddleware({
  *     apiBaseUrl: 'https://astrasync.ai/api',
  *     apiKey: process.env.ASTRASYNC_API_KEY,
- *     // Optional per-tool overrides — tools not listed get the default tier
- *     // from `mcpRiskTier` (`tools/call` → 'standard').
+ *     // Per-tool gates — tools not listed get the default tier from
+ *     // `mcpRiskTier` (`tools/call` → 'standard'). Use the object form:
+ *     // gated tools need a PDLSS purpose (and ideally an action).
  *     toolGates: {
- *       start_checkout: 'standard',
- *       confirm_purchase: 'full',
- *       browse_catalog: 'read-only',
+ *       browse_catalog: { minAccessLevel: 'read-only', purpose: 'shopping' },
+ *       start_checkout: {
+ *         minAccessLevel: 'standard',
+ *         purpose: 'shopping',
+ *         action: 'shopping.purchase',
+ *       },
  *     },
  *   }),
  *   yourMcpServerHandler,
@@ -246,10 +261,11 @@ declare global {
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
- * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * When `action` is set (symmetric with `purpose`), it is
  * authoritative over `X-Astra-Action` / body declarations, letting the
  * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
- * whose callers would otherwise fall to the bare tool-name transport default.
+ * whose callers would otherwise leave the action undeclared (purpose-only
+ * evaluation — raw tool names never travel as PDLSS actions).
  *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
@@ -265,26 +281,31 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Per-tool gating for `tools/call` invocations. Tools not listed inherit
      * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
      *
-     * Accepts both the shorthand access-level string and the full object shape.
-     * NOTE (3.2.0): the access-level band no longer gates, and a gated `tools/call`
-     * must carry a resolvable PDLSS **purpose** (the backend requires it). So the
-     * bare string shorthand — which carries no purpose — only works if the caller
-     * supplies the purpose another way (an `X-Astra-Purpose` header, or
-     * `params._meta.astrasync.purpose`); otherwise the call fails fast with a
-     * `PDLSS_PURPOSE_REQUIRED` 400. Prefer the **object form with `purpose`**:
+     * Use the **object form** — it lets the merchant declare the PDLSS
+     * `purpose` (required for any gated tool: the backend rejects gated calls
+     * with no resolvable purpose) and pin a dotted-verb `action`:
      * ```typescript
      * toolGates: {
-     *   browse_catalog: 'read-only',                 // shorthand — purpose must come
-     *                                                // from a header / _meta, else 400
-     *   list_products:  { purpose: 'shopping',       // object form (recommended)
+     *   list_products:  { minAccessLevel: 'read-only',
+     *                     purpose: 'shopping',
      *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
-     *   start_checkout: { purpose: 'shopping',
+     *   start_checkout: { minAccessLevel: 'standard',
+     *                     purpose: 'shopping',
      *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }
      * ```
      *
+     * The bare access-level string shorthand (`browse_catalog: 'read-only'`)
+     * is a legacy form and a known footgun: it carries no purpose, so the call
+     * only succeeds when the AGENT declares one (an `X-Astra-Purpose` header
+     * or `params._meta.astrasync.purpose`) — otherwise it fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400. It also declares no action, so evaluation
+     * is purpose-only (the SDK never sends the raw tool name as the PDLSS
+     * action). `createMcpMiddleware` logs a warning at construction for every
+     * bare-string gate.
+     *
      * When `tools/call` arrives for a tool not declared in `toolGates`, the SDK
      * falls back to a risk-tier default based on the method classification
      * (`mcpRiskTier`). For `tools/call` the fallback is `'standard'`. Best
@@ -324,7 +345,7 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
      * verify-access when it carries a recent marker for the resolved agent.
      *
-     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13** (audit F-A1-01). The marker
+     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13.** The marker
      * is plaintext semicolon-delimited with no HMAC, so any client that sets
      * the header (with the right format + fresh timestamp + matching ASTRA-id)
      * skipped verify-access entirely. The per-process verify-access result
@@ -335,8 +356,8 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * the header AND you trust the network path between hops (mTLS, internal
      * VPC, etc.). For most installs, leave at the safe default.
      *
-     * Future SDK release will either remove this option entirely OR add HMAC
-     * signing to the marker. Tracked as round-19+ work.
+     * A future SDK release will either remove this option entirely OR add
+     * HMAC signing to the marker.
      */
     trustVerifiedHop?: boolean;
     /** Window for accepting an upstream verified-hop marker. Default 60_000ms. */
@@ -352,9 +373,8 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Posture when the MCP middleware itself throws an internal error.
      * Default `'open'` for backward compatibility in SDK 2.4.13. Shadow logs
      * record what WOULD be denied with `failOnError: 'closed'` so merchants
-     * can grep correlationId for impact analysis during the 1-week
-     * observation window. Default flips to `'closed'` in a follow-up release.
-     * Audit F-A1-06.
+     * can grep correlationId for impact analysis during the observation
+     * window. Default flips to `'closed'` in a follow-up release.
      */
     failOnError?: 'open' | 'closed';
 }