P1: Define the Psyche adapter for automation-triggered orchestration without owning schedules

[BunsDev]

Cross-repository program: OpenCoven/coven#854
Core protocol: OpenCoven/coven#855
Identity/authority integration: OpenCoven/coven#857
Certification: OpenCoven/coven#858
Familiar binding: OpenCoven/familiar-contract#17
Authority profile: OpenCoven/coven-threads#29

Outcome

Define and implement the canonical adapter by which a Coven automation occurrence may invoke Psyche for multi-step, multi-lane, approval-aware orchestration without transferring schedule, occurrence, or run authority into Psyche.

Coven remains the clock, occurrence fence, run/attempt ledger, dispatch authority, and receipt committer. Psyche receives one adopted, identity- and authority-bound invocation; it orchestrates the requested work under its task/lane/lease/approval/recovery semantics and returns durable correlated evidence.

Canonical boundary

Coven owns

• automation definition and exact revision;
• trigger evaluation and occurrence planning;
• occurrence fence and claim/lease;
• authenticated principal/familiar/authority/runtime binding;
• automation run/attempt lifecycle and retries;
• cancellation/recovery decision at the automation level;
• final automation receipt and delivery status.

Psyche owns

• orchestration request validation/adoption;
• task/lane decomposition and dependencies;
• Psyche leases and worker assignments;
• orchestration approvals required by Psyche protocol;
• step/artifact/result evidence;
• orchestration recovery and terminal result semantics;
• a versioned result/receipt consumable by Coven.

Neither may

• create a second copy of familiar identity or authority policy;
• infer authorization from task text;
• rewrite the other system’s terminal history;
• retry ambiguous external side effects blindly;
• collapse automation occurrence, automation attempt, Psyche execution, lane, and worker attempt into one ambiguous identifier.

Invocation contract

Publish a versioned psyche.automation_invocation.v1 or ratified equivalent containing at least:

• stable invocation/adoption ID;
• automation ID and exact definition revision/digest;
• occurrence ID, canonical occurrence key, and fence generation;
• Coven run/attempt IDs;
• authenticated principal context reference;
• exact Familiar Embodiment Binding reference/digest;
• Threads authority decision and approval evidence references/digests;
• requested/granted capabilities and bounded scopes;
• action/risk class;
• orchestration brief/action payload and integrity digest;
• project/workspace/repository context;
• required runtime/worker capability constraints;
• timeout/deadline and cancellation channel;
• result/delivery expectations;
• correlation/causation and event cursors;
• profile/schema versions and producer identity;
• privacy/retention class.

Psyche must validate that the invocation is compatible, current, and adopted exactly once before creating consequential task/lane state.

Semantic separation

Maintain distinct objects and identifiers:

1. Automation occurrence — why/when the work became eligible.
2. Automation run — Coven’s authoritative execution lifecycle.
3. Automation attempt — one fenced dispatch attempt.
4. Psyche invocation/execution — one adopted orchestration request.
5. Psyche task/lane/lease — internal protocol work graph.
6. Worker/runtime session attempt — concrete execution embodiment.
7. Artifacts/results/receipts — evidence produced at each layer.

Define explicit correlation fields and one ownership source for each state. Avoid reusing a generic executionBinding object for semantically different layers.

Adoption and idempotency

• Coven commits/adopts the automation attempt before invoking Psyche.
• Psyche adopts the invocation key transactionally before creating tasks or external work.
• Repeated delivery of the same invocation returns the existing Psyche correlation/result; it does not create a second graph.
• Reuse of an invocation key with different bytes is a conflict.
• A timeout after possible adoption is reconciled by lookup, not blind retry with a new key.
• Coven does not mark the automation attempt running/succeeded merely because Psyche accepted transport.
• Psyche does not mark the automation run terminal directly; it emits its own authoritative result/event evidence.

Identity and authority

• Psyche consumes the exact familiar binding selected by Coven; it does not select or revise familiar identity.
• Every lane/worker session inherits or narrows the authorized projection; no lane may broaden capabilities.
• Threads decisions and approvals remain operation-specific and are rechecked where the protocol requires a later protected step.
• If orchestration discovers additional protected work, it requests approval or degrades to proposal; it does not reinterpret the initial grant.
• Principal, familiar, project, repository, path, network, credential, publication, and runtime scopes remain explicit.
• Revocation/expiry during queued, awaiting-approval, assigned, or running states has a documented cancel/degrade/continue policy and event trail.

Cancellation, timeout, and recovery

Define a bidirectional, replay-safe control contract:

• Coven may request cancellation for the exact Psyche invocation/execution.
• Psyche acknowledges and propagates cancellation to lanes/workers under its protocol.
• Cancellation remains pending until Psyche reports an authoritative reconciled state.
• A completed-vs-cancelled race resolves according to recorded event/order/fence semantics, not client arrival order.
• Psyche timeout or lost worker evidence may produce failed or recovery-required, but never inferred success.
• If Coven restarts, it rehydrates the Psyche correlation and reconciles rather than creating a new invocation.
• If Psyche restarts, adopted invocation/task/lane state remains durable and replayable.
• Ambiguous external side effects are surfaced to Coven as structured recovery-required evidence; automation retry is not automatic.

Result and receipt contract

Psyche returns a versioned PsycheAutomationResult or receipt containing:

• invocation/execution ID and adopted request digest;
• correlated automation occurrence/run/attempt IDs;
• task/lane/worker correlations;
• terminal status and reason;
• exact familiar/authority/runtime bindings exercised;
• approval events and capability narrowing;
• artifact/result digests and provenance;
• verification evidence per lane/step;
• cancellation/retry/recovery history;
• partial/ambiguous external-effect disclosure;
• start/finish/event-cursor data;
• privacy/redaction/retention classification;
• integrity/authentication field.

Coven embeds or references this evidence in the final Automation Receipt. Psyche evidence proves the orchestration observations it owns; Coven’s receipt proves the automation lifecycle/binding/delivery it owns.

Adapter interface

Suggested conceptual seam:

trait PsycheAutomationAdapter {
    fn adopt(&self, invocation: AutomationInvocation) -> Result<PsycheAdoption, PsycheError>;
    fn status(&self, invocation_id: &str) -> Result<PsycheStatus, PsycheError>;
    fn subscribe(&self, invocation_id: &str, after: Cursor) -> Result<EventStream, PsycheError>;
    fn request_cancel(&self, request: CancelRequest) -> Result<CancelAdoption, PsycheError>;
    fn reconcile(&self, invocation_id: &str) -> Result<PsycheReconciliation, PsycheError>;
}

Implement transport-neutral schemas first. In-process, local daemon, or future remote adapters must share identical adoption and evidence semantics.

Changefeed and backpressure

• Psyche events have stable IDs/sequences and support duplicate-safe replay.
• Coven persists its consumer cursor/correlation and does not rely on one live connection.
• Unknown/out-of-order events cannot regress state.
• Bounded buffers and explicit backpressure prevent memory growth.
• Event payloads are minimized/redacted according to principal authorization.
• Snapshot/reset behavior is explicit when a cursor is expired or history compacted.

Golden scenarios

At minimum:

1. one automation occurrence adopts one Psyche execution;
2. duplicate invocation delivery returns the same execution;
3. invocation-key conflict with changed bytes;
4. multi-lane success with verified artifacts;
5. lane failure and overall failed result;
6. additional protected step requires approval;
7. degrade-to-proposal without protected mutation;
8. principal/familiar/project mismatch refusal;
9. stale/revoked familiar binding refusal;
10. runtime capability narrowing per lane;
11. Coven restart after Psyche adoption;
12. Psyche restart with active lanes;
13. subscriber disconnect/replay duplicates;
14. cancellation before assignment;
15. cancellation during worker execution;
16. completion/cancellation race;
17. timeout/lost worker/recovery-required;
18. ambiguous external effect and no automatic automation retry;
19. artifact verification or delivery failure;
20. direct Coven run and Psyche run producing compatible Automation Receipts.

Verification

• schema/canonicalization/golden vector tests;
• adoption/idempotency/conflict tests;
• state/correlation ownership tests;
• duplicate/out-of-order/reconnect event tests;
• identity/authority/capability/approval tests;
• cancellation/timeout/restart/recovery tests;
• privacy/redaction tests;
• packed/released adapter tests;
• immutable cross-repository canaries against exact Coven, Familiar Contract, Threads, runtime, SDK, and Cave artifacts.

Integrate with Psyche’s canonical clean-clone bootstrap and fast/full checks.

Acceptance criteria

• Versioned automation→Psyche invocation, event, result, and error contracts are published.
• Coven schedule/occurrence/run authority and Psyche task/lane authority remain unambiguous.
• Invocation adoption is idempotent and conflict-safe.
• Familiar identity and Threads authority are consumed, pinned, and never broadened by lanes.
• Cancellation, timeout, restart, replay, and ambiguous recovery converge without duplicate orchestration or false success.
• Psyche result evidence composes into the Coven Automation Receipt.
• Golden scenarios and immutable cross-repository canaries pass.
• No Psyche API creates or edits canonical automation schedules.

Non-goals

• Building scheduling into Psyche.
• Mapping every simple familiar prompt through Psyche; direct Coven runtime execution remains valid.
• Merging automation and Psyche lifecycle objects.
• Granting lanes broad ambient authority.
• Blindly retrying ambiguous external side effects.

Bead packet

Create one P1 Psyche Bead mapped exactly to this issue. It depends on OpenCoven/coven#855 and #857 plus the pinned Familiar Contract/Threads profiles; certification depends on OpenCoven/coven#858. Evidence must include normative artifacts, adoption/replay/restart scenarios, authority narrowing, cancellation/recovery, receipt composition, and exact canary revisions.