Skip to content

v0.5.0

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 09 Sep 18:06
· 2704 commits to main since this release
c9f41a9
deno add jsr:@setu-ts/kernel@0.5.0 jsr:@setu-ts/runtime@0.5.0

Added

  • @setu-ts/common, @setu-ts/database-plugin, @setu-ts/messaging-plugin — operator error
    diagnostics survive wrapping and string logger sinks (M90j).
    serializeError now carries a
    bounded, scalar-only driver classifier allowlist and AggregateError members; database adapter
    wrappers retain their original cause; and broker string loggers render the complete bounded
    diagnostic rather than JavaScript's lossy default error interpolation.

  • Documentation — the Deno compiler-option mechanism, corrected wherever it was asserted. Six
    sites — the 0.1.0-alpha.8 CHANGELOG entry, three packages/cli/src JSDoc blocks, the M63 entry
    in CLAUDE.md, and the ROADMAP record — stated that declaring any compilerOptions key in a
    deno.json REPLACES Deno's entire default set, and blamed the full-stack template's 79 TS2686
    errors on an unrelated experimentalDecorators entry displacing the react-jsx default. That
    mechanism is false: measured on Deno 2.9.6, declaring one option leaves every other default in
    force, and the default JSX transform is the CLASSIC one — so a React template must declare jsx
    itself, and the missing jsx was the whole cause. The fix those sites describe is unaffected and
    was always correct; only the stated reason was wrong, which matters because a reader who believed
    it would avoid declaring a compiler option they need. The 0.1.0-alpha.8 section is edited in
    place, with the superseded sentence quoted rather than deleted. No generated output changes — the
    three CLI edits are comments only.

  • Documentation — docs/upgrading.md, and four published claims corrected (M90h / X22-4, X26-1,
    X26-2, X33-2, X20-3).
    A new upgrade guide answers "what must I change in my project",
    version by version, where the CHANGELOG answers what changed in the framework; docs/releasing.md
    gains the release step that maintains it, and docs/README.md indexes it. No package's src/
    changes. The auth README's rate-limit example no longer claims // per IP — the default key is
    the literal 'anonymous' for every unauthenticated caller unless ipSecurityMiddleware is
    registered with trustProxy — and a new test pins the resolved key rather than the comment. The
    session README gains the safe-request-then-mutation CSRF sequence, because its
    ## Session fixation and ## Form CSRF sections each compile and answer 403 when composed; a
    new integration test drives the sequence and asserts the successful path first. The secrets README
    and PUBLIC_API.md gain a per-provider set()/rotate() table — Vault and Azure create on
    write, AWS and GCP require the secret to pre-exist, env refuses — each cell marked
    verified-against-a-real-backend or not. Two published sections are corrected in place: the 0.2.0
    entry now announces the required IRepository.findPage (announced nowhere when it shipped,
    while its sibling findOne was announced twice), backed by a hand-written implementor committed
    as a compile-time tripwire, and the 0.1.0-alpha.10 decorator entry now says that a reader's OWN
    manifest must drop experimentalDecorators. A third published section is corrected below, by a
    separate change.

  • @setu-ts/common, @setu-ts/database-plugin — explicit transaction isolation (M90g / X24-2,
    X38-3).
    TransactionOptions.isolation carries one of the four portable isolation names — the
    new TransactionIsolationLevel union, exported from @setu-ts/common and re-exported from
    @setu-ts/database-plugin — through IDatabaseService.transaction() to the adapter. An adapter
    declares what it honours through the new ITransactionIsolationSupport (common), and a level it
    does not honour is refused with the new exported UnsupportedIsolationLevelError
    (database-plugin), answered 501, rather than silently downgraded. What an adapter honours is
    connector-dependent, not per-adapter: Prisma honours all four on PostgreSQL, MySQL and SQL
    Server, only serializable on CockroachDB and SQLite, and none on MongoDB or a connector it could
    not resolve; a Drizzle bridge honours all four only when the application wraps it with the new
    exported withIsolationSupport(), which is the declaration that its bridge forwards options; and
    Memory serializes process-local transactions. PUBLIC_API.md carries the per-adapter table.
    MongoDB snapshot isolation is not labelled as portable serializable, so MongoDB refuses every
    requested portable level by name rather than silently using its default.

  • @setu-ts/session-plugin — documented snapshot-commit concurrency limit (M90g / X22-6).
    Cookie and store sessions each commit their complete payload snapshot, so overlapping requests
    that update different keys remain last-writer-wins. The README and public API now name this
    explicitly, with short-lived sessions and an application-level serialized or optimistic write path
    as remedies.

  • @setu-ts/cache-plugin — in-process cache-miss coalescing (M90g / X24-1).
    CacheService.getOrSet(key, factory, ttlSeconds?) shares one cold read per key and resolved
    store, stores its successful result with the explicit or configured default TTL, and clears a
    failed load so every waiter can retry its own factory. cacheMiddleware uses the same per-process
    mechanism and report successful waiters as X-Cache: COALESCED; streaming, uncacheable, and
    failed leaders are never replayed. Separate processes do not coordinate.

  • @setu-ts/messaging-plugin — named NATS JetStream startup errors and an explicit subject set
    (M90d / X28-2, X28-3).
    NatsOptions.streamSubjects (and the same member on the public nats
    arm) supplies the subjects the broker may create the configured stream with when it is absent on
    the server. There is deliberately no default and no catch-all: NATS refuses subjects: ['>']
    without no_ack, and no_ack makes every JetStream publish reject unobserved (the rejected
    design, measured against a real server). Supplied and the stream is absent, the broker creates it
    with exactly those subjects; an existing stream is never touched; absent with the stream absent,
    connect() rejects with the new exported JetStreamStreamError, naming the stream and both
    remedies. A JetStream-less server now rejects with the new exported JetStreamUnavailableError
    (the raw 503 carried as cause) instead of surfacing a bare platform error. The
    messaging-plugin CI suite also gained two real-backend suites (nats-real, kafka-real) against
    nats:2-alpine -js and apache/kafka:4.0.0, started by both workflows; the package manifest's
    scoped net grant gained 4222 and 9092.

  • @setu-ts/messaging-plugin — messageId/timestamp on the cloud brokers' metadata (M90d /
    X28-4).
    IPubSubTransport.open and IServiceBusTransport.open delivered-message callbacks gain
    optional messageId/timestamp members (source-compatible for existing transports — a two-member
    implementation stays assignable), the real adapters read message.id/message.publishTime and
    message.messageId/message.enqueuedTimeUtc, and both brokers copy them onto MessageMetadata
    only when the transport carried them, so an absent member means "none delivered" rather than "did
    not look". All seven first-party brokers now populate both members.

  • @setu-ts/messaging-plugin — Service Bus transport reachability and a retry budget (M90b /
    X28-5, X28-6).
    The adapted ServiceBusSdkModule administration client gains an optional
    getNamespaceProperties() and the adapted transport now implements the documented isHealthy()
    probe: a successful read proves the namespace is reachable, a positively identified 401/403 counts
    as reachable too (the namespace answered — a send/listen-only credential is not a network outage),
    and any other failure is unreachability. The new ServiceBusRetryOptions type (exported) is
    accepted as retryOptions on the service-bus production arm only and is passed to
    ServiceBusClient alone, never to the administration client; omission preserves the Azure SDK
    defaults and maxRetries: 0 is the documented short budget for failing fast toward a dead broker.

  • @setu-ts/health-plugin — bounded, concurrent aggregation. New
    HealthPluginOptions.indicatorTimeoutMs (positive finite, default 5,000) applies a per-indicator
    deadline; the service runs selected indicators concurrently, records each latency individually,
    maps a timeout to { status: 'down', data: { reason: 'timeout' } } and a rejection to
    { status: 'down', data: { reason: 'error' } } without serializing the thrown value, and keeps
    checks in registration order. The deadline is validated by ONE check shared by both entry
    points: HealthService is barrel-exported, so
    new HealthService(runtime, { indicatorTimeoutMs }) refuses zero, a negative, NaN and
    Infinity exactly as HealthPlugin does rather than storing a value the deadline timer cannot
    honour. See Changed for the behavior change to timing.

  • @setu-ts/database-plugin — pool capacity as data. New DatabasePoolCapacity type (exported)
    and DrizzleAdapterOptions.poolStats — an application-owned callback reading the driver's own
    pool API. The adapter publishes the snapshot to the database indicator under data.capacity;
    omitted, no capacity fields appear. No threshold is applied. DatabaseService also gains
    readonly isClosed: boolean — a lifecycle-only read that reaches no adapter — which is what the
    indicator's uncached gate now reads: gating on isHealthy() called IDatabaseAdapter.isReady()
    on the one path deliberately outside the probe's 2-second bound, and cost two readiness reads per
    poll. Every adapter readiness call now happens inside the bounded, cached probe, and the gate is
    re-read after the probe settles so a poll already in flight when close() begins cannot publish a
    reachability answer the probe cached before it.

  • @setu-ts/cache-plugin, @setu-ts/secrets-plugin — truthful reachability. The cache and
    secrets indicators now report reachable (true/false/'unknown') beside lifecycle, through
    probes cached 5 s and bounded 2 s via createCachedProbe — exported from @setu-ts/common with
    its CachedProbeOptions and ProbeTiming types and the resolveProbeTiming helper that reads a
    runtime's clock and timers: Redis probes with ping(), Vault with an unauthenticated
    /v1/sys/health request (no secret read, no token), memory/noop/env report lifecycle truth, and a
    cloud facade without the new optional isHealthy() member reports 'unknown' — never a secret
    read standing in for a probe.

  • @setu-ts/queue-plugin — backlog fact. The queue indicator carries backlog whenever at
    least one depth read succeeded: the sum of each successful name's ready + processing,
    deliberately excluding terminal dead. A fact, not a threshold.

  • @setu-ts/common — createPathMatcher(patterns) and PathPattern, the one path-exclusion
    matcher. Three middlewares already carried a private copy of the matching loop and X32-1's fix
    would have made a fourth (§11.1). The copies disagreed: two matched literals only, one accepted a
    RegExp but ran an O(n) typeof branch per request, and exactly one of the three reset
    lastIndex before .test — which is the difference between a g-flagged pattern matching every
    request and matching every other request. The list is partitioned ONCE at construction, literals
    into a Set and patterns into an array walked only on a literal miss, so an all-literal list
    (every default in this framework) costs the same hash lookup the hand-rolled copies did, and
    tenantMiddleware gets faster than its previous per-entry loop. RateLimitOptions.exclude,
    MultiTenancyPluginOptions.exclude, RequestLoggerOptions.excludePaths and
    MetricsPluginOptions.excludePaths all read it. Those last two widen from readonly string[] to
    readonly PathPattern[]: source-compatible for callers, and breaking only for a consumer
    EXTRACTING the option type into a narrower one.

  • @setu-ts/runtime — RuntimeOptions.maxBodyBytes and RequestBodyTooLargeError, the request
    body bound no header can switch off (X32-4). requestSizeMiddleware refuses on a declared
    Content-Length; a chunked request declares none, and since M87 made the body read lazy the read
    happens inside the handler, after every middleware has returned — so the middleware could not
    close the bypass at all, and Request.arrayBuffer() buffered a body of any size. The read now
    streams with a byte cap, comparing the running total before a chunk is retained and cancelling the
    source on refusal rather than abandoning it. Omitted, the read is unbounded and the uncapped
    branch keeps arrayBuffer() verbatim, so an application that configures no limit runs the
    previous code exactly. The refusal is branded with a 413 status hint, so an application running
    errorHandler answers 413 Payload Too Large in its configured format. There are deliberately
    TWO knobs for one concern — the mapping runs before any plugin and no channel exists between them
    — and the docs say which is load-bearing: a reader who sets only maxBodySize keeps the previous
    behaviour rather than getting a silent regression. HttpAdapterFactories' members now take an
    optional HttpAdapterOptions, which keeps a zero-argument injected fake assignable.

  • @setu-ts/http-security-plugin — IpSecurityOptions.trustedProxies and proxyHops,
    resolving the client from the RIGHT of a proxy header (X32-3). trustProxy: true took the
    LEFTMOST entry, which is safe only behind a proxy that overwrites the header — and the standard
    nginx idiom (proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for) APPENDS, so a request
    arriving with a forged X-Forwarded-For: 7.7.7.7 reached the application as
    7.7.7.7, 198.51.100.9 and the leftmost entry was the value the caller chose. Anything keyed on
    CLIENT_IP_STATE_KEY — including defaultRateLimitKey — was then keyed on attacker input.
    trustedProxies walks right to left and returns the first entry that is not a trusted proxy;
    proxyHops returns the nth from the right for proxies with no fixed address, and a header shorter
    than the declared chain resolves undefined rather than falling back to a guess. The two are
    mutually exclusive and supplying both throws at middleware construction, as does a
    trustedProxies entry whose CIDR width is not plain digits (Number('') is 0, so '10.0.0.1/'
    would compile to a /0 matcher trusting every IPv4 address, and a chain whose leftmost entry is
    IPv6 would then return that caller-supplied value as the client) and a proxyHops that is not a
    non-negative integer (0 is the rightmost entry): without that guard it resolves undefined for
    every caller and silently degrades a rate limiter keyed on the client IP to one shared bucket.
    With neither supplied resolution stays leftmost, unchanged — X32-3 requires the operator to
    have opted into trustProxy, so a silent default flip would be a larger change than the finding.
    Only IPv4 CIDR is expanded numerically; every other form is compared as a case-insensitive
    literal, deliberately, since a wrong expansion would silently TRUST an untrusted hop.

  • @setu-ts/graphql-plugin — GraphqlPluginOptions.maxNodes, a query-breadth budget (X32-6).
    maxDepth was the only query-cost control and it bounds NESTING: a document two levels deep can
    still ask for a hundred thousand fields, because every alias is a separate field. Measured, one
    such request produced a ~5 MB response and +822 MB RSS with maxDepth: 5 configured and
    unable to see it, and the only thing bounding it was the request-body size. maxNodes counts the
    fields a document would resolve — aliases separately, and each fragment spread costing its
    definition at EVERY spread site, so defining a hundred fields once and spreading them a thousand
    times counts as a hundred thousand rather than eleven hundred. Expansion is memoized, so a deep
    fragment graph reports a large count in time linear in the document's own size; without that the
    counter would itself be the denial of service. Off by default (0), so no released
    application starts refusing a document it used to serve. A document's cost is its largest
    operation
    , not the sum of all of them — only the operation operationName selects is ever
    executed, so summing refused a bundled document whose selected operation was within budget, and
    the sibling maxDepth was already per-operation. A value that is not a non-negative integer
    throws at construction, for the same reason maxBodyBytes does: maxNodes <= 0 is false for
    NaN, so the rule would be built and then never report, silently enforcing nothing while reading
    as configured. The rule itself is deliberately NOT exported: it is configured through maxNodes,
    nothing outside the package constructs it, and exporting it would leak the plugin's private
    graphql facades into the published surface — which deno doc --lint reports (the M82 precedent).

  • @setu-ts/common — the shared authorization refusal (M90c / X18-2).
    respondWithAuthorizationFailure(target, failure) and the AuthorizationFailure union
    ('authentication-required' | 'not-configured' | 'insufficient-privileges') are exported so
    auth-plugin's guards and decorator-plugin's @Roles/@Permissions middleware write the same
    refusal without either plugin importing the other. Each arm writes through the existing
    respondWithError seam, so all three answer in the application's configured error format:
    401 Unauthorized / Authentication required, 501 Not Implemented /
    Authorization is not configured, and 403 Forbidden / Insufficient privileges. That last
    detail is deliberately fixed text — see Changed for the non-disclosure it replaces.

  • @setu-ts/common — the shared JSON-body parse (M90f / X37-1). parseJsonBody(text) and
    MalformedRequestBodyError are exported so all three IRequest.json() implementations — the
    served HTTP path (@setu-ts/runtime), the kernel's inject(), and @setu-ts/testing's
    MockRequest — reject a malformed body with the SAME 400-branded error instead of each raising
    its own bare SyntaxError. IRequest.json()'s contract now states the rejection.

  • @setu-ts/database-plugin — classified driver errors (M90f / X38-1, X35-2). New exported
    SerializationConflictError and DatabaseUnavailableError. DatabaseService classifies a driver
    rejection at its four interception sites (repository wrappers, the beginTransaction()
    acquisition, the transaction catch, and query()), carrying the original driver error as cause.

  • @setu-ts/secrets-plugin — the package's first error class (M90f / X20-2).
    ReadOnlySecretProviderError, rejected by EnvProvider.set — the provider's only write method —
    so SecretsService.rotate() inherits the refusal from the one throw site.

  • @setu-ts/common, @setu-ts/queue-plugin — the queue carries a trace (M90i / X34-1, X29-3).
    AddJobOptions.headers? and IJob.headers? mirror MessageMetadata.headers exactly, giving the
    queue ingress the header channel it had none of — grep -c headers over
    common/src/services/queue.ts was 0, so this was a designed capability gap rather than an
    adapter declining to read something. Both are OPTIONAL, so every existing IQueue implementor
    stays source-compatible. With a CAPABILITIES.TELEMETRY provider registered, queue.add() now
    runs in an enqueue <name> producer span that injects a W3C traceparent, and every processor
    runs in a process <name> consumer span parented from it — through the processors arm, a
    processors factory, and imperative queue.process() alike. All four adapters carry the map, and
    an M86 ingress behaviour reads it as IngressContext.headers, the same member the 'messaging'
    arm uses. Absent telemetry nothing is injected and behaviour is byte-identical; a headers map
    the CALLER passed is delivered either way, since it is a public option whose delivery must not
    depend on which capabilities are registered.

  • @setu-ts/cloudflare-plugin — WorkersQueue carries the queue header channel (M90i, review
    finding).
    The Cloudflare queue accepted the widened AddJobOptions and dropped headers on the
    floor, so a caller-supplied map — and any propagated traceparent — was silently lost, while the
    contract says a supplied map reaches the processor. The { v, name, id, data } envelope gains an
    OPTIONAL headers, so the version is deliberately NOT bumped: an older consumer ignores the field
    and a newer consumer reads an older message as carrying no channel, which is what absent means. A
    malformed map is dropped and the job runs untraced rather than being refused, because the envelope
    guard RETRIES what it rejects and losing the work to protect the record of it is the worse trade.

  • @setu-ts/common, @setu-ts/telemetry-plugin, @setu-ts/logger-plugin — log records name
    their trace (M90i / X34-2).
    trace_id/span_id appeared in common and telemetry-plugin and
    in no logger, formatter or transport, so every signal the framework emits was individually good
    and mutually unjoinable. ITelemetryService.activeSpanContext?() and the matching
    TracerHost.activeSpanContext?() are new OPTIONAL members — the read could not be expressed
    before, since withSpan hands its span only to its own callback — and LoggerPlugin now enriches
    every record, at every level and through child(), when a telemetry capability is registered. The
    field names are snake_case to match the OpenTelemetry log-correlation convention that log backends
    key on. NoopTelemetryService omits the member, and a service that cannot report an active span
    enriches nothing rather than emitting empty identifiers. Validity is decided by the SHARED trace-
    context codec rather than a rule spelled out twice, so the read path and the propagation path
    cannot disagree about which contexts are real: an empty, malformed or W3C all-zero identifier —
    what OTel reports for an INVALID span context — is reported as no active span, and never reaches a
    log record as a trace nothing else could carry.

Changed

  • BREAKING — @setu-ts/logger-plugin — the registered ILogger is a decorator, not the transport
    instance (M90i / X34-2).
    CAPABILITIES.LOGGER now resolves to an internal trace-enriching
    wrapper around the configured ConsoleLogger/PinoLogger/NoopLogger, so
    logger instanceof ConsoleLogger on the resolved capability no longer holds. Every ILogger
    method behaves identically and level passes through, so code written against the contract is
    unaffected. Migration: if you branch on the concrete class, branch on behaviour or on your own
    configuration instead — ILogger is the contract and the concrete class was never part of it.

    LoggerPlugin deliberately does NOT declare CAPABILITIES.TELEMETRY in optionalDependencies:
    TelemetryPlugin already declares CAPABILITIES.LOGGER in its own, and the two edges together
    are a cycle the kernel's plugin resolver refuses at start()
    (Circular plugin dependency detected). The capability is resolved at call time instead, which is
    required rather than prudent — the resolver orders LoggerPlugin first, so telemetry is
    guaranteed absent when it registers.

  • BREAKING — @setu-ts/messaging-plugin — the Kafka default consumer group is derived per topic
    (M90d).
    Measured against a real broker: members of one consumer group must subscribe the SAME
    topics — kafkajs logs "Consumer group received unsubscribed topics" and every member ends with an
    EMPTY assignment, so the previously shared messaging-consumers group silently stopped ALL
    delivery the moment an application subscribed two topics (including request-reply, whose responder
    subscribes the derived rr.req.<topic> channel). A subscription with no queue now uses
    <defaultQueue>:<topic>; same topic across instances still load-balances, different topics never
    share a group, and a caller-supplied queue still names the group itself. The separator is a
    colon because - is not injective — 'orders-eu' + created and 'orders' + eu-created both
    yield orders-eu-created, restoring the same failure — and a Kafka topic name may not contain :
    (probed: the broker refuses one) while a group id may. Migration: tooling keyed on the literal
    messaging-consumers group reads the derived <defaultQueue>:<topic> names now.

  • BREAKING — @setu-ts/cache-plugin — IRedisClient gains a required ping(). The Redis
    store's reachability probe invokes it. Migration: an injected client structurally typed as
    IRedisClient adds ping(): Promise<string> (ioredis already has it); the probe treats a
    rejection as unreachability.

  • BREAKING (behavior) — @setu-ts/health-plugin — indicators run concurrently under a deadline.
    Previously each selected indicator was awaited in registration order, so a 2-second outage across
    six dependency indicators held /health for 12+ seconds and one never-settling indicator left the
    endpoint pending forever. A timeout is now recorded as
    { status: 'down', data: { reason: 'timeout' } } and a rejection as
    { status: 'down', data: { reason: 'error' } }; report shape and key order are unchanged.
    Migration: an indicator relying on serial execution relative to a sibling (none is documented to)
    no longer gets it; assert on the report, not on wall-clock interleaving.

  • @setu-ts/realtime-backplane-plugin — the 'messaging' backplane calls the broker's
    isHealthy() through its owner (X21-1).
    The probe was captured as a detached reference, so a
    broker whose isHealthy reads instance state (ServiceBusBroker's private probe cache) threw a
    bare TypeError through the health endpoint. It now invokes broker.isHealthy() and retains the
    broker's own probe cache rather than adding a duplicate one.

  • BREAKING — @setu-ts/auth-plugin — refresh-token stores now revoke credential families.
    RefreshTokenStore gains required atomic
    rotate(jti, successor: RefreshTokenRecord): Promise<IRefreshTokenRotation> — the new exported
    union reports whether the presented token was live when its successor was stored, so a concurrent
    refresh cannot mint two descendants — and
    revokeFamily(jti): Promise<readonly RefreshTokenRecord[]>, which returns the records it revoked
    so their paired access-token identifiers can be revoked with them. Custom implementations must
    persist the optional lineage fields on RefreshTokenRecord or revokeFamily has no chain to
    walk. MemoryRefreshTokenStore implements both. RefreshTokenService now issues typed, distinct
    access and refresh JWT identifiers; bearer authentication rejects a signed type: 'refresh'
    token. For immediate access-token logout, construct one IAccessTokenRevocationStore and pass it
    to both AuthPlugin({ jwt: { ... } }) and RefreshTokenService; the new exported
    MemoryAccessTokenRevocationStore is single-process and the refresh service requires
    accessToken.expiresIn when this option is used. Policy failures still answer 403, but their
    detail is now Insufficient privileges rather than disclosing required roles or permissions.
    Migration: add atomic rotate and revokeFamily to custom refresh stores, retain family fields,
    serialize family revocation with rotation, and update tests that assert the old 403 detail.

  • BREAKING — @setu-ts/cli — bare setu generate is informational, not an error. With no
    schematic named it printed the available schematics through the normal output sink yet exited 2
    — an error exit whose guidance read like help. It now lists the schematics and exits 0, printing
    exactly the text setu generate --help prints. No refusal moves: generate <schematic> with a
    missing name, generate custom with a missing name, an unknown schematic, and an over-arity
    invocation all keep exit 2 with nothing written. One addition: the --runtime validation every
    generating path runs now sits above the listing, so bare setu generate --runtime deno2 refuses
    with exit 2 where the listing used to print over the typo. Migration: a script branching on bare
    setu generate exiting 2 sees 0 now — branch on the printed list or drop the branch.

  • BREAKING — @setu-ts/cli — unknown flags are refused instead of silently ignored. setu
    collected every --flag and never consulted the valid names, so a typo scaffolded a DIFFERENT
    project with exit 0 and no warning: new app --dry-run --templat rest produced the minimal
    project where --template rest produces the rest composition, and --base-port (the real flag
    is --port) was swallowed the same way. Each command now refuses a flag outside its own set —
    subcommand-aware for generate app, generate library, and workspace ports — with exit 2, a
    message naming the command and, within a small edit distance, a "did you mean" suggestion, and
    nothing written or created. Flags kept deliberately recognized for a NAMED refusal (--di and
    --depends-on on new; the transport flags, --runtime, and --di on generate app) still
    reach their specific guidance, and plugin-registered commands accept only --dir and --config —
    a CliCommandHandler receives positionals only, so no plugin can read any other flag. Migration:
    a script passing a stray flag today exits 0 and will now exit 2 — remove or correct the flag.
    No compatibility mode preserves ignored flags: accepting an unrecognized option would restore the
    silent misconfiguration this change removes.

  • BREAKING — @setu-ts/cli — extra positional arguments are refused instead of silently
    ignored.
    new read the first positional only, so setu new app extra junk scaffolded app and
    reported success with exit 0; generate read only the schematic word, its name, and (for
    custom) the custom-schematic name, dropping anything after; and adopt, workspace ports,
    commands, and help consumed no positionals at all. Each now refuses an over-arity invocation —
    exit 2, nothing written or created, a message naming the command and the expected count — in the
    dispatcher before any command body runs, mirroring add's existing refusal. Tokens after -- are
    positionals ([parseArgs]) and refuse the same way. Valid arities are unchanged (new app,
    generate <schematic> <name>, generate custom <schematic-name> <name>,
    generate app|library <name>, and the bare add/adopt/workspace ports/commands/help
    forms), and plugin-registered commands still receive every positional. Migration: a script passing
    stray positionals today exits 0 and will now exit 2 — remove them.

  • BREAKING — @setu-ts/database-plugin — default memory raw-SQL and programmatic-migration
    refusals now answer 501 Not Implemented instead of a masked 500.
    query() now rejects with
    UnsupportedRawQueryError rather than throwing synchronously, so callers using .catch() now
    receive the refusal. migrate() rejects with the new UnsupportedMigrationError: migrations are
    a framework-wide unsupported capability, not a raw-query or query-shape refusal. Update status
    assertions from 500 to 501 and synchronous try/catch call sites to await or .catch();
    use each adapter's migration CLI instead of migrate().

  • BREAKING (behaviour) — @setu-ts/auth-plugin — the rate limiter's 429 body answers in the
    application's configured error format
    (X32-2). rateLimitMiddleware wrote its own body with
    ctx.response.status(429).json({ error, message }). M70f routed every first-party short-circuit
    through the respondWithError seam — upload, tenant, session, the nine auth guards,
    http-security's three, the flag guard — and missed this one, presumably because the limiter is
    middleware rather than a guard. So the ONE status a client is most likely to handle
    programmatically was the one status that ignored errorHandler's configuration, and a consumer
    parsing Problem Details (which this framework's own generated SDK does) got an unreadable body
    under application/json. The Retry-After and RateLimit-* headers are unchanged.
    Migration: the body shape changes. With errorHandler({ format: 'rfc9457' }) the 429 is now
    Problem Details under application/problem+json, carrying detail and no message; with
    format: 'default' it is { statusCode, message, details: { detail } }, the shape every other
    refusal already used; with no errorHandler registered it is the seam's { error, detail }
    fallback. A client reading body.message for the limiter's text should read body.detail (or
    body.details.detail under 'default').

  • BREAKING (behaviour) — @setu-ts/auth-plugin — an exhausted rate limiter no longer refuses the
    operational probes
    (X32-1). RateLimitOptions had no exclusion member at all, and the
    middleware is documented as a global one, so a burst of abuse made /live answer 429 — which a
    Kubernetes kubelet reads as a failed liveness probe and restarts the container, whose only fault
    was being under load. exclude now defaults to the six operational paths (/live, /ready,
    /health, /metrics, /openapi.json, /docs), the same list tenantMiddleware exempts. An
    exempt path increments no counter and carries no RateLimit-* headers, because the limit does not
    govern it. Migration: pass exclude: [] to restore the previous behaviour. A caller list
    REPLACES the defaults, so spread DEFAULT_RATE_LIMIT_EXCLUDED_PATHS to extend them.

  • BREAKING (wire keys) — @setu-ts/auth-plugin — RedisRateLimitStore namespaces its keys
    (X32-5). Keys were written exactly as keyGenerator produced them — anonymous,
    ip:203.0.113.7, user:42 — so two applications sharing one managed Redis counted against each
    other's budget, and combined with X32-1 service A's traffic would restart service B's pods. Both
    sibling Redis stores in this framework already namespace and both explain why in their own source.
    keyPrefix defaults to 'setu:ratelimit:', exported as DEFAULT_RATE_LIMIT_KEY_PREFIX.
    Migration: in-flight counters under the old keys are orphaned, so the blast radius is one
    window — they are TTL-bounded and expire on their own. Pass keyPrefix: '' for the previous keys
    byte for byte.

  • BREAKING — @setu-ts/database-plugin — driver conflicts and outages reach the client as 409
    and 503 (M90f / X38-1, X35-2).
    A backend-reported serialization failure (PostgreSQL SQLSTATE
    class 40 — 40001, 40P01 — Prisma's P2034, MongoDB's TransientTransactionError label,
    Bigtable's gRPC ABORTED, Cosmos 449) now answers 409 Conflict through
    SerializationConflictError, where it was a masked 500 that told a well-behaved client to give
    up — silently dropping the write and making optimistic concurrency unusable. A transiently
    unreachable backend (SQLSTATE class 08, 57P03, the node-postgres pool timeout,
    MongoNetworkError/MongoServerSelectionError, gRPC UNAVAILABLE, Cosmos 429/503, the net
    errno ECONNREFUSED family) now answers 503 Service Unavailable through
    DatabaseUnavailableError. The original driver error is preserved as cause (the SQLSTATE stays
    log-reachable); the served detail is a fixed sentence, never driver text. No classified answer
    carries Retry-After — the hint channel has no header and no component holds an honest horizon.
    Migration: an application branching on the masked 500 for these conditions branches on a
    body it could never have parsed ("Internal Server Error"); instanceof SerializationConflictError
    is the retry signal. The typed Drizzle builder (getDrizzleDatabase) bypasses the classifier, and
    DynamoDB's TransactionConflictException / Cosmos's 449 are documented-unverified — neither was
    reproducible against DynamoDB Local or the local emulator.

  • BREAKING — @setu-ts/runtime, @setu-ts/kernel, @setu-ts/testing — a malformed JSON request
    body answers 400 (M90f / X37-1).
    IRequest.json() rejects with MalformedRequestBodyError
    (branded 400 Bad Request) instead of a bare SyntaxError that errorHandler masked to 500.
    The read stays lazy, so the 400 is produced when the handler reads, and a handler that catches
    its own rejection keeps full control. An empty body still parses as {} on inject() and
    MockRequest. Migration: none for well-formed callers; a 500-matching catch for malformed
    bodies now sees 400.

  • BREAKING — @setu-ts/secrets-plugin — a write against a read-only provider answers 501 (M90f
    / X20-2).
    EnvProvider.set (and SecretsService.rotate() on the env provider) rejects with
    ReadOnlySecretProviderError, answered 501 Not Implemented with the class's own sentence, where
    it was a masked 500. Migration: an application catching the old plain
    Error('EnvProvider is read-only; …') by message still catches the new class (same message); add
    an instanceof branch to distinguish it from faults.

  • BREAKING — @setu-ts/resilience-plugin — the shedding errors answer 503/503/504 (M90f /
    X32-7).
    BulkheadFullError and CircuitOpenError are answered 503 Service Unavailable and
    TimeoutError is answered 504 Gateway Timeout under errorHandler, where all three were masked
    500s that read as bugs in every dashboard. Shedding is the bulkhead's purpose, so the status is
    part of the contract. None carries Retry-After — the hint channel has no header, and no
    component holds an honest drain horizon; 503 is itself the retryable signal. Migration: an
    application serving its own fallback for these errors is unaffected; one relying on the masked
    500 must match the new statuses or instanceof the classes.

Security

  • The deno.lock resolution of npm:nodemailer moves 9.0.4 → 9.1.1
    (GHSA-2x7j-588g-ccc2, high).
    Quadratic
    (O(n²)) time in nodemailer's addressparser lets a crafted address list drive a remote denial of
    service; the advisory was published 2026-09-08 and names < 9.1.0. No source change was
    needed
    — smtp-provider.ts already imports npm:nodemailer@^9, which the patched version
    satisfies — so this moves the resolution CI and the test suite use.

    Scope, stated precisely, because a lockfile entry is easy to over-read: this repository's lock
    governs its own CI and tests, not a consumer's. An application using @setu-ts/mail-plugin
    resolves npm:nodemailer@^9 against its own lock, so it was never pinned to 9.0.4 by us and
    receives nothing automatically from this entry. If your lock resolves that specifier below
    9.1.0, update it. Only the SMTP provider reaches nodemailer at all; every other mail backend is
    unaffected.

Fixed

  • @setu-ts/openapi-plugin — a type union is spelled anyOf on every supported zod v4, not
    whichever spelling the installed patch version chose
    (issue #253). Draft 2020-12 permits both
    spellings, and zod's public toJSONSchema() changed which one it emits INSIDE the declared
    >=4.4.0 <5 support range: through 4.4 a union of bare types emitted
    anyOf: [{ type: 'string' }, { type: 'null' }], and from 4.5 it collapses to
    type: ['string', 'null']. The transformer passed that through, so an application's zod PATCH
    version decided the document's shape — isStructuralShape keys on anyOf, so a nullable or
    primitive union silently stopped earning a components/schemas entry and a regenerated
    @setu-ts/sdk client changed shape for no API reason. It also produced a value the published
    OpenApiSchemaObject.type cannot express (a single type name, not an array), so a consumer
    switching on it got no compiler warning, and a type array is 3.1-only where anyOf converts
    down to OpenAPI 3.0. #adaptDocument now normalizes the collapsed form back at any depth, on both
    the plain and the component-hoisting path, keeping the v4 path in agreement with the v3 path —
    measured: one schema now yields byte-identical documents under 4.4.3 and 4.5.4. Sibling keywords
    stay beside the anyOf instead of being distributed into its arms, which would apply a string
    constraint to the null arm. No public type changed and no consumer call site breaks. Reached the
    weekly dependency-drift gate rather than a pull request because the committed lockfile resolved
    4.4.3; it now resolves 4.5.4, and a pinned npm:zod@4.5.4 case asserts the behaviour against a
    version that really collapses, so a later lockfile move cannot make it vacuous. The rewrite
    descends only into schema positions, so a default, const, enum, example or vendor-extension
    value keeps its own type key verbatim, and a node already asserting anyOf keeps it — the
    normalized union is conjoined through allOf.

  • @setu-ts/static-plugin — gzip sidecars now use the registered gzip content-coding token. A
    .gz sidecar was sent as Content-Encoding: gz, which standard clients cannot decode and a
    shared cache could retain after the origin was corrected. Purge affected cached variants to
    recover immediately. Conditional evaluation now runs after content negotiation, so an
    If-None-Match validator for the uncompressed source cannot incorrectly return 304 for a
    selected compressed sidecar. On runtimes without a filesystem, the registered IStaticFiles
    service now returns 404 as documented rather than throwing when an application calls serve().

  • @setu-ts/messaging-plugin — the Kafka broker starts (M90d / X28-1). KafkaBroker wired its
    reconnect supervisor with the uppercase KEYS of kafkajs's producer.events
    ('CONNECT'/'DISCONNECT') where the wire VALUES are required
    (producer.connect/producer.disconnect); kafkajs validates the name and threw
    KafkaJSNonRetriableError inside register(), so an application configured with
    broker: 'kafka' never bound a socket. The broker now attaches two declared wire-value constants;
    a guarded real-import test pins them against the real module's own events map and proves the
    uppercase keys are rejected by real kafkajs. The corrected event names also fix the JSDoc that
    documented the keys as the accepted names (C1).

  • @setu-ts/messaging-plugin — the NATS broker delivers (M90d, found by the new real-backend
    suite).
    Two delivery-path defects no injected fake could see, both probed against
    npm:nats@2.29: subscribe() created the durable consumer through js.consumers.add, which the
    JetStream client does not expose (consumer creation is a management operation on
    jsm.consumers.add), so every real subscribe threw a bare TypeError; and the delivery cast read
    info.timestamp, which nats 2.29 spells info.timestampNanos — an integer above the float
    safe-integer range — so every real delivery carried an Invalid Date. Consumer creation now goes
    through the manager and the timestamp is converted from nanoseconds through BigInt; the test
    fixture models the real timestampNanos field rather than the string it claimed.

  • @setu-ts/messaging-plugin — the NATS broker fails startup with a name, not a bare platform
    error (M90d / X28-3).
    See Added: JetStreamUnavailableError and JetStreamStreamError
    replace the raw 503 and the catch-all-refusal text at both connect() failure sites, carrying
    the platform error as cause wherever the platform produced one. The absent-stream refusal is the
    one arm with no cause: no platform call failed, the broker declines to invent a subject set.


Releases before v0.1.0-alpha.8 shipped as tags only; their notes live in
CHANGELOG.md.