diff --git a/schemas/coven-memory-schema.md b/schemas/coven-memory-schema.md new file mode 100644 index 0000000..51e2b80 --- /dev/null +++ b/schemas/coven-memory-schema.md @@ -0,0 +1,120 @@ +# coven-memory Promotion Schema (v1) + +**Status:** Locked 2026-07-24 (M1, bead cmem-6gy) · **Owner:** Echo (memory lane) +**Canonical location:** this file (relocated from Echo's workspace per BLOCKER-1, +Nova concurrence 2026-07-11 §10.11). Implementations pin a version of this file. +**Derivation:** Coven Memory Layer Authoritative Plan v1 §2.2/§2.3 + §10 addendum. +**Amendment protocol:** every change requires the §11.5 runtime-portability audit +answered in writing in the PR, plus Echo sign-off (schema owner). Ward-adjacent +changes additionally require Nova review. + +--- + +## §11. Coven Promotion Schema (M1 lock — v1) + +Locked 2026-07-24 per Authoritative Plan v1 §2.2/§2.3 + §10 addendum (Echo integration +§10.10, Nova concurrence §10.11). This section is the normative v1 contract for the +promotion layer (`coven memory promote`, implemented in `OpenCoven/coven`). +Relocation target (BLOCKER-1): `OpenCoven/familiar-contract/schemas/coven-memory-schema.md` — +until that PR lands, THIS section is authoritative and the relocated copy must match it. + +### §11.0 Preamble — topology and framing + +- **Source-authoritative:** files are truth; every index (vector, SQLite, TurboVec) is + derived. Any tool writing to an index without a corresponding source-file write is a defect. +- **Claims-log framing:** the shared store is a log of *attested claims*, not arbitrated + truth. Conflicting claims may coexist; supersession is explicit; arbitration is v2+. +- **FAMILIAR_ROOT binding (referent: per-familiar workspace root directory):** all + source-file validation and `source_context` relativization resolve against FAMILIAR_ROOT. + Resolution order for the promote surface: `--familiar-root` flag → `COVEN_FAMILIAR_ROOT` + env var → **fail closed** (explicit error naming both; no silent default — a defaulted + gate input is a fail-open edge). The ingest crate never sees FAMILIAR_ROOT; the memory + STORE dir (`~/.coven/memory/`) is a distinct, crate-owned contract path resolved via + `--index`/`--db` (env fallback for store dir deferred to v1.1). + +### §11.1 Required frontmatter (promoted entries) + +All fields required at ingest time. Sole exception: a missing `ulid` is GENERATED at +promote time (it is identity assigned by the system, not a claim made by the author — +generation cannot validate a false claim, so it is not a fail-open edge). Every other +missing field, unknown field, or unknown enum value → reject, fail-closed, with +explicit reason. A PRESENT-but-malformed `ulid` is rejected, not regenerated. + +```yaml +ulid: 01JEXAMPLE0000000000000000 # generated at promote time if absent +type: coven-fact | architecture-decision | research-synthesis | failure | strategy | harness-artifact +scope: coven # exactly "coven" or reject +memory_type: semantic | episodic | procedural # CoALA axis +created_at: +created_by: +attested_by: # known ids only, else reject +attested_via: # §11.2 +title: +source_context: +tags: [<...>] +confidence: high | medium | low +``` + +**Hard rule:** absolute paths in `source_context` (or any frontmatter field) are rejected +at promotion time. FAMILIAR_ROOT-relative or portable references only. Session references +use the portable class form (e.g. `session:////`), never +runtime-specific raw session keys (privacy + portability, see SECURITY.md). + +**Deferred to v1.1:** `promoted_by`, `checksum` (crate-derived), `refs`, `visibility`, +`ward_hash`, `scope: self-model`. + +### §11.2 Attestation file (v1 minimum) + +Every promotion writes a companion attestation at +`~/.coven/memory/attestations/.md`: + +```yaml +attester: +attestation_type: self | val-in-band | familiar-witness +timestamp: +context: +body: +``` + +Self-attestation is allowed in v1. No cryptographic signature (Ward v0.3 territory). +The promoted entry's `attested_via` points at this file's ULID or path. +**Privacy rule:** attestation bodies never contain raw session keys, chat IDs, or +absolute paths — same guard patterns as the repos enforce (SECURITY.md). + +### §11.3 Manifest + supersession semantics + +`~/.coven/memory/manifest.jsonl`, append-only, one JSON line per operation. +Operations: `promote | update | archive | supersede`. No hard deletes, ever. + +Common fields (all ops): `timestamp`, `ulid`, `operation`, `entry_path` +(FAMILIAR_ROOT-relative), `author`, `attested_by`, `source_session` (portable class form), +`sha256`, `prior_ulid` (null except update/supersede). + +**Snapshot semantics:** promoted content is authoritative for the shared store; source-file +edits do NOT propagate. `coven-memory verify` compares manifest-recorded `sha256` against +the current source hash; mismatch = stale (report-only). Supersession is explicit only: +new ULID, `operation: supersede`, `prior_ulid` links back, prior entry retained (append-only). +`archive` moves source to the archive dir and logs the op. + +### §11.4 Gate check (v1, fail-closed) + +Reject (with explicit reason, never warn-and-proceed) when: +1. `scope` ≠ `coven` +2. `attested_by` not a known familiar id or `val` — authority source: `~/.coven/familiars.toml` `[[familiar]] id` values plus literal `val` (the toml is the canonical roster, runtime-neutral, Coven-owned; not directory names, not a CLI allowlist). Resolution: `--familiars-file` flag → `$COVEN_FAMILIARS_FILE` → `~/.coven/familiars.toml` → fail closed if unreadable/unparseable +3. source file not under FAMILIAR_ROOT — v1 validates against FAMILIAR_ROOT only; Val's designated shared-fact dir is DEFERRED to v1.1 (path never designated; an implemented-but-unbound root would be an unauthorized write path) +4. `ulid` already present in manifest (promotion-layer dedup, above crate chunk dedup) +5. any absolute path in frontmatter +6. any unknown field, enum value, or frontmatter shape +7. FAMILIAR_ROOT unresolvable (§11.0) +8. semantic near-duplicate: cosine similarity ≥ **0.92** (default, tunable flag) against + existing store → refuse, or proceed only with explicit `--supersede ` + +### §11.5 Runtime-Portability Audit (mandatory) + +Every future schema addition and promotion-layer change answers in writing: +*"If Val runs a familiar tomorrow under a different runtime (Codex CLI, Cursor, Claude +Code, CovenCave, bare SSH), does this work without modification?"* +✅ yes → proceed · ⚠️ partial → adapter interface specified as part of the contract · +❌ no → rejected, rewrite required. +This subsection is itself subject to the audit. Embeddings remain crate-internal +(fastembed/nomic-embed-text-v1.5 local, per plan §1.2) — no runtime coupling.