coven-threads

Status (2026-09-11): Engineering phases 0–4 remain frozen. Phase 5 is active, with four unresolved remediation gates and independent Nova/Val decisions outstanding. Baseline protection now enforces reviews and four existing checks on main; required pinned-daemon acceptance is still missing. Coven v0.4.3 includes the earlier integration, not proof of full Phase-5 conformance. Start with the delivery strategy, evidence ledger, and readiness review. License: the committed LICENSE and Cargo package metadata specify MIT. The frozen design retains an older Apache-2.0 plan; reconciling that historical text requires a maintainer decision, not an inferred license change. Owners (design phase): Sage 🌿 + Echo 🔮 co-drive; Nova 👑 + Sage on lane assignments; Cody ⚡ Phase 1+ crate lane

---

What this is

coven-threads is OpenCoven's protected-authority validator, imported inside the trusted coven daemon. Threads defines typed validation contracts; the daemon owns authentication, protected writes, persistence, and recovery.

In the vocabulary of the Familiar Contract (RFC-0001) and the Ward v0.2 spec: this is the gate-shaped receiver on which Ward's four validation gates sit. Ward specifies what the gates check; coven-threads specifies how they are enforced, by an authority outside familiar cooperation.

It defines validator contracts for RFC-0001 §5. RFC wins on any conflict with this repository. Full daemon conformance remains subject to the unresolved boundary findings in the delivery ledger.

Gate 4 fail-closed is a line-one conformance property, not a hardening milestone: an implementation that allows Gate 4 to be bypassed does not conform to RFC-0001 (§5.4).

Documentation

User-facing docs live in docs/:

• Concepts — the vocabulary (Thread, Weave, Strand, Channel), the two-compaction contract, the descriptor-vs-predicate anti-pattern. Read this first.
• Architecture — where this layer sits, the enforcement flow, the ward.audit store.
• Authority model — fail-closed, the three verdicts, the tension state machine.
• Automation Authority Profile — operation-specific permit / approval / proposal / reject decisions, replay-safe approval evidence, and portable vectors.
• Channels and strands — the four channels, the five strand kinds, WARD-C1–C7.
• Phases — what is frozen, what is implemented, what is active, what is blocked.
• Delivery strategy: ordered workstreams, owners, acceptance evidence, and release gates.
• Readiness review: the dated documentation audit and engineering recommendations for #13, #31, #40, and #46.
• FAQ · Glossary

The frozen design doc is specs/PHASE-0-DESIGN.md; the docs describe it and never amend it.

The versioned Automation Authority Profile is specs/AUTOMATION-AUTHORITY-PROFILE-v1.md, with closed schemas, a Node-core reference validator, and its mandatory exact conformance manifest under profiles/automation-authority/v1/. Threads defines the authority decision; Coven still owns scheduling, persistence, final dispatch, and effects.

Why this is not just "OpenTrust"

The coven daemon already ships an authority boundary — untrusted clients speak over a unix socket to a trusted Rust daemon that revalidates every sensitive request. That boundary is real, documented in coven/docs/SAFETY-MODEL.md, and works.

Threads supplies the typed protected-surface question alongside who may act and what action exists. The daemon imports this validator; Threads does not replace its trust boundary or own filesystem and persistence effects. The remaining work is complete route, predicate, and replay enforcement, not the absence of any integration.

This historical diagram includes a staging branch that must not be read as protected-write authority. The current contract rejects proposals touching protected surfaces; see the authority model.

The weaving metaphor

The architecture is named around the metaphor of weaving because the metaphor does load-bearing work, not because it sounds pretty. Every term is bound to a concrete referent at first use (design doc §2.5); the referents below are the frozen v0.2 bindings:

• Thread (authority relationship: surface → writer) — a directional line from a protected surface (SOUL.md, MEMORY.md, an identity field) to the authority that gates writes to it. One thread per (surface, writer) pair. Threads have tension: they hold, fray, or snap under load.
• Weave (enforced pattern of threads across a familiar or Coven) — the invariant that these specific threads must all hold together for the identity to be coherent. Ward's four gates are the loom the weave is made on — the fixed structure threads run through — not threads themselves.
• Strand (fiber inside a thread: hash | signature | manifest entry | audit trail | serialization marker) — the fibers that make a thread survive stress. A thread survives a channel iff its strands survive that channel; a thread frays when a strand fails, which is what makes failure legible.
• Channel (axis of load a thread must hold under) — Deliberate, Forced, Serialization, Mutation. Every gate check is one question: does thread T hold under channel C?

Design intent of the metaphor: a familiar's identity is not a single object protected by a single gate. It is a woven structure of typed protected surfaces with distinct authority relationships. The metaphor makes the multi-surface, multi-authority reality of the architecture visible instead of collapsing it into "protect SOUL.md."

The four invariants this layer must preserve

Co-designed as channels a weave must survive, not stacked as features (design doc §3.3):

1. Identity-as-memory-property — the identity surface is a typed layer of memory, not a runtime configuration; threads bind to typed surfaces at construction time.
2. Structural mutation authority — the gate is external to the familiar; the familiar cannot cooperate its way past it. Enforcement is Rust-side, daemon-called.
3. Two-compaction contract — deliberate memory compaction (dreaming) and forced context compaction are distinct channels with distinct survival requirements; WARD-C1–C6 govern the forced channel.
4. Survives serialization (WARD-C7) — the authority contract must round-trip across export/import, or fail visibly. Numbered seventh so its lineage from C1–C6 stays legible; canonical home for C1–C7 jointly is the coven-grimoire Ward Layer Spec Brief §9.

These are non-negotiable and must be co-designed, not stacked — the Channel enum is where the type system holds them together.

Phase plan

Honest labels; the detailed ledger is docs/phases.md.

• Phase 0 — design doc + beads scaffolding + repo skeleton. ✅ FROZEN v0.2 (2026-07-14, tag v0.2-phase0-design). Nova sign-off; RFC-0001 §5 round-trip verified. No enforcement code, by design.
• Phase 1: core crate. [FROZEN; IN RELEASE TAG]. coven-threads-core provides typed validation and conformance vectors. Coven v0.4.3 imports revision c102844; it does not automatically test this checkout. threads-986.18 is closed.
• Phase 2: daemon integration. [FROZEN; IN RELEASE TAG]. Contracts in audit.rs and staging.rs are consumed by the integration from OpenCoven/coven#382. Beads .14, .20, and .19 are closed; later proposal-route defects remain Phase-5 blockers.
• Phase 3 — portability contract. C7 round-trip semantics implemented and tested (portability module + 17-test round-trip suite); the interchange envelope is decided (threads-986.16 closed): Shape B (.weave) canonical, plus a lossy one-way .af exporter — see the §6 decision record in specs/PHASE-3-PORTABILITY.md.
• Phase 4: cockpit integration. [COMPLETE; FROZEN 2026-07-17]. The weave rail, thread pane, strand inspector, and proposal flow landed in OpenCoven/coven-cave#3223 with the recorded human gates. The daemon-adapter follow-up (threads-v3g) and degraded-familiar follow-up (threads-k9s) are also closed. New Phase-5 live-daemon acceptance remains separate.
• Phase 5: approval semantics. [ACTIVE], not frozen. ApprovalPath and Channel remain independent; delayed apply requires live evidence replay and exactly one typed terminal close. The earlier core, scheduler, Cave contract, RFC alignment, and corpus implementation beads are closed, but threads-okc, threads-980, threads-dgg, and threads-zav remain unresolved. OpenCoven/coven#931, OpenCoven/coven#932, and OpenCoven/coven#933 are draft checkpoints, not closure proof. Nova coherence sign-off (threads-uqx.9) and Val freeze (threads-uqx.10) remain human gates.

Anti-goals

• Not a general-purpose policy engine. This is a typed authority layer for OpenCoven familiar surfaces. Reusability is a nice-to-have; typed correctness is the goal.
• Not a runtime implementation. Threads owns the .weave portability contract and lossy one-way .af export. Coven owns runtime adoption and effects; an imported artifact grants no authority by itself.
• Not .af-compatible. Documented divergence, source-verified 2026-07-14: Letta's CoreMemoryBlockSchema has no protection field and runtime read_only is stripped at export — silent downgrade on import is exactly what WARD-C7 refuses. See docs/faq.md.

Related

• coven/docs/SAFETY-MODEL.md — authority boundary this layer sits on
• familiar-contract/rfcs/RFC-0001-familiar-contract.md — the contract this layer enforces (RFC wins on conflict)
• coven-grimoire Ward Layer Spec Brief §9 — canonical home of WARD-C1–C7
• research/synthesis/memory-layer-comparison-opencoven-openclaw-hermes-2026-07-13.md — comparative context

---

First commit: 2026-07-14. Repo scaffolded in Phase 0 evening session with Val's greenlight.