Developer Docs Updates

This page tracks developer-visible documentation changes.

2026-04-07

• Added an explicit stock-bootstrap trace dashboard activation path with TRACE_AUTO_MOUNT=true. Core boot now keeps runtime registration and dashboard exposure separate by default, but it can auto-mount registerTraceDashboard(...) at TRACE_BASE_PATH with optional TRACE_MIDDLEWARE when that env flag is enabled, which removes the old partial-success trap where trace storage was active but /trace still returned 404.
• Added a shared CI install fallback at scripts/ci/install-deps.sh. Root workflows now try npm ci first and automatically fall back to npm install when npm reports lock/package sync drift such as missing internal @zintrust/core entries, so CI self-heals instead of stopping on EUSAGE.
• Fixed the release/CI version sync flow so internal @zintrust/* peer, dependency, and devDependency ranges stay pinned to currently published npm versions instead of drifting to an unpublished future version such as 0.4.75 before @zintrust/core is actually live. CI, smoke, SonarQube, and security workflows no longer auto-bump the root package ahead of npm ci.
• Scoped queue deduplication locks by queue name in core and @zintrust/queue-redis, so the same logical deduplication.id can now be reused safely across different queues while still deduplicating true duplicates inside the same queue. Worker-side releaseAfter lock cleanup now uses the same queue-scoped storage key contract.
• Fixed the release package-publish shim for @zintrust/core so package-local publish builds can type-check and run against the new resolveDeduplicationLockKey(...) export while publishing affected packages such as @zintrust/queue-redis.

2026-04-05

• Updated the Cloudflare Worker scaffold to include the non-secret runtime vars and env-local bindings needed for first-request boot in new deploys, and relaxed startup secret validation so ENCRYPTION_CIPHER is no longer treated as universally required in production. ZinTrust now only blocks on ENCRYPTION_CIPHER when encrypted-envelope interoperability is actually enabled by encryption-specific env such as ENCRYPTION_CIPHER itself or APP_PREVIOUS_KEYS.
• Relaxed strict startup env validation so non-critical runtime vars such as APP_NAME, HOST, PORT/APP_PORT, BASE_URL, LOG_LEVEL, and LOG_CHANNEL now surface as startup warnings instead of fatal config errors when STARTUP_REQUIRE_ENV=true. Critical startup requirements such as NODE_ENV, DB_CONNECTION, and APP_KEY remain blocking, and Cloudflare startup failures now log structured config errors, warnings, and startup health report details to make missing Worker runtime env easier to diagnose.
• Added development-safe Redis lifecycle tracking in core so subsystem-scoped direct Redis clients can be reused across non-production Node reloads, framework shutdown now drains tracked Redis clients before exit, and both app/bootstrap and worker shutdown flows respond to SIGUSR2 hot-reload restarts to reduce BullMQ/worker Redis zombie connections during local watch mode.
• Added first-class HTTP bridge broadcast support for isolated worker/container runtimes. Core now supports both automatic inmemory bridge forwarding in isolated runtimes and an explicit http-bridge broadcaster, so cross-process local socket delivery no longer requires application-level proxy wrappers.
• Added compatibility fallback from TIME_ZONE to APP_TIMEZONE and wired scheduler cron defaults to inherit the configured app timezone instead of hardcoded UTC when a schedule does not specify its own timezone.
• Updated the D1 migrator to normalize null-like string values such as NULL and null into real SQL NULL during data migration and schema default-value generation, preventing those sentinel strings from being preserved as quoted text in D1.
• Hardened @zintrust/queue-redis/register so official plugin auto-imports no longer treat a partially initialized core Queue export as a hard import failure; the Redis queue driver now registers only when the core queue registry API is actually available.
• Fixed the advanced queue enqueue path so AdvancedJobOptions.jobId and AdvancedJobOptions.uniqueId are forwarded into the shared queue payload when not already set there, while preserving explicit payload identifiers as the authoritative values.
• Clarified queued broadcast delivery in core so queued payloads treat channels as the authoritative resolved target list, keep legacy channel only as derived compatibility metadata, and ensure framework-owned broadcast workers publish from channels while preserving socket, delivery, and broadcaster metadata.
• Added strict helper type guards isNullish(...) and isDefined(...) so application code can get correct TypeScript narrowing for null | undefined checks without changing the legacy null-like semantics of isUndefinedOrNull(...).
• Enabled fresh-project request-path logging by default, added scaffolded LOG_COLOR=true and LOG_COLOR_THEME=arctic entries for colored text request logs, and aligned the documented logging env defaults with the runtime behavior.
• Hardened Broadcast.publish(...) so core now normalizes channelScope, tries the package-owned internal socket publish route before falling back to in-process socket or driver delivery, reports explicit transport attempts including internal-http, and surfaces clearer official-plugin auto-import failure details when optional packages are missing or broken.
• Added named request-log terminal color themes with LOG_COLOR_THEME, set arctic as the default palette, and documented all five supported theme options plus the standalone visual palette sheet for developer preview.
• Added a framework-owned Broadcast.publish(...) / Broadcast.publishLater(...) surface that prefers the active socket runtime automatically when available, kept the older broadcast helpers as compatibility aliases, updated queued broadcast processing to use the new object-based publish contract, and rewrote the broadcast docs/scaffolds so normal application code no longer needs custom publish helpers or a default /broadcast/send bridge.
• Updated the release version-sync flow so root and dist internal @zintrust/* dependency pins now resolve to the currently published npm version for each workspace package, falling back to the local workspace version only when a package has not been published yet. This prevents release metadata from pointing core or dist consumers at an unpublished next patch such as 0.4.62 when npm still only has 0.4.61.
• Removed @zintrust/workers from the root core runtime dependencies so worker support is install-on-demand again, and narrowed the official runtime auto-import sweep to packages explicitly selected by env/config signals instead of warning about every optional adapter package that is not installed.

2026-04-04

• Fixed socket bootstrap ownership for published consumers. @zintrust/core/start no longer re-exports ZintrustSocketHub, which avoids published core builds resolving @zintrust/socket through internal workspace paths like packages/socket/src/index.js in downstream apps, while the Cloudflare worker entry continues to expose the durable object from @zintrust/socket where it is actually needed.

• Updated Node bootstrap to always try the official base plugin auto-import set before project-local plugin files, so plain zin s no longer depends on src/zintrust.plugins.ts to discover built-in optional packages such as @zintrust/socket/register.

• Relaxed socket compatibility route registration for POST /broadcasting/auth so apps with an existing broadcast auth endpoint can keep their own handler when sockets are enabled instead of failing bootstrap with a reserved-route conflict.

• Fixed repository test and coverage flows so importing the governance ESLint config no longer depends on a previously patched local ESLint install. Vitest setup and pretest hooks now apply the Ajv draft-04 compatibility patch before governance config tests run, matching the existing lint-time workaround used for ESLint 10 with Ajv 8.

• Fixed queue-monitor recent job visibility for Redis/BullMQ workers at the package level. @zintrust/workers now records completed and failed recent-job history for both BullMQ event-driven workers and pull/dequeue-ack workers using the shared @zintrust/queue-monitor metrics contract, and @zintrust/queue-redis now finalizes acked pulled jobs as completed instead of deleting them immediately so Recent Jobs fallback queries can still see them.

• Hardened the unified socket compatibility surface so POST /broadcasting/auth is now framework-owned by default with configurable auth middleware, strict default authorization for private-* and presence-* channels, optional application takeover behind SOCKET_ALLOW_AUTH_ROUTE_OVERRIDE=true, startup-fatal reserved-route conflict detection instead of silent app-route shadowing, and a new project-level broadcast.socket.publish policy hook that can approve, reject, or rewrite server-side publish requests before fan-out.

• Fixed the shared @zintrust/core/start Cloudflare entry so lazy worker imports now resolve module-namespace default exports correctly instead of falling through to a non-function call path under Wrangler after additional named exports are present.

• Added a unified optional socket runtime surface for ZinTrust. Core now exposes socket runtime contracts and registry hooks, auto-discovers @zintrust/socket/register, intercepts Node upgrade requests and Worker websocket requests before the HTTP adapter path, and the new @zintrust/socket package provides zero-touch Pusher-compatible upgrade/auth/publish endpoints for local in-memory broadcast flows across Node and Cloudflare runtimes.

• Relaxed the default zin new ESLint scaffold so freshly generated apps no longer fail on relative imports just because the governance preset prefers ZinTrust path aliases. The governance ESLint preset now exposes an enforcePathAliases switch, and the generated app config disables that rule by default while still using the shared preset.

• Fixed framework-managed CORS preflight handling so OPTIONS requests now terminate with an empty 204 response instead of leaving browser preflight checks hanging after the status code is set.

• Added a monolith env-precedence gate for manifest-backed microservices. When RUN_AS_MONOLITH=true, zin start/zin s and manifest route registration now keep root env values authoritative for duplicate keys while still loading service-local env files to fill missing values.

• Fixed zin start / zin s Node startup so importing @zintrust/core/start no longer eagerly links the Worker, Deno, and Lambda handlers before root env loading completes. The Node start() path now lazy-loads those non-Node runtime handlers, which prevents fresh projects from caching fallback config values too early and restores env-driven features such as /queue-monitor under the CLI start path.

• Updated fresh project scaffolding to generate a default flat ESLint config backed by @zintrust/governance/eslint, add a default lint script, and place both eslint and @zintrust/governance in devDependencies instead of leaving governance tooling unconfigured by default.

• Fixed the public @zintrust/core/boot Node startup path so it now loads project env files before importing the stock bootstrap lifecycle, matching the existing CLI/bootstrap env parser behavior instead of starting with fallback defaults when apps use the thin src/boot/bootstrap.ts wrapper directly. The boot entry now also emits one structured warning when no env files were loaded for that Node bootstrap path.

• Fixed fresh Node startup queue-monitor registration so the runtime now prefers the preloaded project config/queue.ts override from StartupConfigFileRegistry before falling back to cached framework defaults or generated runtime config. This keeps /queue-monitor aligned with the same app-owned queue settings used during startup instead of disappearing when only the fallback config had monitor.enabled=false.

• Unified Node startup around a shared env-first path so @zintrust/core/start, @zintrust/core/boot, and zin start/zin s no longer rely on separate Node bootstrap wrappers. Root project env files now load through one singleton helper before any bootstrap import, and CLI Node starts run through generated @zintrust/core/start runners instead of executing the project bootstrap file directly.

2026-04-03

• Fixed package Docker and CI builds so workspace package builds no longer run redundant package-local npm install steps that can trigger npm workspace-filter warnings or unpublished-package resolution failures such as @zintrust/governance in filter set, but no workspace folder present and ETARGET for internal packages. The package build orchestrator now reuses the root workspace install by default and only performs a package-local install when FORCE_PACKAGE_INSTALL=true is explicitly set.
• Fixed local worker dashboard registration so /workers and /queue-monitor now mount in the normal Node runtime even when WORKER_ENABLED=false, while worker execution-only RPC gateways still stay disabled until worker mode is explicitly enabled. Also reduced noisy D1 lifecycle logging to debug level and stopped the System Trace query watcher from recording its own zin_trace_* storage SQL.
• Fixed Queue Monitor live dashboard stability. @zintrust/queue-monitor can now merge a stable knownQueues inventory into snapshots, the core runtime now feeds that inventory from persisted worker records, per-client SSE polling no longer shares queue selection across subscribers, and the dashboard preserves the selected queue while automatically hard-resetting the page only after the stream stays stale long enough to get out of sync.
• Improved ORM relation-bootstrap diagnostics so model methods that touch the database during Model.define(...) now emit one structured warning with the model table, relation name, and first probable user-code source frame instead of repeated generic Database connection 'default' is not registered noise. Added opt-in ZINTRUST_DEBUG_RELATIONS=1 tracing for per-relation bootstrap probes.
• Fixed published package compatibility between @zintrust/core and @zintrust/workers. The generated dist/package.json for core now pins workspace package dependencies like @zintrust/workers to the exact released version instead of a floating caret range, preventing older published core releases from resolving a newer workers patch with a stricter peer requirement. The workers package release sync now also keeps its @zintrust/core peer compatible across the active 0.4.x line so npm install -g @zintrust/core and similar fresh installs do not fail with ETARGET when workers is published ahead of core.

2026-04-02

• Fixed @zintrust/trace migration packaging so the published package now exports runnable JavaScript migrations from ./migrations instead of relying on TypeScript files in node_modules. The core trace migration command now resolves trace migrations as a package target with an explicit extension, prefers built JS when available, and fails with a packaging-specific error if an installed trace package still exposes TS-only migrations.
• Split @zintrust/trace activation so plugin/bootstrap loading now registers runtime watchers only, while dashboard UI/routes are an explicit route-level opt-in. Added registerTraceDashboard(router, options) for the common routes/api.ts case, added a lightweight @zintrust/trace/ui export so route code does not need to import the package root re-export surface, removed the stock core auto-mount behavior, and clarified trace route exposure in the CLI/package docs.
• Added a dedicated npm run lint:strict script and switched CI/publish verification to it so the repository no longer relies on the deprecated npm run lint --max-warnings=0 form that newer npm versions warn about. Use npm run lint:strict or npm run lint -- --max-warnings=0 for zero-warning ESLint runs.
• Fixed the pre-build npm workspace install topology for unpublished core versions. The root package-lock.json now keeps the local @zintrust/core links pointed at the repository root package instead of dist, the dist lock entry stays version-synced with the root package metadata, and scripts/release/sync-package-versions.mjs --check now fails if either lockfile edge drifts. This prevents npm ci --ignore-scripts from fetching an unpublished @zintrust/core@^... and failing release/CI installs with ETARGET.
• Added a Model.with(relations) static shorthand on defined models so developers have three equivalent eager-loading signatures: Model.with(['rel1', 'rel2']) (array shorthand that starts a fresh query), Model.query().with('rel1').with('rel2') (chained), and Model.query().with({ rel1: constraint, rel2: constraint }) (constrained object). Updated the eager loading section in docs/models.md with examples of all three signatures.

2026-04-01

• Replaced regex-based query redaction and stack-frame parsing in @zintrust/trace with deterministic scanners so CodeQL no longer flags ReDoS-prone handling on trace query strings, exception traces, or job failure traces. Also re-synced the trace/default database connection fallback so literal DB_CONNECTION=default resolves to the active runtime default connection while TRACE_DB_CONNECTION still overrides trace migrations and runtime storage when explicitly set.
• Hardened ORM eager loading so belongsTo now batches on the parent foreign key and related owner key, belongsToMany follows the pivot-join resolution path during eager loading, and lazy-vs-eager parity coverage now spans standard, polymorphic, and through relations plus withCount(...) support for the currently counted relation types.
• Fixed core ORM hydration and model-instance write semantics so first() and firstOrFail() now return hydrated models like get() and paginate(), raw hydrate(...) no longer re-runs mutators on stored values, and save() now persists model-instance inserts and dirty updates through the query builder with mutator-transformed values intact.
• Added a reusable core Wrangler local-dev env materialization path driven by .zintrust.json Cloudflare env groups. ZinTrust can now generate manifest-scoped .dev.vars files for Workers through the CLI, and the Wrangler start flow reuses the same resolver instead of maintaining a separate transient-only implementation.
• Added a dedicated zin wrangler:dev-vars command so Cloudflare local-dev env generation is available as a first-class CLI workflow instead of only as a prepare option.
• Tightened the @zintrust/trace request-context bridge so trace batching, auth-tag correlation, and route filtering now read the live request context synchronously during runtime hooks. The trace now skips its own /trace/* traffic across watcher emissions instead of recursively recording dashboard requests, SQL writes, and related log noise.
• Improved the inline @zintrust/trace entry detail views so structured JSON payloads and SQL statements render with type-aware syntax colors plus one-click copy actions, and surfaced execution duration more consistently across request, query, outbound HTTP, and other timed trace entries.
• Refreshed the inline @zintrust/trace dashboard shell to match the rest of the ZinTrust admin UI more closely: it now uses the shared Inter-based dashboard font stack, swaps the old sidebar-heavy Telescope note for a responsive header-plus-tabs layout, embeds the docs-website/brand/prism-shield-pulse-core.svg mark as the visible logo and favicon, and adds built-in light/dark mode support for the trace experience.
• Fixed the plugin-driven @zintrust/trace boot path so it no longer recurses back through getKernel() while the application is already booting. ZinTrust now queues trace global middleware registrations through the kernel itself, which prevents repeated Database connection 'default' is not registered noise during Worker reloads and keeps the optional trace package buildable again after the logger/watcher import cleanup.
• Fixed the trace connection fallback so both the core auto-mount path and @zintrust/trace/register now inherit the app's active DB_CONNECTION when TRACE_DB_CONNECTION is omitted, instead of forcing the literal registry key default. This restores the documented TRACE_ENABLED=true local setup for D1-backed Worker apps and avoids the old Requesting connection: default failure path.
• Updated @zintrust/trace setup guidance so the supported activation path now goes through src/zintrust.plugins.ts and src/zintrust.plugins.wg.ts via @zintrust/trace/plugin, instead of telling developers to wire trace bootstrap imports into ad hoc start files. The core runtime now only lazy-mounts the trace dashboard after that explicit plugin opt-in is present, and the inline dashboard shell was refreshed toward a lighter request-trace layout while removing the broken showPage inline-handler bug.

2026-03-31

• Added first-class optional CLI registration for @zintrust/trace, including zin migrate:trace, zin trace:status, zin trace:prune, and zin trace:clear, and wired the stock runtime boot path to auto-mount the trace dashboard when TRACE_ENABLED=true so the package can be enabled and inspected live without hand-editing the example app routes.
• Added a packed Cloudflare secret compatibility mode to the core env surface. When USE_PACK=true, ZinTrust now expands JSON secret bindings listed in PACK_KEYS into the resolved Env.get(...) view, keeps direct env values above packed values, tracks the winning source for diagnostics, and auto-loads local .env.pack files for Node-side development without overriding the direct control keys.
• Extended the Cloudflare shared-env manifest workflow so deploy commands now reuse the same target-aware secret selection as zin put cloudflare, letting zin deploy, zin deploy d1-proxy, zin deploy kv-proxy, and zin deploy:ccp sync selected Worker secrets automatically before wrangler deploy unless --no-sync-secrets is passed.
• Updated microservice scaffolding so new services automatically register their canonical domain/name ID under .zintrust.json -> cloudflare.targets, keeping service-specific Cloudflare secret selection aligned with the generated runtime manifest and service-local Worker config.

2026-04-06

• Updated scripts/release/sync-package-versions.mjs so CI can opt into --bump-root-to-next, which advances the root package.json version to the next published patch line when needed and pins non-local @zintrust/* dependency specs to the live npm versions while preserving package-local file: links.
• Reworked the npm-based GitHub workflows to stop failing fast on sync-package-versions.mjs --check. CI, smoke, SonarQube, and security jobs now self-heal by running the sync script plus npm install --package-lock-only --ignore-scripts before npm ci, while the publish workflow refreshes workspace metadata without auto-bumping the publish line.

2026-03-30

• Added a first-class Cloudflare env-target manifest shape to fresh .zintrust.json scaffolds via cloudflare.shared_env, cloudflare.targets, and cloudflare.wrangler_envs, then wired that manifest into zin put and local zin s --wg snapshots. Fresh projects can now keep one canonical shared secret list plus additive per-target keys, and Wrangler dev no longer needs to dump every loaded env var into every Worker by default.
• Fixed the zin init:container-workers scaffold so the generated docker-compose.workers.yml keeps WORKER_ENABLED and WORKER_AUTO_START correctly indented inside the workers-api.environment list. This prevents malformed compose output in freshly scaffolded worker container setups.

2026-03-29

• Fixed the Cloudflare Containers proxy gateway so it now routes both the documented public service prefixes such as /redis/* and the internal ZinTrust proxy paths such as /zin/redis/command to the correct backend container. This prevents Worker startup and auth flows from failing with Redis proxy request failed (404) when a caller reaches the gateway using the raw proxy path.

• Fixed the release -> master Release PR patch-bump flow so scripts/ci/bump-version.js --apply no longer calls npm install --package-lock-only after bumping to an unpublished workspace version. scripts/release/sync-package-versions.mjs now keeps workspace package manifests and the matching package-lock.json entries in exact lockstep with the core version, which prevents the CI ETARGET No matching version found for @zintrust/core@^... failure during automated release PR bumps.

• Updated the active dependency-maintenance line on dev by bumping the root ranges for @cloudflare/containers, @faker-js/faker, @types/pg, eslint, miniflare, mongodb, mssql, and typescript-eslint, syncing the Cloudflare Containers proxy workspace package to @cloudflare/containers@^0.2.0 plus newer Workers types, and refreshing pinned GitHub Actions SHAs for actions/checkout, docker/login-action, TruffleHog, and CodeQL. The TypeScript 6.0.2 bump was intentionally left out because typescript-eslint@8.57.2 still requires typescript < 6.0.0 in this repo.

• Fixed Docker release builds so they keep DIST_SKIP_NPM_VERSION_CHECK=true during the builder stage. This prevents the dist package manifest and build banner from auto-advancing past the published release line during local and CI image builds.

• Extended the release version sync flow so it now updates and validates root package.json dependencies on workspace packages alongside the workspace manifests themselves. This keeps package-lock.json aligned for npm ci consumers such as the Docker image build, preventing release lines like 0.4.34 from publishing packages successfully while the container build still resolves an older internal package range.

• Updated Queue Monitor middleware validation so QUEUE_MONITOR_MIDDLEWARE now accepts supported dynamic route middleware keys such as rateLimit:1000:1, then documented that env usage in the queue docs.

• Hardened the automated release bump flow so scripts/ci/bump-version.js --apply now re-syncs workspace package versions and refreshes the root lockfile immediately after bumping core, and the release PR workflow now commits those workspace manifest updates too. This prevents the workspace version sync CI gate from failing on freshly bumped release branches.

• Re-synced all workspace package versions, @zintrust/core peer ranges, and the root package-lock.json to 0.4.33 after publish so the node scripts/release/sync-package-versions.mjs --check CI gate stays green for the new release line.

• Documented the Queue Monitor env surface more clearly, including that QUEUE_MONITOR_MIDDLEWARE is the env key for protecting the dashboard with registered route middleware keys such as auth or auth,jwt, and that invalid keys fail config loading.

• Expanded the middleware docs to show inline route rate-limit keys alongside the existing RateLimiter.create() registration pattern, and added focused middleware key tests so malformed rateLimit:<max>:<windowInMinutes> strings are rejected while valid parameterized keys remain accepted.

• Added parameterized route middleware support for rate limiting, so routes can now declare inline keys such as rateLimit:6:1 or rateLimit:100:0.4 and get a lazily created RateLimiter instance without pre-registering a separate middleware name.

• Synced all workspace package versions and @zintrust/core peer ranges to 0.4.32, regenerated the root lockfile, and added a pre-npm ci workspace-version check in every npm-based CI workflow so package/version drift fails fast with a direct error instead of an ERESOLVE install failure.

• Updated the fresh project scaffold to generate src/boot/bootstrap.ts as a thin @zintrust/core/boot wrapper, so new apps can reuse the stock ZinTrust Node/Docker bootstrap lifecycle without copying the full core bootstrap source.

• Published a stable @zintrust/core/boot subpath backed by src/boot.ts so fresh-app and Docker/bootstrap flows can import the side-effect boot entrypoint directly instead of relying on internal @boot/* aliases.

• Updated the Wrangler-backed zin proxy:d1 and zin proxy:kv commands to accept --port <port> and forward it to wrangler dev, so local Cloudflare proxy Workers can be started on an explicit port like zin proxy:d1 --port 8787.

• Bumped @zintrust/core to 0.4.31 for the proxy CLI consumer-app fix after correcting both the published scaffold output and the core proxy runtime exports.

• Updated the generated D1 and KV proxy Worker shims plus the developer docs to use the stable @zintrust/core/proxy export surface instead of nested proxy subpath imports, which fixes fresh consumer apps where Wrangler could not resolve @zintrust/core/proxy/d1/ZintrustD1Proxy or @zintrust/core/proxy/kv/ZintrustKvProxy during local dev.

• Replaced the core ZintrustD1Proxy and ZintrustKvProxy exports with built-in Worker handlers instead of optional package loaders, which fixes fresh apps that previously failed at runtime with Optional dependency not installed: @zintrust/cloudflare-d1-proxy or the KV equivalent.

• Updated the zin proxy:d1 scaffold so the generated env.d1-proxy block now includes a commented Wrangler custom-domain route example for d1-proxy.example.com, matching the existing proxy scaffold guidance style.

• Updated the zin proxy:kv scaffold so the generated env.kv-proxy block now includes a commented Wrangler custom-domain route example for kv-proxy.example.com, matching the existing proxy scaffold guidance style.

2026-03-28

• Fixed the package release flow for published adapters/packages so it now runs the same ESM relative-import repair and package artifact post-processing used by the normal package builder before publishing, which prevents broken extensionless imports such as the @zintrust/queue-monitor Docker startup failure on fresh installs.
• Updated zin new --with-d1-proxy so it no longer scaffolds the stale standalone @zintrust/cloudflare-d1-proxy dependency into fresh apps and instead points developers at the supported core entrypoint plus zin proxy:d1 and zin deploy d1-proxy workflow.
• Added zin proxy:d1 for local D1 proxy development. The command now scaffolds env.d1-proxy into wrangler.jsonc when missing, then starts local Wrangler dev against the core D1 proxy entrypoint, and the docs now point developers to @zintrust/core/proxy/d1/ZintrustD1Proxy.
• Added zin proxy:kv for local KV proxy development. The command now scaffolds env.kv-proxy into wrangler.jsonc when missing, then starts local Wrangler dev against the core KV proxy entrypoint, and the docs now point developers to @zintrust/core/proxy/kv/ZintrustKvProxy.
• Updated the Cloudflare proxy docs so the D1, KV, and Containers package pages plus the D1/KV remote guides now show the supported ZinTrust deploy CLI and local dev CLI commands directly after installation/setup, and corrected the D1/KV package pages to reflect that those Worker packages are currently deployed from the repo rather than installed as public npm packages.
• Updated the container worker scaffold again so docker-compose.workers.yml now boots a single bootstrap-driven workers-api service that serves the worker pages and auto-starts eligible workers in the same process, replacing the previous split workers-api plus worker-runner default.
• Updated @zintrust/workers so worker discovery can fall back to project worker files when persistence is empty, which lets fresh projects surface worker metadata and details without first creating worker rows in the database.
• Added an explicit workerDefinition starter worker template for fresh apps, extended worker auto-start to use file-backed definitions only when persisted auto-start candidates are absent, and documented direct zin migrate:worker --connection <name> usage for D1-backed worker persistence.
• Added an optional src/zintrust.workers.ts project worker bootstrap file for fresh apps, and updated Docker/worker startup so the worker image and worker:start-all can auto-load that entrypoint while also falling back to file-backed worker definitions when persisted worker rows are absent.
• Updated the container worker scaffold to generate a dedicated Dockerfile.workers overlay image that builds fresh projects with npm run build, then layers compiled worker artifacts onto the published zintrust/zintrust base image so developers can use either app/Workers discovery or an optional src/zintrust.workers.ts entrypoint.

2026-03-27

• Updated the container worker scaffold so generated database password env vars no longer ship with an insecure hard-coded secret fallback, which removes the Sonar new-code security finding on the release PR while keeping password values configurable through project env files.
• Updated the basic app scaffold to include the published @zintrust/d1-migrator package by default so fresh projects keep the zin migrate-to-d1 command available without a separate manual install, and clarified the CLI reference to match the optional-package auto-registration flow.

2026-03-26

• Verified the Cloudflare Workers auth and jwt failure path keeps the default 401 contract by default and honors project responder overrides for custom status/body output, then added a focused regression test covering both cases.
• Updated the auth-response verification note and middleware failure override docs so they reflect the current @zintrust/core@0.4.22 API surface and the supported responder-based customization path.

2026-03-23

• Added Microservices Runtime Guide to document the generated manifest, runtime hook files, canonical service IDs, standalone service boot, and layered config overrides.
• Clarified that generated services use routes/api.ts and src/bootstrap/service-manifest.ts as the main runtime entry files developers work with.
• Documented the current implementation status: manifest-based route mounting is in place, standalone Node config layering has started, and Worker-specific service-local config integration is still being extended.
• Documented that scaffolded microservices now generate their own wrangler.jsonc, with service-owned aliases kept local and root-owned aliases mapped back to the root project.
• Clarified terminology in the developer docs so Cloudflare Worker runtime, generic serverless runtime, and ZinTrust background workers are described explicitly instead of all being shortened to “worker”.
• Extended that terminology cleanup into broader developer docs including cloud deployment, architecture, worker management, and helpers so Cloudflare Worker runtime and ZinTrust background workers are not conflated.
• Updated the runtime guide to state explicitly that standalone microservice boot code lives in the microservice src/index.ts, replaced internal-sounding headings like Current behavior and Current Limits, and rewrote the remaining runtime work section in developer-facing terms.
• Implemented scaffolded Cloudflare Worker / serverless service-local startup config merging so generated microservice wrangler.jsonc files keep root config aliases pointing at the root app while also exposing optional service-local config aliases for layered overrides.
• Moved scaffolded standalone microservice boot ownership into a first-class core start helper so generated service entrypoints delegate runtime setup to framework code instead of hand-wiring ProjectRuntime.set(...) themselves.
• Updated generated runtime hook and service manifest files so the built CLI can import source-owned runtime metadata in consumer apps without failing on extensionless local imports, which fixes manifest-backed zin routes loading and standalone service boot in freshly scaffolded projects.
• Refreshed the maintainer-facing scaffold runtime fix process note so it documents the implemented core behavior, the dist-package consumer validation, and the remaining need for legacy generated-file normalization.
• Updated CLI service-directory startup env loading so root .env* files load first and service-local .env* files override them, and added clearer developer guidance for the missing tsx runtime dependency during standalone microservice starts.
• Added monolith-only manifest route prefixes for microservices so standalone services keep their native paths while monolith mounting defaults each service to /<domain>/<name> unless the manifest overrides the prefix.
• Updated official runtime plugin auto-imports so missing optional ZinTrust adapter packages no longer raise a startup warning in consumer apps, while genuinely broken installed plugin register modules still surface as failures.
• Added explicit standalone microservice env controls so bootStandaloneService() and zin s can keep root env loading enabled by default, skip it with rootEnv: false or --no-root-env, and override the inferred microservice env source with envPath or --env-path.
• Upgraded simulate/fresh-check into a generated-style standalone microservice fixture with src/bootstrap/service-manifest.ts, src/zintrust.runtime*.ts, and a focused simulation test that verifies root .env loading plus service-local .env overrides from a service-directory context.
• Fixed three runtime regressions in the startup path: root monolith starts now preload service-local .env files with service values overriding root duplicates, service-directory zin s now boots the standalone service instead of short-circuiting on partially cached runtime metadata, and Worker startup now avoids eager non-default database instantiation that previously triggered Cloudflare PostgreSQL socket failures during boot.
• Fixed the remaining standalone Worker env propagation gap so zin s --wg from a microservice directory now injects the merged root-plus-service env set into Wrangler dev bindings, allowing Worker routes to see root values and service overrides consistently in both Env.get(...) and static Env.* reads.
• Added a per-service loadEnv manifest flag so monolith startup can mount a microservice while explicitly skipping that service's local .env* preload layer.
• Updated service scaffolding guidance and generated manifest entries to default mounted services to loadEnv: false, avoiding monolith root/global env merging unless developers opt in explicitly.
• Updated startup so official runtime plugin auto-import failure warnings are only emitted in Docker worker mode, which prevents noisy zin s and freshly scaffolded project flows from showing Loaded 0/16 official plugin imports during normal local development.
• Added d1 as a first-class zin new database option alongside d1-proxy, so the interactive database list now includes direct Cloudflare D1 as well as the HTTPS proxy mode.
• Updated zin new project scaffolding so generated .gitignore files include .dev*, which keeps temporary Wrangler-style dev variable files out of git by default.
• Fixed manifest-backed microservice route loading in zin s --wg for generated apps by generating src/zintrust.plugins.wg.ts with the required ProjectRuntime.set({ serviceManifest }) seed automatically, so developers no longer need to add that block by hand in fresh projects.
• Fixed zin s --wg startup in fresh projects when the optional @zintrust/workers package is not installed, so Cloudflare/Wrangler No such module "@zintrust/workers" failures now fall back to the disabled worker runtime instead of aborting app boot.
• Corrected the newstart Worker entry example so it re-exports the core Cloudflare handler instead of calling getKernel() before Worker bindings are initialized; middleware in fresh apps should stay registered through config/middleware.ts and route metadata rather than custom Worker bootstrap wrappers.
• Updated zin s --wg to force WORKER_ENABLED=false, which prevents background worker package initialization in Wrangler dev even if a custom Worker entrypoint is written incorrectly, and added a start-time warning when src/index.ts calls getKernel() before the core Cloudflare handler.
• Added project-level custom middleware registration support through config/middleware.ts, updated the middleware docs with the full fresh-app flow, and made zin add middleware <Name> generate and register a route middleware skeleton automatically.
• Fixed standalone zin s --wg from src/services/<domain>/<name> so it now prefers service-local port env vars like <SERVICE_NAME>_PORT and no longer falls back to a conflicting root APP_PORT; newly scaffolded services now also write APP_PORT, PORT, and SERVICE_PORT into their local .env files.

2026-03-25

• Merged the typed middleware registry guide into docs/middleware.md so middleware usage, project registration, typed route keys, and governance test guidance now live in one canonical page, and updated the docs site navigation to point at that single doc.
• Updated JSON request error handling so NotFoundError stacks are still logged server-side but no longer returned in API error payloads.
• Blocked accidental root-package npm publish so releases fail fast unless they publish the compiled dist package, which fixes the broken global CLI install path where source bin entries tried to resolve aliases like @config/logger at runtime.
• Updated zin docker to reuse one deterministic .dev.vars*.disabled-by-zin backup per file and remove legacy UUID-suffixed backups automatically, so repeated Docker/Wrangler dev runs no longer keep accumulating stale backup files.
• Updated request-body XSS sanitization to strip markup without HTML-encoding opaque JSON payload characters like / and =, which preserves base64 and signed token inputs in fresh apps while keeping output escaping in the HTML render layer.
• Documented and scaffolded the plug-and-play built-in middleware override path for fresh apps, including overriding keys like jwt in config/middleware.ts so developers can customize default auth error payloads without changing route metadata.
• Updated core middleware assembly so built-in keyed overrides now apply consistently to both route resolution and the shared global middleware slots, making fresh-app plug-and-play overrides factual for framework-owned middleware keys instead of only route-local keys.
• Added a first-class middleware responder contract for response-writing built-ins so fresh apps can customize default auth, CSRF, rate-limit, validation, and JSON error payloads through config/middleware.ts without replacing the underlying middleware logic.
• Refreshed vulnerable transitive dependencies so the workspace now resolves picomatch to patched 2.3.2 and 4.0.4 releases and yaml to 2.8.3, clearing the reported npm audit advisories without changing the top-level dependency API.
• Fixed two Workers DX regressions that previously forced repository-level core patching in fresh apps: SecurityMiddleware.create() now derives default CORS behavior from securityConfig.cors instead of hard-coded values, and the Cloudflare response bridge now preserves middleware-set HTTP status codes when the framework response wrapper writes to res.statusCode.
• Fixed the Worker startup-config loader so fresh-app overrides from config/middleware.ts are bundled and applied in live zin s --wg runs, which restores app-owned auth/jwt responder customization, and added OPTIONS path fallback routing so global security middleware can answer CORS preflights even when a route only exists under other HTTP methods.
• Updated core auth/jwt built-in unauthorized fallback bodies to ship a structured { error: { code, message } } contract by default, and fixed @zintrust/queue-redis package builds to normalize dist ESM imports before publish so clean installs no longer depend on downstream rewrite scripts.
• Split the default middleware failure body helper into a dedicated middleware body module so editor/type-service resolution stays stable when auth and jwt middleware import the structured fallback body factory.
• Updated @zintrust/queue-redis to publish against a semver peer on @zintrust/core while keeping a local file:../../dist dev dependency, so package-local work still uses the local core build but clean tarball installs resolve like published consumers.