[kriszyp]

⊙ Problem

Stop update() reads from becoming writes, and make addTo calls in one transaction add up changes what a tracked update() record writes. The Resource API reference covers none of it:

• Reading a sub-object or array element is no longer a write.
• An in-place Date or Bytes edit no longer saves.
• A BigInt delta on a number-typed property is converted to a number.
• An undeclared property assigned alone now saves on a non-sealed table.
• Repeated addTo / subtractFrom calls add up, and subtractFrom takes a BigInt.

🤔 Is the requirement right?

Yes. The in-place Date / Bytes change can drop writes silently after an upgrade, so readers need it in the reference and the release notes.

💡 Solution

• update() gets a What a tracked record writes subsection, with a Date / Bytes replacement example.
• addTo lists how calls combine. A delta after an assignment stays an assignment, which does not merge with concurrent writers.
• Both signatures read number | bigint; old anchors still work.
• Three 5.4 release-note entries, Date / Bytes first.

🤔 Badged v5.4.0

The core PR merged on main and first shipped in v5.4.0-alpha.2. It is not in v5.3.5.

🔧 Changes

• reference/resources/resource-api.md: a new subsection under update(), the instance-methods intro (drops "declared in the schema"), addTo, subtractFrom, set, and one bullet in Concurrency and Safe Concurrent Writes. Look hardest at the addTo bullets: they state merge semantics readers will rely on.
• release-notes/v5-lincoln/5.4.md: new Resource API section.
• Text follows what merged: an array's Date / Bytes elements still save when edited in place, and other non-plain values (a Map) must be reassigned.

✅ Verification

• Each claim was traced in the merged core code (resources/tracked.ts, resources/Table.ts at v5.4.0-alpha.2) and matches a test in unitTests/resources/trackedUpdateCommit.test.js. Not run against a live Harper.
• npm run build passes, and the new and kept anchors are in the built page. npm run format:check is clean.

Docs for HarperFast/harper#3586.

_{🤖 Generated by Anthropic Claude Opus 5.5; posted via @kriszyp.}

🤖 Generated with Claude Code

Related PRs: #779 independent (open; other sections of the same two files), #783 independent (open; same), #784 independent (open; same), 3 others independent
Complexity: easy

Origin — the dispatch brief this PR was written from

Document tracked update() changes: addTo composition, BigInt subtractFrom, reassigning Date/Bytes

Document tracked-update behavior changed by HarperFast/harper#3586 (HarperFast/harper#3586) in the Resource API reference (reference/resources/resource-api.md: the update() / tracked record, addTo, subtractFrom, and set sections).

What changed for users:

1. addTo(property, delta) / subtractFrom(property, delta) compose within one transaction. Two calls on the same property add both deltas: addTo('n', 5); addTo('n', 3) adds 8 as one commutative addition, which still merges with other writers' additions. A delta after an assignment adds to the assigned value: rec.n = 100; rec.addTo('n', 7) stores 107. An assignment after addTo replaces the pending delta.
2. subtractFrom accepts a BigInt delta, like addTo.
3. Reading a property of a record returned by update() (a sub-object, an array element) is no longer a write. Only properties you change are written, sent to source.patch, and recorded in the audit history.
4. A Date or Bytes (Buffer/Uint8Array) value must be reassigned to be saved, e.g. rec.when = new Date(...). Changing it in place (rec.when.setTime(...), rec.bytes[0] = 9) is not tracked.
5. On a non-sealed table, assigning an undeclared property on the tracked record (rec.extra = 'x') saves it, even when nothing else changed.

Keep the examples short; no internals. Link the harper PR in the docs PR body.

_{Dispatch: task docs-harper-3586 · queued by task:harper-tracked-update-collapse-addto · ran by claude/opus/high · worker kzyp-xps-1}

_{Ready-For-Promotion: 99041d7 urgency=normal late=none}

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,muse; rounds=7; full=2 @ 99041d7}

_{Review-Attention: skim ~2m (decisions: silent-break-placement, date-bytes-copy-semantics) @ 99041d7}

[gemini-code-assist]

Code Review

This pull request updates the Resource API documentation and release notes for version 5.4.0, detailing that only assigned or changed properties are written, in-place modifications to Date and Bytes objects are no longer tracked, and repeated addTo and subtractFrom calls (which now support bigint) combine within a transaction. The review feedback points out several instances where the component is used at the start of a paragraph in running prose, recommending replacing it with plain text (e.g., 'As of v5.4.0') to improve readability and consistency.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-760

This preview will update automatically when you push new commits.