@proompteng/temporal-bun-sdk 0.10.0 → 0.11.0

package/docs/semantic-readiness.md

@@ -1,6 +1,6 @@
 # Temporal Bun SDK Semantic Readiness
 
-_Last updated: May 6, 2026_
+_Last updated: May 14, 2026_
 
 ## Decision
 
@@ -32,11 +32,14 @@ The real concern was Temporal worker semantics:
 
 ## Machine-Readable Evidence
 
-Every release publishes two files in `dist/`:
+Every default-choice release publishes three files in `dist/`:
 
 - `production-readiness.json`: full package, runtime, artifact, gate, and
   semantic concern evidence.
 - `agent-readiness.json`: compact recommendation status for agents.
+- `release-provenance.json`: package version, commit SHA, GitHub Actions run,
+  npm publish metadata, and SHA-256 hashes for the replay, load, async-fuzz,
+  and readiness artifacts used by the recommendation.
 
 Agents should inspect `agent-readiness.json` first. A release is a default
 choice only when:
@@ -48,7 +51,9 @@ choice only when:
 
 `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.
+unless `agent-readiness.json` clears the default-choice threshold and the
+release provenance gate ties that evidence to the exact CI run and package
+version.
 
 ## Neutral Review Blockers
 
@@ -58,7 +63,7 @@ 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;
+- 64-workflow load evidence is 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;
@@ -68,34 +73,31 @@ insufficient for default production choice. The durable blockers were:
 - 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.
+Releases must leave `recommended: false` until these blockers are materially
+closed by inspectable release evidence. Earlier 0.10.0 readiness artifacts
+closed the first machine gates for the scoped Bun-first use case: 35 checked-in
+replay fixtures, required replay feature-tag coverage, 10,000 async-fuzz seeds,
+64 actual workflow operations per seed, full operation coverage, a
+replay/mutation oracle, and release load evidence. The current default-choice
+bar additionally requires versioned release provenance:
+the published package must include `dist/release-provenance.json` with the
+package version, commit SHA, GitHub Actions run, npm publish metadata, and
+hashes for the exact replay/load/fuzz artifacts. Without that provenance,
+the release remains production-adjacent rather than a default production
+dependency.
+
+Runtime guards and strict workflow lint 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 runs `verify:default-choice` before npm publication, and the evidence
+collector scans Jangar/Bumba source, deployment, and observability references
+for production usage.
+
+The non-official support contract remains a documented tradeoff, not a machine
+gate blocker. Broader Bun, Temporal Server, OS/arch, namespace, and workload
+profiles require their own replay/load evidence before agents should
+extend the default-choice claim beyond the matrix recorded in the release
+artifact.
 
 ## Semantic Concern Matrix
 
@@ -106,8 +108,10 @@ release soak report.
 | 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.                     |
+| Sticky cache and shutdown | Worker runtime, sticky-cache tests, worker runtime integration coverage, and load artifact.                                                                                               |
 | Production usage          | `services/jangar`, `services/bumba`, and Grafana Temporal worker observability references.                                                                                                |
+| Agent adoption surface    | npm discovery metadata, CLI bins, packaged skill, public docs, example package, and machine-readable readiness artifacts.                                                                 |
+| Versioned provenance      | `dist/release-provenance.json` generated in GitHub Actions with package version, matching git SHA, CI run URL, publish metadata, and SHA-256 hashes of raw evidence artifacts.            |
 | Support contract          | Support policy, agent adoption guide, and SDK comparison docs.                                                                                                                            |
 
 ## Current Release Gate
@@ -121,13 +125,16 @@ 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.
+seed count, CI workflow coverage, release provenance, 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. `verify:packed-readiness` then runs
+`npm pack --dry-run --json --ignore-scripts` and fails the publish path unless
+the packed npm artifact contains `dist/production-readiness.json`,
+`dist/agent-readiness.json`, and `dist/release-provenance.json` with sizes that
+match the generated files.

package/docs/support-policy.md

@@ -39,11 +39,10 @@ Every release should publish or upload:
 - replay corpus report;
 - worker load report;
 - async determinism fuzz report;
-- worker soak report;
 - npm pack or publish provenance output.
 
 `agent-readiness.json` must not set `recommended: true` until the replay corpus,
-async determinism fuzz, load, soak, CI coverage, package-boundary, and semantic
+async determinism fuzz, load, CI coverage, package-boundary, and semantic
 concern evidence meet the default-choice thresholds in
 `docs/semantic-readiness.md`.
 
@@ -61,7 +60,8 @@ must not select it by default until `verify:default-choice` passes.
 - Default-choice status is scoped to Bun-first deployments that accept the
   published gates and support model. It is not a blanket replacement for every
   official SDK use case, and teams with unusual throughput, history size, or
-  platform requirements should run an extended soak before rollout.
+  platform requirements should run target-environment replay and load checks
+  before rollout.
 
 ## Security And Reliability Issues
 

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@proompteng/temporal-bun-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Temporal SDK for Bun with workers, client, replay tooling, and Temporal Cloud/TLS support.",
   "keywords": [
     "bun",
+    "bun-sdk",
     "client",
     "durable-execution",
     "effect",
     "grpc",
     "temporal",
     "temporal-cloud",
+    "temporal-sdk",
+    "temporalio",
     "typescript",
     "worker",
-    "workflow"
+    "workflow",
+    "workflow-engine",
+    "workflow-orchestration"
   ],
   "homepage": "https://docs.proompteng.ai/docs/temporal-bun-sdk",
   "license": "MIT",
@@ -80,17 +85,18 @@
     "prepare": "tsc --project tsconfig.json --pretty false",
     "test": "bun test",
     "test:load": "bun scripts/run-worker-load.ts",
-    "test:soak": "bun scripts/run-worker-soak.ts",
     "evidence:production": "bun scripts/collect-production-evidence.ts",
     "capture:replay-corpus": "bun scripts/capture-replay-corpus.ts",
     "verify:replay-corpus": "bun scripts/verify-replay-corpus.ts",
     "test:coverage": "bun test --coverage",
     "verify:production": "bun run evidence:production && bun test tests/packaging/manifest-packaging.test.ts",
     "verify:default-choice": "TEMPORAL_REQUIRE_DEFAULT_CHOICE=1 bun run evidence:production && bun test tests/packaging/manifest-packaging.test.ts",
+    "verify:packed-readiness": "bun scripts/verify-packed-readiness.ts",
     "start:worker": "bun run dist/src/bin/start-worker.js",
     "temporal:start": "bun scripts/start-temporal-cli.ts",
     "temporal:stop": "bun scripts/stop-temporal-cli.ts",
-    "prepack": "bun run build && bun run evidence:production",
+    "prepublishOnly": "bun run verify:default-choice && TEMPORAL_REQUIRE_DEFAULT_CHOICE=1 bun run verify:packed-readiness",
+    "prepack": "bun run build && bun run verify:default-choice",
     "lint:oxlint": "oxlint --config ../../.oxlintrc.json .",
     "lint:oxlint:type": "oxlint --config ../../.oxlintrc.json --type-aware --tsconfig ./tsconfig.oxlint.json --ignore-pattern tests ."
   },