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

[BunsDev]

Delivery checkpoint — 2026-09-21 UTC

Read surfaces are delivered by #251 (capabilities), #254 (definitions), #256 (health), #259 (run history), #261 (occurrence inspection), #265 (receipt reads), and #266 (Windows parity and client integration).

#300 now delivers bounded events() and demand-driven subscribe() pages for canonical automation, occurrence, and run streams, pinned to Coven aa28d994965a83c0dfba8eaca071e182d605fed1. Merge dd07e1d455565f6ca6099c2eee0f4d14c834d5cd has a verified signature and the exact reviewed tree. All PR and merged-main checks passed; the pinned hosted verifier passed 2,796 tests in both normal and coverage runs, packed consumers, stress tests, typecheck, and lint. Independent spec and quality reviews are clean. No retry, polling, prefetch, implicit cursor reset, or mutation authority was added.

#304 delivers local receipt integrity and seven explicit caller-supplied identity bindings, with optional digest-reference comparisons. Merge 0cd6e510beaae50ddffa2168d6da92bc7f12ea09 has a verified signature and exactly the reviewed tree. All final PR checks passed; the pinned hosted verifier passed all 2,912 tests in both normal and coverage runs, packed consumers, stress tests, typecheck and lint. Independent final review is clean. Results never promote local consistency to authenticated producer or runtime authority. All merged-main checks passed.

#303 delivers exact original 17-file and released 19-file artifact inventory support; it does not authenticate conformance-result envelopes. #305 delivers computeDefinitionDigest(), verifyEventIntegrity(), and reduceAutomationEvents(). Merge 49b7ab5e3d1eae559240e9126196748c8a54e163 has a verified signature and exactly the independently reviewed tree. All final PR and merged-main checks passed; the pinned hosted verifier passed 2,978 tests in both normal and coverage runs, contracts, packed consumers, release-configuration guards, stress tests, typecheck and lint. The reducer preserves unknown initial occurrence state and checks occurrence continuity only when prior state is available in the current projection. Extension digest coverage follows pinned executable sources and golden vectors, with the conflicting schema prose recorded explicitly. Full guarded transition validation across every stream remains unreconciled.

Authentication, Familiar/Threads authority, and runtime authority verification remain unavailable without their canonical verification profiles. The current Coven producer at 14487ac7b23fe285db6ff6dd102109b995f58cdc still does not expose the requested getRun(runId) route or per-automation occurrence-list filter; the SDK does not synthesize those queries. The mixed global feed does have a producer position cursor; SDK adoption is a separate design choice, not a missing producer route. Production authority adapter wiring and rich persistence/lifecycle parity also remain upstream prerequisites.

Keep this program open for the remaining Phase 1 contracts and later authority-bearing phases. Coven #857/#858 remain prerequisites for authority-bearing commands. This development work does not alter frozen release candidate 96804bc4 or authorize publication.

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.

[BunsDev]

Concrete follow-on conformance progress is open in #248 at 3ae2867: the retained #106 canary now independently recomputes the pinned golden definition/receipt and embedded definition integrity before consuming replay vectors, and verifies receipt definition digest/ID/revision binding. Eight new negative cases reproduced the old acceptance gap; focused suites now pass 39/39. The actual immutable artifact 9909975069 and its authenticated live workflow/provenance checks both pass; typecheck, builds, packed package/API baseline, contract, lint, stress, and commit-hook gates also pass. Hosted PR CI is running; local full-verify limitations from the mandated deep worktree scratch path are explicitly recorded in the PR, not bypassed.

Dependency status refreshed from producer: #855 is CLOSED; #991 d277ade3 and #999 735e2f05 landed packaged capability negotiation, durable CAPABILITY_UNSUPPORTED, and exact wire fingerprinting. #857/#858 remain OPEN. The old artifact pin is intentionally not presented as certification of those newer changes. This PR advances independently implementable contract verification; it does not claim public authenticated verifyReceipt/read/subscribe APIs, rich executable persistence, production lifecycle emission, or completion of #80.

[BunsDev]

#248 exact-head CI passed: https://github.com/OpenCoven/sdk/actions/runs/34807985455

Full Node 24.18.1 verification (including extended immutable artifact integrity/binding canary), moving Node 24 compatibility, and native Linux/macOS/Windows keyring jobs are green.

The PR remains open for review; #80 remains open for its unimplemented public and authority-bearing phases.

[BunsDev]

Cody native-Automations dependency reconciliation (2026-09-14): OpenCoven/coven-runtimes#48 now explicitly owns the missing signed runtime terminal-observation producer; OpenCoven/coven#857 retains production trust adapters, accepting verification and inbox consumption. OpenCoven/coven#1054 tracks executable command/lifecycle parity deferred by the closed protocol issue. Reuse the active #248 canary-integrity work rather than duplicating it. Read-only APIs and truthful unavailable/unverified projections can advance against advertised source-pinned Coven reads now; full authenticated receipt/authority acceptance must not be inferred from old canary hashes, registry signatures, or a passing fixture. This does not mark #80 complete.

[BunsDev]

Implemented a concrete previously missing producer-vector requirement in #248: independently recompute embedded golden SHA-256 digests before consuming vectors and bind receipt definition digest/ID/revision to the golden definition. Outer archive/manifest hash agreement no longer substitutes for fixture semantic consistency. The historical exact artifact pin remains unchanged; this is fixture integrity, not authenticated public verifyReceipt or current-producer certification. Roadmap now reflects closed OpenCoven/coven#855 and the newer OpenCoven/coven#991 / OpenCoven/coven#999 capability-negotiation slices. Public phase-1 APIs remain open, not blanket-blocked on certification. #248 is being held for the separately reproduced Windows lock issue, now addressed in focused #249; no unrelated checks are waived.

[BunsDev]

#248 is now merged at 99fa244 after integrating the separately reviewed #249 native-lock fix. Exact combined head 01a06f5 passed all CI and CodeQL, including native Windows/macOS/Linux, run 34810032962. Delivered scope is independent pinned golden-fixture integrity and receipt-definition binding plus corrected producer status documentation; no public API, authentication, positive authority, or current-producer certification claim. #80 remains open for its unfinished phases.