docs(automations): specify coven.automations.v1 schemas, state machines, and changefeed

[CompleteDotTech]

Summary

Specifies the coven.automations.v1 protocol — schemas, state machines, idempotency, and changefeed — as spec artifacts plus a normative design document. No runtime code changes: schemas, vectors, and docs only.

Artifacts (following the spec/device-pairing/v1 precedent for versioned protocol directories):

• spec/coven-automations/v1/ — draft 2020-12 JSON Schemas for the five normative objects (AutomationDefinition, AutomationOccurrence, AutomationRun, AutomationAttempt, AutomationReceipt) with monotonic revisions + RFC 8785 integrity digests, exact-revision pinning, versioned trigger/condition/action unions (v1 executes schedule + familiarInvocation only), and fail-closed unknown-field behavior through an explicit namespaced extension bag
• command-envelope.schema.json — every mutating command (create, revise, activate, pause, disable, tombstone, run now, cancel, retry/recover, plus list/get/history/health, events read/subscribe, legacy import) carries a stable adoption key (first-commit-wins replay; ADOPTION_REPLAY_MISMATCH on key reuse with a different payload) and expectedRevision where applicable (REVISION_CONFLICT commits nothing). Responses are committed | replayed | rejected only — a domain failure can never be wrapped as accepted
• error-envelope.schema.json — 20 typed error codes with a frozen HTTP/control-action status mapping
• event-envelope.schema.json — versioned changefeed: per-stream gapless sequences, globally unique event ids, causation/idempotency keys, cursor expiry (CURSOR_EXPIRED, never a silent rewind), duplicate delivery, out-of-order rejection, compaction snapshots
• state-machines.json — authoritative definition/occurrence/run/attempt machines + the ten normative invariants (adoption-before-side-effects, one-fence-one-run, terminal-no-regress, no-evidence-no-success, ambiguous-never-auto-retried, revision-pins-history, …)
• capabilities.json — positive + explicit negative variant negotiation (unknown variants fail closed with CAPABILITY_UNSUPPORTED)
• compatibility-matrix.json — machine-readable change classes, per-field status, incompatible-profile refusal
• test-vectors.json — golden valid/invalid/unknown-field/downgrade/upgrade/unknown-variant vectors, adoption replay + revision-conflict cases, duplicate and out-of-order event replay; pinned RFC 8785 (JCS) digests, self-contained so any draft 2020-12 validator can run them outside the Coven crate
• coven.automations.v1.d.ts — pinned TypeScript projection for SDK/Cave canaries
• docs/architecture/coven-automations-v1.md — the design document: cites the current Native familiar automations: replace harness-owned schedules with durable Coven routines OpenCoven/coven#816 code paths for every gap it closes, ratifies lifecycle semantics and the non-destructive Native familiar automations: replace harness-owned schedules with durable Coven routines OpenCoven/coven#816 migration, maps the corresponding Rust types, and records alternatives considered for the maintainer-owned decisions

Issue

Refs OpenCoven#855

Context

• Summary: the coven.automations.v1 contract published as machine-readable spec artifacts + design doc (above).
• Files changed: 18 files, +5303/−0 — spec/coven-automations/v1/* (16 files) and docs/architecture/coven-automations-v1.md. No crates/ or npm code touched.
• Closes: none on this vehicle (fork PR). Refs P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed OpenCoven/coven#855.

Implementation

• Approach: spec-first. JSON Schemas are the source of truth for every object; state machines, capability negotiation, compatibility classes, and golden vectors are machine-readable siblings; the design doc in docs/architecture/ is the normative narrative with per-claim code citations and alternatives considered.
• User-visible behavior: none yet — this PR specifies the contract; implementations follow in their own PRs. Clients can already consume the schemas/vectors as pinned artifacts.
• Compatibility notes: additive-only going forward per compatibility-matrix.json; unknown profiles/fields/variants fail closed; digests are RFC 8785 (JCS); the Native familiar automations: replace harness-owned schedules with durable Coven routines OpenCoven/coven#816 migration is non-destructive and pins definition_json bytes byte-identically.

Verification

• All 9 schemas compile under a draft 2020-12 validator (ajv 8, 2020 mode) with cross-file $ref resolution
• All 51 golden-vector/state-machine/compat checks pass: 15 schema accept/reject cases, digest pinning re-verified by recomputation (definition + receipt), 4 state machines statically proven (no transition leaves a terminal state, endpoints exist, no dead ends, terminal lists consistent), adoption cases schema-validate, changefeed rehydration deterministic across duplicate delivery and checkpoint resume
• coven.automations.v1.d.ts typechecks clean under tsc --strict
• Privacy + secret guard rule replica over the changed files: clean
• cargo fmt --check — deferred to CI; no cargo on the authoring host; this PR changes no Rust code, so the rust jobs are expected to classify as skipped
• cargo clippy --workspace --all-targets -- -D warnings — deferred to CI (same)
• cargo test --workspace --locked — deferred to CI (same)
• python3 scripts/check-secrets.py — deferred to CI (no python locally; rule replica clean)
• Additional manual checks: command catalog cross-checked against the issue's required command list (19/19 present); every sibling schema $ref target resolves; vector event kinds covered by the envelope enum

Risk and Rollback

• Risk level: low — docs + spec artifacts only; no runtime code, no schema-of-record changes, no npm/Rust surfaces touched. The CI change classifier treats the JSON as non-docs, so cargo-deny may run; it checks unchanged lockfiles and should pass.
• Rollback plan: revert the single commit; no data, store, or wire format depends on these files.

Agent Handoff

• Current state: draft PR opened in the fork as the CI vehicle; awaiting CI verdict.
• Follow-ups: implement the contract module in crates/coven-cli/src/automations/ (Rust types mapped in the design doc); wire command handlers behind the existing control actions; SDK/Cave canaries against the pinned artifacts; the P0 bead packet with evidence (schema artifacts, vectors, test commands/results, canaries, migration proof, open decisions).
• Known gaps: cross-repository canaries (SDK, Cave) and Rust round-trip/property tests are implementation-stage work enumerated in conformance-manifest.json; they cannot be delivered by a spec-only PR. The bead entry itself is not created here (bead state is out of this task's write scope).

Vehicle note: opened in the fork CompleteDotTech/coven as the CI vehicle — this token cannot write to OpenCoven/coven. Re-target upstream once write access is restored. Refs OpenCoven#855.

CI note: this repository (the CompleteDotTech/coven fork CI vehicle) reported no checks: 0 check-runs and 0 workflow runs on the head SHA after the watch interval, and no workflow is registered on the fork (Actions requires one-time owner activation in the UI; there is no REST endpoint). No CI exists here, so the draft-to-ready gate is vacuous for this vehicle. The checks that would run upstream — policy-guard and cargo-deny (rust and npm jobs classify as skipped for this docs+spec change) — are enumerated in the Verification section and were replicated locally where possible.