Capability Matrix — what this port does, deliberately doesn't, and how to fill the gap

Benzene is honest about its boundaries. This page is the single place that states, for the TypeScript port, what is provided (with the package that provides it), what is deliberately not done and why, and how to solve the rest outside Benzene. Nothing here is a hidden gap — a deliberate "no" is a design decision stated with its reasoning; a plain "not implemented" is an honest omission, and the two are never conflated. Where this port does less than the .NET original, the row says so.

Refreshed 2026-10-11 for spec-0.2.0 (Phase 1): the settlement breakdown and its summary row, the Kafka, Versioning, Validation, Health checks, HTTP hosting, Spec endpoint and Conformance rows, and the new Envelope over HTTP / Default paths / Reserved topics rows were rewritten from source. Other rows were not re-verified in this pass. Refreshed again for spec-0.3.0 (Phase 3a, one self-description): the Spec endpoint, Codegen & clients and Conformance rows. Refreshed for spec-0.4.0 (Phase 3b, the Contract Document is the register body): the Reserved topics, Mesh — service side, Mesh — collector, Spec endpoint and Conformance rows. Refreshed for Phase 4 (the profile is R1–R5 and R7; the meshed-service claim is M1 and M2): the Mesh — service side, Spec endpoint / Cloud Service Profile and Distributed tracing rows. Refreshed for the spec 1.1 follow-ups: the gRPC, Mesh — service side, Codegen & clients, Validation, Outbound HTTP and Conformance rows. Refreshed 2026-10-14 for spec 1.2 (issue error detail, a flow's status): the Mesh — service side, Mesh — collector and Conformance rows.

The one idea behind every row

Benzene abstracts at the business-logic boundary — you write a message handler once and host it anywhere — and never at the transport or storage boundary. Wrapping SQS or Service Bus behind a generic "queue" interface would hide the transport-specific capabilities that were the reason to choose it. So the answer to "does it abstract X?" is usually a deliberate no: you keep full, direct access to the underlying SDK, and when Benzene doesn't ship an adapter, rolling your own is a first-class, supported path — a small middleware or custom pipe, not an escape hatch. See Middleware and Common Middleware.

Two corollaries you'll see below:

• A database is not a transport. Benzene delivers events in; persisting state is your handler's own code (TypeORM, Prisma, the AWS/Azure SDKs, …).
• Some problems can't be solved at runtime inside Benzene at all. Independent processes (separate Lambda invocations, separate containers) can't coordinate without external shared state with atomic semantics. Benzene won't pretend otherwise.

Packages and areas

Cross-cutting production concerns

Returned-failure-result settlement — the per-transport breakdown

What each inbound binding does with a delivery, by outcome, as of spec-0.2.0 (transport-bindings §1, obligation 8). Each row names the class that makes the decision. The rule is written once, in src/Benzene.Core.MessageHandlers/Settlement.ts (isSettledAsFailure), and every binding calls it.

• Failure result: the invocation ended with isSuccessful === false.
• No result: the pipeline finished without recording one — a middleware ended the pipeline without setting a result, or a non-envelope message fell through useBenzeneMessage. A middleware that ends a one-way pipeline must set a result.
• Unmatched topic: no handler matches. MessageRouter records a not-found failure and marks it (an invisible mark, never on the wire), so a binding can tell it apart from a handler's own not-found. A missing topic records validation-error, an ordinary failure.

Every one-way binding's options/config carries the same two knobs (SettlementOptions):

• atMostOnce (default false) — acknowledge every message whatever the outcome: failure, no result, or uncaught error (logged). Nothing is redelivered.
• ignoreUnmatchedTopics — treat an unmatched topic as ignored (acknowledged), for a subscriber on a shared bus. Default false on queue and one-shot bindings, true on stream bindings (below).

The settlement words: redeliver (not acknowledged; the transport redelivers, subject to its own redrive / DLQ / max-delivery / retry-policy configuration), acknowledged, skip-and-continue (a stream position advances past it), n/a (no per-message result). transport-metadata-cases.json → settlementDefaults names each binding's shape; TransportMetadataConformanceTest asserts every binding below against it, reading the default from the binding's own options.

Request/response bindings settle nothing; the result goes back to the caller (http, grpc, envelope): HTTP (Express, API Gateway, Azure Functions HTTP, Cloud Functions HTTP), gRPC, the envelope endpoint (/benzene/invoke) and a synchronous Lambda invoke of the envelope.

¹ Partial reporting needs ReportBatchItemFailures on the event source mapping. Without it, Lambda ignores the returned failures and the batch is acknowledged. ² Requeued once; a failure on an already-redelivered message goes to the dead-letter exchange, or is dropped if there is none. ³ The Timer trigger follows .NET: a failure result fails the invocation (the host's retry policy decides whether the tick is retried; otherwise the failure is visible as a failed invocation and the next tick runs on schedule). A tick consumed with useTick(...) never records a result, so a missing result is not a failure here. ⁴ The documented stream carve-out. A stream binding may skip-and-continue (transport-bindings §1). As in .NET, a missing result is acknowledged on these bindings, and an unmatched topic is too (ignoreUnmatchedTopics defaults true — in .NET an unrouted record is a missing result): Kafka and Event Hubs have no per-record dead-letter path, so retaining such a record would replay its partition or batch forever. Set ignoreUnmatchedTopics: false to redeliver unmatched records instead. A failure result is still redelivered. ⁵ Benzene's part ends at failing the invocation. Whether the Functions host then redelivers a failed Event Hubs or Kafka trigger batch depends on the host's retry-policy configuration, which the application sets. ⁶ The self-hosted stream workers default to skip-and-continue (logged; the position advances), as .NET does: a stream has no per-message ack, so the safe-by-default alternative would halt the worker on every poison record. Opt into at-least-once: Event Hub catchHandlerExceptions: false; Kafka commitOnlyOnSuccess: true with catchHandlerExceptions: false (enforced at startup) — a failure result or an exception then stops the worker without committing, so a restart redelivers it.

Where this port and .NET still differ. The defaults above match .NET's 1.0 settlement contract on every binding .NET has. The remaining differences are shapes, recorded in the README "Porting conventions" ledger: the uniform atMostOnce/ignoreUnmatchedTopics knobs (spec-0.2.0 requirements .NET had not added yet); Kinesis is a per-record fan-out here, settled by invocation, where .NET runs a fan-in stream with a checkpointer; and the TypeScript-only options types (KinesisOptions, DynamoDbOptions, BlobStorageOptions, CosmosDbChangeFeedOptions, BenzeneMessageLambdaOptions).

Binding with no fixture id. The in-process fan-out client (@benzenejs/clients-in-process, InProcessFanOutClientMiddleware) dispatches to in-process consumers one-way, logs a consumer's failure and never redelivers (there is no transport to redeliver from). settlementDefaults names no such binding.

Why "we don't do that" is a feature

Every deliberate "no" above buys you something: you keep the full power of the tool you chose, you're never blocked by a leaky abstraction, and the surface you depend on stays small and stable. When you need something this port doesn't ship, the extension model (custom middleware, custom pipes, the getter/setter mapper pattern) is a supported, documented path — and where this port does less than the .NET original (outbox, claim check, retry jitter), the row above says so plainly rather than papering over it.

Edit this page on GitHub