spec(phase-4): Cave surfaces data contract (threads-986.17.1)#1
Merged
Conversation
…shness, fail-closed rendering Written first per threads-986.17.1, before any UI code. OpenTrust MEMORY-API-CONTRACT shape (contract-first, freshness everywhere, evidence over summaries), coven-cave stack. Covers: read models (TensionView with UI-only unknown/stale fail-closed states, Weave/ Thread/Strand views, ward_audit row, PendingProposal), eight API routes (approve/reject as thin daemon-forwarders), response envelope (observedAt/staleAfter/sourceCursor), R1-R11 fail-closed rendering enumeration, metaphor-referent UI glossary. Co-authored-by: Sage <sage@opencoven.local> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
BunsDev
marked this pull request as ready for review
July 17, 2026 14:35
There was a problem hiding this comment.
Pull request overview
Adds the Phase 4 “Cave surfaces” contract spec that defines the read models, API routes, response envelope freshness metadata, and fail-closed rendering rules for the Coven Cave UI to consume daemon memory state (fixtures-first until daemon integration lands).
Changes:
- Introduces a new contract document (
PHASE-4-CAVE-SURFACES.md) describing sources of truth, adapters, and normalized UI-facing JSON read models. - Specifies the Phase 4 API surface (8 routes) and a uniform response envelope with freshness/verification metadata.
- Enumerates fail-closed rendering rules (R1–R11) and a glossary binding metaphor terms to referents for UI copy.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+108
to
+112
| { | ||
| "id": "weave-uuid", | ||
| "familiarId": "sage", // human-readable id, as ward_audit stores it | ||
| "threadCount": 4, | ||
| "tensionRollup": { "state": "frayed", "…": "worst contained thread state; §4.R1" }, |
Comment on lines
+187
to
+191
| "eventType": "proposal_submitted|proposal_approved|proposal_rejected|proposal_vetoed|ward_updated|validation_verdict|compaction_ledger", | ||
| "proposalId": "uuid | null", | ||
| "familiarId": "sage", | ||
| "wardVersion": "string | null", | ||
| "wardHash": "hex", // weave_hash at decision time — binds decision to authority state |
|
|
||
| | # | Route | Method | Returns | | ||
| |---|---|---|---| | ||
| | 1 | `/api/weaves` | GET | `WeaveSummary[]` — optional `?familiar=<id>` filter | |
BunsDev
added a commit
that referenced
this pull request
Jul 18, 2026
…uqx) Add substantive annotations from Sage and Echo review (2026-07-18): Decision #1: rationale callback — ApprovalPath is authoritative, Channel is derived; if enforcement rule shifts, revisit all eight decisions. Decision #2: audit implication — close event needs reason field (applied|vetoed|expired|superseded); delayed-apply without it is a post-hoc audit black hole. Decision #3: forward-only promotion — retroactive region projection corrupts authority trail with apparently-authored writes from before promotion. Decision #4: fail-closed on extraction ambiguity — not silent LLM fallback; ambiguity is an explicit ignored/blocked state. Decision #5: RFC provenance pointer added. Decision #6: Cave ProposalView labeled [DESIGNED, NOT SHIPPED] from the start. Decision #7: label-variant round-trip is daemon wire contract (load-time reject on drift); Cave has zero policy freedom over label strings. Decision #8: proposal_window_opened paired with close event; window is a first-class audit interval. threads-uqx.3 design constraints (Sage): evidence_replay_hash on ProposalClassification; VetoWindow.min_visible: Duration; label mapping as daemon wire contract. Co-authored-by: Sage <sage@opencoven.dev> Co-authored-by: Echo <echo@opencoven.dev> Co-authored-by: Nova <nova@opencoven.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 4 opening deliverable per bead threads-986.17.1 — the written contract between coven daemon memory state (weaves, tension,
ward_audit,~/.coven/pending/staged writes) and the Cave UI, written before any UI code.OpenTrust
MEMORY-API-CONTRACT.mdshape (contract-first, freshness metadata everywhere, evidence over summaries) — coven-cave stack, nothing vendored.Covers:
TensionView(crate's 3 states + UI-onlyunknown/stalefail-closed states),WeaveSummary/WeaveDetail,ThreadView,StrandView(+ Frayed current-vs-expected diff),AuditEntryView,ProposalViewobservedAt/staleAfter/sourceCursor/adapter/verifiedon every responseEpic: threads-986.17 · Phase 3 freeze verified (
.14,.11closed) · fixtures-first until.19merges.