Implementation sequence¶
Project requirements: prioritize native Go Lambda, keep CGO disabled, use local Docker by default, and favor cohesive packages with small dependencies. The legacy X-Ray SDK adapter is deprecated and frozen; maintained X-Ray support uses OpenTelemetry. Documentation and code comments remain English.
| Order | Scope | Current status |
|---|---|---|
| 1 | Logger and OpenTelemetry Tracer | Core implementation verified, including reference getters, OTel buffering/correlation, optional JMESPath extraction, struct/marshaler redaction, HTTP event-envelope extraction, standard sampler configuration, and legacy SDK deprecation. Current composed local acceptance: 868/868 assertions. Exhaustive configuration/serialization and lifecycle gates remain open. |
| 2 | Metrics | EMF emission, selective store APIs, metric presence and scoped runtime empty policy are implemented with 104 additional lifecycle reference cases and local Lambda composition. Scoped diagnostics and invalid-dimension/timestamp behavior now have 203 reference cases plus local Lambda acceptance. Manual cold-start capture and scoped function-name precedence now have 302 reference cases and wrapper composition acceptance. Configuration and fresh single-metric reconstruction now have 532 reference cases and local Lambda acceptance. Numeric values, exact errors and object-key behavior now have 641 reference cases, with key ordering shared by Metrics/Parser/Validation. Numeric/Date timestamp input and lazy clock reads have 968 reference cases and Lambda acceptance. Wrapper defaults, strict policy and ordered/duplicate multi-instance publication have 876 middleware-hook cases and Lambda acceptance. Remaining decorator/framework lifecycle, metadata/type/encoding edges and broader compatibility remain open in METRICS_PLAN.md. |
| 3 | Parameters | Five providers, defaults, cache/transforms, SSM writes/batches, reference fixtures, and Docker composition implemented and verified. Remaining boundaries: PARAMETERS.md. |
| 4 | Commons foundation and Metadata | Implemented, reused by existing utilities, and verified with reference fixtures and 100 Docker assertions. See COMMONS_REUSE.md and COMMONS_PLAN.md. |
| 5 | Signer | Standalone module implemented with SigV4, typed errors, body replay, signed transport, reference signatures, and local composition. See SIGNER.md and SIGNER_PLAN.md. |
| 6 | JMESPath and Batch | JMESPath is implemented with standard queries, custom functions, thirteen envelopes, and optional Logger integration. Batch now implements SQS/FIFO and stream partial failure handling, concurrency, typed wrappers, and generic parsing. Remaining acceptance and composition gates: BATCH_PLAN.md. |
| 7 | Idempotency | Core lifecycle, DynamoDB and optional Redis/Valkey persistence implemented with canonical-key/lifecycle/wire fixtures, local response caching, typed wrappers and concurrency checks. Real Valkey and basic bidirectional TypeScript/Go records verified. Full cross-language, topology and remaining gates: IDEMPOTENCY_PLAN.md. |
| 8 | Parser and Validation | Parser has all 24 initial event families, fourteen envelopes, 90 mapped runtime schema exports, 3,493 reference cases and Batch/Idempotency composition. Validation has compiled/manual APIs, typed wrappers, formats/references, JMESPath extraction, a pure-Go Unicode regex adapter, scoped applicator/type/reference/strict-pattern diagnostics, structure-versus-compilation separation, controlled conditional compilation, global nested resource aliases, ordered external registration and 23,071 exact reference cases. Both compose with the HTTP handler through explicit callbacks. Current acceptance: 31 modules/28 consumers, both Linux builds and 868 Docker assertions. Complete Parser type/error/encoding parity and Validation keyword/extension/remaining regex parity remain open. See PARSER_PLAN.md and VALIDATION_PLAN.md. |
| 9 | HTTP event handler | Four event adapters, routing, middleware/stores, response/error conversion, optional schema checks, CORS/compression and native streaming implemented. Optional Metrics/OTel middleware now uses separate modules. Verified 2,066 scoped reference cases (1,762 core, 176 Metrics, 128 Tracer contract), functional concurrency and actual utility composition. HTTP core has no third-party dependencies. Current acceptance: 31 modules/28 consumers, 868/868 RIE and 95/95 streaming checks. Cloud/platform, URL/header/regex/error/observability edges and full parity remain open in HTTP_PLAN.md. |
| 10 | AppSync Events | Initial independent module implemented with 100 reference scenarios, shared LRU, ordered concurrent publication, aggregate/subscription authorization and size warnings. Parser/Logger/OTel composition passes local Lambda acceptance. Full type/native/service/performance gates remain in APPSYNC_EVENTS_PLAN.md. |
| 11 | AppSync GraphQL | Independent module, single/batch routing, exception handlers and scalar helpers implemented. Verified 114 resolver scenarios, 91 scalar cases, all 25 modules/22 consumers, both Linux builds and 790/790 RIE assertions. Full compatibility and remaining gates are tracked in APPSYNC_GRAPHQL_PLAN.md. |
| 12 | Bedrock Agents | Independent function-based Action Group module implemented. Tool routing, ordered parameters and response/error contracts pass 371 actual TypeScript scenarios and native concurrency checks. Verified all 25 modules/22 consumers, both Linux builds, 790/790 RIE and 95/95 streaming checks. Remaining gates: BEDROCK_PLAN.md. |
| 13 | Kafka | Initial independent primitive/JSON consumer implemented with 165 reference scenarios and native concurrency/context checks. All 28 modules/25 consumers, both CGO-disabled Linux builds, 829/829 RIE and 95/95 streaming checks passed, including Parser/Idempotency/Logger/OTel composition. Optional Avro/Protobuf adapters now pass 370 Avro, 220 prefix and nine native message reference scenarios; complete packaged/runtime acceptance passed. Subsequent scoped checks verified 22 additional core JSON-mode cases, 172 mixed events through the native Go SDK, and the Protobuf schema ID length fix; unchanged modules reuse the prior complete acceptance. Remaining modes/parity/service gates are open in KAFKA_PLAN.md. |
| 14 | Data Masking | Initial independent erasure/provider core implemented with 240 reference cases and native concurrency/ownership/error/panic checks. Shared regex adds 7,671 Node replacement cases, 19 invalid patterns and 30 actual masking compositions, and reuses Validation's extracted engine. The optional uncached AWS Encryption SDK provider verifies 39 TypeScript ciphertext cases, five rejection cases and 108 reverse-direction assertions. Combined checks cover 31 modules/28 consumers, both Linux builds, 868/868 RIE and 95/95 streaming checks. Remaining regex, data-key caching, full encryption/native compatibility and actual KMS acceptance remain in DATAMASKING_PLAN.md. |
| 15 | Remaining shared contracts | Remaining public Commons contracts and cross-utility compatibility/service/performance/release gates. |
Complete a reviewable implementation slice with reference evidence before adding another package. Keep unfinished compatibility gates visible; a core implementation does not imply full parity. Performance, license review, release identity, and cross-package acceptance remain release requirements.
Use standard Go interfaces where sufficient. Metrics writes EMF through io.Writer and does not depend on Logger or Tracer. Parameters adapters share only cache/transform logic and default-provider lifecycle; service-specific requests remain in separate packages. Reuse primitives when demonstrated by multiple implementations rather than adding speculative frameworks.
Priority correction (2026-09-14): Commons is a shared foundation, not an end-stage utility. Existing modules already expose configuration/encoding inconsistencies, so consolidate their proven shared contracts before implementing more consumers. Metadata is a separate optional service client and must not become an unconditional dependency of ordinary logging, tracing, or parameter retrieval. Utility-specific defaults and cache policies remain with their owners.
Signer priority assessment (2026-09-14): no other pinned public package declares a Signer dependency, and Signer does not depend on Commons. Bring it forward for its bounded implementation and immediate IAM HTTP use cases; it does not unblock the remaining utilities. JMESPath remains the next shared dependency.
Module distribution (updated 2026-09-24): modules have independent dependencies and versions in one repository. HTTP, AppSync Events/GraphQL, Bedrock, Kafka with optional binary adapters, the shared optional regex module and the optional AWS Encryption SDK provider extend the layout to twenty-eight public modules and three development modules, with stable import paths and a shared workspace. See MODULES.md and PUBLISHING_PLAN.md. Subsequent utilities should receive their own modules when implemented; no public release has been created.