Skip to content
Draft
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,9 @@ Owns stable value contracts without I/O:
- `InstructionSource` and `SecretDelivery`;
- `RiskClass`, `Capability`, and `ActionKind`;
- exact action, target-origin, and intent-bound `ApprovalScope` and `ApprovalEvidence`;
- `ActionRequest` and `PolicyContext`.
- `ActionRequest` and `PolicyContext`;
- session-, context-, origin-, and epoch-bound `ObservedNodeHandle` values;
- `SameDocumentMutationKind` decisions that rotate `DocumentEpoch` when a same-document mutation can change actionable identity.

### `originweave-policy`

Expand Down Expand Up @@ -166,7 +168,7 @@ Observation should prefer the most structured trustworthy source available:
4. accessibility tree combined with DOM and layout;
5. screenshot or vision fallback for canvas and inaccessible custom interfaces.

Raw HTML is not the default model input. Full snapshots are followed by incremental semantic diffs, versioned by document epoch. Node references become invalid after navigation or epoch change.
Raw HTML is not the default model input. Full snapshots are followed by incremental semantic diffs, versioned by document epoch. Node references become invalid after navigation or after a relevant same-document mutation rotates the epoch.

## 8. Action lifecycle

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ All notable changes to OriginWeave are documented in this file. The format follo

### Added

- Same-document mutation kinds that rotate `DocumentEpoch` when a checkout-field replacement, role/name change, accessibility invalidation, frame-document replacement, or actionable subtree replacement can change node identity, while a reviewed non-semantic mutation may keep the current handle and overflow fails closed.
- Rust workspace for independently reusable core, policy, destination, network, TLS, resource, and evidence modules.
- Canonical HTTPS and loopback-origin boundary with case-normalized schemes and hosts, default-port normalization, IPv4/IPv6 handling, browser-special numeric-host rejection, and explicit malformed-input errors.
- Typed browser actions, capabilities, risk classes, execution modes, robots decisions, secret-delivery contracts, immutable canonical action-intent digests, and intent-bound approval scopes.
Expand Down
62 changes: 62 additions & 0 deletions crates/originweave-core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -292,6 +292,63 @@ impl DocumentEpoch {
pub const fn value(self) -> u64 {
self.0
}

/// Rotate the epoch when a same-document mutation can change actionable identity.
///
/// Re-observe the current document and use the new handle. Do not reuse a
/// handle emitted at the previous epoch after a relevant mutation.
pub const fn after_same_document_mutation(
self,
mutation: SameDocumentMutationKind,
) -> Result<Self, NodeHandleError> {
if !mutation.requires_epoch_increment() {
return Ok(self);
}
match self.0.checked_add(1) {
Some(next) => Self::new(next),
None => Err(NodeHandleError::DocumentEpochOverflow),
}
}
Comment thread
seonghobae marked this conversation as resolved.
Resolved
}

/// A same-document lifecycle event that may invalidate actionable node handles.
///
/// This is a control-plane decision input. It does not observe the live DOM,
/// accessibility tree, or browser process.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SameDocumentMutationKind {
/// The previously observed target node was removed from the document.
TargetRemoved,
/// The previously observed target was replaced by a different node.
TargetReplaced,
/// The target's actionable role, accessible name, or actionability changed.
RoleOrNameChanged,
/// A relevant accessibility-tree invalidation changed the target's meaning.
AccessibilityTreeInvalidated,
/// A nested frame document was replaced while the parent document remained.
FrameDocumentReplaced,
/// A subtree mutation replaced the observed actionable target.
ActionableSubtreeReplaced,
/// A reviewed non-semantic change that cannot affect any emitted handle.
NonSemanticUnrelated,
}

impl SameDocumentMutationKind {
/// Return whether this mutation must increment the document epoch.
///
/// Uncertainty must use a relevant variant so the old handle cannot be reused.
#[must_use]
pub const fn requires_epoch_increment(self) -> bool {
match self {
Self::NonSemanticUnrelated => false,
Self::TargetRemoved
| Self::TargetReplaced
| Self::RoleOrNameChanged
| Self::AccessibilityTreeInvalidated
| Self::FrameDocumentReplaced
| Self::ActionableSubtreeReplaced => true,
}
}
}

/// A node identity bound to the exact session, context, origin, and document that produced it.
Expand Down Expand Up @@ -422,6 +479,8 @@ pub enum NodeHandleError {
/// Epoch currently active in the browser context.
current: DocumentEpoch,
},
/// Incrementing the document epoch would wrap the identifier space.
DocumentEpochOverflow,
}

impl fmt::Display for NodeHandleError {
Expand Down Expand Up @@ -456,6 +515,9 @@ impl fmt::Display for NodeHandleError {
observed.value(),
current.value()
),
Self::DocumentEpochOverflow => {
formatter.write_str("document epoch cannot wrap after a same-document mutation")
}
}
}
}
Expand Down
4 changes: 4 additions & 0 deletions crates/originweave-core/tests/document_epoch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,10 @@ fn node_handle_errors_are_standard_and_deterministic_for_adapters() {
},
"observed node document epoch 7 is stale; current epoch is 8".to_owned(),
),
(
NodeHandleError::DocumentEpochOverflow,
"document epoch cannot wrap after a same-document mutation".to_owned(),
),
];

for (error, expected) in cases {
Expand Down
103 changes: 103 additions & 0 deletions crates/originweave-core/tests/same_document_mutation.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
#![allow(clippy::expect_used)]

use originweave_core::{
BrowserSessionId, BrowsingContextId, DocumentEpoch, NodeHandleError, ObservedNodeHandle,
Origin, SameDocumentMutationKind,
};

fn checkout_field_handle() -> ObservedNodeHandle {
ObservedNodeHandle::new(
BrowserSessionId::new(3).expect("browser session"),
BrowsingContextId::new(11).expect("browsing context"),
Origin::parse("https://shop.example").expect("canonical origin"),
DocumentEpoch::new(1).expect("initial document epoch"),
42,
)
.expect("observed checkout field")
}

#[test]
fn a_same_document_target_replacement_invalidates_the_previous_checkout_field_handle() {
let handle = checkout_field_handle();
let session = handle.browser_session();
let context = handle.browsing_context();
let origin = handle.origin().clone();
let observed_epoch = handle.document_epoch();

let current_epoch = observed_epoch
.after_same_document_mutation(SameDocumentMutationKind::TargetReplaced)
.expect("replacement must rotate the document epoch");

assert_eq!(current_epoch.value(), 2);
assert_eq!(
handle.validate_current(session, context, &origin, current_epoch),
Err(NodeHandleError::StaleDocumentEpoch {
observed: observed_epoch,
current: current_epoch,
})
);

let reobserved = ObservedNodeHandle::new(session, context, origin.clone(), current_epoch, 43)
.expect("re-observed checkout field");
assert_eq!(
reobserved.validate_current(session, context, &origin, current_epoch),
Ok(())
);
}

#[test]
fn relevant_same_document_mutations_rotate_the_document_epoch() {
let epoch = DocumentEpoch::new(4).expect("document epoch");
let cases = [
SameDocumentMutationKind::TargetRemoved,
SameDocumentMutationKind::TargetReplaced,
SameDocumentMutationKind::RoleOrNameChanged,
SameDocumentMutationKind::AccessibilityTreeInvalidated,
SameDocumentMutationKind::FrameDocumentReplaced,
SameDocumentMutationKind::ActionableSubtreeReplaced,
];

for mutation in cases {
assert!(
mutation.requires_epoch_increment(),
"mutation={mutation:?} must rotate the document epoch"
);
let next = epoch
.after_same_document_mutation(mutation)
.expect("relevant mutation must produce the next epoch");
assert_eq!(next.value(), 5, "mutation={mutation:?}");
}
}

#[test]
fn an_unrelated_non_semantic_mutation_may_keep_the_checkout_field_handle() {
let handle = checkout_field_handle();
let session = handle.browser_session();
let context = handle.browsing_context();
let origin = handle.origin().clone();
let observed_epoch = handle.document_epoch();

assert!(!SameDocumentMutationKind::NonSemanticUnrelated.requires_epoch_increment());
let current_epoch = observed_epoch
.after_same_document_mutation(SameDocumentMutationKind::NonSemanticUnrelated)
.expect("unrelated mutation may preserve the epoch");

assert_eq!(current_epoch, observed_epoch);
assert_eq!(
handle.validate_current(session, context, &origin, current_epoch),
Ok(())
);
}

#[test]
fn document_epoch_overflow_fails_closed_instead_of_wrapping() {
let epoch = DocumentEpoch::new(u64::MAX).expect("maximum document epoch");
assert_eq!(
epoch.after_same_document_mutation(SameDocumentMutationKind::TargetRemoved),
Err(NodeHandleError::DocumentEpochOverflow)
);
assert_eq!(
NodeHandleError::DocumentEpochOverflow.to_string(),
"document epoch cannot wrap after a same-document mutation"
);
}
2 changes: 1 addition & 1 deletion docs/PRD.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ public-crawl purpose
| ID | Requirement | Status | Implementation evidence / note |
|---|---|---|---|
| PRD-OBS-001 | Autonomous observations can carry explicit browser-session, browsing-context, canonical-origin and document-epoch authority | Implemented | `ObservedNodeHandle`, `BrowserSessionId`, `BrowsingContextId` and `DocumentEpoch` are on protected main under Accepted ADR 0010; real browser adapter remains planned |
| PRD-OBS-002 | Actionable semantic-node handles are invalidated by relevant document-epoch changes at the action linearization boundary | Accepted architecture | Core exact-authority validation exists; adapter lifecycle/mutation invalidation and atomic dispatch evidence remain planned; active PR #40 owns the bounded protocol-ID registry and remains non-shipped evidence |
| PRD-OBS-002 | Actionable semantic-node handles are invalidated by relevant document-epoch changes at the action linearization boundary | Accepted architecture | Core `SameDocumentMutationKind` now decides when a same-document mutation must rotate `DocumentEpoch` so a replaced checkout field cannot keep its old handle; live MutationObserver/BiDi invalidation and atomic dispatch remain planned adapter work; active PR #40 owns the bounded protocol-ID registry and remains non-shipped evidence |
| PRD-OBS-003 | Observation prefers typed/structured evidence before accessibility/DOM/layout and bounded visual fallback | Accepted architecture | ADR 0103; active PR #52 adds a bounded `SemanticNodeObservation` value contract bound to `ObservedNodeHandle`, typed node-local action descriptors and explicit non-empty evidence-channel provenance. It is not a browser observation adapter and remains active/non-shipped evidence |
| PRD-OBS-004 | Observation can use bounded incremental updates rather than full repeated snapshots | Planned | Adapter-specific design needed |
| PRD-OBS-005 | Source channel and trust/provenance remain explicit | Accepted architecture | Evidence model foundations exist; active PR #52 fails closed when a semantic observation has no contributing evidence channel, while channel identity itself grants no execution authority |
Expand Down
2 changes: 1 addition & 1 deletion docs/THREAT_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ Remote sites, proxies, DNS resolvers, PAC sources, model providers, connectors a

**Attack:** an adapter-local node ID collides across sessions, frames, origins or documents; an agent acts on stale UI after navigation.

**Implemented controls:** `originweave-core` already binds `ObservedNodeHandle` to OriginWeave browser-session, browsing-context, canonical-origin, document-epoch and adapter-local-node identities and exposes deterministic validation for cross-session, cross-context, cross-origin and stale-document reuse. These contracts are covered by the current core tests and remain observation-authority primitives rather than proof of a live Chromium dispatch path.
**Implemented controls:** `originweave-core` already binds `ObservedNodeHandle` to OriginWeave browser-session, browsing-context, canonical-origin, document-epoch and adapter-local-node identities and exposes deterministic validation for cross-session, cross-context, cross-origin and stale-document reuse. `SameDocumentMutationKind` rotates the document epoch when a same-document replacement, role/name change, accessibility invalidation, frame replacement, or actionable subtree change can alter the target, so a checkout-field handle cannot survive a single-page replacement. These contracts are covered by the current core tests and remain observation-authority primitives rather than proof of a live Chromium dispatch path.

**Planned controls:** the browser adapter must rotate the document epoch for relevant same-document DOM/accessibility mutations, revalidate the same handle authority at the action linearization point immediately before the trusted side effect, abort on any competing mutation, and require re-observation before a new action can proceed. The first real Chromium vertical slice must prove that a pre-mutation handle is rejected while the newly observed handle succeeds.

Expand Down
2 changes: 1 addition & 1 deletion docs/TRD.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ An actionable node reference is valid only when every component matches the live

### 5.2 Document epochs

Navigation, document replacement, or another adapter-defined actionable-document lifetime change rotates `document_epoch`. A stale node reference must fail deterministically before input dispatch. Core exact-authority validation is Implemented; real browser lifecycle invalidation/linearized dispatch remains adapter work.
Navigation, document replacement, or another adapter-defined actionable-document lifetime change rotates `document_epoch`. Core `SameDocumentMutationKind` is Implemented for the control-plane decision: target removal/replacement, role/name change, accessibility-tree invalidation, frame-document replacement, and actionable subtree replacement increment the epoch; a reviewed non-semantic mutation may preserve it; overflow fails closed. A stale node reference must fail deterministically before input dispatch. Real browser lifecycle observation and linearized dispatch remain adapter work.

### 5.3 Idempotency

Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0010-session-context-bound-node-authority.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ OriginWeave represents actionable observed-node authority with five explicit val

`ObservedNodeHandle` stores all five values. Immediately before acting, an adapter must compare the handle with the current session, browsing context, canonical origin, and document epoch. Any mismatch fails closed before the adapter issues a browser action.

The numeric identifiers are internal opaque registry identities. They are not raw WebDriver, WebDriver BiDi, CDP, renderer, process, frame-tree, or DOM identifiers, and they are not durable across process restarts. A protocol adapter must translate external identifiers through a validated, session-scoped registry and allocate collision-free internal identities. It must rotate the document epoch whenever the actionable document lifetime changes, including navigation or document replacement that invalidates earlier node references.
The numeric identifiers are internal opaque registry identities. They are not raw WebDriver, WebDriver BiDi, CDP, renderer, process, frame-tree, or DOM identifiers, and they are not durable across process restarts. A protocol adapter must translate external identifiers through a validated, session-scoped registry and allocate collision-free internal identities. It must rotate the document epoch whenever the actionable document lifetime changes, including navigation, document replacement, or a same-document mutation classified by `SameDocumentMutationKind` as able to change the target's identity or user-visible action semantics.

## Consequences

Expand Down
8 changes: 8 additions & 0 deletions docs/doctoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ This document records external evidence that changes OriginWeave architecture, t

The 1 June 2026 WebDriver BiDi Working Draft defines a bidirectional remote-control protocol, events, commands, and user contexts. Because it remains a W3C Working Draft, OriginWeave places BiDi behind a versioned adapter and Web Platform Tests-derived contract tests rather than make it the internal authority model.

WebDriver reports `stale element reference` when a previously referenced node is no longer attached to the active document. That is necessary but not sufficient for OriginWeave: a single-page checkout can replace a labelled field, change its accessible name, or swap a nested frame document while the node remains attached or a similar selector still matches. The WHATWG DOM Standard defines mutation records for attribute, character-data, and child-list changes. WAI-ARIA 1.2 defines role, accessible name, and state as the user-visible action semantics an agent must not confuse after mutation. OriginWeave therefore rotates `DocumentEpoch` from an explicit `SameDocumentMutationKind` before a handle may be reused. The Rust decision function does not claim live MutationObserver or BiDi event consumption.

Comment thread
seonghobae marked this conversation as resolved.
Resolved
### Browser origin equivalence

The WHATWG URL host parser and Chromium canonicalizer classify shortened decimal, integer, hexadecimal, legacy octal-looking, and mixed-component numeric hosts as IPv4 or broken IPv4 candidates rather than ordinary DNS names. Chromium's regression suite includes values such as `192`, `0xC0a80001`, `030052000001`, and mixed hexadecimal components. A non-final empty `0x` component can participate in Chromium's multi-part IPv4 truncation behavior, but a final `0x` label does not produce an IPv4 number because stripping its prefix leaves no digits; it remains a domain label. Chromium also warns that broken IP-like hosts must not be connected because another resolver could accept them. OriginWeave therefore admits only canonical dotted-decimal IPv4 into its policy origin type, rejects browser-special numeric spellings before DNS validation, and preserves final non-numeric DNS labels such as `0x`.
Expand Down Expand Up @@ -150,10 +152,16 @@ The Rust Project Developers. (2026). *Ipv6Addr in std::net* (Rust 1.97.1) [Softw

The Rust Project Developers. (2026). *TcpStream in std::net* (Rust 1.97.1) [Software documentation]. https://doc.rust-lang.org/stable/std/net/struct.TcpStream.html

Web Hypertext Application Technology Working Group. (2026). *DOM standard*. https://dom.spec.whatwg.org/

Web Hypertext Application Technology Working Group. (2026). *URL standard*. https://url.spec.whatwg.org/

World Wide Web Consortium. (2013). *PROV-O: The PROV ontology*. https://www.w3.org/TR/prov-o/

World Wide Web Consortium. (2023, June 6). *Accessible Rich Internet Applications (WAI-ARIA) 1.2* (W3C Recommendation). https://www.w3.org/TR/wai-aria-1.2/

World Wide Web Consortium. (2026). *WebDriver*. Retrieved August 16, 2026, from https://www.w3.org/TR/webdriver2/

World Wide Web Consortium. (2026, June 1). *WebDriver BiDi* (W3C Working Draft). https://www.w3.org/TR/2026/WD-webdriver-bidi-20260601/

Xu, J., Sun, Q., Schwendeman, P., Nielsen, S., Cetin, E., & Tang, Y. (2025). *TRINITY: An evolved LLM coordinator* [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2512.04695
Expand Down
Loading
Loading