Deviation Records

Status: Design landing Reference epics: INK-828 ADRs: ADR-019

What a deviation record is

A deviation record is a durable, queryable artifact produced when a write to the workspace disagrees with canonical content the workspace already holds. The record names the disagreement, points at the content involved, and sits in an author-facing triage inbox until the author resolves it.

Deviation records are the world model’s commitment not to silently reconcile. When the agent’s inference, the author’s instruction, or the workspace’s existing canonical content disagree, the world model does not pick a winner; it records the disagreement and surfaces it to the author.

Record type, not workspace entity

A deviation record is a first-class workspace record type, distinct from workspace entities (pages, blocks, relationships). It is queryable, referenceable from content, and surfaceable through dedicated product surfaces. It is not a node in the workspace graph, and it does not carry its own origin or lifecycle.

This distinction is deliberate:

• Deviation records do not need to be derived from, linked to by other entities through the relationship system, or walked by graph queries that reason about workspace structure.
• They do need to be queryable by content reference, by status, by type, and by age; referenceable from revision history on workspace content by ID; and surfaced through inboxes and inline markers.

A typed record with indices satisfies the second set without incurring the architectural weight of the first. The product value — triage inbox, inline markers, reference from revision history, durable self-awareness — lands at the record level.

Storage-wise, deviation records live in their own storage surface, separate from the tables that hold pages, blocks, and relationships. See Database Schema for the schema placement.

What a deviation record carries

Field	Shape
Type	One of the four conflict types below.
Timestamp	When the conflict was detected.
Detecting source	Conversational agent run, scheduled autonomous task, user flag.
Content references	Pointers to the workspace content involved — the submitted content, the canonical content it conflicts with, any supporting context.
Status	open, resolved, or dismissed.
Body	Narrative naming the inconsistency in human terms.
Resolution note	Populated on resolve or dismiss; captures what the author did and why.

What a deviation record deliberately does not carry:

• No origin axis. “Detecting source” captures who noticed; origin as a provenance concept does not apply to a record that is not workspace content.
• No lifecycle axis. Status (open / resolved / dismissed) is a narrower, deviation-specific field.
• No derivation links. Content can reference a deviation record by ID from its revision history, but deviations are not derivation sources in the derivation-link graph sense.

Four conflict types

Deviation records discriminate on the shape of the disagreement:

1. agent-answer-vs-canonical — The agent stated something in conversation that contradicts canonical content. The conflict was detected as the agent’s answer was composed against the current workspace state.
2. agent-inference-revisited — An earlier agent inference that was accepted into the workspace now conflicts with revised canonical content. The retroactive-revision queue is the typical detector.
3. user-correction-signaling-structural-gap — The user corrected the agent and the correction implies something about the world that canonical content does not reflect. The correction is a hint that the world needs a matching edit somewhere.
4. canonical-vs-canonical — Two pieces of canonical content disagree with each other. Typically detected by scheduled consistency passes or encountered during derivation.

The type is not a hierarchy or a workflow; it is a discriminator that downstream surfaces use to compose appropriate triage context.

Always produce; never self-dismiss

Every conflict detected at the submit boundary produces a deviation record. The agent does not self-assess “this conflict is my error, not a genuine disagreement” and suppress the record. That assessment is the author’s.

This is a hard rule. The agent is structurally prevented from hiding conflicts from the author, including conflicts it suspects the author would resolve trivially. The mechanical rule is uniform: conflict at submit → deviation record. No judgment in the pipeline.

Volume is the tradeoff this rule accepts. Prominence and triage — where the author’s attention gets drawn first — are product-surface concerns, discussed under prominence below. The honesty of the pipeline is worth the volume.

See ADR-019 for the record-not-entity rationale and the always-produce commitment.

When records are produced

Two paths produce deviation records:

At the submit boundary (D9 / D21). When an agent submission — conversational or autonomous — crosses the submit boundary and disagrees with existing canonical content, the submit-boundary adapter emits a deviation record as part of the same operation that persists the write. The record is created whether or not the write itself is accepted; the accepted write and the record are two outputs of the same transit.

By explicit detection. The agent or the user can create a deviation record explicitly when they notice an inconsistency that was not caught at a submit. The agent’s scheduled consistency-check task is the standard autonomous path; user-filed records enter through the triage inbox’s compose affordance.

A third apparent path — a scheduled re-validation walk detecting a conflict on existing content — is really a variant of the second: the scheduled task is the detector; it produces a deviation record explicitly, not through a submit-boundary adapter. The distinction matters because the re-validation queue is not crossing the submit boundary; it is examining already-persisted content against revised sources.

What does not produce a deviation record

• Submit denials under the permission system. When the submit boundary rejects a write because the agent lacks the required capability, no deviation record is produced. D21’s obligation applies only to submit-boundary conflicts on content the agent was entitled to operate on.
• Agent confusion or retrieval failure. A deviation record names a disagreement between content and content. An agent that produced a wrong answer because it failed to retrieve a relevant page is not a deviation — it is an agent bug, caught by other observability surfaces.
• Non-canonical conflicts. Canonical is the baseline. A candidate submission that disagrees with another candidate submission is not a deviation record; neither has been accepted into the world. Disagreements between candidates are for the author to resolve as part of deciding whether to canonicalize either.

Prominence and triage

Deviation records are surfaced through two product surfaces that read from the deviation record store directly, not from the workspace graph:

• Triage inbox. A dedicated surface that lists open deviation records in prominence-weighted order. The inbox is the author’s workbench for resolving disagreements.
• Inline markers. Each piece of workspace content involved in an open deviation record carries a marker on its surface, so the author sees the deviation in context when they open the page, not only when they open the inbox.

Prominence ordering in the triage inbox scales with standing of the content involved, consistent with the retroactive-revision prominence rule (D12). A deviation touching high-standing content surfaces before one touching peripheral content. The ordering is stable once set — standing is read at record creation time, not re-evaluated continuously — so the author can work the queue without it reshuffling underfoot.

Prominence does not gate. Every deviation is visible; prominence orders the presentation.

See [parking-lot PL-F] internally for the resolved product framing.

Resolution

The author resolves a deviation record by picking one of three actions, which correspond to the three options available whenever the world flags potentially stale content (see Retroactive Revision):

1. Accept. The conflict is defensible as-is. The record is marked resolved with a resolution note explaining why the apparent conflict is acceptable.
2. Update. The author edits one or both pieces of content to remove the conflict. The edit flows through the submit boundary as an authored write; closing the record is a separate write to the deviation record store. The derived page’s revision history can reference the deviation record by ID, capturing that this edit resolved it.
3. Retire. Retire one of the conflicting pieces of content. The retirement is a lifecycle transition; closing the record is a separate write to the record store.

The record also supports a dismiss action for cases where the conflict is judged spurious after inspection (the author reviewed it and the record is noise). Dismissal sets status to dismissed with a resolution note.

Resolved and dismissed records are not deleted. They are retained as the durable trace of how the world has reconciled with itself over time. A year later, the author can ask: “when did my world say two things at once about X, and how did I reconcile it?” The deviation record store answers.

What deviation records are not

• Not errors. Deviation records are epistemic artifacts — the world noticing itself being inconsistent. The product surface treats them as such, not as exceptions to be cleared.
• Not governance gates. The author resolves at their own pace. No deviation blocks a write, a canonicalization, or any other operation. D14 (no governance machinery) and D24 (no middle-ground gates) both apply.
• Not derivations. A deviation record names a disagreement; it is not a source the derived content was built from. See the derivation-vs-deviation distinction.
• Not workspace entities. They live in their own store; they are not pages, blocks, or relationships.

Worked example

Moment 4 — Deviation record and author triage walks through an agent-inference-revisited deviation end-to-end: a scheduled task detects the conflict during a re-validation walk, emits the record, the author finds it in the triage inbox the next morning, and resolves by editing the derived page.

What this page does not do

• Does not describe the storage schema. See Database Schema.
• Does not describe the submit-boundary mechanics that produce records automatically. See Submit Boundary.
• Does not describe the re-validation queue that frequently produces records via scheduled walks. See Retroactive Revision.
• Does not describe the triage-inbox UI surface in detail. See the platform docs for the inbox component.