# API and Events

## API surface

All writes require authenticated principal, Realm, Authority evidence, idempotency key, and expected object version.

```text
GET    /v1/coherence/dimensions/{id}?version=
POST   /v1/coherence/dimensions:validate
POST   /v1/coherence/profiles
GET    /v1/coherence/profiles/{id}/versions/{version}
POST   /v1/coherence/profiles/{id}:rehearse
POST   /v1/coherence/profiles/{id}:publish
POST   /v1/coherence/effective-profile:resolve
POST   /v1/coherence/observations
POST   /v1/coherence/state:aggregate
POST   /v1/coherence/assessments
POST   /v1/coherence/preflight
POST   /v1/coherence/interventions
POST   /v1/coherence/interventions/{id}:accept
POST   /v1/coherence/interventions/{id}:decline
POST   /v1/coherence/interventions/{id}:appeal
POST   /v1/coherence/mediation-sessions
POST   /v1/coherence/repairs
GET    /v1/coherence/audit?subject=&from=&to=
POST   /v1/coherence/observations:reset
```

`preflight` returns:

```json
{
  "decision": "allow-with-modulation",
  "assessmentRef": "assessment://asmt.rowan.104",
  "directives": ["State one material counterargument before endorsing the plan."],
  "deniedEffects": [],
  "requiredEscalations": [],
  "policyVersions": ["coherence-policy://kiduna/constitutional@1"],
  "expiresAt": "2026-08-21T18:10:00Z"
}
```

## Events

Events follow a CloudEvents-compatible envelope implemented by `coherence-event.schema.json`. Types:

- `coherence.profile.published`
- `coherence.policy.changed`
- `coherence.consent.changed`
- `coherence.observation.recorded`
- `coherence.state.updated`
- `coherence.assessment.completed`
- `coherence.drift.detected`
- `coherence.boundary.approached`
- `coherence.boundary.violated`
- `coherence.intervention.proposed`
- `coherence.intervention.started`
- `coherence.intervention.completed`
- `coherence.escalation.requested`
- `coherence.calibration.completed`

Events contain references, not unnecessary raw evidence. Consumers MUST re-check visibility and purpose rather than assuming Event possession grants data access.

## Concurrency

Profile/policy writes use optimistic version checks. State updates use observation IDs for deduplication. Assessments include resolved profile/policy versions; an intervention created from a stale assessment must be re-evaluated before execution.