Skip to content

Parser implementation checklist

Reference: TypeScript v2.35.0 and Zod v4.1.12. Check an item only after its acceptance criteria pass. Full Parser scope includes every schema family, exported variant and envelope in the parent feature checklist.

  • PR-01: Verify the generic schema contract, typed/manual/safe parsing, structured failures, operational errors, wrappers and shared invocation context. Independent packaged Parser tests/vet passed on 2026-09-15; full runtime composition is tracked separately below.
  • PR-02: Verify object/collection composition, unknown fields, nullable/optional/default behavior, transforms, refinements, typed outputs and immutable defaults. Reference fixtures and isolation/concurrency tests passed; exhaustive edges remain under PR-10.
  • PR-03: Verify JSONStringified and Base64Encoded, plus initial SQS/EventBridge schemas and envelopes, against the forty generated TypeScript cases. All cases passed after preserving absent unknown fields and safe envelope aggregation through transforms. JSON syntax diagnostic normalization is documented in PARSER.md.
  • PR-04: Verify concrete Parser/Batch/Idempotency composition, typed SQS/EventBridge extraction, safe error aggregation and first-invalid-record behavior in local Lambda Docker acceptance. All 184/184 assertions and 14/14 Batch artifact checks passed on 2026-09-15; see LOCAL_ACCEPTANCE.json and BATCH_ACCEPTANCE.json.
  • PR-05: Verify independent packaged Parser tests/vet/dependencies, standalone consumption, examples and both CGO-disabled Lambda architecture builds. All 18 modules and 15 consumers passed with GOWORK=off. Parser has no external module dependencies. The first acceptance attempt stopped on an integration-only SQS field spelling error; it was fixed before the successful full run. See MODULE_ACCEPTANCE.json.
  • PR-06: Review and map every runtime/type export in PARSER_EXPORTS.json, including all variants behind wildcard schema subpaths.
  • PR-06a: Map all 90 unique public runtime schema names to Go definitions, including wildcard subpaths and re-exports, in PARSER_SCHEMA_MAP.json. The pinned generator fails on missing symbols; all definitions compile in the independently packaged Parser module. Non-schema runtime contracts and complete inferred-type mapping remain under PR-06.
  • PR-07a: Implement all 22 runtime schema exports in SNS, DynamoDB Streams, Kinesis, Firehose and CloudWatch Logs. Verify valid/missing inputs, decoded values, enums, window fields, malformed data and custom image extension through 106 actual TypeScript cases. Full error/format edges remain under PR-10. See PARSER_STREAMS.md.
  • PR-07b: Implement all eighteen runtime schema exports from API Gateway REST/v2/WebSocket/proxy, ALB, Lambda URL and VPC Lattice v1/v2. Verify 458 actual TypeScript cases covering field omissions/types, identity/authorizer variants, IPs, refinements and body policies. Full nested error/type/format gates remain under PR-10; see PARSER_HTTP.md.
  • PR-07c: Implement all fifteen runtime schema exports in Kafka, CloudFormation, Transfer, Connect campaigns, SES and S3. Verify 270 actual reference cases, safe integer bounds, surrogate pairs and malformed UTF-8; reuse SQS/EventBridge and shared text/IP validators. All 18 packaged modules, 15 consumers, both Lambda builds and 250 Docker assertions passed (2026-09-15). See PARSER_SERVICES.md for explicit operational-error mappings and remaining Unicode boundaries.
  • PR-07: Implement the remaining AppSync/shared, AppSync Events and Cognito schema families: 29 unique runtime exports, shared identity/request primitives and Null. Verify 1,467 actual reference cases (2,341 total), typed resolver/Cognito examples, all 18 packaged modules/15 consumers, both CGO-disabled Lambda builds, 274/274 Docker assertions and 14/14 Batch artifact checks (2026-09-15). All 24 initial schema families now have implementations; full type/behavior parity remains under PR-06/PR-10. See PARSER_IDENTITY.md.
  • PR-08a: Implement SNS, SNS-SQS, Kinesis, Firehose, CloudWatch and DynamoDB envelopes using shared record traversal. Verify ordinary/safe behavior, missing old/new images, error prefixes, independent decoding and concurrent reuse. All 205 Docker assertions and 14 Batch artifact checks passed (2026-09-15).
  • PR-08b: Implement API Gateway REST/v2, Lambda URL and VPC Lattice v1/v2 body envelopes, sharing field extraction with EventBridge. Verify safe/ordinary modes, combined metadata/body errors, explicit decoding and accepted absence. All 18 modules, 15 consumers, both CGO-disabled Lambda builds, 226/226 Docker assertions and 14/14 Batch artifact checks passed (2026-09-15). Parser reference coverage totals 604 cases.
  • PR-08c: Implement the Kafka envelope for both event sources, explicit JSON decoding, raw JSON topic ordering, numeric keys, duplicate keys and safe/ordinary error paths. Verify concurrent reuse, input preservation, cancellation, error/panic identity, safe-schema dispatch and no partial successes. The native RawMessage Lambda example, 250/250 Docker assertions and 14/14 Batch artifact checks passed (2026-09-15). Parser reference coverage totals 874 cases; all fourteen envelopes have implementations.
  • PR-08: Finish extension and exhaustive compatibility gates across all fourteen implemented envelopes.
  • PR-09: Implement DynamoDBMarshalled and extract existing raw conversion/numeric behavior into SDK-free root Commons. Retain SDK adapter entrypoints and error aliases; verify precision, conversion errors, custom schema extension and existing Commons/DynamoDB tests. All 18 packaged modules, 15 consumers, both CGO-disabled Lambda builds and 205 Docker assertions passed; Parser still has no external module dependencies.
  • PR-10a: Implement recursive union errors, sole continuable branch selection, continued refinements, array-check ordering and safe-mode propagation through containers/helpers. Compose nested ParseError failures without losing sibling diagnostics, preserve branch-relative paths and isolate shared error trees. Regenerate all corpora with recursive comparisons and add 1,152 cases (3,493 total). All 18 modules/15 consumers, both CGO-disabled Linux builds, 292/292 Docker assertions and 14/14 Batch artifact checks passed (2026-09-16, Asia/Shanghai). See PARSER_ERRORS.md.
  • PR-10: Complete remaining constraint/error metadata, primitive/union, numeric, malformed Unicode/encoding and invalid-schema edge parity, and measure throughput/allocations/payload-size costs.
  • PR-11: Complete Parser/Validation documentation and event-handler integration when those modules exist.

Finite boundary audit #188

This audit reuses all 3,493 preserved TypeScript v2.35.0/Zod v4.1.12 cases, including 90 runtime schemas, numeric/UTF-16 checks and 1,152 recursive union cases. It adds 84 actual observations: missing-object, scalar and array input in ordinary and safe modes for every one of the fourteen implemented envelopes. tools/reference/generate-parser-boundaries.mjs fails on missing pinned exports.

Reviewed boundary Result / native mapping
Fourteen envelopes: SQS, SNS, SNS-SQS, EventBridge, Kinesis, Firehose, CloudWatch, DynamoDB, Kafka, REST/v2 API Gateway, Lambda URL and VPC Lattice v1/v2 All 84 invalid-input observations retain exact portable issue trees, failure mode and original safe input; existing fixtures cover source-specific body/image/record decoding.
Runtime schema exports Reuse the explicit 90-symbol PARSER_SCHEMA_MAP.json and public export inventory; no inferred TypeScript declarations are treated as automatic Go types.
Application inferred shape Typed[T] plus explicit JSON tags maps strings, optional/nullable pointers, arrays and numeric fields into caller-owned structs. Unknown fields follow the supplied schema policy. Unicode text and array ownership are verified.
Numbers The built-in Number returns float64: an int64 above 2^53 rounds as in JavaScript, negative zero is retained, and NaN/infinities fail. Exact integer domains require a custom schema.
Constraint and union diagnostics Existing corpora compare code, message, path, expected type and recursive branch errors in order. Thirty-two concurrent Prefix calls keep nested paths/branches private. Zod-specific minimum/maximum/origin/format metadata is intentionally outside the portable Issue contract; custom schemas supply domain diagnostics.
Malformed JSON/Unicode JSON v2 rejects duplicate keys, malformed UTF-8, lone surrogates and trailing documents. This native strict-input policy is deliberate; syntax suffixes alone use the existing documented cross-runtime comparison. Raw JSON values retain interoperability.
Operational errors and cancellation Transform failures preserve the original cause and execute once; pre-cancellation skips the transform. Existing union/composition tests retain panic and safe-mode contracts.

No production defect was reproduced in these reviewed rows. Packaged Parser checks and its standalone consumer use CGO disabled and GOWORK off. Full PR-06 declaration equivalence, PR-08 extension permutations, PR-10 exhaustive native boundaries and resource budgets (#200) remain open. No AWS acceptance is claimed.