Repository navigation
v0.5.0
Pre-releasedeno add jsr:@setu-ts/kernel@0.5.0 jsr:@setu-ts/runtime@0.5.0Added
-
@setu-ts/common,@setu-ts/database-plugin,@setu-ts/messaging-plugin— operator error
diagnostics survive wrapping and string logger sinks (M90j).serializeErrornow carries a
bounded, scalar-only driver classifier allowlist andAggregateErrormembers; 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 — the0.1.0-alpha.8CHANGELOG entry, threepackages/cli/srcJSDoc blocks, the M63 entry
inCLAUDE.md, and the ROADMAP record — stated that declaring anycompilerOptionskey in a
deno.jsonREPLACES Deno's entire default set, and blamed thefull-stacktemplate's 79TS2686
errors on an unrelatedexperimentalDecoratorsentry displacing thereact-jsxdefault. 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 declarejsx
itself, and the missingjsxwas 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. The0.1.0-alpha.8section 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, anddocs/README.mdindexes it. No package'ssrc/
changes. The auth README's rate-limit example no longer claims// per IP— the default key is
the literal'anonymous'for every unauthenticated caller unlessipSecurityMiddlewareis
registered withtrustProxy— 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 fixationand## Form CSRFsections each compile and answer403when composed; a
new integration test drives the sequence and asserts the successful path first. The secrets README
andPUBLIC_API.mdgain a per-providerset()/rotate()table — Vault and Azure create on
write, AWS and GCP require the secret to pre-exist,envrefuses — 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 requiredIRepository.findPage(announced nowhere when it shipped,
while its siblingfindOnewas 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 dropexperimentalDecorators. 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.isolationcarries one of the four portable isolation names — the
newTransactionIsolationLevelunion, exported from@setu-ts/commonand re-exported from
@setu-ts/database-plugin— throughIDatabaseService.transaction()to the adapter. An adapter
declares what it honours through the newITransactionIsolationSupport(common), and a level it
does not honour is refused with the new exportedUnsupportedIsolationLevelError
(database-plugin), answered501, rather than silently downgraded. What an adapter honours is
connector-dependent, not per-adapter: Prisma honours all four on PostgreSQL, MySQL and SQL
Server, onlyserializableon 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
exportedwithIsolationSupport(), which is the declaration that its bridge forwards options; and
Memory serializes process-local transactions.PUBLIC_API.mdcarries the per-adapter table.
MongoDB snapshot isolation is not labelled as portableserializable, 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.cacheMiddlewareuses the same per-process
mechanism and report successful waiters asX-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 publicnats
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 refusessubjects: ['>']
withoutno_ack, andno_ackmakes 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 exportedJetStreamStreamError, naming the stream and both
remedies. A JetStream-less server now rejects with the new exportedJetStreamUnavailableError
(the raw503carried ascause) 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 -jsandapache/kafka:4.0.0, started by both workflows; the package manifest's
scopednetgrant gained4222and9092. -
@setu-ts/messaging-plugin—messageId/timestampon the cloud brokers' metadata (M90d /
X28-4).IPubSubTransport.openandIServiceBusTransport.opendelivered-message callbacks gain
optionalmessageId/timestampmembers (source-compatible for existing transports — a two-member
implementation stays assignable), the real adapters readmessage.id/message.publishTimeand
message.messageId/message.enqueuedTimeUtc, and both brokers copy them ontoMessageMetadata
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 adaptedServiceBusSdkModuleadministration client gains an optional
getNamespaceProperties()and the adapted transport now implements the documentedisHealthy()
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 newServiceBusRetryOptionstype (exported) is
accepted asretryOptionson theservice-busproduction arm only and is passed to
ServiceBusClientalone, never to the administration client; omission preserves the Azure SDK
defaults andmaxRetries: 0is 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
checksin registration order. The deadline is validated by ONE check shared by both entry
points:HealthServiceis barrel-exported, so
new HealthService(runtime, { indicatorTimeoutMs })refuses zero, a negative,NaNand
Infinityexactly asHealthPlugindoes 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. NewDatabasePoolCapacitytype (exported)
andDrizzleAdapterOptions.poolStats— an application-owned callback reading the driver's own
pool API. The adapter publishes the snapshot to thedatabaseindicator underdata.capacity;
omitted, no capacity fields appear. No threshold is applied.DatabaseServicealso gains
readonly isClosed: boolean— a lifecycle-only read that reaches no adapter — which is what the
indicator's uncached gate now reads: gating onisHealthy()calledIDatabaseAdapter.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 whenclose()begins cannot publish a
reachability answer the probe cached before it. -
@setu-ts/cache-plugin,@setu-ts/secrets-plugin— truthful reachability. Thecacheand
secretsindicators now reportreachable(true/false/'unknown') beside lifecycle, through
probes cached 5 s and bounded 2 s viacreateCachedProbe— exported from@setu-ts/commonwith
itsCachedProbeOptionsandProbeTimingtypes and theresolveProbeTiminghelper that reads a
runtime's clock and timers: Redis probes withping(), Vault with an unauthenticated
/v1/sys/healthrequest (no secret read, no token), memory/noop/env report lifecycle truth, and a
cloud facade without the new optionalisHealthy()member reports'unknown'— never a secret
read standing in for a probe. -
@setu-ts/queue-plugin—backlogfact. Thequeueindicator carriesbacklogwhenever at
least one depth read succeeded: the sum of each successful name'sready + processing,
deliberately excluding terminaldead. A fact, not a threshold. -
@setu-ts/common—createPathMatcher(patterns)andPathPattern, 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
RegExpbut ran an O(n)typeofbranch per request, and exactly one of the three reset
lastIndexbefore.test— which is the difference between ag-flagged pattern matching every
request and matching every other request. The list is partitioned ONCE at construction, literals
into aSetand 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
tenantMiddlewaregets faster than its previous per-entry loop.RateLimitOptions.exclude,
MultiTenancyPluginOptions.exclude,RequestLoggerOptions.excludePathsand
MetricsPluginOptions.excludePathsall read it. Those last two widen fromreadonly 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.maxBodyBytesandRequestBodyTooLargeError, the request
body bound no header can switch off (X32-4).requestSizeMiddlewarerefuses 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, andRequest.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 keepsarrayBuffer()verbatim, so an application that configures no limit runs the
previous code exactly. The refusal is branded with a413status hint, so an application running
errorHandleranswers413 Payload Too Largein 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 onlymaxBodySizekeeps the previous
behaviour rather than getting a silent regression.HttpAdapterFactories' members now take an
optionalHttpAdapterOptions, which keeps a zero-argument injected fake assignable. -
@setu-ts/http-security-plugin—IpSecurityOptions.trustedProxiesandproxyHops,
resolving the client from the RIGHT of a proxy header (X32-3).trustProxy: truetook 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 forgedX-Forwarded-For: 7.7.7.7reached the application as
7.7.7.7, 198.51.100.9and the leftmost entry was the value the caller chose. Anything keyed on
CLIENT_IP_STATE_KEY— includingdefaultRateLimitKey— was then keyed on attacker input.
trustedProxieswalks right to left and returns the first entry that is not a trusted proxy;
proxyHopsreturns the nth from the right for proxies with no fixed address, and a header shorter
than the declared chain resolvesundefinedrather than falling back to a guess. The two are
mutually exclusive and supplying both throws at middleware construction, as does a
trustedProxiesentry whose CIDR width is not plain digits (Number('')is0, so'10.0.0.1/'
would compile to a/0matcher trusting every IPv4 address, and a chain whose leftmost entry is
IPv6 would then return that caller-supplied value as the client) and aproxyHopsthat is not a
non-negative integer (0is the rightmost entry): without that guard it resolvesundefinedfor
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 intotrustProxy, 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).
maxDepthwas 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 withmaxDepth: 5configured and
unable to see it, and the only thing bounding it was the request-body size.maxNodescounts 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 operationoperationNameselects is ever
executed, so summing refused a bundled document whose selected operation was within budget, and
the siblingmaxDepthwas already per-operation. A value that is not a non-negative integer
throws at construction, for the same reasonmaxBodyBytesdoes:maxNodes <= 0isfalsefor
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 throughmaxNodes,
nothing outside the package constructs it, and exporting it would leak the plugin's private
graphql facades into the published surface — whichdeno doc --lintreports (the M82 precedent). -
@setu-ts/common— the shared authorization refusal (M90c / X18-2).
respondWithAuthorizationFailure(target, failure)and theAuthorizationFailureunion
('authentication-required' | 'not-configured' | 'insufficient-privileges') are exported so
auth-plugin's guards anddecorator-plugin's@Roles/@Permissionsmiddleware write the same
refusal without either plugin importing the other. Each arm writes through the existing
respondWithErrorseam, so all three answer in the application's configured error format:
401 Unauthorized/Authentication required,501 Not Implemented/
Authorization is not configured, and403 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
MalformedRequestBodyErrorare exported so all threeIRequest.json()implementations — the
served HTTP path (@setu-ts/runtime), the kernel'sinject(), and@setu-ts/testing's
MockRequest— reject a malformed body with the SAME400-branded error instead of each raising
its own bareSyntaxError.IRequest.json()'s contract now states the rejection. -
@setu-ts/database-plugin— classified driver errors (M90f / X38-1, X35-2). New exported
SerializationConflictErrorandDatabaseUnavailableError.DatabaseServiceclassifies a driver
rejection at its four interception sites (repository wrappers, thebeginTransaction()
acquisition, the transaction catch, andquery()), carrying the original driver error ascause. -
@setu-ts/secrets-plugin— the package's first error class (M90f / X20-2).
ReadOnlySecretProviderError, rejected byEnvProvider.set— the provider's only write method —
soSecretsService.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?andIJob.headers?mirrorMessageMetadata.headersexactly, giving the
queue ingress the header channel it had none of —grep -c headersover
common/src/services/queue.tswas0, so this was a designed capability gap rather than an
adapter declining to read something. Both are OPTIONAL, so every existingIQueueimplementor
stays source-compatible. With aCAPABILITIES.TELEMETRYprovider registered,queue.add()now
runs in anenqueue <name>producer span that injects a W3Ctraceparent, and every processor
runs in aprocess <name>consumer span parented from it — through theprocessorsarm, a
processorsfactory, and imperativequeue.process()alike. All four adapters carry the map, and
an M86 ingress behaviour reads it asIngressContext.headers, the same member the'messaging'
arm uses. Absent telemetry nothing is injected and behaviour is byte-identical; aheadersmap
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—WorkersQueuecarries the queue header channel (M90i, review
finding). The Cloudflare queue accepted the widenedAddJobOptionsand droppedheaderson the
floor, so a caller-supplied map — and any propagatedtraceparent— was silently lost, while the
contract says a supplied map reaches the processor. The{ v, name, id, data }envelope gains an
OPTIONALheaders, 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_idappeared incommonandtelemetry-pluginand
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, sincewithSpanhands its span only to its own callback — andLoggerPluginnow enriches
every record, at every level and throughchild(), when a telemetry capability is registered. The
field names are snake_case to match the OpenTelemetry log-correlation convention that log backends
key on.NoopTelemetryServiceomits 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 registeredILoggeris a decorator, not the transport
instance (M90i / X34-2).CAPABILITIES.LOGGERnow resolves to an internal trace-enriching
wrapper around the configuredConsoleLogger/PinoLogger/NoopLogger, so
logger instanceof ConsoleLoggeron the resolved capability no longer holds. EveryILogger
method behaves identically andlevelpasses 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 —ILoggeris the contract and the concrete class was never part of it.LoggerPlugindeliberately does NOT declareCAPABILITIES.TELEMETRYinoptionalDependencies:
TelemetryPluginalready declaresCAPABILITIES.LOGGERin its own, and the two edges together
are a cycle the kernel's plugin resolver refuses atstart()
(Circular plugin dependency detected). The capability is resolved at call time instead, which is
required rather than prudent — the resolver ordersLoggerPluginfirst, 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 sharedmessaging-consumersgroup silently stopped ALL
delivery the moment an application subscribed two topics (including request-reply, whose responder
subscribes the derivedrr.req.<topic>channel). A subscription with noqueuenow uses
<defaultQueue>:<topic>; same topic across instances still load-balances, different topics never
share a group, and a caller-suppliedqueuestill names the group itself. The separator is a
colon because-is not injective —'orders-eu'+createdand'orders'+eu-createdboth
yieldorders-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-consumersgroup reads the derived<defaultQueue>:<topic>names now. -
BREAKING —
@setu-ts/cache-plugin—IRedisClientgains a requiredping(). The Redis
store's reachability probe invokes it. Migration: an injected client structurally typed as
IRedisClientaddsping(): 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/healthfor 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 whoseisHealthyreads instance state (ServiceBusBroker's private probe cache) threw a
bareTypeErrorthrough the health endpoint. It now invokesbroker.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.
RefreshTokenStoregains 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 onRefreshTokenRecordorrevokeFamilyhas no chain to
walk.MemoryRefreshTokenStoreimplements both.RefreshTokenServicenow issues typed, distinct
access and refresh JWT identifiers; bearer authentication rejects a signedtype: 'refresh'
token. For immediate access-token logout, construct oneIAccessTokenRevocationStoreand pass it
to bothAuthPlugin({ jwt: { ... } })andRefreshTokenService; the new exported
MemoryAccessTokenRevocationStoreis single-process and the refresh service requires
accessToken.expiresInwhen this option is used. Policy failures still answer403, but their
detail is nowInsufficient privilegesrather than disclosing required roles or permissions.
Migration: add atomicrotateandrevokeFamilyto custom refresh stores, retain family fields,
serialize family revocation with rotation, and update tests that assert the old 403 detail. -
BREAKING —
@setu-ts/cli— baresetu generateis informational, not an error. With no
schematic named it printed the available schematics through the normal output sink yet exited2
— an error exit whose guidance read like help. It now lists the schematics and exits0, printing
exactly the textsetu generate --helpprints. No refusal moves:generate <schematic>with a
missing name,generate customwith a missing name, an unknown schematic, and an over-arity
invocation all keep exit2with nothing written. One addition: the--runtimevalidation every
generating path runs now sits above the listing, so baresetu generate --runtime deno2refuses
with exit2where the listing used to print over the typo. Migration: a script branching on bare
setu generateexiting2sees0now — branch on the printed list or drop the branch. -
BREAKING —
@setu-ts/cli— unknown flags are refused instead of silently ignored.setu
collected every--flagand never consulted the valid names, so a typo scaffolded a DIFFERENT
project with exit0and no warning:new app --dry-run --templat restproduced the minimal
project where--template restproduces therestcomposition, 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 forgenerate app,generate library, andworkspace ports— with exit2, 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 (--diand
--depends-ononnew; the transport flags,--runtime, and--diongenerate app) still
reach their specific guidance, and plugin-registered commands accept only--dirand--config—
aCliCommandHandlerreceives positionals only, so no plugin can read any other flag. Migration:
a script passing a stray flag today exits0and will now exit2— 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.newread the first positional only, sosetu new app extra junkscaffoldedappand
reported success with exit0;generateread only the schematic word, its name, and (for
custom) the custom-schematic name, dropping anything after; andadopt,workspace ports,
commands, andhelpconsumed no positionals at all. Each now refuses an over-arity invocation —
exit2, nothing written or created, a message naming the command and the expected count — in the
dispatcher before any command body runs, mirroringadd'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 bareadd/adopt/workspace ports/commands/help
forms), and plugin-registered commands still receive every positional. Migration: a script passing
stray positionals today exits0and will now exit2— remove them. -
BREAKING —
@setu-ts/database-plugin— default memory raw-SQL and programmatic-migration
refusals now answer501 Not Implementedinstead of a masked500.query()now rejects with
UnsupportedRawQueryErrorrather than throwing synchronously, so callers using.catch()now
receive the refusal.migrate()rejects with the newUnsupportedMigrationError: migrations are
a framework-wide unsupported capability, not a raw-query or query-shape refusal. Update status
assertions from500to501and synchronoustry/catchcall sites toawaitor.catch();
use each adapter's migration CLI instead ofmigrate(). -
BREAKING (behaviour) —
@setu-ts/auth-plugin— the rate limiter's429body answers in the
application's configured error format (X32-2).rateLimitMiddlewarewrote its own body with
ctx.response.status(429).json({ error, message }). M70f routed every first-party short-circuit
through therespondWithErrorseam — 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 ignorederrorHandler's configuration, and a consumer
parsing Problem Details (which this framework's own generated SDK does) got an unreadable body
underapplication/json. TheRetry-AfterandRateLimit-*headers are unchanged.
Migration: the body shape changes. WitherrorHandler({ format: 'rfc9457' })the429is now
Problem Details underapplication/problem+json, carryingdetailand nomessage; with
format: 'default'it is{ statusCode, message, details: { detail } }, the shape every other
refusal already used; with noerrorHandlerregistered it is the seam's{ error, detail }
fallback. A client readingbody.messagefor the limiter's text should readbody.detail(or
body.details.detailunder'default'). -
BREAKING (behaviour) —
@setu-ts/auth-plugin— an exhausted rate limiter no longer refuses the
operational probes (X32-1).RateLimitOptionshad no exclusion member at all, and the
middleware is documented as a global one, so a burst of abuse made/liveanswer429— which a
Kubernetes kubelet reads as a failed liveness probe and restarts the container, whose only fault
was being under load.excludenow defaults to the six operational paths (/live,/ready,
/health,/metrics,/openapi.json,/docs), the same listtenantMiddlewareexempts. An
exempt path increments no counter and carries noRateLimit-*headers, because the limit does not
govern it. Migration: passexclude: []to restore the previous behaviour. A caller list
REPLACES the defaults, so spreadDEFAULT_RATE_LIMIT_EXCLUDED_PATHSto extend them. -
BREAKING (wire keys) —
@setu-ts/auth-plugin—RedisRateLimitStorenamespaces its keys
(X32-5). Keys were written exactly askeyGeneratorproduced 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.
keyPrefixdefaults to'setu:ratelimit:', exported asDEFAULT_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. PasskeyPrefix: ''for the previous keys
byte for byte. -
BREAKING —
@setu-ts/database-plugin— driver conflicts and outages reach the client as409
and503(M90f / X38-1, X35-2). A backend-reported serialization failure (PostgreSQL SQLSTATE
class40—40001,40P01— Prisma'sP2034, MongoDB'sTransientTransactionErrorlabel,
Bigtable's gRPCABORTED, Cosmos449) now answers409 Conflictthrough
SerializationConflictError, where it was a masked500that told a well-behaved client to give
up — silently dropping the write and making optimistic concurrency unusable. A transiently
unreachable backend (SQLSTATE class08,57P03, the node-postgres pool timeout,
MongoNetworkError/MongoServerSelectionError, gRPCUNAVAILABLE, Cosmos429/503, the net
errnoECONNREFUSEDfamily) now answers503 Service Unavailablethrough
DatabaseUnavailableError. The original driver error is preserved ascause(the SQLSTATE stays
log-reachable); the serveddetailis a fixed sentence, never driver text. No classified answer
carriesRetry-After— the hint channel has no header and no component holds an honest horizon.
Migration: an application branching on the masked500for 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'sTransactionConflictException/ Cosmos's449are 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 answers400(M90f / X37-1).IRequest.json()rejects withMalformedRequestBodyError
(branded400 Bad Request) instead of a bareSyntaxErrorthaterrorHandlermasked to500.
The read stays lazy, so the400is produced when the handler reads, and a handler that catches
its own rejection keeps full control. An empty body still parses as{}oninject()and
MockRequest. Migration: none for well-formed callers; a500-matching catch for malformed
bodies now sees400. -
BREAKING —
@setu-ts/secrets-plugin— a write against a read-only provider answers501(M90f
/ X20-2).EnvProvider.set(andSecretsService.rotate()on theenvprovider) rejects with
ReadOnlySecretProviderError, answered501 Not Implementedwith the class's own sentence, where
it was a masked500. Migration: an application catching the old plain
Error('EnvProvider is read-only; …')by message still catches the new class (same message); add
aninstanceofbranch to distinguish it from faults. -
BREAKING —
@setu-ts/resilience-plugin— the shedding errors answer503/503/504(M90f /
X32-7).BulkheadFullErrorandCircuitOpenErrorare answered503 Service Unavailableand
TimeoutErroris answered504 Gateway TimeoutundererrorHandler, 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 carriesRetry-After— the hint channel has no header, and no
component holds an honest drain horizon;503is itself the retryable signal. Migration: an
application serving its own fallback for these errors is unaffected; one relying on the masked
500must match the new statuses orinstanceofthe classes.
Security
-
The
deno.lockresolution ofnpm:nodemailermoves9.0.4→9.1.1
(GHSA-2x7j-588g-ccc2, high). Quadratic
(O(n²)) time in nodemailer'saddressparserlets 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.tsalready importsnpm: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
resolvesnpm:nodemailer@^9against its own lock, so it was never pinned to9.0.4by 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 spelledanyOfon every supported zod v4, not
whichever spelling the installed patch version chose (issue #253). Draft 2020-12 permits both
spellings, and zod's publictoJSONSchema()changed which one it emits INSIDE the declared
>=4.4.0 <5support 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 —isStructuralShapekeys onanyOf, so a nullable or
primitive union silently stopped earning acomponents/schemasentry and a regenerated
@setu-ts/sdkclient changed shape for no API reason. It also produced a value the published
OpenApiSchemaObject.typecannot express (a single type name, not an array), so a consumer
switching on it got no compiler warning, and atypearray is 3.1-only whereanyOfconverts
down to OpenAPI 3.0.#adaptDocumentnow 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 theanyOfinstead of being distributed into its arms, which would apply a string
constraint to thenullarm. 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 pinnednpm:zod@4.5.4case 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 adefault,const,enum, example or vendor-extension
value keeps its owntypekey verbatim, and a node already assertinganyOfkeeps it — the
normalized union is conjoined throughallOf. -
@setu-ts/static-plugin— gzip sidecars now use the registeredgzipcontent-coding token. A
.gzsidecar was sent asContent-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-Matchvalidator for the uncompressed source cannot incorrectly return304for a
selected compressed sidecar. On runtimes without a filesystem, the registeredIStaticFiles
service now returns404as documented rather than throwing when an application callsserve(). -
@setu-ts/messaging-plugin— the Kafka broker starts (M90d / X28-1).KafkaBrokerwired its
reconnect supervisor with the uppercase KEYS of kafkajs'sproducer.events
('CONNECT'/'DISCONNECT') where the wire VALUES are required
(producer.connect/producer.disconnect); kafkajs validates the name and threw
KafkaJSNonRetriableErrorinsideregister(), 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 owneventsmap 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 throughjs.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 bareTypeError; and the delivery cast read
info.timestamp, which nats 2.29 spellsinfo.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 realtimestampNanosfield 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:JetStreamUnavailableErrorandJetStreamStreamError
replace the raw503and the catch-all-refusal text at bothconnect()failure sites, carrying
the platform error ascausewherever the platform produced one. The absent-stream refusal is the
one arm with nocause: 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.