@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-path/SKILL.md

@@ -14,7 +14,10 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Core package: `storage/framework/core/path/src/`
 
 ## Node.js Path Re-exports
-`basename`, `delimiter`, `dirname`, `extname`, `isAbsolute`, `join`, `normalize`, `parse`, `relative`, `resolve`, `sep`, `toNamespacedPath`
+`basename`, `delimiter`, `dirname`, `extname`, `isAbsolute`, `join`, `normalize`,
+`relative`, `resolve`, `sep`, `toNamespacedPath`. `parse` is available through
+the `path` facade, not a named root export. Named `sep`/`delimiter` are strings;
+their facade counterparts are functions.
 
 ## Framework Path Builders
 
@@ -24,9 +27,9 @@ All accept an optional relative path suffix and return absolute paths.
 ```typescript
 appPath('Models')                  // ~/app/Models
 userActionsPath()                  // ~/app/Actions
-userComponentsPath()               // ~/app/Components
-userViewsPath()                    // ~/app/Views
-userFunctionsPath()                // ~/app/Functions
+userComponentsPath()               // ~/resources/components (root components/ wins if present)
+userViewsPath()                    // ~/resources/views
+userFunctionsPath()                // ~/resources/functions (root functions/ wins if present)
 userJobsPath()                     // ~/app/Jobs
 userControllersPath()              // ~/app/Controllers
 userListenersPath()                // ~/app/Listeners
@@ -42,10 +45,11 @@ userEventsPath()                   // ~/app/Events.ts
 ```typescript
 actionsPath()                      // ~/storage/framework/core/actions
 buddyPath()                        // ~/storage/framework/core/buddy
-runtimePath()                      // ~/storage/framework/core/buddy
+runtimePath()                      // ~/storage/framework/buddy (Buddy output)
 buildPath()                        // ~/storage/framework/core/build
-cachePath()                        // ~/storage/framework/cache
-cloudPath()                        // ~/cloud
+cachePath()                        // ~/storage/framework/core/cache (package source, not cache data)
+cloudPath()                        // ~/storage/framework/core/cloud (package source)
+projectPath('cloud')               // ~/cloud (application infrastructure)
 frameworkCloudPath()               // ~/storage/framework/cloud
 libsPath()                         // ~/storage/framework/libs
 ```
@@ -57,19 +61,19 @@ arraysPath()     authPath()         browserPath()
 cliPath()        chatPath()         collectionsPath()
 configPath()     databasePath()     datetimePath()
 dnsPath()        docsPath()         emailPath()
-enumsPath()      envPath()          errorHandlingPath()
+enumsPath()      coreEnvPath()      errorHandlingPath()
 eventsPath()     fakerPath()        gitPath()
-healthPath()     httpPath()         i18nPath()
+healthPath()     paginationPath()   featuresPath()
 lintPath()       loggingPath()      notificationsPath()
 objectsPath()    ormPath()          pathPath()
-paymentsPath()   pluginsPath()      pushPath()
+paymentsPath()   modelMetaPath()    pushPath()
 queuePath()      realtimePath()     routerPath()
 schedulerPath()  searchEnginePath() securityPath()
 serverPath()     shellPath()        slugPath()
 smsPath()        socialsPath()      storagePath()
 stringsPath()    testingPath()      tinkerPath()
-tunnelPath()     typesPath()        uiPath()
-utilsPath()      validationPath()   whoisPath()
+skillsPath()     typesPath()        uiPath()
+utilsPath()      validationPath()   actionRunnerPath()
 ```
 
 ### Resource Paths
@@ -77,7 +81,7 @@ utilsPath()      validationPath()   whoisPath()
 assetsPath()                       // ~/resources/assets
 resourcesPath()                    // ~/resources
 publicPath()                       // ~/public
-localesPath()                      // ~/locales
+langPath()                         // ~/locales
 routesPath()                       // ~/routes
 ```
 
@@ -87,16 +91,17 @@ buildEnginePath()
 libsEntriesPath()
 frameworkPath()                    // ~/storage/framework
 corePath()                         // ~/storage/framework/core
-defaultsPath()                     // ~/storage/framework/defaults
+frameworkPath('defaults')          // ~/storage/framework/defaults
 defaultsAppPath()
 defaultsResourcesPath()
 ```
 
 ### Relative Path Variants
-Most paths have `relative*` variants:
+Only some helpers have relative modes. Inspect the selected signature rather
+than deriving a function name from another path helper:
 ```typescript
 relativeActionsPath()
-relativeAppPath()
+layoutsPath('main.stx', { relative: true })
 ```
 
 ## Path with Suffix
@@ -104,15 +109,30 @@ relativeAppPath()
 ```typescript
 appPath('Models/User.ts')           // ~/app/Models/User.ts
 databasePath('migrations')          // ~/storage/framework/core/database/migrations
-configPath('app.ts')                // ~/config/app.ts
+projectConfigPath('app.ts')         // ~/config/app.ts
+configPath('src/index.ts')          // ~/storage/framework/core/config/src/index.ts
 ```
 
 ## Gotchas
+- Distinguish application paths from package paths. `databasePath` and
+  `configPath` point to core package sources; `userDatabasePath`,
+  `userMigrationsPath` and `projectConfigPath` point to application files.
+- Runtime state has explicit helpers: `stxPath`, `frameworkRuntimePath` and
+  `cloudStatePath`. `cloudPath` points to the core package; use
+  `projectPath('cloud')` for the application's committed infrastructure.
+- `defaultsPackagePath` resolves bundled defaults in a packaged install;
+  `inspectDefaultsProvenance` reports version/source skew. Use these instead
+  of assuming every consumer vendors the entire framework source tree.
+- `runtimeDirectoryEnv`/`applyRuntimeDirectoryEnv` carry STX/cloud state roots
+  into subprocesses while preserving explicit environment overrides.
+- Path joining is not an authorization or root-containment check. Validate
+  an untrusted file path at the storage/request boundary before reading it.
 - Always use `@stacksjs/path` instead of Node's `path` for framework paths
 - All paths resolve to absolute paths by default
 - Most functions accept an optional relative path suffix
 - `relative*` variants return paths relative to project root
-- `user*Path()` functions point to application-level directories (app/)
+- `user*Path()` functions point to application files; frontend resources are
+  under resources, not an invented app/Components or app/Views directory.
 - `built*Path()` functions point to compiled output directories
 - Path is a dependency of almost every framework package
 - Some paths accept `options` with `relative` flag

package/ai/skills/stacks-payments/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-payments
-description: Use when implementing payment processing in Stacks - Stripe charges, subscriptions, checkout sessions, customer management, payment methods, invoices, coupons, promo codes, products, prices, webhooks, or the Payment facade. Covers @stacksjs/payments and config/payment.ts.
+description: Use when implementing Stacks payment drivers, charges, subscriptions, checkout, customer methods, Stripe billing/catalog/Connect, provider webhooks, or the Payment facade. Covers @stacksjs/payments and config/payment.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -553,6 +553,14 @@ The instance methods are exactly the keys of `createBillableMethods` in
   `transactionHistory()`.
 
 ## Gotchas
+- A provider name in config is not a claim that every operation or live
+  environment is supported. Check the selected driver implementation and
+  retained provider tests, and test sandbox completion/webhook behavior for
+  the configured account. Unsupported operations must remain explicit errors.
+- Payment records, provider state and entitlement state are distinct. Use
+  `subscriptionGrantsAccess` and `subscriptionPeriod` rather than inferring
+  access from a catalog price id alone. A webhook signature is verified against
+  its original raw payload before applying domain events.
 - Stripe API keys MUST be in `.env` as `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY` -- never hardcode them in config files
 - The Stripe client is created lazily, on first use: importing `@stacksjs/payments` without `STRIPE_SECRET_KEY` (or without the opt-in `stripe` package) is fine, and the first Stripe call throws naming what is missing
 - All amounts are in cents -- use `toCents()` and `toDollars()` for conversion

package/ai/skills/stacks-pr/CREDITS.md

@@ -0,0 +1,3 @@
+# Credits
+
+The **Summary** section's menu of visuals (pseudocode, call trees, component trees, file trees, Mermaid, diffs) and its placement guidance come from [Dex Horthy](https://github.com/dexhorthy)'s [`show-me`](https://github.com/humanlayer/humanlayer) skill, reproduced almost word for word and aimed at a diff instead of a live conversation. `stacks-pr` does not depend on `show-me` as a skill (it isn't part of this repo, and a hard dependency would break standalone installs), so the content is copied in rather than pointed at; this file is the attribution a dependency would otherwise have carried.

package/ai/skills/stacks-pr/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-pr/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## pr
+
+Source: [skills/engineering/pr/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/pr/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Ported with Stacks skill names, canonical guidance, local-tracker fallback, TypeScript/Bun tooling, and conditional external actions.

package/ai/skills/stacks-pr/PLAYBOOK.md

@@ -0,0 +1,127 @@
+> Adapted playbook. Read [the Stacks rules](../stacks-flow/ENGINEERING.md) first. Commit, push, publish, and tracker mutations are conditional on the user's authorization.
+
+
+Use this template for writing the PR body:
+
+```markdown
+## Summary
+
+<diagram, diff-sketch, or tree>
+
+## Evidence
+
+- **Before:** <screenshot/output/failing test run>
+  **After:** <screenshot/output/passing test run>
+
+## Merge Danger
+
+**Door:** <one-way or two-way>
+
+<optional: description>
+
+**Blast Radius:** <one-word description>
+
+<optional: potential ramifications of merge>
+```
+
+## Sections
+
+Skip all preambles and keep prose brief. Use the user's domain language from `GLOSSARY.md`.
+
+### Summary
+
+Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```text
+<SessionPage> (resources/views/session.stx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a behavior change, a compact diff sketch can be enough:
+
+```diff
+- Always write content
++ Return the cached result when content is unchanged
++ Write changed content and invalidate the cache
+```
+
+For a nested file, component, or call-tree change, use the actual diff when its
+indentation communicates ownership. Otherwise show the before and after trees
+separately using the examples above. Preserve the smallest view that makes the
+change clear.
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1);
+  return `use the ${skillName} skill`;
+}
+```
+
+#### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.
+
+### Evidence
+
+Concrete evidence that the change works. Show a before and after.
+
+Screenshots are S-tier - when the environment is set up for it and the change is visual.
+
+Execution-based evidence is A-tier. Test results, console output. Show the exact test that now fails and passes, using pseudocode.
+
+### Merge Danger
+
+Describe whether it's a one-way or two-way door. You can walk back through two-way doors, but not one-way doors. A PR that is cheap to roll back is lower risk. Changes that involve destructive actions or hard-to-reverse decisions are one-way doors.
+
+The blast radius is the potential impact or scope of the changes introduced by this PR. Consider all possibilities. Examples are layout shift, breakages for consumers, mobile responsiveness, etc.

package/ai/skills/stacks-pr/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: stacks-pr
+description: Use when writing a PR description with concise behavior, concrete evidence, and material rollback or compatibility risks. Covers Stacks pull request descriptions.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# PR
+
+Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md), then
+[PLAYBOOK.md](PLAYBOOK.md). The playbook preserves this workflow's decision
+criteria; the Stacks rules govern APIs, tooling, tracking, and authorization.
+
+Credit: adapted from Matt Pocock's `pr` skill, MIT licensed.
+See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+
+## Completion
+
+Produce the requested behavior or reviewable artifact and satisfy the
+playbook's completion criteria. Preserve existing decisions and user edits.
+Use the native Stacks skills for implementation and verification, and carry
+existing authorization through the workflow.

package/ai/skills/stacks-prototype/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-prototype/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## prototype
+
+Source: [skills/engineering/prototype/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/prototype/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

package/ai/skills/stacks-prototype/SKILL.md

@@ -64,3 +64,9 @@ bar, and this skill only answers "which direction".
 > Answer in hand? Take it into `/stacks-plan-review` or `/stacks-new-feature`.
 > If the winning variant is the one you will build, `/stacks-design-taste` sets
 > the bar for the real implementation.
+
+## Upstream provenance
+
+The reviewed source revision and MIT notice are in [NOTICE.md](NOTICE.md) and
+[LICENSE](LICENSE). Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md)
+with this workflow. Existing Stacks APIs and supporting helpers remain authoritative.

package/ai/skills/stacks-push/SKILL.md

@@ -385,3 +385,23 @@ await fcm.unsubscribeFromTopic(['token1'], 'news')
 - FCM v1 includes both Android and APNS-specific priority headers automatically
 - `badge` only works on iOS -- Android uses notification channels (set via `channelId` on Expo)
 - `sound: null` sends a silent notification
+
+
+## Browser Web Push
+
+The separate browser subscription API exports `generateVapidKeys`,
+`buildVapidHeaders`, `encryptPayload` and `sendWebPush`, plus
+VapidKeys, WebPushSubscription, SendWebPushOptions and WebPushResult types.
+Read `storage/framework/core/push/src/drivers/web-push.ts` before constructing
+the subscription/options. It performs VAPID authorization and payload encryption
+natively; it does not add a web-push value to `send(..., { driver })`, whose
+choices remain Expo and FCM. The browser must supply its actual subscription.
+
+Expo/FCM read credentials from `config/services.ts` when explicit configure
+calls have not overridden them. Inspect structured PushResult success; a resolved
+send does not imply final device receipt. Native notify's push fan-out defaults
+to Expo; explicit FCM selection uses this package's direct send API.
+
+Evidence: `core/push/tests/web-push.test.ts`,
+`config-credentials.test.ts` and `fcm.test.ts`. These tests do not prove
+live delivery to a registered physical device.

package/ai/skills/stacks-query-builder/SKILL.md

@@ -11,13 +11,15 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core package: `storage/framework/core/query-builder/src/`
 - Configuration: `config/query-builder.ts`
-- QB state: `.qb/`
+- Migration snapshot: `storage/framework/database/model-snapshot.<dialect>.json`
 - External library: `bun-query-builder`
 - Package: `@stacksjs/query-builder`
 
 ## API
 
-The package re-exports everything from `bun-query-builder` plus a compatibility alias:
+The package wraps `bun-query-builder`, preserves its fluent surface, and adds
+Stacks configuration, persistent query hooks, SQLite bootstrap behavior, and
+identifier/operator validation. The `QueryBuilder` compatibility alias remains:
 
 ```typescript
 export * from 'bun-query-builder'
@@ -27,7 +29,7 @@ export { createQueryBuilder as QueryBuilder } from 'bun-query-builder'
 ## Usage
 
 ```typescript
-import { db } from '@stacksjs/database'
+import { db } from '@stacksjs/database/runtime'
 
 // Select
 const users = await db.selectFrom('users')
@@ -76,6 +78,7 @@ fork application code into a separate raw-query path for this optimization.
   verbose: true,
   dialect: env.DB_CONNECTION || 'sqlite',
   database: { database, username?, password?, host?, port? },
+  snapshotDir: 'storage/framework/database',
 
   timestamps: {
     createdAt: 'created_at',
@@ -124,11 +127,24 @@ fork application code into a separate raw-query path for this optimization.
 ```
 
 ## Gotchas
-- **Thin wrapper** — re-exports `bun-query-builder` with no additions
+- **Wrapped surface** - use `assertSafeIdentifier`, `assertSafeOperator`, and
+  allowlists when a request influences column, table, ordering or operator names.
+  Parameter binding protects values, not arbitrary SQL identifiers.
 - **One config file** — `config/query-builder.ts`. Its `dialect` and connection details are derived from `DB_CONNECTION` and the other `DB_*` env vars, so switching databases is an env change, not a config edit
-- **`.qb/` directory** — stores query builder state for migration diffing
+- **One committed snapshot** - Stacks config directs migration state to
+  `storage/framework/database`; a second `.qb` snapshot indicates the wrong configuration.
 - **Prefer ORM models** — query builder is the low-level interface; use models for most operations
 - **`db` proxy** — the `db` export from `@stacksjs/database` is a lazy proxy that auto-initializes the query builder on first access
 - **Soft deletes disabled by default** — must be explicitly enabled in config
 - **Transaction retries** — defaults to 2 retries with exponential backoff + jitter
 - **Dialect detection** — reads `DB_CONNECTION` env var, falls back to `sqlite`
+- **Turso/libSQL** - uses SQLite SQL with a remote transport selected by the
+  libSQL URL and credentials. Vitess maps to MySQL wire SQL with distinct DDL
+  and transaction constraints. Read the driver capability registry.
+- **Raw versus model queries** - raw `db` has no model definition and cannot
+  infer ownership, hidden fields, per-model casts, encryption or soft-delete traits.
+- **After commit** - `@stacksjs/database/runtime` exposes the native transaction
+  scope helpers; deferring side effects does not rebind model executors to `tx`.
+
+Source: `core/query-builder/src/index.ts`, `config/query-builder.ts`, and the
+database runtime, query-hook, pragma, identifier and transaction tests.

package/ai/skills/stacks-queue/DURABLE-WORKFLOWS.md

@@ -0,0 +1,121 @@
+# Durable queue workflows
+
+Read this for transaction boundaries, deduplication, persisted callbacks and
+failure recovery. Source root: `storage/framework/core/queue/src/`.
+
+## Commit-aware dispatch
+
+```ts
+import { db } from '@stacksjs/database/runtime'
+import { job } from '@stacksjs/queue'
+
+await db.transaction(async () => {
+  // Persist the application's state transition here.
+  await job('SendEmailJob', {
+    message: { to: 'user@example.com', subject: 'Welcome', text: 'Welcome, Ada.' },
+    driver: 'log',
+  })
+    .withIdempotencyKey('welcome:user-7:v1')
+    .afterCommit()
+    .dispatch()
+})
+```
+
+SendEmailJob is bundled; the example log transport avoids external delivery.
+Use the selected application transport for actual mail. Inside db.transaction,
+the builder defers dispatch until commit by
+default. Rollback discards buffered dispatches. `.afterCommit()` is explicit
+intent; outside a transaction it warns and dispatches immediately.
+`.withoutCommit()` opts into a side effect before commit. This is not a durable
+transactional outbox across a process crash between commit and dispatch.
+
+`.withIdempotencyKey(key)` uses `job_idempotency` to claim dispatch atomically.
+The key identifies one intended dispatch, not merely a reusable job name; a
+failed dispatch releases its claim. Apply the supporting migration and inspect
+missing-table behavior before relying on deduplication. A dispatch claim does
+not make the handler's external side effects exactly-once; handlers still need
+idempotency at their own durable boundary.
+
+Source: `job.ts`, `idempotency.ts`; database after-commit callbacks are owned by
+`core/database/src/`. Evidence: `tests/idempotency-claim.test.ts`,
+`idempotency-dialects.test.ts`, `job-builder.test.ts` and integration tests.
+
+## Envelope, context and tracing
+
+Database and Redis use the versioned JobEnvelope: jobName, payload, options,
+envelopeVersion, dispatchedAt and optional traceId/context. `.withContext(value)`
+passes context as the second argument to handle on sync and durable drivers.
+Request trace IDs travel in the envelope; a worker's own request scope cannot
+inherit an AsyncLocalStorage from another process.
+
+Use `assertEnvelopeSerializable`/`serializeEnvelope` to inspect the JSON wire
+contract. Objects containing undefined properties lose them; undefined array
+entries and non-finite numbers become null; Dates become ISO strings; custom
+classes lose prototypes; BigInt and cycles throw with diagnostic paths.
+These helpers detect a serialization failure, not every lossy conversion.
+Payloads should be explicit data with identifiers, not a model instance or an
+executable closure. Legacy envelope forms are parsed with warnings; future
+versions are left for a worker that understands them.
+
+Source: `envelope.ts`. Evidence: `tests/envelope-json-contract.test.ts`,
+`envelope-trace.test.ts`, `job-context.test.ts` and `sync-trace.test.ts`.
+
+## Batch callbacks that survive a worker restart
+
+Inline `.then(fn)/.catch(fn)/.finally(fn)/.progress(fn)` callbacks are process-local
+conveniences. Persistent terminal handlers are descriptors stored in database
+columns or Redis, then fired by the worker that wins terminal finalization:
+
+```ts
+import { Batch } from '@stacksjs/queue'
+
+const pending = Batch.create([]).name('import')
+  .thenHandler({ kind: 'module', module: './app/BatchHandlers.ts', export: 'done' })
+  .finallyHandler({ kind: 'job', name: 'CleanupImport', payload: { importId: 7 } })
+```
+
+Replace the descriptors with real exported modules/jobs and supply the actual
+batch jobs before dispatch. Native methods are thenHandler/catchHandler/
+finallyHandler; each slot holds one descriptor. Job handlers receive an added
+batch ID in their payload; module functions receive `(payload, batchId)`.
+Old batch schemas missing the handler columns warn and cannot promise restart
+persistence. A terminal winner avoids duplicate finalization in the retained
+storage contract, but downstream external effects still need their own retry
+and idempotency policy.
+
+Source: `batch.ts`; evidence: `tests/batch-persistent-handlers.test.ts`,
+`batch-add-races.test.ts`, `batch-redis-lifecycle.test.ts` and
+`batch-add-atomicity.test.ts`.
+
+## Progress and cancellation
+
+setJobProgress(id, percent, message?), getJobProgress(id), cancelJob(id),
+isJobCancelled(id) and clearJobState(id) are native helpers. Percent means 0-100;
+one means 1%, not 100%. Cancellation is cooperative: the running handler checks
+the flag between safe units of work. It does not forcibly interrupt a promise.
+
+Current `job-progress.ts` imports the public default cache singleton, which is
+memory, with one-hour entries. Do not claim those helpers share state across
+processes merely because config.cache selects Redis. A separate application
+progress store or explicit shared integration is needed for that topology.
+Evidence: `tests/job-progress.test.ts` and `job-progress-cache.test.ts`.
+
+## Failure controls and operator actions
+
+The public entry exposes listDeadLetterJobs/moveToDeadLetter/retryDeadLetterJob/
+purgeDeadLetterJobs; poison detection and quarantine helpers; and
+pauseQueue/resumeQueue/isCircuitOpen/listCircuitState plus circuit record helpers.
+Read `dead-letter.ts`, `poison.ts`, `circuit-breaker.ts` and their exported
+option/filter types before building an operator action around them. A retry,
+purge or unquarantine changes real work state and needs the task's authorization.
+CLI inventory and flags come from `buddy list` and `buddy queue:* --help`.
+
+Workers apply retry options, backoff and failed/dead-letter bookkeeping.
+Timeout signaling cannot roll back an external operation already issued by a
+handler. Redis retry behavior and database retry behavior have their own source
+paths. Health/metrics and process-local event subscribers are not authoritative
+state for all workers in a fleet.
+
+Evidence: `tests/dlq-quarantine-wiring.test.ts`, `failure-path-correctness.test.ts`,
+`worker-declared-retries.test.ts`, `graceful-shutdown-wiring.test.ts` and
+`worker-queues.test.ts`. Driver status comes from `core/config/src/capabilities.ts`.