Co-work Truth surface

First-class Co-work rail surface for observing and managing the claims, expressions, evidence, decision provenance, and lifecycle beneath a document or Folder.

Details

Co-work Truth surface

Truth is a first-class user surface within Co-work. The rail tabs are Review | Provenance | Truth | Chat:

• Review answers “What needs my decision?” and remains the inbox for edit proposals, flags, and evaluation results. Claim attention belongs to Truth.
• Provenance answers “Where did these words come from, who is said to have written them, and what human review is recorded?” It owns document-level and exact-span source/authorship/review attestations.
• Truth answers “What does this work rest on?” and owns both observation and the complete domain review for claim, expression, and evidence work.
• Chat remains the general conversational interaction surface. Starting, steering, clarification, and explanation for Truth-analysis runs are later integrations.

The product-visible Truth name is deliberate. Internal implementation terms such as TruthStore, hashes, raw IDs, gestures, and rows remain out of routine copy.

Truth is not primarily a manual ledger-authoring form. Its default mixed-initiative interaction has AI prepare exact typed work for human review. Direct claim and connection authoring remain secondary escape hatches.

Terms and boundaries

A claim is a proposition in the append-only ledger. Facts is a filter, not a claim type or a second subsystem. It uses the canonical current-claim semantics: confirmed base status, current validity, not redacted or voided, and no active needs-review overlay. Do not implement it as claim_kind == "fact".

An expression is a passage where the document says a claim. Evidence is why the claim is believed. A selected or matching passage does not become evidence automatically. The needs-review overlay is also separate from the claim's base lifecycle status.

Document API expression records expose is_fact for current fact status, proposition for readable claim text, evidence_count for positive recorded receipts, and stale for connection health. Redacted propositions are absent. stale is null, claim_terminal, claim_changed, or span_missing; Truth passage connections carry the same value. A span-side warning can reflect a changed document version even when the quote still resolves, so it calls for review rather than proving that the passage disappeared.

A candidate claim is a proposition prepared by an analysis run and is not yet a ledger claim or fact. An evidence candidate is a retrieved source passage which has not yet been selected and captured as an immutable evidence receipt. A support assessment does not itself confer fact status.

Truth defaults to This document, which contains claims with expression rows in the open document. Folder widens the view to the selected Co-work Folder's complete claim ledger, including claims expressed elsewhere and unconnected claims. Routine UI says Folder, not bare scope.

Available state filters are All claims, Facts, Proposed, Needs review, Challenged, and Unconnected. Claim detail leads with the exact proposition and a plain-language state, then passages, evidence, and the applicable decision. Source trust and preparation are explained beside the record they describe. History and record details keeps lifecycle history, separate status dimensions, structured metadata, and fingerprints available without competing with that decision. Preparation and human addition remain separate; an addition time does not stand in for an unavailable analysis time.

Passages groups connections by document, puts the open document first, and orders resolvable passages as they appear in that document. Missing or ambiguous locations follow deterministically. Each connection has its own Show in document action, and Next passage cycles through the same order. A passage in another document opens that document and reveals the selected passage once. Refresh can restore emphasis but never repeats navigation.

User jobs and staged workflows

Truth serves four user jobs:

1. Discover the checkable claims expressed by a passage or document.
2. Ground each claim in exact permitted evidence, including qualifying or contradictory passages.
3. Decide which prepared claim, expression, and evidence work should enter or change Truth.
4. Maintain affected Truth after prose, evidence, or claim foundations change.

The first slice and primary action is Analyze passage. AI uses one exact selected passage plus permitted surrounding context to select, disambiguate, and decompose atomic candidate claims, infer claim kind and expression role, match likely existing claims, and run bounded guarded web research when it would materially help assess a factual claim. Each run may issue three queries, admit five lead-only hits per query, and fetch only its own server-issued hit IDs. The user receives prepared cards rather than a verbatim copy in a manual form. Add claim manually and Connect selection manually stay available under Add or connect claim. When Analyze passage is unavailable, its reason is visible beside the controls. Analysis and claim creation are available from the claims list; claim detail retains its own decision flow.

The exact selected passage is capped at 32 KiB of UTF-8. Existing Truth context is capped at 32 KiB serialized, including at most 200 claims and 200 recorded support receipts under smaller claim and receipt sub-budgets; the complete worker context is capped at 90,000 bytes. Normalized output is capped at 80,000 bytes, 20 claim candidates, and 10 evidence candidates per claim. The selected account-model worker session has a provider-enforced $2.00 hard ceiling. Guarded web search and fetch are separate provider-dependent egress with no enforced monetary ceiling; their activity limits do not guarantee provider cost.

Later slices widen this contract to Analyze document, Find evidence, Build from source, and change-driven maintenance. Find evidence remains the dedicated claim-contextual research workspace for explicit source selection, steering, broader Folder and connected sources, and ongoing evidence management. Analyze passage reports what its bounded run actually searched, failed to search, or did not search from durable receipts; it does not pretend the later workflow or an unqueried source class already ran.

Review cross-listing

Review passively cross-lists the current document's proposed, challenged, and active needs-review claims under Truth needs attention. Activating an item opens that exact claim in Truth, where its evidence and applicable decisions are available. Review does not offer a separate claim decision bar. Ordinary confirmed facts and terminal history remain observable in Truth.

Truth owns the complete domain review for prepared claims, inferred expressions, evidence candidates and receipts, support assessments, conflicts, and lifecycle decisions. A compact analysis-ready handoff remains reserved and must not duplicate that workspace. Any prose correction prepared while grounding or maintaining a claim becomes an ordinary immutable proposal in Review.

The attention feed sits inside Review's existing scroll body and reads the same Truth provider as the domain panel. A claim decision refreshes that shared projection. The feed does not create a separate scroll region above Review or compress the proposal workspace.

Truth does not host edit proposals, Verify setup, Co-think controls, or a second conversation. Starting, steering, or explaining Truth analysis through Chat is a later extension, not part of the current Analyze-passage slice. That future path must carry the exact target and must not let conversational text accept a candidate or confirm a claim. Verify remains criteria checking; Truth analysis builds and maintains the claim-expression-evidence record.

Editor lenses

The editor lens is explicit view state:

• review projects proposals, flags, and evaluation-result anchors;
• provenance projects document source, authorship, human-review, and target-health treatments;
• truth projects expression anchors; and
• neutral projects neither persistent ledger overlay.

Review selects the review lens, Provenance selects the provenance lens, Truth selects the truth lens, and Chat selects neutral. Temporary Working on and Chat passage highlights remain independent. A lens switch replaces decorations only and clears incompatible focus; it never changes content, selection, scroll, or persisted document state. Truth marks distinguish current facts from claims that still need judgment through text, underline patterns, and glyphs. Stale connections have a separate treatment, and the legend explains the meanings and reports claims in view, facts, claims to judge, and unlocated passages. Terminal claims retain history in Truth without persistent editor marks.

Hover explains the proposition, state, and recorded evidence count and offers Open in Truth. It does not change the claim. Expanded text selection suppresses hover, and Escape, scrolling, focus changes, or leaving the lens dismiss it. Clicking a marked passage opens its claim detail. The shared Passage actions menu offers Truth actions for that exact passage; Show claim opens detail, while Confirm claim… and Reject claim… open the same staged decision used by detail. An unmarked selection can be analyzed, connected, or added through the same actions as the Truth header.

Selecting a claim card highlights all its located passages. When the editor is visible beside Truth and none of those passages is in its viewport, that click reveals the first passage in document order; when any passage is visible, the editor stays put. Passive selection and refresh only restore emphasis. Show in document and Next passage remain explicit navigation, including for terminal history through a temporary highlight when the exact passage still resolves. Missing or ambiguous passages report that they could not be located instead of jumping to a guessed range. On narrow screens, explicit navigation opens the Editor before revealing. A stale connection can still resolve: its warning asks the user to review the connection against the current document version rather than asserting that the passage disappeared.

Truth still explains provenance attached to Truth-domain records: who prepared or decided a candidate, how evidence was acquired, and what source occurrence a receipt retains. That does not make Truth the home for document-authorship and human-review attestations. Their exact coverage, supersession history, hover explanation, and Mark reviewed action belong to Provenance. The accepted boundary and overlay contract live at .data/designs/co-work/provenance-surface/README.md.

The Provenance list is deliberately non-navigating by default: selecting a row opens stable detail and may focus compatible decoration, while Show in document is the explicit one-shot reveal. Hover is passive and action-free. A changed-head span that reanchors uniquely remains inspectable but cannot be used for Mark reviewed; review requires an editor persistence barrier, a forced authoritative refresh, and one exact current head.

Modification authority and limits

Truth's primary creation workflow is Analyze passage. It creates one durable typed analysis run and stages prepared candidates in operational state outside the append-only Truth ledger. Each candidate binds the exact captured target and hashes, proposed proposition and kind, expression selector and inferred role, possible existing-claim match, available recorded support, and explicit ambiguity or limitations. Raw model prose is not a candidate until the server validates schema, identity, anchors, authorization, and output hashes.

No claim, expression, evidence receipt, or fact is created merely because AI prepared it. Accepting a new item calls the canonical operation to create a proposed claim and expression; accepting a match connects the passage to the existing claim. Manual connection records where a claim is expressed without editing prose or inventing support. The selected document passage remains an expression, not evidence.

Mutations call canonical Truth/Co-work operations. Agents may propose and humans retain confirmation authority over exact content and displayed context. That decision context includes lifecycle and review state, support and premise assessment, conflicts and derivations, source-integrity state, and prose connections as well as claim text and receipt rows. Any drift requires a fresh review, and a changed claim or decision context dismisses an open confirmation.

Only an exact human decision can confirm a claim. Editing a candidate changes the payload and requires a fresh binding. Surrounding context may resolve a reference but cannot silently widen the expression span. There is no Confirm all; each confirmed proposition has its own exact gesture.

Rejecting a proposed claim records that it was rejected without implying it had been a confirmed fact. Add a corrected claim starts the ordinary proposal form with the rejected proposition, kind, and passage role filled in. It captures the exact connected passage again and requires an explicit add; it neither edits prose nor rewrites the rejected claim's history.

Provenance keeps preparation separate from addition. Candidate output is AI-prepared and bound to its run, provider/model authorization, and hashes. A later Add as proposed or connection consequence is authored by the human who made that decision while retaining run and candidate metadata. A selected web source keeps its agent_run acquisition actor and external-quarantined origin; the person authors the support decision rather than laundering the acquisition as human-created.

Operational runs persist only prepared, launching, running, completed, unavailable, and failed; the UI projects the first two as queued and unavailable as failed. Every run has a thirty-minute execution deadline. An overdue active run is terminalized as failed with execution_deadline_exceeded, including when a worker-context read discovers the timeout. Candidates persist as pending, saved, or dismissed. Stale is a decision-time validation failure, not a stored candidate status: the server rejects the action and the person reruns analysis.

Worker submission returns only a compact receipt containing ok, schema wb.cowork.truth-analysis-submit-receipt/v1, analysis_run_id, public status, and output_sha256. Candidate content remains in the durable run projection; the receipt does not imply a Truth-ledger consequence.

Evidence research follows permitted sources from existing claim receipts to cited and Folder artifacts, configured connected sources, and the open web only when authorized. Analyze passage's current web seam persists lead-only search results, fetches only run-admitted hits, validates and pins every public HTTP(S) destination and redirect, permits only HTTP port 80 and HTTPS port 443, and preserves exact bounded text plus source, digest, acquisition, and truncation metadata in a run-owned receipt. Fetch is bounded to five redirects, twenty seconds total, ten seconds per request, and 512 KiB of identity-encoded response. Model-facing text is capped at 64 KiB; a partial capture records text_truncated, full and captured byte counts, and both full-extracted and captured-content digests. Keep source trust/integrity separate from the assessed relationship: supports, partially supports, contradicts, does not address, or inconclusive. Failure to find evidence is not contradiction, and a citation marker or search snippet is not a receipt. Only human-selected exact source passages become Truth-ledger evidence spans and support links; external acquisition retains actor/model, integrity, and quarantine provenance.

Analysis copy reports the actual provider, content egress, source boundary, fallback, and cost behavior. It never says work ran locally unless the executed authorization guarantees that fact.

Read-only mode still permits browsing, history inspection, and passage navigation while mutation controls explain why they are unavailable. Confirm and Reaffirm are validated against the exact lifecycle state in the same write transaction. Quarantined-only support remains observable, but this surface suppresses confirmation until a dedicated quarantine-override ceremony is designed.

Do not expose an unconditional six-verb claim bar. Challenge requires a supported conflicting claim; supersede requires a successor, relationship, and reason. The surface reserves those operations for their dedicated flows. Redaction is the narrow exception: it is destructive, so it appears only behind a dedicated warning, reason, and exact hash-bound confirmation. Expressions currently have no safe append-only unlink or retraction lifecycle, so the surface must not offer Remove connection.

UX invariants

Persist tab, This document/Folder selection, filter, and independent Truth scroll per full Folder and document identity. Restoration never replays passage navigation. Background refresh retains prior data and geometry; first-load failure offers Retry and is not rendered as an empty ledger.

List scroll is independent from transient claim details and selection forms. Entering a drill-in starts it at the top without overwriting the saved list position; returning restores the list. Scope and filter changes deliberately reset the new list to the top. Paginated backend reads are exhausted by the provider so Folder claims and connection candidates are never silently capped at the first page.

Analysis progress, prepared candidates, and review position survive refresh, tab changes, and sidecar restart without replaying editor navigation. A changed document or source is revalidated at decision time; when the exact target cannot be proven, the action fails as stale and the person reruns analysis. The server never silently rebases. Opening Truth or typing does not start a model or web search. Deterministic hashes, fingerprints, integrity, and dependency state first identify affected work; semantic re-evaluation remains an explicit bounded action.

Distinguish no document connections, an empty Folder ledger, and no filter matches. The four-item rail tablist uses roving keyboard focus with Arrow keys and Home/End and keeps every tab reachable at narrow widths. Claim cards retain semantic keyboard activation, nested controls do not also select the card, and status meaning never depends on color alone.

The accepted architecture and full acceptance contract live at .data/designs/co-work/truth-surface/README.md. The staged AI-assisted slices, typed candidate boundary, source rules, and initial vertical-slice acceptance live at .data/designs/co-work/truth-surface/ai-assisted-interaction-roadmap.md.