getaxonflow
diff --git a/‎.lint_baselines/transformer_coverage.json‎
Lines changed: 1 addition & 2 deletions b/‎.lint_baselines/transformer_coverage.json‎
Lines changed: 1 addition & 2 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 34 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎scripts/wire-shape/lib.js‎
Lines changed: 156 additions & 3 deletions b/‎scripts/wire-shape/lib.js‎
Lines changed: 156 additions & 3 deletions
diff --git a/‎scripts/wire-shape/refresh.js‎
Lines changed: 8 additions & 1 deletion b/‎scripts/wire-shape/refresh.js‎
Lines changed: 8 additions & 1 deletion
diff --git a/‎scripts/wire-shape/validate.js‎
Lines changed: 36 additions & 1 deletion b/‎scripts/wire-shape/validate.js‎
Lines changed: 36 additions & 1 deletion
@@ -2,7 +2,6 @@
   "_comment": "Pre-existing transformer-coverage findings. Generated by scripts/transformer-coverage/check.js --write-baseline. CI fails on any finding NOT listed here. Burn this list down via targeted PRs that either populate the missing keys in the transformer or mark them @deprecated on the type definition.",
   "findings": [
     "src/client.ts:executePlan:PlanExecutionResponse:policyInfo",
-    "src/client.ts:getPlanStatus:PlanExecutionResponse:policyInfo,workflowId",
-    "src/client.ts:resumePlan:ResumePlanResponse:nextStep,nextStepName,stepResult,totalSteps,workflowId"
+    "src/client.ts:getPlanStatus:PlanExecutionResponse:policyInfo,workflowId"
   ]
 }
@@ -7,10 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`WebhookSubscription.secret`** — HMAC-SHA256 signing key now exposed on the response from `createWebhook`. Required to verify the `X-AxonFlow-Signature` header on inbound webhook deliveries; without it, callers couldn't validate payload authenticity. Also adds `org_id` and `tenant_id` (ownership scoping).
+- **`StepGateRequest`** carries `cost_usd`, `tokens_in`, `tokens_out` so budget-based policies can evaluate gate-time cost estimates.
+- **`StepGateResponse.decision_id`** — unique audit correlator that links a gate response to its audit row (previously absent on the SDK, present on the wire).
+- **`StepGateResponse.policies_evaluated` / `policies_matched`** (snake_case wire-canonical). The previous camelCase `policiesEvaluated` / `policiesMatched` always read `undefined` because the gate decoder is JSON.parse passthrough; both forms are kept (camel marked `@deprecated`) to preserve type-compat. Removed in v7.
+- **`ListWorkflowsResponse.limit` / `offset`** — pagination echo, surfaced on the response.
+- **`StaticPolicy.policy_id` / `priority` / `has_override`** — wire-canonical fields surfaced. `hasOverride` (camelCase) kept as `@deprecated` alias; it has always read `undefined` against the JSON.parse passthrough decoder.
+- **`CreateStaticPolicyRequest.priority` / `tags`** and **`UpdateStaticPolicyRequest.priority` / `tags`** — match the spec.
+- **`UpdatePlanRequest.metadata`** — accept arbitrary plan metadata, opaque to the platform.
+- **`UsageBreakdownItem.group_by`** — dimension name (provider/model/agent/etc.) is now exposed on each item.
+- **`BudgetAlert.acknowledged`** — alert dismissal flag.
+- **`Budget.org_id` / `tenant_id`** — ownership scoping.
+- **`UsageRecord`** gains `created_at`, `success`, `error_message`, `latency_ms`, `team_id`, `tenant_id`, `user_id`, `workflow_id` to match the wire. The legacy `timestamp` field is `@deprecated`; the decoder reads `r.timestamp`, but the wire emits `created_at`, so `timestamp` has always read `undefined`.
+- **`WorkflowStatusResponse.metadata`** — arbitrary workflow metadata.
+- **`CreateWorkflowResponse.started_at`** — wire-canonical timestamp. Legacy `created_at` and `source` are `@deprecated`; they have always read `undefined` (wire emits neither).
+- **`ExecutionSnapshot.retryCount`** — number of retry attempts on a step.
+- **`Finding.article`** — regulatory article reference (e.g. MAS FEAT principle number).
+- **`PolicyOverride.id` / `enabled_override`** — wire-canonical fields. `active` is `@deprecated`; the wire emits `enabled_override`, so `active` has always read `undefined`.
+- **`PolicyVersion.id` / `policy_id` / `change_summary` / `snapshot`** — match the wire shape (versions are immutable snapshots, not before/after diffs). `changeDescription`, `previousValues`, `newValues` are `@deprecated` orphan-reads.
+- **`DynamicPolicyMatch.message`** — wire-canonical name. `reason` is `@deprecated` (read `undefined` today).
+- **`ExfiltrationCheckInfo.exceeded` / `limit_type`** — match the wire. `within_limits` is `@deprecated`.
+- **`CancelPlanResponse.success`** — wire-canonical boolean. `message` is `@deprecated` (orphan read).
+- **`PlanResponse`** gains the wire top-level fields `success`, `version`, `result`, `error`, `workflow_execution_id`, `policy_info`. The decoder is JSON.parse passthrough, so consumers can now read these directly.
+- **`EffectivePoliciesResponse`** gains the tier-stratified wire shape (`static`, `dynamic`, `tenant_id`, `organization_id`, `computed_at`). Legacy `policies` flat array and `inheritance` summary kept as SDK-side conveniences.
+- **`Policy`** gains the rich wire shape (`policy_id`, `category`, `tier`, `pattern`, `severity`, `action`, `actions`, `conditions`, `description`, `organization_id`, `tenant_id`, `created_at`/`_by`, `updated_at`/`_by`, `version`). The legacy rules-only shape has only seen ~5 of 21 wire fields.
+- **`ResumePlanResponse.result`** — final aggregated result (canonical wire field). The interface previously declared 5 fields (`workflowId`, `message`, `stepResult`, `nextStep`, `nextStepName`, `totalSteps`) that the transformer never populated; all 5 are now `@deprecated`.
+
 ### Fixed
 
 - Telemetry path is bounded at `TELEMETRY_TIMEOUT_MS` (3s) total; the `/health` probe and checkpoint POST share a single monotonic deadline instead of stacking independent timeouts. Aligns with python/go/java SDKs.
 
+### Notes
+
+The above is an audit-driven sweep against the wire-shape contract gate. The validator now snake_case-normalizes TS interface field names against transformer evidence in `client.ts` (matching what pydantic alias / Go `json:"…"` tag / Java `@JsonProperty(…)` do natively in the other SDKs). The `@deprecated` marks above are set on fields that historically read `undefined` against the JSON.parse-passthrough decoder paths — keeping the typed name kept compile-time compat for callers that referenced the now-dead names. Removal scheduled for v7.
+
+Two platform-side spec corrections filed alongside this work, for issues the audit surfaced where the spec was wrong (server emits the SDK's name): `AISystemRegistry.materiality_classification` (axonflow-enterprise#1708), `DynamicPolicyInfo` schema completely wrong shape (axonflow-enterprise#1709). No SDK change for those — the SDK is correct.
+
 ## [5.6.0] - 2026-04-22
 
 ### Added
 
@@ -27,8 +27,48 @@ const YAML = require('yaml');
 
 const SDK_ROOT = path.resolve(__dirname, '..', '..');
 const SRC_DIR = path.join(SDK_ROOT, 'src');
+const CLIENT_TS = path.join(SRC_DIR, 'client.ts');
 const BASELINE_PATH = path.join(SDK_ROOT, 'tests', 'fixtures', 'wire-shape-baseline.json');
 
+/**
+ * Convert a camelCase identifier to snake_case. Handles three boundaries:
+ * - acronym → word: `AIRequest` → `AI_Request` (preserves consecutive caps)
+ * - lowercase → uppercase: `myField` → `my_Field`
+ * - lowercase letter → digit: `per1k` → `per_1k`
+ *
+ * Digit → lowercase letter is intentionally NOT a boundary so that
+ * `1k` stays as a unit-suffix (matches OpenAPI convention `input_per_1k`,
+ * `tokens_per_1k`, etc.).
+ */
+function toSnakeCase(s) {
+  return s
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/([a-z])(\d)/g, '$1_$2')
+    .toLowerCase();
+}
+
+/**
+ * Read src/client.ts (the hand-rolled snake_case ↔ camelCase
+ * transformer surface) and return a Set of every snake_case identifier
+ * that appears anywhere in the file. Used as the safety-net check for
+ * the case-normalizer below: we only treat a TS interface field as
+ * "bridged to its snake_case wire form" if the snake form actually
+ * appears in client.ts. Without this guard a missing transformer would
+ * pass the gate by silent normalization.
+ */
+function loadTransformerEvidence() {
+  if (!fs.existsSync(CLIENT_TS)) {
+    return new Set();
+  }
+  const content = fs.readFileSync(CLIENT_TS, 'utf8');
+  // Snake-case-shaped identifier: starts with a lowercase letter, must
+  // contain at least one underscore, lowercase + digits + underscores
+  // only. Avoids matching uppercase constants like `MAX_RETRIES`.
+  const matches = content.match(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g) || [];
+  return new Set(matches);
+}
+
 /**
  * Load every *.yaml in specDir. Returns {merged, crossSpecDuplicates,
  * intraFileDuplicates}.
@@ -174,7 +214,84 @@ function discoverSDKInterfaces() {
     );
     ts.forEachChild(sourceFile, (node) => collectTopLevelTypes(node, result));
   });
-  return result;
+  return canonicalizeWireNames(result);
+}
+
+/**
+ * Canonicalize each TS interface field name to its on-the-wire form.
+ *
+ * The TS SDK convention is camelCase TS properties + hand-rolled
+ * snake_case transformers in client.ts. Comparing TS in-memory names
+ * to OpenAPI wire names produces false drift (cosmetic camelCase ↔
+ * snake_case mismatches that the transformers already bridge).
+ *
+ * For each TS field name:
+ *   - If it's already snake_case, keep it.
+ *   - If its snake_case form appears in client.ts (transformer
+ *     evidence), output the snake_case form.
+ *   - If it's camelCase but no transformer evidence is found, emit a
+ *     console.warn and KEEP the camelCase name. The validator will
+ *     then surface this as drift, which is the correct behavior — a
+ *     camelCase TS field with no bridging transformer means the SDK
+ *     is wired to read/write camelCase on the wire, which won't match
+ *     a snake_case OpenAPI spec.
+ *
+ * Mirrors the wire-name extraction the Python (pydantic alias),
+ * Go (`json:"…"` tag), and Java (`@JsonProperty(…)`) discovery layers
+ * already do natively.
+ */
+function canonicalizeWireNames(typeMap) {
+  const evidence = loadTransformerEvidence();
+  const out = {};
+  // Per-type unbridged tracker — used downstream to suppress noise on
+  // SDK-internal config types (every field camelCase, none bridged) and
+  // surface only the wire-bound types where a transformer is missing.
+  const unbridgedByType = {};
+  for (const [typeName, fields] of Object.entries(typeMap)) {
+    const canonical = new Set();
+    let bridged = 0;
+    const unbridgedHere = [];
+    for (const field of fields) {
+      const snake = toSnakeCase(field);
+      if (snake === field) {
+        // Already snake_case or a single word — no normalization needed.
+        canonical.add(field);
+        continue;
+      }
+      if (evidence.has(snake)) {
+        canonical.add(snake);
+        bridged += 1;
+      } else {
+        unbridgedHere.push(field);
+        canonical.add(field);
+      }
+    }
+    out[typeName] = [...canonical].sort();
+    // Only flag a type as having unbridged fields if at least one OTHER
+    // field in the same type IS bridged. If no field is bridged, the
+    // type is almost certainly SDK-internal (configs, options, adapter
+    // metadata) and the whole type isn't wire-bound — there's nothing
+    // for a transformer to bridge against.
+    if (unbridgedHere.length > 0 && bridged > 0) {
+      unbridgedByType[typeName] = unbridgedHere;
+    }
+  }
+  const unbridgedFlat = Object.entries(unbridgedByType).flatMap(([t, fs]) =>
+    fs.map((f) => `${t}.${f}`),
+  );
+  if (unbridgedFlat.length > 0) {
+    console.warn(
+      `wire-shape: ${unbridgedFlat.length} TS field(s) on wire-bound types ` +
+        `are camelCase with no snake_case transformer evidence in client.ts; ` +
+        `keeping camelCase (may surface as drift):\n  ${unbridgedFlat
+          .slice(0, 20)
+          .join('\n  ')}` +
+        (unbridgedFlat.length > 20
+          ? `\n  ... and ${unbridgedFlat.length - 20} more`
+          : ''),
+    );
+  }
+  return out;
 }
 
 function walkTsFiles(dir, cb) {
@@ -220,6 +337,31 @@ function hasExportModifier(node) {
 }
 
 function extractInterfaceProps(iface) {
+  // A `heritageClauses` (e.g. `interface Foo extends Bar`) means the
+  // interface inherits members from its parents that we won't see by
+  // walking iface.members alone. The wire-shape gate would then
+  // under-report fields and silently miss drift on inherited
+  // properties. The TS SDK has no such interfaces today; flag it
+  // loudly the first time one appears so coverage gets resolved
+  // before it ships, instead of slipping past as invisible
+  // under-counting.
+  if (iface.heritageClauses && iface.heritageClauses.length > 0) {
+    const parents = [];
+    for (const clause of iface.heritageClauses) {
+      for (const t of clause.types || []) {
+        const expr = t.expression;
+        if (expr && ts.isIdentifier(expr)) {
+          parents.push(expr.text);
+        }
+      }
+    }
+    console.warn(
+      `wire-shape: interface ${iface.name.text} extends [${parents.join(', ')}]; ` +
+        'inherited fields are NOT walked. Add explicit field flattening to ' +
+        'scripts/wire-shape/lib.js::extractInterfaceProps before merging an ' +
+        'extending wire interface, or wire-shape coverage will be incomplete.',
+    );
+  }
   const names = [];
   for (const member of iface.members) {
     const name = propertyName(member);
@@ -290,8 +432,19 @@ function writeBaseline(baseline) {
     fs.mkdirSync(dir, { recursive: true });
   }
   const tmp = `${BASELINE_PATH}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(baseline, null, 2) + '\n');
-  fs.renameSync(tmp, BASELINE_PATH);
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(baseline, null, 2) + '\n');
+    fs.renameSync(tmp, BASELINE_PATH);
+  } catch (e) {
+    // Don't leave a `.tmp.<pid>` sidecar behind — the next run from
+    // the same PID would collide and confuse a future writer.
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* tmp may not exist yet; ignore */
+    }
+    throw e;
+  }
 }
 
 function difference(a, b) {
 
@@ -44,7 +44,14 @@ function main() {
   let specsDir = null;
   let explicitSha = null;
   for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === '--sha' && i + 1 < args.length) {
+    if (args[i] === '--sha') {
+      if (i + 1 >= args.length) {
+        // `--sha` as the last token used to be silently consumed as
+        // a positional `specsDir`, masking the missing value. Fail
+        // loudly instead.
+        console.error('error: --sha requires a value (e.g. --sha bf1ca22…)');
+        process.exit(2);
+      }
       explicitSha = args[i + 1];
       i += 1;
     } else if (!specsDir) {
 
@@ -104,6 +104,19 @@ function main() {
       crossProblems.push(lines.join('\n'));
     }
   }
+  // Reverse pass: a baselined cross-spec divergence that is no longer
+  // observed must be removed from the baseline. Otherwise the stale
+  // fingerprint shields a future reintroduction of the same old
+  // incompatible shape from the gate. (Mirrors Gate 2's reverse pass
+  // for intra_file_duplicates.)
+  for (const name of Object.keys(baselinedCross)) {
+    if (!crossSpecDuplicates[name]) {
+      crossProblems.push(
+        `  ${name}: baselined cross-spec divergence no longer observed — remove from ` +
+          `baseline.cross_spec_duplicates.${name} so a future reintroduction of the same shape is caught as new.`,
+      );
+    }
+  }
   if (crossProblems.length > 0) {
     console.error('Cross-spec schema divergence gate failed:\n');
     for (const p of crossProblems) {
@@ -223,7 +236,29 @@ function main() {
   }
 
   // Gate 4: registered-type coverage.
-  if (baseline.registered_types.length > 0) {
+  // After the first introduction, the baseline always has registered
+  // types — emptying the list would silently disable the rename-
+  // escape guard. Fail loudly on an empty list unless the baseline
+  // is itself empty (genuine first-pin / fresh-repo case where every
+  // baseline section is empty).
+  const baselineIsFresh =
+    baseline.registered_types.length === 0 &&
+    Object.keys(baseline.per_type_drift).length === 0 &&
+    Object.keys(baseline.cross_spec_duplicates).length === 0 &&
+    Object.keys(baseline.intra_file_duplicates).length === 0;
+  if (baseline.registered_types.length === 0 && !baselineIsFresh) {
+    console.error(
+      'baseline.registered_types is empty but other baseline sections are not.',
+    );
+    console.error(
+      'This combination silently disables the rename-escape gate. Regenerate',
+    );
+    console.error(
+      'tests/fixtures/wire-shape-baseline.json via scripts/wire-shape/refresh.js,',
+    );
+    console.error('or remove the file entirely if introducing a fresh baseline.');
+    errors += 1;
+  } else if (baseline.registered_types.length > 0) {
     const missingSDK = [];
     const missingSpec = [];
     for (const name of baseline.registered_types) {
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,6 @@`
`2`	`2`	`"_comment": "Pre-existing transformer-coverage findings. Generated by scripts/transformer-coverage/check.js --write-baseline. CI fails on any finding NOT listed here. Burn this list down via targeted PRs that either populate the missing keys in the transformer or mark them @deprecated on the type definition.",`
`3`	`3`	`"findings": [`
`4`	`4`	`"src/client.ts:executePlan:PlanExecutionResponse:policyInfo",`
`5`		`- "src/client.ts:getPlanStatus:PlanExecutionResponse:policyInfo,workflowId",`
`6`		`- "src/client.ts:resumePlan:ResumePlanResponse:nextStep,nextStepName,stepResult,totalSteps,workflowId"`
	`5`	`+ "src/client.ts:getPlanStatus:PlanExecutionResponse:policyInfo,workflowId"`
`7`	`6`	`]`
`8`	`7`	`}`