@agenticprimitives/coordination

The Endeavor coordination core (spec 332, Wave 1): a durable, shared, multi-principal coordination object — someone posted a request; the group adopted it as a goal; a shared plan was proposed, revised, and adopted; participants were allocated and committed; work executed against plan steps; the outcome was validated — expressed as a pure, deterministic, event-sourced machine.

Install

pnpm add @agenticprimitives/coordination

Subpath exports: . (everything), ./core (records, commands, events, reducer, provenance inputs), ./planning (plans, steps, edges, milestones, content hash, acyclicity), ./participation (participations, proposals, allocations, signed commitments). ./profiles, ./decisions, and ./projections are reserved stubs whose real contents land with spec 333/334.

Model

• EndeavorRequestV1 — structured intake before adoption (ereq_ id). Any entry point (Home request, discussion ask, inbox ask, A2A intent) produces the same request and drives the same machinery.
• EndeavorV1 — the durable multi-principal Situation (end_ id) pursuing an OutcomeSpecificationV1 (observable success criteria, versioned).
• CoordinationPlanV1 — the durable shared plan (p-plan:Plan grounding). Revisions are immutable; planContentHash is sha256(JCS(steps + edges + milestones)); adoption is an explicit decision, never implicit; at most one revision is adopted at a time.
• EndeavorParticipationV1 — a participant's relationship to the Endeavor (role + scope + validity), asserted through invitation/acceptance or allocation/commitment.
• ContributionProposalV1 → AllocationDecisionV1 → ContributionCommitmentV1 — offer, selection, and the participant's signed acceptance. A commitment binds an exact plan revision hash; a stale hash is rejected.

Usage

import {
  initialCoordinationState,
  validateCoordinationCommand,
  applyCoordinationEvent,
  deriveProvenanceInputs,
} from '@agenticprimitives/coordination/core';

let state = initialCoordinationState();
const result = validateCoordinationCommand(state, {
  kind: 'SubmitEndeavorRequest',
  actor: requesterAddress,
  issuedAt: new Date().toISOString(),
  requestId: 'ereq_1',
  targetPrincipal: orgAddress,
  goal: 'Produce the Q3 treasury report',
  entryPoint: 'home-request',
});
if (!result.ok) throw new Error(result.reason);
for (const event of result.events) state = applyCoordinationEvent(state, event);

validateCoordinationCommand rejects before append (fail-closed) and returns the events to persist; applyCoordinationEvent is a pure reducer that enforces monotonic revisions. Replaying the event log always reproduces the state; deriveProvenanceInputs(events) yields a structural summary (entities, activities, agents, correspondsToStep links) a P-Plan/PROV projection can consume.

Invariants (spec 332 §6/§9)

1. Allocation is never authority. No gate reads an apcoord: record; capable / available / allocated / committed / authorized / performing / satisfied are seven separate facts.
2. Commitments are signed by the participant against the exact adopted plan revision hash.
3. Conversation never mutates state. Only signed commands produce events; PlanRejected is the only way a plan proposal dies; unknown command kinds are rejected fail-closed.
4. One mechanism (ADR-0013): the reducer is the only state-transition path.
5. Deterministic: ids and timestamps come from commands/events, never from the reducer.

Boundaries

Depends on @agenticprimitives/types, @agenticprimitives/situations (EntityRef, validity, JCS), and @agenticprimitives/ontology (apcoord: IRIs). Never imports fabric/home/a2a/delegation/vault — those layers consume coordination. Vendor adapters (Linear, Jira, Temporal, LangGraph, …) live in external repos; only ExternalObjectBindingV1 (the adapter contract surface) ships here.

Spec

specs/332-coordination-endeavor-core.md · ADR-0054 · golden fixtures in test/fixtures/.