P1: Add constrained Coven Automations SDK types, subscriptions, verification, and authority-aware commands

[BunsDev]

Cross-repository program: OpenCoven/coven#854
Core protocol: OpenCoven/coven#855
Authority integration: OpenCoven/coven#857
Certification: OpenCoven/coven#858

Outcome

Expose Coven Automations through a constrained, typed SDK that consumes canonical versioned artifacts, observes one Coven-owned truth, verifies receipts independently, handles replay/reconnect deterministically, and never infers authority from client state.

Ship read/verify/subscribe support before broad mutation. Authority-bearing commands may graduate only after the core protocol and authority profiles are stable and the SDK passes immutable cross-repository conformance.

Canonical boundary

The SDK owns:

• generated/pinned public types;
• transport-neutral client ergonomics;
• typed command, query, event, and error handling;
• reconnect/cursor/replay behavior;
• independent receipt and binding verification helpers;
• constrained authority-aware proposal/approval command construction;
• compatibility negotiation and client-side validation that does not replace server validation.

The SDK must not own:

• automation persistence, scheduling, occurrence planning, run transitions, or leases;
• familiar identity or authority decisions;
• client-authored approval, success, running, or health state;
• direct SQLite/Coven-home access;
• silent fallback to Cave routes, Codex files, or direct runtime execution.

Phased public surface

Phase 1 — read, verify, subscribe

Publish stable APIs for:

client.automations.capabilities()
client.automations.list(options?)
client.automations.get(automationId)
client.automations.health(automationId)
client.automations.occurrences(automationId, options?)
client.automations.runs(automationId, options?)
client.automations.getRun(runId)
client.automations.getReceipt(receiptId)
client.automations.verifyReceipt(receipt, trustContext)
client.automations.subscribe({ after, filters, signal })

Requirements:

• types are generated from or mechanically checked against coven.automations.v1 artifacts;
• pagination and cursors are explicit;
• subscriptions tolerate duplicate delivery and reconnect using canonical event IDs/sequences;
• stale/degraded/unavailable states remain explicit;
• unknown enum/variant behavior follows capability negotiation rather than unsafe coercion;
• receipt verification returns structured verified/degraded/unverifiable/invalid results;
• read projections respect principal authorization and privacy classes.

Phase 2 — low-risk lifecycle commands

After #855 adoption/idempotency semantics are certified:

client.automations.createDraft(input, commandContext)
client.automations.revise(id, expectedRevision, patch, commandContext)
client.automations.pause(id, expectedRevision, commandContext)
client.automations.activate(id, expectedRevision, commandContext)
client.automations.disable(id, expectedRevision, commandContext)
client.automations.tombstone(id, expectedRevision, commandContext)

Every mutating command requires:

• stable adoption/idempotency key;
• authenticated principal context supplied through the configured transport/session, never raw credentials in the object;
• expected revision where applicable;
• explicit intent/origin and optional correlation;
• abort/cancellation signal;
• typed adopted/completed/rejected/conflict/unknown-outcome result.

A timeout after adoption must not invite blind retry with a new key; expose a lookup/reconcile path.

Phase 3 — run, cancel, retry, approval

Graduate only after #857 and #858 pass:

client.automations.runNow(id, options, commandContext)
client.automations.requestCancel(target, reason, commandContext)
client.automations.retry(target, expectedDisposition, commandContext)
client.automations.requestApproval(target, commandContext)
client.automations.approve(approvalId, decision, commandContext)
client.automations.reconcile(target, commandContext)

Rules:

• the SDK constructs requests; Coven/Threads decide authority;
• approval helpers bind exact action/definition/familiar/runtime/capability digests;
• retry refuses unsupported, ambiguous, unauthorized, or stale dispositions client-side and server-side;
• cancellation remains a request until authoritative acknowledgement/reconciliation;
• no convenience API converts a proposal, acceptance, or transport success into run success.

Type and module layout

Suggested shape, adapted to the SDK’s actual language/package structure:

src/automations/
  client.ts
  queries.ts
  commands.ts
  subscriptions.ts
  verification.ts
  capability-negotiation.ts
  errors.ts
  transport.ts
  generated/
    v1/
  index.ts

conformance/automations/
  vectors/
  canary.test.*

Generated files must declare provenance, source artifact revision/digest, and regeneration command. Hand-authored ergonomic wrappers stay separate from generated contract types.

Error model

Expose typed errors/results for at least:

• invalid request/schema;
• unauthenticated/unauthorized;
• approval required/rejected/expired/revoked;
• revision conflict;
• adoption conflict/duplicate;
• unsupported capability/profile/variant;
• not found/tombstoned;
• stale identity/authority/runtime descriptor;
• daemon unavailable/degraded;
• rate/backpressure limit;
• cancellation requested/acknowledged;
• timeout;
• recovery required/ambiguous outcome;
• receipt invalid/unverifiable;
• cursor expired/replay required.

Transport, command-adoption, domain, and verification failures must be distinguishable.

Subscription/replay contract

• maintain one consumer cursor per explicit subscription context;
• deduplicate by canonical event ID/stream sequence;
• refuse state regression or impossible transition in local projections;
• support reconnect from a retained cursor and explicit snapshot/reset when a cursor is expired;
• expose event lag/staleness metadata;
• never synthesize missing success events;
• cancellation/abort stops the client stream without mutating the automation;
• bounded buffers and backpressure prevent memory growth.

Provide a reference reducer for convenience, but document that it is a projection of Coven events, not an alternate authority.

Verification helpers

Provide deterministic helpers for:

• contract/schema version support;
• canonical definition/event/receipt digests;
• familiar embodiment binding verification using pinned Familiar Contract artifacts;
• Threads decision/approval evidence verification using pinned profile artifacts;
• runtime descriptor/capability binding verification;
• receipt integrity/authentication and artifact/delivery digest checks;
• privacy-aware disclosure of why verification is degraded or impossible.

Trust roots and verification policy must be caller-configured or obtained through an authenticated Coven profile; do not embed environment-specific secrets.

Security and ergonomics

• never accept raw bearer tokens/credentials inside automation definition objects;
• redact secrets and sensitive prompts/paths from errors/logs;
• validate size/count bounds before transport;
• use abort signals and explicit timeouts;
• default create/import helpers to paused/draft;
• require explicit activation and risk/capability intent;
• make potentially destructive or external commands visually/API-distinct;
• provide safe builders for schedule/action/policy objects without hiding normative fields;
• avoid methods named success, approve, or retry that can be mistaken for local state mutation.

Compatibility

• publish a machine-readable supported-contract matrix;
• pin exact producer artifact revisions in tests/releases;
• unknown additive fields are preserved or ignored only according to the core contract;
• unknown trigger/action/policy variants return explicit unsupported capability;
• packed package tests must not rely on monorepo/source-relative imports;
• support deprecation windows and negative tests for incompatible versions.

Verification

• generated-type drift check;
• all core valid/invalid golden vectors;
• query/pagination/cursor tests;
• duplicate/out-of-order/reconnect subscription tests;
• command adoption/replay/conflict/unknown-outcome tests;
• approval/retry/cancel safety tests;
• receipt/binding/authority verification and tamper tests;
• privacy/redaction tests;
• daemon unavailable and partial response tests;
• package tarball/install/import tests;
• immutable canaries against exact Coven, Familiar Contract, Threads, and runtime artifacts.

Integrate with:

./scripts/agent-bootstrap
./scripts/agent-check fast
./scripts/agent-check full

Acceptance criteria

• SDK types are generated from or mechanically checked against pinned coven.automations.v1 artifacts.
• Read/health/history/receipt and replay-safe subscription APIs ship first.
• Receipt, familiar binding, authority, and runtime evidence can be independently verified.
• Mutations use adoption keys, expected revisions, typed outcomes, and no blind retry.
• Approval/retry/cancel APIs remain gated until #857/#858 conformance passes.
• SDK never reads/writes Coven SQLite, Codex files, Cave-local state, or runtime processes directly.
• Packed package and immutable cross-repository canaries pass.
• Security, privacy, redaction, and compatibility behavior is documented and tested.

Non-goals

• Reimplementing the scheduler or maintaining an offline authoritative run ledger.
• Inferring principal authority or familiar identity from strings.
• Offering broad unattended external-action convenience methods.
• Hiding recovery-required or degraded states behind automatic retries.

Bead packet

Create one P1 SDK Bead mapped exactly to this issue. Phase 1 depends on OpenCoven/coven#855 and blocks interoperability certification. Authority-bearing phases depend on OpenCoven/coven#857 and #858. Evidence must include generated artifact provenance, package tests, replay/verification vectors, exact cross-repository pins, and supported-contract matrix.

[BunsDev]

Reviewed against the current SDK 0.1 dependency chain. This work is intentionally post-0.1 and is not safe to implement before the canonical producer contracts exist:

• Phase 1 is blocked by P0: Specify coven.automations.v1 schemas, state machines, idempotency, and changefeed coven#855 (coven.automations.v1).
• Authority-bearing phases are additionally blocked by P0: Bind automation runs to principal authority, familiar revisions, capabilities, approvals, and receipts coven#857 and P0: Build automations conformance, chaos, SLO, and operator diagnostics coven#858.
• The roadmap now records those gates via docs(roadmap): track automations SDK dependencies #86, merged as a918f854ebb47691c383c940e702399d3f230aa8.

The requested P1 Bead could not yet be persisted: the repository Beads database is at schema v49 while the installed CLI requires v53, and the remote-backed migration gate requires an explicit single-migrator vs. adopt decision. No database migration or JSONL-only workaround was performed.

[BunsDev]

Exact-artifact canary slice started for OpenCoven/coven#855.

Pinned producer evidence:

• source commit 8a796807b37d4ad33eaeca37498debf1ca55dd49
• CI artifact ID 9909975069
• bundle SHA-256 512460db71d4257d7a4d33ea306578e66d9ac499d9384eb9c2b8e2b4e2e32363
• contract content SHA-256 3c145eb92a93426ed64631f6487a8cd12903b0a49a6e752269f594ac50a779f5
• 17 manifest files

Implementation is isolated on test/80-automations-artifact-canary and will require explicit archive/digest inputs, verify the immutable bundle independently, typecheck the pinned declaration, and exercise duplicate/out-of-order/reconnect changefeed vectors without a source-relative Coven import.

[BunsDev]

Exact-artifact consumer canary PR opened: #106 at 46c1d16c2b4f8eaf23d527b94076c6221c569b3e. It pins and independently verifies Coven artifact 9909975069, reproduces exact source-bound bytes in normal CI, authenticates live producer evidence while retained, and rejects vectors that omit real duplicate or resume-after-cursor semantics. Fresh local evidence: focused 37/37, exact artifact and live evidence passed, full SDK verify passed 1,520 tests with 2 skips plus coverage/package/stress/lint, and staged secret scanning passed.

[BunsDev]

Phase 1 exact-artifact canary merged via #106 at 942aaea71bc025f80089a743f14b10d7fa9df871. The SDK now independently validates artifact 9909975069, exact source 8a796807b37d4ad33eaeca37498debf1ca55dd49, bundle SHA-256 512460db71d4257d7a4d33ea306578e66d9ac499d9384eb9c2b8e2b4e2e32363, content SHA-256 3c145eb92a93426ed64631f6487a8cd12903b0a49a6e752269f594ac50a779f5, all 17 manifest files, declarations, and duplicate/out-of-order/reconnect vectors. The merged-main CI run 33823935413 passed both Node 24 verification jobs. This completes the immutable base-artifact canary, not the remaining read/verify/subscribe and authority-aware SDK phases tracked here.

[BunsDev]

Dependency checkpoint: the immutable artifact canary remains complete via #106, but the next public read/verify/subscribe implementation slice is still blocked by the canonical producer contract: OpenCoven/coven#855 remains open. Authority integration OpenCoven/coven#857 is now closed, while certification OpenCoven/coven#858 remains open for later authority-bearing phases. No SDK API surface is being guessed ahead of the canonical contract; work is moving back to the independently actionable #38 release gate.

[BunsDev]

OpenCoven/coven#939 pins SDK revision 160864ad61ef and confirms the shipped Automations support is currently the immutable artifact canary, not live getReceipt, verifyReceipt, or subscription APIs. This issue remains the typed retrieval and independent-verification owner after OpenCoven/coven#858 publishes certified producer/read artifacts.

[BunsDev]

Refreshed dependency scope: OpenCoven/coven#855 explicitly reports its remaining gate as the Cave exact-artifact consumer canary, not unfinished schema design. The SDK artifact canary remains complete via #106. The preserved Cave implementation is still uncommitted because its mandatory commit metadata policy conflicts with the required automated co-author trailer; no hook bypass has been used. OpenCoven/coven#857 and OpenCoven/coven#858 are currently open, so the earlier closed-#857 checkpoint is no longer current. Public retrieval/verification/subscription and later authority APIs remain unshipped and are not credited as complete.