[wangbill (YunchuWang)]

Summary

What changed?

• Add provider-independent PayloadStore/options/errors and explicit protobuf field mapping, retaining structural ES2020-compatible cause options.
• Snapshot eligible nonempty fields and their UTF-8 sizes, validate every eligible size before any upload, then externalize with the existing bounded runner. Thresholds remain inclusive; the maximum applies only to externalized payloads.
• Traverse native continue-as-new carryover history using the existing history-field mapping. Five runtime-generated 1 MiB event inputs externalize below a 4 MiB binary response limit and hydrate back with unchanged metadata, order, and data.
• Preserve the eight-operation concurrency cap, stop-dispatch/drain behavior, lowest-message-order I/O failure selection, and existing non-retriable activity/orchestrator upload-failure conversion. Precanceled eligible work cancels before size validation; canceled no-op messages remain no-ops.
• Cover history/entity oneofs, 150,000-element entity batches, UTF-8 threshold/maximum boundaries, zero-upload deterministic size failures, cancellation, and gated transient/permanent I/O failure controls.
• Skip store-recognized tokens before externalization size checks/uploads so retries do not wrap references again.
• Preserve aborted processing as an error before permanent-failure conversion, while retaining the drained runner's selected original error.
• Include rewind-history input in hydration, externalization and UTF-8 size preflight while preserving the rewind reason and metadata.
• Reserve core 0.4.1 and synchronize only its lock entry and the Functions exact pin. No transport wiring, Azure Blob dependencies, or cleanup client/worker implementation is included.

Why is this change needed?

• Phase 1/6 of the requested large-payload implementation split. This PR's base is upstream main.
• Field-mapping reference: durabletask-dotnet 91739687. Native carryover traversal and whole-message size preflight are intentional targeted improvements beyond the reference interceptor's mapping and per-operation size checks, not a claim of exact unchanged .NET parity.
• The original phase stack was split from c9b53fcb3ab8585c4b3b22f9c0500cc9dd122c5a, with the documented instance-kind routing correction. This phase includes reviewed carryover/preflight repair commits: d5c9df7e28b7d0bdc9ddaa01defa5f1a727aa880 (carryover) and 55dfcf37da0ed3a2791f778d75621cb7f91144a7 (size preflight), followed by aeb598f68d0d4a47c89a762b516a5131af60d4c8 (recognized-token skip) and bee13134d6ea2e317938b3e4eda450cf6b463bc1 (aborted-signal precedence).
• Previously, native carryover bypassed externalization and size limits, and an otherwise valid earlier field could be uploaded before a later deterministic size failure. Preflight prevents those avoidable writes and payload-token mutations; worker responses still convert size failures to the existing non-retriable Failed form.

Issues / work items

• Resolves: N/A (user-requested phased feature review).
• Related: original oversized PR #387. It is closed without merging; its original branch/history remain preserved.

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • If yes:
    • Impact: No intentional API break in this phase; the payload feature remains opt-in.
    • Migration guidance: Do not release partial phases. Merge the stack in order and publish the completed core before dependent packages.

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot.
• AI-assisted areas/files: This phase's source, regression tests, and directly related metadata/documentation.
• What you changed after AI output: Split the implementation along independently buildable boundaries; retained focused regression evidence and removed unrelated formatting-only changes. Added separately reviewed, regression-tested carryover/preflight and token/cancellation repairs. Human review is still required.

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

These human attestations are intentionally left unchecked.

---

Testing

Automated tests

• Result: Current review head 137bb547e8781fd84c2738c3e13ae0f65cd66174.
• npm run test:unit -w @microsoft/durabletask-js -- --runTestsByPath test\payloads.spec.ts test\build-rewind-result.spec.ts test\history-event-converter.spec.ts --verbose=false — passed 162 tests in 3 suites, including all 114 payload tests.
• npm run build:core and npm run lint — passed on this phase1 head. Scoped Prettier checks of the processor, payload tests and changelog passed.
• git diff --check bee13134d6ea2e317938b3e4eda450cf6b463bc1..137bb547e8781fd84c2738c3e13ae0f65cd66174 — passed. The reviewed repair is exactly 3 files / 117 added lines: one field mapping, 12 regressions and two changelog lines.
• TDD before the processor edit: the payload suite had 10 expected failures and 104 passing controls. Current green evidence is rewind-input-green.log; red/build/lint/format receipts are rewind-input-red.log, rewind-input-build.log, rewind-input-lint.log, rewind-input-format.log in the phase1 session artifacts.
• Combined-final validation on exact 901eb85a3a8c615ca6dbea9c754bedb3ccbd74e0: npm run test:unit — passed 3,116 tests in 133 suites (core 1,964; Functions 226; Azure Blob 39; Azure-managed 821; export-history 66). The 10 opt-in service tests are skipped in this unit command.
• On that same final head, npm run build — passed all five workspaces; npm run lint — passed. These are one aggregate final-head run, not per-intermediate-head reruns.
• Combined final-stack hosted check: DTS emulator run 39824017089 on exact 901eb85a3a8c615ca6dbea9c754bedb3ccbd74e0 — PENDING (in_progress) at 2026-10-22T17:36:27.5984515Z. The live link is authoritative for later completion; no early pass is claimed.
• Current PR388 head 137bb547e8781fd84c2738c3e13ae0f65cd66174: 30 hosted checks SUCCESS, one inapplicable check SKIPPED, no failed/pending checks at the recorded read. REVIEW_REQUIRED persists; resolved threads are not approvals.
• Existing main-base-only PR filters are unchanged. This dispatched final-stack run is not independent hosted execution of every intermediate PR, and absent stacked-PR jobs are not passes.
• Scope limits remain: no live storage-outage or mixed .NET/JavaScript execution, no transactional upload/submit rollback and no generic orphan collector. Tombstone auto-purge cannot discover blobs without a backend-recorded reference.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js v24.14.0; Jest and the owning SDK build/type-check.
• Steps + observed results:
  1. Materialized this phase on its declared predecessor, with no future-phase imports.
  2. Reproduced carryover/size, token/cancellation and rewind-input defects before their implementations, then ran the exact owning checks above and inspected the approved incremental commits.
  3. Kept the original feature branch/history and primary user checkout unchanged; changes are limited to the processor, payload regression tests, and directly related changelog notes.
• Evidence (optional): Full local logs are session artifacts, not repository changes: carryover-red.log, carryover-green-focused.log, preflight-red.log, preflight-green.log, and preflight-full-core.log.

---

Notes for reviewers

Latest review repair

• 137bb547e8781fd84c2738c3e13ae0f65cd66174 adds rewind-history input to the existing payload field traversal, so hydration, externalization and whole-message UTF-8 preflight cover rewound input without changing its reason/metadata. Twelve permanent regressions accompany the one-line mapping repair.
• This foundation phase still contains no client transport wiring. The separate scheduling error-domain follow-up is isolated in #389, not included in this PR.

Merge order	Phase	PR	Base branch
1	Core contracts	#388	main
2	SDK integration	#389	yunchuwang-payload-phase-1-core
3	Azure Blob provider	#390	yunchuwang-payload-phase-2-sdk
4	Purge protocol/client	#391	yunchuwang-payload-phase-3-blob
5	Purge worker	#392	yunchuwang-payload-phase-4-client
6	Release/usage/consumers	#393	yunchuwang-payload-phase-5-worker

Merge 1 → 2 → 3 → 4 → 5 → 6. Each PR targets its predecessor; retarget the next PR only after its prerequisite merges. Do not publish packages or describe a partial phase as the complete feature. All reviewed phase1 repairs are now ancestors of the dependent phases.

• This phase is a tested foundation only. Public client/worker opt-in is phase 2; no Azure provider is imported.
• Core 0.4.1 is reserved for the complete API set. No release tag or npm publication is performed.
• The zero-upload guarantee applies to deterministic size preflight. Real transient storage failures or uncertain client/worker submission can still leave stored payloads. No automatic rollback deletion is added: failed or uncertain submission is not proof that references were never published.
• Full live DTS/mixed-.NET execution has not been run locally (Docker daemon unavailable). The final phase records aggregate local Blob/Azurite, source/wire interoperability and packed-consumer evidence without claiming absent hosted checks.

[Copilot]

🟡 Changes recommended

Continue-as-new carryover payloads bypass externalization and configured size limits.

1 open finding

• Externalize and enforce size limits for continue-as-new carryover events · New

What changed in this PR

Adds the core foundation for optional external payload storage, ahead of transport and provider integration.

Changes:

• Introduces storage contracts and explicit protobuf payload mapping.
• Adds bounded processing, size checks, failure conversion, and regression tests.
• Reserves core version 0.4.1 and synchronizes dependency metadata.

File	Description
packages/​durabletask-js/​test/​payloads.spec.ts	Tests mapping, limits, failures, and concurrency.
packages/​durabletask-js/​src/​payloads/​run-bounded.ts	Bounds concurrency and drains started operations.
packages/​durabletask-js/​src/​payloads/​payload-store.ts	Defines storage contracts, options, and errors.
packages/​durabletask-js/​src/​payloads/​payload-processor.ts	Maps and processes protobuf payload fields.
packages/​durabletask-js/​src/​index.ts	Exports payload contracts.
packages/​durabletask-js/​package.json	Reserves core 0.4.1.
packages/​azure-functions-durable/​package.json	Updates the exact core dependency.
package-lock.json	Synchronizes version metadata.
CHANGELOG.md	Documents the foundation and phased release.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.