Scrubbed extract of Spatial-Cognition-Platform/ADR/ADR-SCP-006-Reasoning-Immutability-In-Client.md — cited by the Chronicle (08-now-shipping). Redactions: phone / service detail / secrets / clearance / personal / internal hosts.

type: project project: Spatial-Cognition-Platform status: accepted created: 2026-08-27 tags:

adr
reasoning-plane
immutability
provenance

ADR-SCP-006: Reasoning objects are immutable; the client appends revisions, never edits

Status: Accepted Date: 2026-08-27 Deciders: Solo (Cory) Context Project: [[Spatial-Cognition-Platform]] · [[Concept-Layered-Planes-Architecture]] §2–§4, §8

Context

The concept’s differentiating move is Git-like semantics for reasoning: grabbing an agent’s proposal in XR and “changing” it must create a new versioned object linked to its parent, preserving provenance — never mutating the original. The POC renders a canned reasoning set and lets the user revise objects in-headset, which makes this the first place the platform could quietly cheat.

Decision

AgentWork objects are immutable records. A revision creates a new object with a fresh id, derivedFrom: [parent], and the parent gains revisedBy in the projection; content of the parent is never rewritten.
The reasoning store is append-only. IReasoningStore exposes Append(AgentWork) and reads; there is no update or delete. Supersession is expressed by status on the new object and linkage, mirroring how this vault handles ADRs.
The client writes Reasoning and Workspace planes only. Truth (SystemGraphSnapshot) is read-only in the client, structurally: Scp.App exposes no port that could write it. Humans revising in-headset are symmetric actors to agents — their revisions carry author: {kind: human} with the same provenance obligations.
Typed edges are data: derivedFrom, supports, contradicts, and evidence links into truth entities/assertions/artifacts come from the overlay contract (ADR-SCP-004); the renderer visualizes them but cannot invent them.
POC persistence: in-headset revisions append to a local reasoning-local.json overlay merged over the served ReasoningOverlay at load — same contract shape, so promotion to a real reasoning service (S6) is an adapter swap.

Consequences

Positive

Provenance chains (Decision → Claim → Observation → Artifact) stay intact by construction — the demo’s provenance beam is honest, not staged.
Merge semantics (post-POC) get a clean substrate: merge nodes reference parents, nothing is destroyed.
Append-only stores are trivial for agents to implement and test (rung 1).

Negative / Risks

Object count grows monotonically; acceptable at POC scale, and later planes get compaction/archival views without touching semantics.
Two overlay sources at load (served + local) need a defined merge rule: union by id, local wins on linkage additions, duplicate ids are a validation error.

Alternatives Considered

Alternative 1 — Mutable reasoning objects with an edit history log

Rejected because: history-as-afterthought always diverges from state; the concept demands revision chains as first-class graph structure, not a changelog beside a mutable row.

Alternative 2 — Client-local edits as pure view state (no reasoning writes at all)

Rejected because: guts the demo’s core moment and the thesis — humans and agents as symmetric actors on the same world model. Workspace-only “fake” revisions would have to be thrown away.

Alternative 3 — CRDTs for reasoning state now

Rejected because: multi-writer convergence is a real future need (collaboration, S8+) but premature; append-only + explicit merge nodes is the concept’s own answer and is POC-sized.

[[ADR-SCP-004-Contract-First-Projection-Wire-Format]] — ReasoningOverlay shape
[[ADR-SCP-005-Workspace-State-Separation]] — the other client-writable plane

Adr Scp 006 Reasoning Immutability