Release 18.2.1

[flyingrobots]

Summary

• Prepare @git-stunts/git-warp and private workspace package metadata for 18.2.1.
• Move the current-release docs from stale v18.1.2 wording to the merged v18.2.1 state-cache materialization fix.
• Add docs/TECHNICAL_TEARDOWN.md with the technical teardown for the git-cas / git-warp / XYPH materialization-cache incident.
• Keep historical changelog, migration, fixture, sentinel, and semver-example version strings intact where they describe older releases or syntax rather than the current release.

Issue

Refs #709

Test plan

• npm run release:guard -- --stage prep-pr --tag v18.2.1
• npm run lint:docs-topology
• npx markdownlint docs/TECHNICAL_TEARDOWN.md CHANGELOG.md README.md ARCHITECTURE.md docs/topics/README.md
• npm run lint:md:code -- docs/TECHNICAL_TEARDOWN.md CHANGELOG.md README.md ARCHITECTURE.md docs/topics/README.md
• npm run lint:source-version-names
• JSON parse check for package.json, jsr.json, workspace package manifests, and package-lock.json
• git diff --check
• pre-push IRONCLAD M9: link check, lint, typecheck, policy, consumer typecheck, surface validator, markdown/doc gates, CAS invariants, and stable unit-test shards

ADR checks

• This PR does not implement ADR 2 without satisfying ADR 3
• If this PR touches persisted op formats, I linked the ADR 3 readiness issue
• If this PR touches wire compatibility, I confirmed canonical-only ops are still rejected on the wire pre-cutover
• If this PR touches schema constants, I confirmed patch and checkpoint namespaces remain distinct

This release-prep PR does not change persisted op formats, wire compatibility, or schema constants.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c73194d6-5a7b-4441-b69e-0bb4ef7bfdc0

📥 Commits

Reviewing files that changed from the base of the PR and between 9606a6f and c0a3247.

📒 Files selected for processing (1)

• docs/TECHNICAL_TEARDOWN.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (4)

• GitHub Check: preflight
• GitHub Check: test-node (22)
• GitHub Check: type-firewall-lint
• GitHub Check: coverage-threshold

🧰 Additional context used

🪛 LanguageTool

docs/TECHNICAL_TEARDOWN.md

[grammar] ~173-~173: Ensure spelling is correct
Context: ... and compatibility exports. 2. Calls installDefaultRuntimeHostNodePorts(). 3. Exports the API surface, including ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[style] ~668-~668: The double modal “requires materialized” is nonstandard (only accepted in certain dialects). Consider “to be materialized”.
Context: ...ytes - removing nodes or edges requires materialized state so observed dots can be tombsto...

(NEEDS_FIXED)

---

[style] ~1253-~1253: The double modal “requires cached” is nonstandard (only accepted in certain dialects). Consider “to be cached”.
Context: ... Error | | --- | --- | | Query requires cached state but none exists | E_NO_STATE | ...

(NEEDS_FIXED)

🔇 Additional comments (1)

docs/TECHNICAL_TEARDOWN.md (1)

1379-1381: 📐 Maintainability & Code Quality

Narrow the runtime-portability claim.

index.ts installs Node-specific defaults at import time, so the statement that the same runtime model is usable in “Node, browser-like environments, Bun, Deno, and tests” looks broader than what this file proves. Please verify the supported runtime matrix, or scope this claim to the actual entry points that work without Node-only bootstrapping.

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Corrected state-cache materialization behavior and improved live materialization snapshot reuse.
  • Ensures replay-backed reads publish under the correct coordinate and include complete diff and provenance data.

• Documentation

  • Added a new v18.2.1 release entry to the changelog.
  • Updated README, architecture guidance, and topic docs to reflect v18.2.1 changes.
  • Added a comprehensive technical teardown document.

• Chores

  • Bumped package versions to 18.2.1 and refreshed release workflow/preflight examples to match the current tag.

Walkthrough

This PR bumps package versions to 18.2.1, updates release-facing docs and examples, and adds a new technical teardown document describing git-warp end to end.

Changes

Release version bump and documentation

Layer / File(s)	Summary
Package version bumps jsr.json, package.json, packages/warp-adapters/package.json, packages/warp-kernel/package.json, packages/warp-orset/package.json	Version field bumped from 18.2.0 to 18.2.1 in all package manifests.
Release documentation and changelog ARCHITECTURE.md, README.md, docs/topics/README.md, CHANGELOG.md	Updated release target/version text and added a new changelog entry describing the corrected WARP state-cache materialization path and the git-warp/git-cas snapshot-replay boundary.
Example tag references .github/workflows/release.yml, scripts/release-preflight.sh	Sample tag values in workflow input description and script comment updated to v18.2.1.
Technical teardown document docs/TECHNICAL_TEARDOWN.md	Added a long-form technical teardown covering git-warp terminology, architecture, flows, error handling, concurrency, security, and configuration.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• git-stunts/git-warp#107: Both PRs add or revise technical documentation around git-warp’s release and architecture, including the teardown-style material.
• git-stunts/git-warp#674: Shares the same release-facing documentation surfaces in ARCHITECTURE.md, README.md, docs/topics/README.md, and CHANGELOG.md.
• git-stunts/git-warp#680: Also updates package/version metadata and release documentation for the same release line.

Poem

Hop, hop, the release bells ring,
18.2.1 is now the spring,
Snapshots, docs, and versions neat,
A rabbit taps in jaunty beat,
🐇✨ The trail is tidy, bright, and new.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is related to the release bump, but it's too generic to identify the main change.	Use a more specific title like "Bump git-warp to 18.2.1 and update release docs".

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description matches the template with Summary, Issue, Test plan, and ADR checks filled in.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Release Preflight

• package version: 18.2.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Main Push Release Branch Check will run final preflight and create v18.2.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[github-actions]

Release Preflight

• package version: 18.2.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Main Push Release Branch Check will run final preflight and create v18.2.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.