Document that PolicyBlock field names are not the wire format

[vvillait88]

Summary

Documentation only. No behavior change.

PolicyBlock uses camelCase and the AgentScore API expects snake_case. This SDK already translates the five compliance fields correctly at the request boundary (buildGateFromPolicy, src/core.ts:779-783), so anyone using the SDK is unaffected and always has been.

The gap is that the type is exported, so a caller who hand-rolls the HTTP request takes the field names from it and sends camelCase. The API used to ignore a key it did not recognise, which meant such a policy matched no rule, ran no check, and returned decision: "allow": a compliance gate passing without evaluating anything. The API now rejects it with a 400 invalid_policy naming the correct spelling, so the failure is loud instead of silent.

That leaves this type as the last place still suggesting a shape the API refuses, which is what this fixes. It also records which fields actually cross the wire: enforcement, allowedShippingCountries and allowedShippingStates are merchant-side concerns the SDK acts on locally and never sends, which is not obvious from a type whose other members all do.

Worked with Varun, going through the Q3 2026 penetration test findings.

Type of change

• Bug fix (no breaking change)
• New feature (no breaking change)
• Breaking change (existing callers must update)
• Docs, tests, or internal maintenance only

Public API

None. No exported type, signature, wire format or response shape changes. PolicyBlock's members are untouched; only its doc comment is added to.

Deliberately NOT renamed: aligning the field names to snake_case would be a breaking change to a published package, and the SDK's translation is already correct, so the camelCase names are a genuine convenience rather than a defect. If we ever want them aligned it belongs in a major.

Test plan

Nothing here is executable, so the suite is a regression check rather than evidence for the change itself: bun run lint, bun run typecheck (including the examples project) and bun run test all clean, 119 files and 1817 tests passing with 4 skipped.

The claims in the doc comment were checked against the source rather than assumed. src/core.ts:779-783 maps exactly the five compliance fields to snake_case, and the three merchant-side fields (enforcement, allowedShippingCountries, allowedShippingStates) appear nowhere in the outbound request.

Two things deliberately left out. The commerce-side half of the same finding is not here: the report separately flags const allow = decision === 'allow' || decision == null in src/core.ts, which treats a missing decision as allow, and that is a behavior change with its own tests and release. The finding stays open until it lands. And the 14 pre-existing em-dashes in this file are left alone, since our convention is that a gate judges the lines a change publishes and sweeping the prose would balloon a documentation diff.

Checklist

• Tests cover the new behavior, and the suite passes locally
  Not ticked deliberately: this is a doc comment, so there is no behavior to
  cover. The suite passes and is included above as a regression check.
• Lint, format, and type checks pass
• Docs and README examples updated if the public surface changed
• No secrets, credentials, or personal data in the diff or the tests