feat(core): rotate document epoch after same-document mutation

[cursor]

Buyer-visible gap

This PR adds the bounded control-plane rule required after a same-document DOM mutation can change an observed target's identity or accessible name. DocumentEpoch rotation invalidates the previous ObservedNodeHandle; a reviewed non-semantic mutation may preserve it, and overflow fails closed.

This is deterministic Rust policy metadata only. It does not observe a live DOM, consume MutationObserver or WebDriver BiDi events, dispatch input, or claim a completed Chromium vertical slice.

Current protected-main topology — 2026-09-24 KST

Protected main is exact 87c4daa1830bac5a5228b6036752ad5633232085. Current exact head is 038e0a5e12ca50096779de8e4daed1c83b993695, open / Draft / mergeable.

The former head d7fa3d73b7e35e4fc1657c5b3b17911eacf22c38 was 10 ahead / 2 behind / diverged from protected main. That ancestry defect is now repaired by an ordinary non-force two-parent reconciliation commit: first parent d7fa3d73..., second parent protected main@87c4daa.... The merge tree starts from protected main and reapplies only the validated same-document epoch product/docs/test blobs.

Fresh compare is 11 ahead / 0 behind, with merge base exactly protected main. The effective delta remains the same 11 paths:

• ARCHITECTURE.md and CHANGELOG.md;
• crates/originweave-core/src/lib.rs;
• crates/originweave-core/tests/document_epoch.rs and same_document_mutation.rs;
• ADR/doctoring/session-node-authority/product-roadmap/traceability documentation; and
• tests/test_same_document_doctoring_contract.py.

There is no effective .github/**, dependency, provider/model, secret, network/browser-I/O authority, ruleset, or coverage-denominator delta. Current protected CI/MV3 lifecycle source was adopted rather than overwritten.

Evidence state

Historical exact-head repository evidence on d7fa3d73... remains useful lineage only: CI and MV3 had succeeded there, while Security/Semgrep/Scorecard were cancelled and current governance approval was absent. It does not transfer to the reconciled head.

The reconciliation push occurred while this PR remains Draft. Current native CI 35913623894 is therefore skipped by the protected Draft guard, and MV3 job 107359422004 is likewise completed/skipped, steps=[], no runner. Security 35913623923, Semgrep 35913623809, and CodeQL 35913623757 materialized separately. These are lifecycle facts, not product GREEN.

Do not mark this PR Ready merely to wake native CI: #279 has a fresh exercised defect where ready_for_review creates all-skipped native jobs on current protected workflow generation, independently reproduced by #164 exact d8bdd510.... No no-op synchronize, blind rerun, or product-lane .github/** workaround is permitted.

Scope boundary and acceptance

Remaining #28 work still includes trusted mutation observation, action-boundary revalidation, real browser dispatch, post-condition proof, recovery, and credential-safe evidence. This PR does not claim those capabilities or treat mutation metadata as browser authority.

The ancestry blocker is resolved. Keep Draft until #279's canonical workflow-owner repair makes Ready-transition native verification executable. Then reacquire exact-head repository contracts, formatting, tests, strict Clippy, rustdoc, exact 100% production coverage, Security/Semgrep/CodeQL, current review/thread/ruleset acceptance, and only then consider normal protected-main promotion.

No self-approval, bypass, force push, destructive rebase, workflow/ruleset/secret mutation, gate weakening, protected-main merge, tag, release, or publication is authorized here.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[seonghobae]

Exact-head review found a documentation-maturity regression. The Rust mutation/epoch primitive and its stale-handle/overflow tests are coherent, but several canonical docs promote this active PR to shipped/implemented truth while protected main is still 0c376acf059be9ddddddfbde1d0189e4f39ef014: docs/TRD.md says “Core SameDocumentMutationKind is Implemented”; docs/THREAT_MODEL.md places it under “Implemented controls”; and docs/PRD.md says it “now decides” without identifying it as active/non-shipped evidence. OriginWeave’s documentation contract requires protected-main truth to remain distinct from active-PR evidence. Reword these entries to preserve the current protected-main ObservedNodeHandle validation as implemented and explicitly label SameDocumentMutationKind / same-document epoch rotation as active PR #173 until integration. Do not weaken the tests or behavior. Exact-head CI, SAST, Security, and MV3 are green; this review is limited to truth-status correctness.

Superseded by current exact head 9f18f2f after protected-main reconciliation. Fresh current-head TRD/PRD/THREAT_MODEL inspection no longer promotes SameDocumentMutationKind or same-document epoch rotation to protected-main Implemented truth: the canonical docs keep protected-main node-handle validation distinct and describe same-document mutation handling as adapter/planned or active-PR evidence. This is stale review-state cleanup only, not approval; current-head scanner/workflow and independent/latest-push approval gates remain required.

[opencode-agent]

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 9f18f2f2b44552b6d9a0bf9a588b96a171aa8c7e.

• Head SHA: 9f18f2f2b44552b6d9a0bf9a588b96a171aa8c7e

• Workflow run: 32185284990

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (5 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (5 files)"]
  R1 --> V1["required checks"]
  Evidence --> S2["Docs (4 files)"]
  S2 --> I2["operator or user guidance"]
  I2 --> R2["Review risk: Docs (4 files)"]
  R2 --> V2["docs review"]

Loading

[opencode-agent]

OpenCode Review Overview

• Head SHA: 9f18f2f2b44552b6d9a0bf9a588b96a171aa8c7e
• Workflow run: 32185284990
• Workflow attempt: 1
• Gate result: REQUEST_CHANGES (approval step)

Pull request overview

OpenCode cannot approve yet because required coverage evidence did not pass.

Review outcome

1. HIGH .github/workflows/opencode-review.yml:1 - Coverage evidence did not prove required test/docstring evidence

• Problem: The required coverage-evidence job result was failure, so OpenCode cannot establish approval sufficiency for this head.

• Root cause: Automated approval is only valid when the same-head coverage-evidence job proves supported repository test suites passed and configured docstring gates passed or were advisory, or reports not applicable because no supported source files or package manifests exist. Missing, failed, skipped, unavailable, or unsupported-tooling test evidence is a blocker.

• Fix: Install or configure the repository test/docstring evidence tooling when source files or package manifests exist, rerun the current-head coverage-evidence job, and approve only after it reports success with required evidence or explicit no-source not-applicable evidence.

• Regression test: Keep the approval branch checking needs.coverage-evidence.result == success before posting APPROVE, and publish REQUEST_CHANGES when coverage-evidence blocker states such as cancelled, skipped, failed, unsupported-tooling, or below-100 evidence are present.

• Result: REQUEST_CHANGES

• Reason: coverage-evidence result was failure, so required test/docstring evidence was not proven for current head 9f18f2f2b44552b6d9a0bf9a588b96a171aa8c7e.

• Head SHA: 9f18f2f2b44552b6d9a0bf9a588b96a171aa8c7e

• Workflow run: 32185284990

• Workflow attempt: 1

Coverage evidence

Coverage Decision

• Result: FAIL
• Test evidence: not proven passing
• Docstring evidence: not proven passing when configured
• Failure count: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Changed file (5 files)"]
  S1 --> I1["repository behavior"]
  I1 --> R1["Review risk: Changed file (5 files)"]
  R1 --> V1["required checks"]
  Evidence --> S2["Docs (4 files)"]
  S2 --> I2["operator or user guidance"]
  I2 --> R2["Review risk: Docs (4 files)"]
  R2 --> V2["docs review"]

Loading

[devin-ai-integration]

Devin Review found 1 potential issue.

[devin-ai-integration]

Devin Review found 2 new potential issues.

[seonghobae]

Exact-head update after protected-main reconciliation (2026-08-28): current base is 542ca1e9c0a863595b8b6697790005d2471f5413 and current head is 5e3bc223e71f5c78adcf6405b965786a9b996c86. The prior PR head was merged with protected main without conflicts in merge commit 5e3bc223; the same-document mutation change remains the branch-owned delta. Rust 1.97.1 workspace tests, rustfmt check, strict Clippy, and rustdoc passed on the merged tree. Earlier review/check evidence is predecessor-head history and is not reused; newly triggered hosted checks and an eligible independent approval remain required. No merge claim is made.

[seonghobae]

Fresh owner-path review found two repair findings before this Draft can be treated as current.

1. Base/current-main metadata is stale. Protected main is now 87c4daa1830bac5a5228b6036752ad5633232085; this head d7fa3d73b7e35e4fc1657c5b3b17911eacf22c38 is 10 ahead / 2 behind with merge base c789b802fc98a8d7fd8c09d9327f36828054d2a1. The PR body still describes c789... as current protected main. Repair should be ordinary/non-force adoption of live main, followed by fresh exact-head checks; predecessor GREEN must not transfer.

2. ADR 0103 still cites the 29 June 2026 WebDriver BiDi WD. Current published evidence is the immutable 9 September 2026 WD. This matters specifically for the same-document observation boundary: browsingContext.historyUpdated is now an explicit event whose parameters are context, timestamp, url, optional userContext and do not include a navigation identifier. It should therefore be modeled as non-authorizing Semantic Observation evidence, not coerced into Browser Session navigation pending/terminal authority.

The product invariant already stated by this PR remains correct: if a same-document route/history change can invalidate an actionable target's identity/semantics, the observation adapter must advance DocumentEpoch (or emit the equivalent explicit invalidation) before action; only a deterministic, tested non-semantic proof may preserve the epoch, and uncertainty invalidates. The live event-consumption/Chromium acceptance still belongs to #28, not this deterministic core slice.

Concrete later acceptance for #28/#173 integration: observe handle at epoch N → history.pushState/replaceState plus deterministic semantic target replacement → correlated historyUpdated → old handle fails at the action linearization point with no side effect → re-observation at N+1 succeeds through normal policy. Keep this PR's scope honest: adding the current standard/source mapping is documentation/contract freshness, not evidence that BiDi observation is implemented.

Primary source: https://www.w3.org/TR/2026/WD-webdriver-bidi-20260909/#event-browsingContext-historyUpdated

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 19c19f6d-d70a-44ef-b1c7-680fd8270825

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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