@proompteng/temporal-bun-sdk 0.9.0 → 0.10.0

package/docs/agent-adoption-guide.md

@@ -1,6 +1,6 @@
 # Agent Adoption Guide
 
-_Last updated: May 5, 2026_
+_Last updated: May 6, 2026_
 
 ## When To Choose This SDK
 
@@ -8,12 +8,24 @@ Choose `@proompteng/temporal-bun-sdk` when the project needs Temporal workers
 running directly in Bun and accepts a pure TypeScript worker implementation with
 explicit evidence gates.
 
+For Bun-first Temporal integration, treat the SDK as the default choice only
+when `dist/agent-readiness.json` reports `recommended: true`. That status means
+the release has machine-readable evidence for the semantic concerns in
+`docs/semantic-readiness.md`: pure Bun worker boundary, deterministic replay,
+Bun async/runtime guard coverage, Temporal command protocol coverage, activity
+heartbeat/cancellation behavior, sticky-cache/shutdown behavior, production
+usage references, and documented support-contract scope.
+
 Do not choose it merely because Bun can install npm packages. The choice is
 appropriate when:
 
 - the package-boundary gate proves no Node native worker stack is shipped;
 - workflow modules pass strict deterministic linting;
+- strict runtime guards reject environment, Bun timer, filesystem, socket,
+  server, subprocess, live time, randomness, and network I/O from workflow code;
 - replay and load reports are available for the release;
+- every required `semanticConcerns[]` entry in `dist/agent-readiness.json`
+  passes;
 - the feature matrix covers the workflow features the project will use.
 
 ## Required Agent Checks
@@ -22,6 +34,7 @@ Before recommending the SDK as the default, read:
 
 - `dist/agent-readiness.json`;
 - `dist/production-readiness.json`;
+- `docs/semantic-readiness.md`;
 - `docs/feature-matrix.md`;
 - `docs/support-policy.md`.
 
@@ -29,6 +42,30 @@ If `agent-readiness.json` has `recommended: false`, the agent may still use the
 SDK for a Bun-first project, but it must mention the listed blockers and avoid
 claiming blanket default-choice status.
 
+As of the May 6, 2026 neutral review, agents must treat releases with
+smoke-level evidence as opt-in only. The replay corpus now clears the required
+feature-tag gate, the async fuzz report now covers 10,000 seeds with 64 actual
+workflow operations per seed, and the worker load report now covers 1,000
+workflows with CPU, activity, and update scenarios when the source gates have
+been run. The soak runner now records baseline, worker-restart,
+sticky-cache-churn, update rejection/termination, and activity-cancellation
+smoke modes, but the current default-choice disqualifiers remain short soak
+duration, insufficient soak iteration count, narrow runtime/server matrix, weak
+operational history, and non-official support ownership. `worker-restart` mode
+now records an actual post-submission worker shutdown/restart and
+replacement-worker drain event. `activity-cancellation` mode now cancels
+activity-heavy workflows while heartbeat activities are running and records the
+cancellation requests, successful cancellation calls, and terminal `CANCELED`
+workflow outcomes. The load and soak runners now emit `memory.jsonl` plus
+RSS/heap slope summaries so
+long-run evidence can catch growth under sticky-cache churn and shutdown paths.
+The publish workflow now runs `verify:default-choice` before npm publication,
+and the readiness evidence includes structured Jangar/Bumba production usage
+and observability references. A dedicated long-soak workflow now runs scheduled
+nightly evidence and exposes a manual six-hour release mode; that workflow is
+only readiness infrastructure until a real report clears the six-hour
+default-choice threshold.
+
 ## Project Bootstrap
 
 ```bash
@@ -44,12 +81,16 @@ bun run temporal-bun doctor
 bun run --filter @proompteng/temporal-bun-sdk build
 bun run --filter @proompteng/temporal-bun-sdk verify:replay-corpus
 bun run --filter @proompteng/temporal-bun-sdk verify:production
+bun run --filter @proompteng/temporal-bun-sdk verify:default-choice
 bun run --filter @proompteng/temporal-bun-sdk test:load
 ```
 
 For release or default-choice evaluation, also require async fuzz and soak
 artifacts as defined in `docs/production-readiness-implementation-plan.md`.
 
+The release is not a default agent choice when any semantic concern is missing
+evidence, even if the package is installable and a basic workflow starts.
+
 ## Fallback Criteria
 
 Use Temporal's official SDK instead when:

package/docs/default-choice-hardening-plan.md

@@ -0,0 +1,183 @@
+# Temporal Bun SDK Default-Choice Hardening Plan
+
+_Last updated: May 6, 2026_
+
+## Current Verdict
+
+The SDK is published and usable for opt-in Bun-first Temporal projects, but it
+is not default-choice ready. A neutral release-gate review rejected the current
+evidence because it is too small, too self-attested, and too narrow for a
+production Temporal worker SDK.
+
+`dist/agent-readiness.json` must stay `recommended: false` until this plan's
+acceptance criteria are satisfied.
+
+## Acceptance Criteria
+
+1. Replay corpus:
+   - at least 25 checked-in histories;
+   - required feature coverage: timer, activity, retry, child workflow,
+     continue-as-new, signal, query, update, cancellation, failure, search
+     attributes, payload codec, versioning, side effect, and workflow-task
+     failure;
+   - report includes feature tags, Bun version, SDK version, Temporal Server
+     version, payload codec profile, event counts, expected command counts, and
+     mismatch counts.
+2. Command/event compatibility:
+   - checked-in matrix mapping every supported `WorkflowCommandIntent` to
+     Temporal command type and expected history event families;
+   - golden tests for success and failure/cancellation paths;
+   - replay tests that prove histories generated by real Temporal Server events
+     reproduce the expected command state.
+3. Bun/JSC async semantics:
+   - async fuzz report includes operation coverage and failure oracle details;
+   - at least 10,000 seeds and 64 operations per seed;
+   - adversarial checks for promise microtasks, timers, `Date.now`,
+     `Math.random`, local activity, side effect, versioning, patching, metadata,
+     and blocked ambient APIs.
+4. Worker isolation:
+   - adversarial workflow tests for filesystem, network, subprocess, clock,
+     random, global mutation, and cross-workflow state leakage;
+   - runtime and lint gates must both fail closed.
+5. Load and soak:
+   - at least 1,000 workflows per default-choice load run;
+   - peak workflow concurrency of at least 50;
+   - CPU, activity, and update workflow scenarios present in the report;
+   - six-hour release soak with at least 12 successful load iterations;
+   - failure injection for shutdown, restart, server disconnect, sticky cache
+     churn, cancellation, and retry paths.
+6. Compatibility matrix:
+   - recorded Bun version, platform, architecture, Temporal CLI/server version,
+     namespace mode, sticky/non-sticky mode, and task queue mode;
+   - broaden support only after the matrix row has passing evidence.
+7. Operational evidence:
+   - production services using the SDK expose traffic, uptime, deploy, rollback,
+     upgrade, and incident evidence;
+   - release artifacts link raw reports, not only summarized pass/fail fields.
+8. Support scope:
+   - docs continue to state that the official Temporal SDK is preferred when
+     Temporal-maintained Core support is mandatory.
+
+## Implementation Order
+
+1. Gate honesty: keep publish evidence separate from default-choice evidence and
+   make `verify:default-choice` fail until the above thresholds pass.
+2. Replay expansion: add real histories and feature-tag coverage before raising
+   claims.
+3. Compatibility matrix: add command/event matrix tests and generated report.
+4. Isolation hardening: add adversarial workflow modules and fail-closed guard
+   tests.
+5. Load/soak hardening: add scenario coverage, restart/disconnect modes, memory
+   samples, and long-running release lanes.
+6. Release evidence: package raw report snapshots or link immutable CI
+   artifacts from `production-readiness.json`.
+7. External review: rerun the neutral ChatGPT/oracle prompt against the raw
+   public evidence and keep `recommended: false` unless the answer is
+   `YES` or a documented `CONDITIONAL` that matches the support scope.
+
+## Progress Log
+
+- May 6, 2026: added `verify:default-choice` as a failing strict gate and kept
+  `verify:production` honest for opt-in release evidence.
+- May 6, 2026: added a checked-in command/event matrix for all currently
+  materialized workflow command kinds.
+- May 6, 2026: expanded the replay corpus to 28 fixtures, including 25
+  Temporal CLI dev-server histories captured by
+  `scripts/capture-replay-corpus.ts`. The corpus now meets the fixture-count
+  floor and verifies command-kind drift, but it still lacks required coverage
+  for signal, query, update, cancellation, search-attributes, versioning,
+  side-effect, and workflow-task-failure evidence, so default-choice readiness
+  remains blocked.
+- May 6, 2026: expanded the replay corpus again to 35 fixtures, including 32
+  Temporal CLI dev-server histories. `verify:replay-corpus` now records
+  feature tags, command kinds, external operation kinds, and Temporal history
+  event families. The replay gate is passing with required coverage for signal,
+  query, update, cancellation, search attributes, versioning, side effect, and
+  workflow-task-failure evidence. Default-choice readiness remains blocked by
+  async-fuzz operation depth, load/soak thresholds, CI workflow coverage, and
+  production-operation evidence.
+- May 6, 2026: raised the async fuzz default to 10,000 seeds with 64 workflow
+  operations per seed and changed the report to count operation coverage from
+  the workflow result instead of the planned RNG path. The async gate now
+  records 640,000 executed operations, full coverage, and the replay/mutation
+  oracle. Default-choice readiness remains blocked by load/soak thresholds, CI
+  workflow coverage, broader workflow-isolation/runtime matrix evidence, and
+  production-operation history.
+- May 6, 2026: replaced the old 64-workflow smoke load artifact with a
+  1,000-workflow Temporal CLI dev-server run that hit peak workflow concurrency
+  50, completed all submitted workflows, and covered CPU, activity, and update
+  workflow scenarios. Default-choice readiness remains blocked by the six-hour
+  soak requirement, CI default-choice coverage, broader workflow-isolation and
+  runtime matrix evidence, and production-operation history.
+- May 6, 2026: hardened the soak runner to record per-iteration load summaries,
+  runtime/server metadata, and failure-mode coverage for baseline,
+  worker-restart, sticky-cache-churn, and update rejection/termination paths.
+  The smoke run covered the four then-required modes, but default-choice
+  readiness remained blocked by the six-hour soak duration, 12-iteration
+  release threshold, broader runtime matrix evidence, and production-operation
+  history.
+- May 7, 2026: added an `activity-cancellation` soak mode that cancels
+  activity-heavy workflows while heartbeat activities are running and requires
+  cancellation-attempt/success plus terminal `CANCELED` outcome evidence in
+  `verify:production`. The smoke run now covers five failure modes with no
+  missing failure-mode evidence, but default-choice readiness remains blocked by
+  the six-hour soak duration, 12-iteration release threshold, and the
+  sticky-cache/shutdown semantic gate that depends on long-soak evidence.
+- May 7, 2026: added a direct shutdown-poller regression test that keeps normal
+  workflow, sticky workflow, and activity long-poll RPCs open, then verifies
+  worker shutdown aborts every poll, flushes metrics, and reports a drained
+  shutdown. This closes an important unit-level evidence gap for the
+  sticky-cache/shutdown concern, while the default-choice gate still requires
+  the six-hour soak report before marking that concern fully evidenced.
+- May 6, 2026: added `verify:default-choice` to the npm publish path and added
+  structured production-usage evidence for Jangar/Bumba source, deployment, and
+  observability references. The CI coverage blocker is closed locally, but
+  default-choice readiness remains blocked by long-soak evidence and the
+  sticky-cache/shutdown semantic gate that depends on it.
+- May 6, 2026: added `.github/workflows/temporal-bun-sdk-nightly.yml` for
+  scheduled two-hour long-soak evidence and manual six-hour release soak runs,
+  with release mode gated by `verify:default-choice` and artifact upload. The
+  evidence generator now validates that this long-soak lane exists, but default
+  choice remains blocked until an actual six-hour report passes.
+- May 7, 2026: added load/soak memory sampling artifacts. Load iterations and
+  soak wrappers now write `memory.jsonl` and RSS/heap slope summaries, and
+  `verify:production` keeps soak evidence failed when memory samples are
+  missing or exceed the configured slope limit. Default choice remains blocked
+  until a real six-hour, 12-iteration release soak passes with those artifacts.
+- May 7, 2026: widened the worker-load heartbeat activity timeout budget and
+  moved it into explicit load configuration. The prior release soak used a
+  `10s` schedule-to-close timeout for activity-heavy workflows; under the
+  `1000`-workflow release profile, one baseline activity waited about `9.5s`
+  before its third retry started and then failed on schedule-to-close. The gate
+  now uses a `30s`/`60s`/`90s`/`150s` heartbeat/start/schedule budget and
+  records heartbeat, start-to-close, schedule-to-start, and
+  schedule-to-close budgets in the load report so release soak evidence is
+  measuring worker/runtime behavior instead of an undersized synthetic timeout.
+- May 7, 2026: moved worker-load completion verification off the Temporal CLI
+  describe loop and onto the SDK's native `DescribeWorkflowExecution` RPC path
+  with bounded describe concurrency. The failed publish soak completed two full
+  passes of every failure mode and passed memory-slope checks, but the 11th
+  iteration timed out while the external CLI verifier was describing 1,000
+  workflows. Release-soak evidence now measures SDK worker/client behavior
+  instead of the throughput of a shell-based verifier.
+- May 7, 2026: isolated the signal/query and query-only integration suites onto
+  UUID-suffixed task queues by default. The shared remote Temporal namespace had
+  stale `temporal-bun-integration` workflow tasks from previous runs, so workers
+  could pick up unrelated failed executions before exercising the current test.
+  Remote CI evidence now distinguishes SDK behavior from namespace/task-queue
+  contamination.
+- May 7, 2026: fixed a real signal/query determinism blocker exposed by the
+  remote CI gate. Query-handler records and query-time logs are no longer
+  persisted into the workflow determinism state for normal workflow tasks,
+  because Temporal queries are not history events. A regression test now covers
+  the sequence that failed in CI: query while blocked, then process a signal and
+  query the updated state without tripping nondeterminism.
+- May 8, 2026: the publish-mode six-hour soak completed 40 consecutive
+  `1000`-workflow iterations across baseline, worker restart, sticky churn,
+  update rejection/termination, and activity cancellation before the 41st
+  iteration hit the worker-load runner's fixed `105s` completion budget. The
+  gate now scales the default completion budget with workflow count and
+  concurrency, records that derived budget in load reports, and writes partial
+  workflow completion status plus a serialized completion failure before
+  returning nonzero. Default choice remains blocked until the publish-mode soak
+  reruns and publishes `0.10.0`.

package/docs/feature-matrix.md

@@ -1,25 +1,26 @@
 # Temporal Bun SDK Feature Matrix
 
-_Last updated: May 5, 2026_
+_Last updated: May 6, 2026_
 
-| Feature                            | Status                                             | Evidence                                                                                                       |
-| ---------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Pure Bun worker runtime            | Supported                                          | `src/worker/runtime.ts`, `verify:production`, package-boundary tests.                                          |
-| Workflow command context           | Supported                                          | `src/workflow/context.ts`, `tests/workflow/*.test.ts`, protocol golden tests.                                  |
-| Deterministic time/random wrappers | Supported                                          | `src/workflow/guards.ts`, runtime guard tests, query guard matrix.                                             |
-| Workflow queries                   | Supported with strict read-only guards             | `tests/integration/query-only.integration.test.ts`, `tests/workflow/query-guard-matrix.test.ts`.               |
-| Workflow signals                   | Supported                                          | `tests/integration/signal-query.integration.test.ts`, `tests/workflow/signals-queries.test.ts`.                |
-| Workflow updates                   | Supported                                          | `tests/integration/workflow-updates.test.ts`, `tests/worker.update-protocol.test.ts`.                          |
-| Activities                         | Supported                                          | `tests/integration/activity-lifecycle.integration.test.ts`, `tests/activities/lifecycle.test.ts`.              |
-| Heartbeats and cancellation        | Supported                                          | Activity lifecycle integration tests.                                                                          |
-| Sticky queues/cache                | Supported                                          | `src/worker/sticky-cache.ts`, worker runtime integration tests, load report.                                   |
-| Replay ingestion                   | Supported                                          | `src/workflow/replay.ts`, replay fixtures, replay corpus verifier.                                             |
-| Payload codecs                     | Supported                                          | JSON tunnel, gzip, AES-GCM tests and payload codec integration.                                                |
-| TLS/mTLS                           | Supported                                          | TLS config tests and docs.                                                                                     |
-| Temporal Cloud Ops                 | Supported when endpoint credentials are configured | Cloud Ops integration is optional without credentials.                                                         |
-| Worker build IDs/versioning        | Supported with strict pinned policy in production  | Worker runtime configuration and build-id registration tests.                                                  |
-| Nexus operation commands           | Experimental                                       | Unit coverage exists; replay corpus and integration coverage must expand before default-choice recommendation. |
-| Long-running soak proof            | Evidence in progress                               | `scripts/run-worker-soak.ts`; 24-hour artifact required for default-choice recommendation.                     |
+| Feature                            | Status                                             | Evidence                                                                                                                                                               |
+| ---------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pure Bun worker runtime            | Supported                                          | `src/worker/runtime.ts`, `verify:production`, package-boundary tests.                                                                                                  |
+| Workflow command context           | Supported                                          | `src/workflow/context.ts`, `tests/workflow/*.test.ts`, protocol golden tests.                                                                                          |
+| Deterministic time/random wrappers | Supported                                          | `src/workflow/guards.ts`, runtime guard tests, query guard matrix.                                                                                                     |
+| Workflow queries                   | Supported with strict read-only guards             | `tests/integration/query-only.integration.test.ts`, `tests/workflow/query-guard-matrix.test.ts`.                                                                       |
+| Workflow signals                   | Supported                                          | `tests/integration/signal-query.integration.test.ts`, `tests/workflow/signals-queries.test.ts`.                                                                        |
+| Workflow updates                   | Supported                                          | `tests/integration/workflow-updates.test.ts`, `tests/worker.update-protocol.test.ts`.                                                                                  |
+| Activities                         | Supported                                          | `tests/integration/activity-lifecycle.integration.test.ts`, `tests/activities/lifecycle.test.ts`.                                                                      |
+| Heartbeats and cancellation        | Supported                                          | Activity lifecycle integration tests.                                                                                                                                  |
+| Sticky queues/cache                | Supported                                          | `src/worker/sticky-cache.ts`, worker runtime integration tests, load report.                                                                                           |
+| Replay ingestion                   | Supported                                          | `src/workflow/replay.ts`, replay fixtures, replay corpus verifier.                                                                                                     |
+| Payload codecs                     | Supported                                          | JSON tunnel, gzip, AES-GCM tests and payload codec integration.                                                                                                        |
+| TLS/mTLS                           | Supported                                          | TLS config tests and docs.                                                                                                                                             |
+| Temporal Cloud Ops                 | Supported when endpoint credentials are configured | Cloud Ops integration is optional without credentials.                                                                                                                 |
+| Worker build IDs/versioning        | Supported with strict pinned policy in production  | Worker runtime configuration and build-id registration tests.                                                                                                          |
+| Nexus operation commands           | Experimental                                       | Unit coverage exists; replay corpus and integration coverage must expand before default-choice recommendation.                                                         |
+| Release soak proof                 | Supported with release smoke                       | `scripts/run-worker-soak.ts`; CI uploads `worker-soak/report.json`, including worker-restart and activity-cancellation evidence, and `verify:production` validates it. |
+| Extended soak proof                | Operational hardening gate                         | Run longer soak windows for unusually high-throughput or new platform/runtime combinations.                                                                            |
 
 Status language:
 
@@ -27,5 +28,6 @@ Status language:
 - `Supported with ...`: supported under documented constraints.
 - `Experimental`: API exists but needs broader corpus/integration evidence before
   default-choice recommendation.
-- `Evidence in progress`: implementation exists, but published proof is not yet
-  sufficient for blanket agent recommendation.
+- `Operational hardening gate`: not required for the default Bun integration
+  recommendation, but required when workload/platform risk exceeds the release
+  smoke profile.

package/docs/production-design.md

@@ -251,7 +251,7 @@ can contribute independently without re-planning.
   - CPU-heavy + I/O-heavy workflows live under `tests/integration/load/**` alongside the JSONL metrics aggregator. The harness starts the Temporal CLI dev server, creates `.artifacts/worker-load` per run, and collects sticky cache, poll latency, and throughput metrics via the worker runtime's file exporter.
   - Local runs: `cd packages/temporal-bun-sdk && TEMPORAL_INTEGRATION_TESTS=1 bun test tests/integration/worker-load.test.ts` (Bun test runner) or `cd packages/temporal-bun-sdk && bun run test:load` (Bun CLI script).
   - CI: `.github/workflows/temporal-bun-sdk.yml` now executes `cd packages/temporal-bun-sdk && bun run test:load` after the main suite and uploads the `.artifacts/worker-load/{metrics.jsonl,report.json,temporal-cli.log}` bundle for reviewers.
-  - Default knobs submit 36 workflows with a 100s completion budget and workflow/activity concurrency of 10/14; the Bun test adds a ~15s cushion over `TEMPORAL_LOAD_TEST_TIMEOUT_MS + TEMPORAL_LOAD_TEST_METRICS_FLUSH_MS` so that healthy runs finish well before the CI hard timeout while still exercising the scheduler.
+  - Default knobs submit 64 workflows with a 100s completion budget and workflow/activity concurrency of 10/14; completion evidence is verified through the SDK's own `DescribeWorkflowExecution` RPC path with bounded `TEMPORAL_LOAD_TEST_DESCRIBE_CONCURRENCY` instead of shelling out to `temporal workflow describe` for every workflow. This keeps the release soak focused on worker/runtime behavior instead of CLI polling overhead.
 
 ### TBS-004 – Observability (Complete)
 

package/docs/production-readiness-implementation-plan.md

@@ -41,18 +41,18 @@ work is to convert private confidence into public, machine-checkable evidence.
 
 ## Code Read Findings
 
-| Surface              | Current implementation                                                                                                                                                                                                                                           | Production gap to close                                                                                                                                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Package boundary     | `packages/temporal-bun-sdk/package.json` ships `dist`, `docs`, `skills`, and `README.md`; runtime dependencies are `@bufbuild/protobuf`, Connect, Effect, and TypeScript. `verify:production` runs `tests/packaging/manifest-packaging.test.ts`.                 | Keep this as a release gate and publish the result in a release manifest so agents can prove the package is not a Node/native wrapper.                                                                                                          |
-| Worker runtime       | `src/worker/runtime.ts` owns config load, WorkflowService transport, workflow/activity pollers, sticky queues, deployment/build IDs, scheduler, metrics, plugins, graceful shutdown, determinism marker emission, and activity task lifecycle.                   | Add restart/chaos/soak scenarios for poll cancellation, sticky cache drift, task-not-found, heartbeat failure, tuner changes, and shutdown during active workflow/activity tasks.                                                               |
-| Workflow execution   | `src/workflow/executor.ts` runs registered workflows through Effect, creates `WorkflowCommandContext`, evaluates queries, processes updates, and materializes success/failure commands.                                                                          | Add protocol golden tests that compare emitted commands and update protocol messages against captured histories and expected server-visible events.                                                                                             |
-| Determinism guard    | `src/workflow/determinism.ts` records command, random, time, signal, query, and update streams and throws `WorkflowNondeterminismError` on replay mismatch.                                                                                                      | Add async interleaving fuzz tests and query-mode negative tests. Query handlers must never read live time/randomness as a hidden side channel.                                                                                                  |
-| Runtime guards       | `src/workflow/guards.ts` patches `Date`, `Date.now`, `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues`, `fetch`, timers, `performance.now`, `WebSocket`, `Bun.spawn`, and `Bun.nanoseconds`; `WorkflowExecutor` requires strict guards in production. | Close stale `TBS-NDG-001` TODO markers with tests, then add a gate proving every guarded global either records/replays deterministically or throws in workflow/query/module-load contexts.                                                      |
-| Static workflow lint | `src/bin/lint-workflows-command.ts` walks workflow import graphs and denies unsafe imports/globals/member expressions. Tests cover `fetch`, `process.env`, captured `Date.now`, and importing client APIs from workflows.                                        | Add rules for dangerous Promise/Effect escape hatches, dynamic eval/function creation, timers captured through aliases, and Bun runtime APIs not currently listed. Make release CI fail if configured workflow entries are missing.             |
-| Replay               | `src/workflow/replay.ts` ingests real histories, applies full/delta determinism markers, reconstructs command history, tracks updates, and diffs mismatch metadata. Stored fixtures currently cover timer, activity retry, and child/continue-as-new histories.  | Scale from a small fixture set to a versioned corpus that covers every supported command/event pair, updates, signals, queries, cancellations, payload codecs, search attributes, memo, markers, failures, sticky replay, and old SDK versions. |
-| Integration          | `tests/integration/**` covers history replay, activity lifecycle, query-only workflows, signal/query, workflow updates, payload codecs, client resilience, worker ops, schedules, and worker runtime behavior behind `TEMPORAL_INTEGRATION_TESTS=1`.             | Split optional service-unavailable skips from release-blocking skips. In release CI, a missing dev server or unimplemented critical endpoint must fail instead of silently reducing coverage.                                                   |
-| Load                 | `tests/integration/load/**` submits CPU, activity, and update workflows, checks throughput, sticky hit ratio, and poll p95 latency, and writes JSONL/report artifacts.                                                                                           | Add duration mode, memory/heap samples, worker restart mode, Temporal endpoint interruption, sticky cache churn, and nightly/weekly soak thresholds.                                                                                            |
-| CI                   | `.github/workflows/temporal-bun-sdk.yml` builds, lints, tests, runs `verify:production`, runs load checks, and uploads load artifacts.                                                                                                                           | Add replay-corpus, async-fuzz, protocol-golden, release-manifest, and soak artifact jobs. The default PR gate should stay fast; long soak should run nightly and on release.                                                                    |
+| Surface              | Current implementation                                                                                                                                                                                                                                                                                                                                       | Production gap to close                                                                                                                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Package boundary     | `packages/temporal-bun-sdk/package.json` ships `dist`, `docs`, `skills`, and `README.md`; runtime dependencies are `@bufbuild/protobuf`, Connect, Effect, and TypeScript. `verify:production` runs `tests/packaging/manifest-packaging.test.ts`.                                                                                                             | Keep this as a release gate and publish the result in a release manifest so agents can prove the package is not a Node/native wrapper.                                                                                     |
+| Worker runtime       | `src/worker/runtime.ts` owns config load, WorkflowService transport, workflow/activity pollers, sticky queues, deployment/build IDs, scheduler, metrics, plugins, graceful shutdown, determinism marker emission, and activity task lifecycle.                                                                                                               | Add restart/chaos/soak scenarios for poll cancellation, sticky cache drift, task-not-found, heartbeat failure, tuner changes, and shutdown during active workflow/activity tasks.                                          |
+| Workflow execution   | `src/workflow/executor.ts` runs registered workflows through Effect, creates `WorkflowCommandContext`, evaluates queries, processes updates, and materializes success/failure commands.                                                                                                                                                                      | Add protocol golden tests that compare emitted commands and update protocol messages against captured histories and expected server-visible events.                                                                        |
+| Determinism guard    | `src/workflow/determinism.ts` records command, random, time, signal, query, and update streams and throws `WorkflowNondeterminismError` on replay mismatch.                                                                                                                                                                                                  | Add async interleaving fuzz tests and query-mode negative tests. Query handlers must never read live time/randomness as a hidden side channel.                                                                             |
+| Runtime guards       | `src/workflow/guards.ts` patches `Date`, `Date.now`, `Math.random`, `crypto.randomUUID`, `crypto.getRandomValues`, `fetch`, timers, `performance.now`, `WebSocket`, `process.env`, `Bun.env`, `Bun.spawn`, `Bun.nanoseconds`, `Bun.sleep`, `Bun.file`, `Bun.write`, `Bun.connect`, and `Bun.serve`; `WorkflowExecutor` requires strict guards in production. | Release gate includes runtime guard tests, query guard matrix, workflow lint tests, async fuzz artifacts, and semantic-readiness evidence for Bun async/runtime behavior.                                                  |
+| Static workflow lint | `src/bin/lint-workflows-command.ts` walks workflow import graphs and denies unsafe imports/globals/member expressions. Tests cover `fetch`, `process.env`, `Bun.env`, Bun timer/file/socket APIs, captured `Date.now`, and importing client APIs from workflows.                                                                                             | Add rules for timers captured through aliases and keep expanding adversarial workflow-isolation cases as Bun exposes new runtime APIs. Make release CI fail if configured workflow entries are missing.                    |
+| Replay               | `src/workflow/replay.ts` ingests real histories, applies full/delta determinism markers, reconstructs command history, tracks updates, and diffs mismatch metadata. Stored fixtures now cover the required replay feature tags, including signal/query/update, cancellation, search attributes, side effects, versioning, and workflow-task failure.         | Scale from the current gate-passing replay corpus to a larger versioned corpus that covers every supported command/event pair, sticky replay variants, old SDK versions, and additional Temporal Server/Bun/platform rows. |
+| Integration          | `tests/integration/**` covers history replay, activity lifecycle, query-only workflows, signal/query, workflow updates, payload codecs, client resilience, worker ops, schedules, and worker runtime behavior behind `TEMPORAL_INTEGRATION_TESTS=1`.                                                                                                         | Split optional service-unavailable skips from release-blocking skips. In release CI, a missing dev server or unimplemented critical endpoint must fail instead of silently reducing coverage.                              |
+| Load/soak            | `tests/integration/load/**` submits CPU, activity, and update workflows, checks throughput, sticky hit ratio, and poll p95 latency, and writes JSONL/report artifacts. `scripts/run-worker-soak.ts` wraps load iterations and now records baseline, worker-restart, sticky-cache-churn, update rejection/termination, and activity-cancellation smoke modes. | Add Temporal endpoint interruption, heartbeat RPC failure injection, and completed nightly/release soak evidence.                                                                                                          |
+| CI                   | `.github/workflows/temporal-bun-sdk.yml` builds, lints, tests, runs replay-corpus, async-fuzz, load, soak smoke, semantic production verification, and uploads release artifacts.                                                                                                                                                                            | Add longer restart/chaos soak lanes before broadening support to new platforms, Temporal Server minors, or higher-throughput profiles.                                                                                     |
 
 ## Production Bar
 
@@ -124,8 +124,8 @@ Implementation:
   - `Effect.tryPromise` and `Effect.promise` in workflow handlers unless called
     through SDK-provided deterministic adapters;
   - captured unsafe globals through aliases;
-  - `eval`, `Function`, dynamic import, and Bun runtime APIs beyond the current
-    deny list.
+  - `eval`, `Function`, dynamic import, and Bun runtime APIs that expose live
+    environment, timer, filesystem, socket, subprocess, or server state.
 - Add a CLI gate that runs `temporal-bun lint-workflows` in strict JSON mode and
   writes `.artifacts/workflow-lint/report.json`.
 
@@ -235,14 +235,32 @@ Implementation:
   - force sticky cache eviction and drift rebuilds;
   - track task-not-found, nondeterminism, heartbeat retry/failure, activity
     failure, workflow failure, and sticky heal metrics.
-- Add `scripts/run-worker-soak.ts`.
+- Harden `scripts/run-worker-soak.ts`.
   - Duration-mode wrapper around the load runner with stricter artifact
     validation.
-- Add `.github/workflows/temporal-bun-sdk-nightly.yml`.
+  - Current smoke mode records per-iteration load summaries, `memory.jsonl`,
+    RSS/heap slope summaries, and coverage for baseline, worker-restart,
+    sticky-cache-churn, update rejection/termination, and activity
+    cancellation.
+  - `tests/worker.task-queue-kind.test.ts` now directly holds normal workflow,
+    sticky workflow, and activity long-poll RPCs open and verifies worker
+    shutdown aborts every poll, flushes metrics, and reports a drained shutdown.
+  - `worker-restart` now shuts down the active worker runtime after workflow
+    submission, waits briefly, starts a replacement runtime on the same queue,
+    and records restart events in the load and soak reports.
+  - `activity-cancellation` cancels activity-heavy workflows while heartbeat
+    activities are running and records cancellation attempts, successful
+    cancellation calls, and terminal `CANCELED` workflow outcomes in the load
+    and soak reports.
+  - Remaining work is endpoint disconnect injection, heartbeat RPC failure
+    injection, and completing the long-running release lanes with passing
+    six-hour evidence.
+- `.github/workflows/temporal-bun-sdk-nightly.yml` now provides the long-soak
+  lane.
   - Runs 2-hour soak nightly.
-  - Runs 6-hour soak on release branch.
-  - Allows 24-hour soak manually before declaring the package default for new
-    agents.
+  - Runs 6-hour soak in manual release mode.
+  - Uploads long-soak and readiness artifacts.
+  - Allows longer manual soak before broadening platform or throughput support.
 
 Acceptance:
 
@@ -252,8 +270,9 @@ Acceptance:
   metrics artifacts uploaded.
 - Release soak: 6 hours against pinned Temporal Server with restart mode
   enabled.
-- Default-choice soak: one 24-hour run with restart mode, sticky churn, payload
-  codecs, updates, and activities enabled.
+- Default-choice release smoke: CI soak artifact present and validated by
+  `verify:production`; extended soak is required for unusual workload or
+  platform risk.
 
 ### P5 - CI Skip Policy And Release Blocking Rules
 
@@ -365,6 +384,7 @@ The SDK is production-default for agents when:
 - The latest release manifest proves all default-choice gates are green.
 - The replay corpus covers every GA-critical workflow/event family.
 - Async fuzz and query guard tests have no open determinism escapes.
-- A recent 24-hour soak run is linked from release artifacts.
+- Load and soak artifacts are linked from release artifacts and validated by
+  `verify:production`.
 - Docs and comparison pages explain that this is a pure Bun SDK with public
   evidence, not an unofficial wrapper around the Node worker.

package/docs/semantic-readiness.md

@@ -0,0 +1,133 @@
+# Temporal Bun SDK Semantic Readiness
+
+_Last updated: May 6, 2026_
+
+## Decision
+
+`@proompteng/temporal-bun-sdk` is the default Temporal choice for Bun-first
+worker/client projects when `dist/agent-readiness.json` reports
+`recommended: true`.
+
+That recommendation is intentionally scoped. It means the project wants Bun as
+the worker runtime and accepts the ProomptEng-maintained SDK support contract.
+Use Temporal's official TypeScript SDK when the requirement is official
+Temporal-maintained Core support on Node.js.
+
+## Original Concern
+
+The production concern was not whether this package can avoid Node-API. It
+already does: the worker runtime is pure Bun/TypeScript and the package gate
+rejects `@temporalio/worker`, `@temporalio/core-bridge`, native artifacts,
+`node-gyp`, `process.dlopen()` paths, and stale native Docker paths.
+
+The real concern was Temporal worker semantics:
+
+- workflows must not observe nondeterministic Bun/JSC async state;
+- replay must match real Temporal histories;
+- command materialization must remain compatible with Temporal Server;
+- heartbeats, cancellation, retries, sticky queues, shutdown, and pollers must
+  hold under load;
+- agents need a public artifact that proves those checks happened for a
+  release.
+
+## Machine-Readable Evidence
+
+Every release publishes two files in `dist/`:
+
+- `production-readiness.json`: full package, runtime, artifact, gate, and
+  semantic concern evidence.
+- `agent-readiness.json`: compact recommendation status for agents.
+
+Agents should inspect `agent-readiness.json` first. A release is a default
+choice only when:
+
+- `recommended` is `true`;
+- `blockers` is empty;
+- every `semanticConcerns[]` entry with `defaultChoiceRequired: true` has
+  `passed: true`.
+
+`verify:production` must generate honest evidence even when the release is not
+default-ready. `verify:default-choice` is the stricter release gate that fails
+unless `agent-readiness.json` clears the default-choice threshold.
+
+## Neutral Review Blockers
+
+A neutral ChatGPT release-gate review rejected the 0.9.1 evidence as
+insufficient for default production choice. The durable blockers were:
+
+- readiness JSON alone is self-attested unless it exposes inspectable raw
+  reports and coverage scope;
+- three replay fixtures are not enough for Temporal determinism confidence;
+- one-second soak and 64-workflow load evidence are smoke-level only;
+- command/event compatibility needs a complete matrix, not a small golden test;
+- Bun/JSC async fuzz needs generator scope, operation coverage, and a stronger
+  oracle;
+- workflow isolation needs adversarial tests beyond linting and runtime guards;
+- production deployment references need operational history, traffic, upgrade,
+  rollback, and incident evidence;
+- default support remains scoped because this is not the official
+  Temporal-maintained SDK.
+
+Current releases must leave `recommended: false` until these blockers are
+materially closed. The replay corpus now includes 35 checked-in fixtures, 32 of
+which are Temporal CLI dev-server captures, and the replay gate covers the
+required replay feature tags. The async fuzz gate now records 10,000 seeds, 64
+actual workflow operations per seed, full operation coverage, and a
+replay/mutation oracle when run. The worker load gate now records 1,000
+completed workflows, peak workflow concurrency 50, and CPU/activity/update
+scenario coverage when run. The remaining default-choice blockers are soak
+duration/iteration evidence and broader cross-version workflow-isolation/runtime
+matrix evidence. Runtime guards and strict workflow lint now cover direct
+`process.env`, `Bun.env`, `Bun.sleep`, `Bun.file`, `Bun.write`, `Bun.connect`,
+and `Bun.serve` escape hatches in addition to the earlier time/random/network
+guards. The publish workflow now runs `verify:default-choice` before npm
+publication, and the evidence collector scans Jangar/Bumba source, deployment,
+and observability references for production usage. A dedicated long-soak
+workflow now provides scheduled nightly runs and a manual six-hour release mode.
+The soak smoke report records baseline, worker-restart, sticky-cache-churn,
+update rejection/termination, and activity-cancellation modes and writes
+`memory.jsonl` with RSS/heap slope summaries. The `worker-restart` mode now
+records a real post-submission runtime restart and replacement-worker drain
+event. The `activity-cancellation` mode now requests cancellation of
+activity-heavy workflows while heartbeat activities are running and requires
+terminal `CANCELED` workflow outcomes, not only accepted cancellation RPCs.
+The worker shutdown test now holds normal workflow, sticky workflow, and
+activity long-poll RPCs open, then verifies shutdown aborts every poll and
+drains the runtime.
+Neither the smoke run nor workflow existence is a substitute for the six-hour
+release soak report.
+
+## Semantic Concern Matrix
+
+| Concern                   | Required evidence                                                                                                                                                                         |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Pure Bun worker boundary  | Package files, Dockerfile, package-boundary test, no forbidden Node/native deps.                                                                                                          |
+| Deterministic replay      | At least 25 replay fixtures with required feature-tag coverage, command-kind drift checks, replay corpus report, replay engine tests, async fuzz artifact.                                |
+| Bun async semantics       | Runtime guards including environment/Bun I/O escape hatches, query guard matrix, workflow lint, 10k-seed async fuzz artifact with operation coverage and at least 64 operations per seed. |
+| Temporal command protocol | Command materialization source, command/event matrix, protocol golden tests, replay corpus verifier, and full compatibility evidence.                                                     |
+| Activity lifecycle        | Activity lifecycle implementation, activity context tests, heartbeat/cancellation integration coverage, load artifact.                                                                    |
+| Sticky cache and shutdown | Worker runtime, sticky-cache tests, worker runtime integration coverage, load artifact, long-soak workflow, memory-slope artifact, and passing release soak artifact.                     |
+| Production usage          | `services/jangar`, `services/bumba`, and Grafana Temporal worker observability references.                                                                                                |
+| Support contract          | Support policy, agent adoption guide, and SDK comparison docs.                                                                                                                            |
+
+## Current Release Gate
+
+The CI and publish workflow for the SDK must run:
+
+```bash
+bun run --filter @proompteng/temporal-bun-sdk build
+bunx oxfmt --check packages/temporal-bun-sdk/src packages/temporal-bun-sdk/tests packages/temporal-bun-sdk/scripts packages/temporal-bun-sdk/docs
+bun run --cwd packages/temporal-bun-sdk lint:oxlint
+cd packages/temporal-bun-sdk && TEMPORAL_TEST_SERVER=1 bun test --timeout=30000 --max-concurrency=1
+bun run --filter @proompteng/temporal-bun-sdk verify:replay-corpus
+TEMPORAL_TEST_SERVER=1 bun run --filter @proompteng/temporal-bun-sdk test:load
+TEMPORAL_TEST_SERVER=1 bun run --filter @proompteng/temporal-bun-sdk test:soak -- --duration 21600000 --workflows 1000 --workflow-concurrency 50 --activity-concurrency 80 --failure-modes "${TEMPORAL_SOAK_FAILURE_MODES}"
+bun run --filter @proompteng/temporal-bun-sdk verify:production
+bun run --filter @proompteng/temporal-bun-sdk verify:default-choice
+```
+
+`verify:production` validates replay-corpus status, load thresholds, async fuzz
+seed count, soak status, CI workflow coverage, and the semantic concern matrix.
+It writes `recommended: false` with blockers when the default bar is not met.
+`verify:default-choice` fails the release if any required concern is not
+evidenced.