# Interaction Contract Protocol — FULL RESEARCH CORPUS
Abbreviation: icp
Version: v0.1.0 | Generated: unspecified | Files: 5 | Lines: 2,371 | Payload: 66.0 KiB
Source path: /Users/zachshallbetter/Projects/_protocols/interaction-contract-protocol
Bundle name: llm-full-docs-icp

Corpus Payload SHA-256: a57d4c6d2ccb4108b786f8394d0908ca6b8d53703fa81483e3fda925cbe28182

TABLE OF CONTENTS:
  - INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md (2252 lines, 58.6 KiB)
  - LICENSE (21 lines, 1.0 KiB)
  - README.md (81 lines, 5.4 KiB)
  - package.json (8 lines, 0.4 KiB)
  - protocol-manifest.json (9 lines, 0.6 KiB)

========================================================================

========================================================================
## FILE: INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md (2252 lines, 58.6 KiB)
========================================================================

# Interaction Contract Protocol

**Identifier:** `icp:protocol/interaction-contract`  
**Version:** `0.1.0`  
**Status:** Normative Candidate  
**Date:** 2026-07-24  
**License recommendation:** Specification prose under CC BY 4.0; schemas, validators, examples, and tooling under Apache-2.0  
**Primary artifact:** This document  
**Companion artifacts:** JSON Schema, outcome registry, recovery-action registry, conformance suite, migration guide

---

## 0. Abstract

The **Interaction Contract Protocol (ICP)** is a versioned, machine-readable, implementation-independent protocol for declaring and governing consequential interactions among people, software, services, agents, devices, institutions, and environments.

An Interaction Contract declares:

- what interaction is being attempted;
- who or what participates and in which roles;
- where its boundary begins and ends;
- what state, context, and evidence are relevant;
- which actions are available, permitted, enabled, exposed, and believed available;
- which inputs, checks, authority decisions, and verification steps are required;
- which state transitions or external effects may occur;
- which invariants must remain true;
- which outcomes may be emitted;
- how failure, uncertainty, conflict, partial completion, recovery, reversal, and closure are represented;
- what receipts, audit records, traces, and measurements must be produced.

ICP is a **composition protocol**. It does not replace JSON Schema, OpenAPI, RFC 9457, statecharts, workflow systems, policy engines, accessibility standards, event systems, or domain models. It binds their responsibilities into one declared interaction lifecycle.

The protocol has two coordinated profiles:

1. **Operational Profile** — for product, API, frontend, backend, workflow, agent, and administrative interactions.
2. **Research Profile** — for Foundations of Computational Interaction and related empirical work, adding explicit coupling, perturbation, uptake, recurrence, observation, evidence, uncertainty, and claim boundaries.

The profiles share identity, lifecycle, state, event, transition, outcome, provenance, and conformance structures. They must not be collapsed where their sources of truth differ.

---

# 1. Normative definition

## 1.1 Interaction Contract

An **Interaction Contract** is a stable, versioned declaration of the identity, participants, roles, authority, boundary, timescale, state, context, coupling or communication channels, inputs, preconditions, evidence, checks, verification, events, transitions, effects, protocol, invariants, outcomes, recovery, receipts, observation, failure, uncertainty, and completion conditions of a bounded interaction.

In compact form:

```text
IC = ⟨
  Id, V, P, B, X, C, Tr,
  In, A, Ev, Ch, Ve,
  E, T, Inv, O, R,
  Rc, Ob, U, Cl
⟩
```

where:

| Symbol | Meaning |
|---|---|
| `Id` | Stable interaction identity |
| `V` | Contract version and compatibility envelope |
| `P` | Participants and roles |
| `B` | Boundary and timescale |
| `X` | Relevant state and context |
| `C` | Coupling, communication, or effect channels |
| `Tr` | Trigger and initiation conditions |
| `In` | Inputs and structural validation |
| `A` | Authority, capability, and permission |
| `Ev` | Evidence and provenance |
| `Ch` | Checks, guards, and decision rules |
| `Ve` | Verification requirement and proof |
| `E` | Events |
| `T` | Transitions, mutations, and external effects |
| `Inv` | Preserved invariants |
| `O` | Typed outcomes |
| `R` | Recovery, compensation, and reversal |
| `Rc` | Receipts, audit records, and event lineage |
| `Ob` | Observation, telemetry, and trace rules |
| `U` | Uncertainty, missingness, and abstention |
| `Cl` | Completion, cancellation, expiration, and closure |

An Interaction Contract is not merely an API endpoint definition, form schema, state machine, confirmation dialog, error catalog, or audit event. It coordinates those artifacts while preserving their distinct responsibilities.

## 1.2 Interaction

For the Operational Profile, an **interaction** is a bounded, temporally organized process in which one or more participants attempt to inspect, decide, communicate, or produce a consequential state transition or external effect through a declared system.

For the Research Profile, an interaction additionally requires declared coupling in which perturbations originating in or mediated by one participant alter another participant’s possible or actual trajectory, and the resulting configuration recurrently constrains a later trajectory within the declared boundary and timescale.

The Operational Profile may represent one-way commands, reads, and submissions that do not satisfy the stricter FCI recurrence criterion. Such records are valid operational interactions but must not automatically be treated as scientific interaction episodes.

## 1.3 Contract instance

A **Contract Definition** declares the reusable interaction type.

A **Contract Instance** records one bounded attempt under that definition.

```text
Definition: org.member.remove@2.1.0
Instance:   int_01K0... executed at 2026-07-24T18:30:00Z
```

A definition is normative. An instance is historical.

## 1.4 Protocol

The protocol is the admissible ordering of stages, events, decisions, transitions, obligations, timeouts, retries, and closure conditions. A contract may be atomic, stateful, asynchronous, long-running, distributed, human-reviewed, or partially ordered.

---

# 2. Scope

ICP applies to:

- user interface actions;
- HTTP, RPC, event, and command APIs;
- background jobs;
- durable workflows;
- administrative operations;
- file and evidence processing;
- imports, exports, and batch operations;
- agent tool calls;
- human–AI interactions;
- authorization and policy decisions;
- device and service operations;
- research protocols and bounded interaction episodes;
- recovery, compensation, rollback, and restore operations.

ICP does not prescribe:

- a specific programming language;
- a specific state-management library;
- a specific database;
- a specific transport;
- a specific UI framework;
- a universal definition of usability, trust, understanding, or quality;
- a universal interaction-similarity score;
- an inference from traces to intention, comprehension, strategy, or cause;
- replacement of domain-specific workflow, policy, evidence, measurement, or accessibility standards.

---

# 3. Normative language

The terms **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, and **MAY** are normative.

- **MUST** indicates a conformance requirement.
- **SHOULD** indicates a strong recommendation that may be waived only with a recorded rationale.
- **MAY** indicates an optional capability.
- A field marked **conditional** is required when its declared condition applies.
- “Unknown,” “not observed,” “not applicable,” and “zero” MUST remain distinguishable.

---

# 4. Foundational principles

## 4.1 One interaction, multiple sources of truth

An Interaction Contract coordinates distinct sources of truth without merging them:

```text
Domain state        owns canonical business or world state
Authority policy    owns who may act
Evidence system     owns provenance and evidentiary status
Workflow system     owns durable process state
Interaction runtime owns protocol execution
Event system        owns append-only historical facts
Client runtime      owns accessible presentation
Measurement system  owns operationalization and inference limits
```

No lower-authority artifact may silently redefine a higher-authority meaning.

## 4.2 Capability is not permission

The protocol MUST distinguish:

```text
can perform
may perform
is currently enabled
is reachable
is exposed
is signaled
is believed available
was selected
was executed
succeeded
```

These are not interchangeable.

## 4.3 Evidence is not decision

The protocol MUST distinguish:

```text
Evidence
→ Evaluation
→ Decision
→ Status
```

An external source may provide evidence. It does not receive authority to determine canonical state unless the contract explicitly grants that authority.

## 4.4 Observation is not interpretation

A record of an event is not automatically evidence of intention, understanding, strategy, hesitation, culture, identity, or cause.

Every derived interpretation MUST retain:

- source records;
- transformation or detection rules;
- uncertainty;
- alternative explanations;
- permitted interpretation;
- prohibited interpretation.

## 4.5 Projection reveals; mutation changes

A projection or presentation layer MUST NOT silently mutate the state it reveals. Read and reveal capabilities MUST be structurally separated from write capabilities.

## 4.6 Formalization creates inspectable uncertainty

A contract does not eliminate judgment or ambiguity. It relocates them into explicit:

- boundaries;
- state abstractions;
- classifications;
- policy rules;
- mappings;
- tolerances;
- evidence standards;
- uncertainty declarations.

## 4.7 Failure and recovery are part of the interaction

Timeout, rejection, conflict, deadlock, review, cancellation, compensation, partial completion, and abandonment MUST remain represented. They MUST NOT be deleted from the trace merely because the intended goal was not achieved.

## 4.8 Success requires explanation

A successful mutation SHOULD explain:

- what changed;
- what did not change;
- what evidence or authority supported it;
- whether it can be reversed;
- where its receipt can be inspected.

## 4.9 Recovery is executable

A blocked or failed outcome MUST either:

- provide at least one executable recovery action; or
- declare a terminal reason explaining why no recovery exists.

## 4.10 Conformance is not validation of theory or quality

Schema conformance proves structural validity. Runtime conformance proves declared protocol behavior. Neither, by itself, proves usability, accessibility quality, empirical validity, causal claims, or scientific value.

---

# 5. Canonical lifecycle

The canonical operational lifecycle is:

```text
Declare
→ Instantiate
→ Trigger
→ Bind inputs
→ Validate structure
→ Resolve participant and authority
→ Resolve evidence and context
→ Evaluate checks and policy
→ Derive verification requirement
→ Satisfy or reject verification
→ Check idempotency and concurrency
→ Apply transition or external effect
→ Validate invariants
→ Commit
→ Emit receipt and audit event
→ Emit typed outcome
→ Render explanation
→ Recover, reverse, continue, or close
```

The lifecycle is not necessarily linear. Long-running contracts may pause, branch, retry, compensate, or return to evidence collection.

## 5.1 Canonical instance states

```text
declared
ready
started
validating
blocked
verification_required
verifying
queued
processing
needs_review
conflicted
partially_completed
completed
failed
compensating
reversed
cancelled
expired
abandoned
closed
```

A project MAY define additional states, but MUST map them to one canonical state.

## 5.2 Terminal states

The contract MUST declare its terminal states. `completed` is not the only valid closure. Valid terminal closure may include:

- completed;
- rejected;
- cancelled;
- expired;
- abandoned;
- failed without recovery;
- compensated;
- reversed;
- declared truncation.

---

# 6. Contract architecture

## 6.1 Layered architecture

```text
┌──────────────────────────────────────────────────────────┐
│ Authoring Layer                                          │
│ YAML/JSON contract definitions, registries, documentation│
└──────────────────────────┬───────────────────────────────┘
                           │ compile/validate
┌──────────────────────────▼───────────────────────────────┐
│ Contract Registry                                        │
│ stable IDs, versions, status, dependencies, compatibility│
└──────────────┬──────────────────┬────────────────────────┘
               │                  │
┌──────────────▼──────────┐ ┌────▼────────────────────────┐
│ Policy / Decision Plane │ │ Schema / Validation Plane   │
│ authority, checks,      │ │ inputs, events, outcomes,   │
│ verification, invariants│ │ receipts, migrations        │
└──────────────┬──────────┘ └────┬────────────────────────┘
               │                  │
┌──────────────▼──────────────────▼────────────────────────┐
│ Interaction Runtime                                      │
│ instance state, orchestration, idempotency, concurrency, │
│ mutation boundary, retries, compensation, closure        │
└──────┬──────────────────┬────────────────────┬───────────┘
       │                  │                    │
┌──────▼──────┐    ┌──────▼────────┐   ┌──────▼──────────┐
│ Domain Plane│    │ Evidence Plane│   │ Workflow Plane  │
│ state/effects│   │ provenance    │   │ durable process │
└──────┬──────┘    └──────┬────────┘   └──────┬──────────┘
       └──────────────────┬┴───────────────────┘
                          │
┌─────────────────────────▼────────────────────────────────┐
│ Event, Receipt, and Observation Plane                    │
│ immutable events, traces, audit, telemetry, measurements │
└─────────────────────────┬────────────────────────────────┘
                          │
┌─────────────────────────▼────────────────────────────────┐
│ Client and Projection Plane                              │
│ accessible rendering, recovery execution, status, replay │
└──────────────────────────────────────────────────────────┘
```

## 6.2 Required components

A conforming implementation MUST provide:

1. Contract Registry
2. Schema Validator
3. Interaction Runtime or equivalent constrained execution boundary
4. Authority Resolver
5. Outcome Renderer or client adapter
6. Receipt and event emitter for persistent mutations
7. Conformance test runner

A Level 3 or higher implementation MUST additionally provide:

8. Evidence/provenance resolver
9. Verification challenge service
10. Optimistic concurrency or declared equivalent
11. Idempotency service for retryable effects
12. Recovery-action executor
13. Coverage scanner
14. Version and migration registry

## 6.3 Mandatory execution boundary

Persistent mutations MUST NOT execute outside a registered contract or equivalent generated wrapper.

Reference shape:

```ts
export const removeMember = defineInteraction({
  contract: "icp:interaction/org.member.remove@2.1.0",

  resolveContext,
  validateInputs,
  authorize,
  resolveEvidence,
  evaluateChecks,
  deriveVerification,
  enforceConcurrency,
  execute,
  validateInvariants,
  createReceipt,
  emitEvents,
  mapOutcome,
});
```

Import detection is insufficient. The execution architecture SHOULD make bypass structurally difficult or impossible.

---

# 7. Identity and namespace syntax

## 7.1 Stable identifiers

Stable IDs MUST be version-independent.

```text
icp:interaction/org.member.remove
icp:outcome/conflict
icp:recovery/review-conflict
icp:check/actor.has-permission
icp:invariant/last-admin-protected
icp:event/member.removed
icp:schema/change-receipt
```

Versions live in metadata or references:

```text
icp:interaction/org.member.remove@2.1.0
```

The stable ID MUST NOT change for editorial corrections or compatible extensions. A semantic replacement that changes identity MUST receive a new ID.

## 7.2 Identifier grammar

```abnf
namespace    = "icp:"
kind         = "interaction" / "outcome" / "recovery" / "check" /
               "invariant" / "event" / "schema" / "policy" /
               "profile" / "registry"
path         = segment *("/" segment)
segment      = ALPHA *(ALPHA / DIGIT / "." / "-" / "_")
version      = "@" semver
identifier   = namespace kind "/" path [version]
```

## 7.3 Interaction IDs

Recommended interaction IDs use:

```text
domain.entity.verb
domain.entity.subentity.verb
domain.workflow.step
```

Examples:

```text
org.member.remove
document.evidence.verify
commerce.order.refund
agent.tool.execute
research.episode.begin
```

IDs name semantic intent, not HTTP verbs, component names, or button labels.

---

# 8. Authoring syntax

## 8.1 Canonical authoring format

YAML is the recommended review format. JSON is the canonical interchange format.

```yaml
$schema: https://interaction-contract.org/schema/0.1/interaction-contract.schema.json
kind: InteractionContract
specVersion: 0.1.0

metadata:
  id: icp:interaction/org.member.remove
  version: 2.1.0
  status: normative
  title: Remove organization member
  owner: identity-and-access
  introducedAt: 2026-07-24
  compatibility:
    minimumRuntime: 0.1.0
  dependencies:
    - icp:policy/org-access@1.3.0
    - icp:schema/change-receipt@1.0.0

interaction:
  intent: Remove a member and revoke organization access.
  class: persistent_mutation
  profile: operational
  participants:
    - role: actor
      type: human_or_agent
      required: true
    - role: subject
      type: account
      required: true
    - role: organization
      type: institutional
      required: true

boundary:
  startsWhen: command_accepted
  endsWhen:
    anyOf: [completed, blocked, cancelled, expired, failed]
  timeout: PT5M
  environment: organization_access_domain

trigger:
  events:
    - ui.member.remove_requested
    - api.org.member.remove_requested

inputs:
  schema:
    type: object
    additionalProperties: false
    required: [organizationId, memberId, expectedVersion]
    properties:
      organizationId:
        type: string
        minLength: 1
      memberId:
        type: string
        minLength: 1
      expectedVersion:
        type: integer
        minimum: 0
      reason:
        type: string
        maxLength: 500

authority:
  capability: org.members.manage
  permission: org.member.remove
  scope: organizationId
  subjectRules:
    - icp:invariant/self-role-mutation-prevented
    - icp:invariant/last-admin-protected
  failClosed: true

evidence:
  required:
    - id: current-membership
      kind: canonical_record
      freshness: PT30S
    - id: current-role-count
      kind: derived_fact
      freshness: PT30S
  externalSourcesAreAuthoritative: false

checks:
  - id: organization.exists
    phase: precondition
    onFalse: organization_not_found
  - id: member.exists
    phase: precondition
    onFalse: member_not_found
  - id: actor.can_remove_member
    phase: authority
    onFalse: permission_denied
  - id: target.is_not_actor
    phase: invariant
    onFalse: self_role_mutation_blocked
  - id: target.is_not_last_admin
    phase: invariant
    onFalse: last_admin_blocked

verification:
  policy: icp:policy/access-removal-verification@1.0.0
  allowedLevels: [none, acknowledge, confirm, reauthenticate]
  challenge:
    bindTo: [actorId, interactionId, targetId, inputDigest]
    expiresIn: PT5M
    singleUse: true

concurrency:
  mode: optimistic
  expectedVersionPath: /expectedVersion
  onConflict: stale_record

idempotency:
  required: true
  keyScope: actor_and_input
  retention: PT24H

change:
  operation: revokeOrganizationMembership
  affectedResources:
    - organization.members
    - member.permissions
    - member.sessions
  reversibility: compensatable
  compensationInteraction: icp:interaction/org.member.restore
  atomicity: transaction

invariants:
  preserve:
    - organization.has_at_least_one_active_admin
    - actor.authorization_snapshot_is_current
    - audit_event_is_append_only

outcomes:
  completed:
    class: completed
    severity: success
    title: Member removed
    message: The member no longer has access to this organization.
    receipt: required
    presentation: status
  verification_required:
    class: verification_required
    severity: warning
    title: Verify this access change
    message: Reauthenticate to remove this member.
    recovery:
      - type: reauthenticate
        assurance: high
  stale_record:
    class: conflict
    severity: error
    title: Membership changed
    message: This membership changed after you opened it.
    recovery:
      - type: review_conflict
        resource: organization.members
  last_admin_blocked:
    class: blocked
    severity: error
    title: Another administrator is required
    message: The last active administrator cannot be removed.
    recovery:
      - type: start_workflow
        workflowId: transfer-administration
  permission_denied:
    class: blocked
    severity: error
    title: You cannot remove this member
    message: Request the organization member-management permission.
    recovery:
      - type: request_access
        permission: org.member.remove

receipts:
  changeReceipt: required
  auditEvent: member.removed
  include:
    - actor
    - subject
    - beforeVersion
    - afterVersion
    - changedFields
    - verificationId
    - evidenceIds

observation:
  emit:
    - interaction.started
    - verification.required
    - interaction.completed
    - recovery.started
    - recovery.completed
  correlation:
    traceId: required
    requestId: required
    instanceId: required

closure:
  completedWhen:
    - membership_revoked
    - sessions_invalidated
    - receipt_persisted
    - audit_event_persisted
  terminalOutcomes:
    - completed
    - permission_denied
    - last_admin_blocked
    - cancelled
    - expired
```

---

# 9. Contract field schema

## 9.1 Top-level fields

| Field | Requirement | Purpose |
|---|---|---|
| `$schema` | MUST | Schema dialect and version |
| `kind` | MUST | `InteractionContract` |
| `specVersion` | MUST | Protocol schema version |
| `metadata` | MUST | Identity, ownership, status, version |
| `interaction` | MUST | Intent, class, profile, participants |
| `boundary` | MUST | Start, closure, timescale, environment |
| `trigger` | MUST | Initiating events or conditions |
| `inputs` | MUST | Canonical structural input schema |
| `authority` | MUST | Capability, permission, scope, subject rules |
| `evidence` | SHOULD; conditional | Required evidence and provenance |
| `checks` | MUST | Preconditions, guards, policy checks |
| `verification` | MUST | Explicit `none` or policy |
| `concurrency` | MUST for mutable shared state | Stale-state behavior |
| `idempotency` | MUST for retryable effects | Duplicate request behavior |
| `change` | MUST for mutation/effect | Transition and effect semantics |
| `invariants` | MUST | Properties preserved before commit |
| `outcomes` | MUST | Exhaustive typed outcome map |
| `receipts` | MUST for persistent effects | Change and audit requirements |
| `recovery` | MAY globally | Shared compensation/recovery |
| `observation` | MUST | Events, traces, telemetry |
| `uncertainty` | SHOULD; MUST for inferential contracts | Unknowns and abstention |
| `closure` | MUST | Completion and terminal conditions |
| `research` | Research Profile only | Coupling and evidence additions |

## 9.2 Interaction classes

```text
read
ephemeral
persistent_mutation
external_effect
batch
workflow
review
verification
reversal
research_episode
```

## 9.3 Verification levels

```text
none
acknowledge
confirm
reauthenticate
prove
```

Verification level MUST be derived from declared consequence factors, not UI preference alone.

Recommended factors:

- reversibility;
- affected participants;
- authority change;
- sensitive-data exposure;
- financial or legal consequence;
- external irreversibility;
- evidence confidence;
- user surprise;
- session assurance;
- policy obligation.

## 9.4 Outcome classes

Canonical classes:

```text
completed
accepted
queued
partially_completed
invalid_input
not_found
verification_required
needs_evidence
needs_review
blocked
conflict
dependency_failure
background_failure
system_failure
cancelled
expired
abandoned
reversed
compensated
unknown
```

Severity is orthogonal:

```text
info
success
warning
error
critical
```

`blocked` is not synonymous with `error`. A valid policy decision may block an action without system failure.

## 9.5 Recovery actions

Canonical recovery actions:

```text
focus_field
select_file
replace_evidence
retry_operation
retry_later
refresh_record
open_record
review_conflict
reauthenticate
provide_proof
request_access
start_workflow
resume_workflow
contact_support
download_report
undo
compensate
cancel
```

A recovery action MUST carry enough typed data for a client or runtime to execute it.

## 9.6 Reversibility classes

```text
reversible
compensatable
irreversible
unknown
```

Reversibility and recovery MUST remain distinct. An irreversible action may still have a recovery path.

---

# 10. Wire protocol

## 10.1 Request envelope

```json
{
  "interaction": "icp:interaction/org.member.remove",
  "contractVersion": "2.1.0",
  "instanceId": "int_01K0ABC...",
  "requestId": "req_01K0ABC...",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "idempotencyKey": "idem_01K0ABC...",
  "actor": {
    "id": "usr_123",
    "sessionAssurance": "normal"
  },
  "target": {
    "type": "organization_member",
    "id": "mem_456",
    "expectedVersion": 17
  },
  "input": {
    "organizationId": "org_1",
    "memberId": "mem_456",
    "expectedVersion": 17
  },
  "verification": {
    "challengeId": "vfy_123",
    "proof": "opaque-proof-reference"
  }
}
```

## 10.2 Success envelope

```json
{
  "interaction": "icp:interaction/org.member.remove",
  "instanceId": "int_01K0ABC...",
  "status": "completed",
  "outcome": {
    "id": "completed",
    "class": "completed",
    "severity": "success",
    "title": "Member removed",
    "message": "The member no longer has access to this organization."
  },
  "receipt": {
    "id": "rcpt_01K0ABC...",
    "resource": {
      "type": "organization_member",
      "id": "mem_456"
    },
    "beforeVersion": 17,
    "afterVersion": 18,
    "reversibility": "compensatable"
  },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}
```

## 10.3 Problem envelope

Non-success HTTP responses SHOULD use RFC 9457-compatible `application/problem+json`.

```json
{
  "type": "https://interaction-contract.org/problems/stale-record",
  "title": "Record changed",
  "status": 409,
  "detail": "This membership changed after you opened it.",
  "instance": "urn:interaction:int_01K0ABC...",
  "interaction": "icp:interaction/org.member.remove",
  "outcome": "stale_record",
  "class": "conflict",
  "severity": "error",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "recovery": [
    {
      "type": "review_conflict",
      "resourceType": "organization_member",
      "resourceId": "mem_456",
      "currentVersion": 18
    }
  ],
  "changed": false
}
```

Every problem MUST state or make derivable whether a persistent effect occurred.

## 10.4 Verification challenge

```json
{
  "status": "verification_required",
  "interaction": "icp:interaction/org.member.remove",
  "challenge": {
    "id": "vfy_123",
    "level": "reauthenticate",
    "actorId": "usr_123",
    "targetId": "mem_456",
    "inputDigest": "sha256:...",
    "issuedAt": "2026-07-24T18:30:00Z",
    "expiresAt": "2026-07-24T18:35:00Z",
    "singleUse": true
  },
  "recovery": [
    {
      "type": "reauthenticate",
      "assurance": "high"
    }
  ]
}
```

## 10.5 Change receipt

```json
{
  "$schema": "https://interaction-contract.org/schema/0.1/change-receipt.schema.json",
  "id": "rcpt_01K0ABC...",
  "interaction": "icp:interaction/org.member.remove",
  "contractVersion": "2.1.0",
  "instanceId": "int_01K0ABC...",
  "requestId": "req_01K0ABC...",
  "actor": {
    "id": "usr_123",
    "role": "organization_admin"
  },
  "resource": {
    "type": "organization_member",
    "id": "mem_456"
  },
  "beforeVersion": 17,
  "afterVersion": 18,
  "changes": [
    {
      "path": "/status",
      "before": "active",
      "after": "revoked"
    }
  ],
  "evidenceIds": ["ev_123", "ev_124"],
  "verificationId": "vfy_123",
  "occurredAt": "2026-07-24T18:31:10Z",
  "reversibility": "compensatable",
  "compensationInteraction": "icp:interaction/org.member.restore",
  "integrity": {
    "algorithm": "sha-256",
    "digest": "..."
  }
}
```

---

# 11. Reference JSON Schema

The normative repository SHOULD divide the schema into reusable modules:

```text
/schema
  interaction-contract.schema.json
  interaction-instance.schema.json
  participant.schema.json
  boundary.schema.json
  authority.schema.json
  evidence.schema.json
  check.schema.json
  verification.schema.json
  transition.schema.json
  outcome.schema.json
  recovery-action.schema.json
  change-receipt.schema.json
  audit-event.schema.json
  trace-event.schema.json
  uncertainty.schema.json
  research-profile.schema.json
```

Minimal root schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://interaction-contract.org/schema/0.1/interaction-contract.schema.json",
  "title": "Interaction Contract",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "$schema",
    "kind",
    "specVersion",
    "metadata",
    "interaction",
    "boundary",
    "trigger",
    "inputs",
    "authority",
    "checks",
    "verification",
    "invariants",
    "outcomes",
    "observation",
    "closure"
  ],
  "properties": {
    "$schema": { "type": "string", "format": "uri" },
    "kind": { "const": "InteractionContract" },
    "specVersion": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
    },
    "metadata": { "$ref": "./metadata.schema.json" },
    "interaction": { "$ref": "./interaction.schema.json" },
    "boundary": { "$ref": "./boundary.schema.json" },
    "trigger": { "$ref": "./trigger.schema.json" },
    "inputs": { "$ref": "./inputs.schema.json" },
    "authority": { "$ref": "./authority.schema.json" },
    "evidence": { "$ref": "./evidence.schema.json" },
    "checks": {
      "type": "array",
      "items": { "$ref": "./check.schema.json" },
      "minItems": 1
    },
    "verification": { "$ref": "./verification.schema.json" },
    "concurrency": { "$ref": "./concurrency.schema.json" },
    "idempotency": { "$ref": "./idempotency.schema.json" },
    "change": { "$ref": "./change.schema.json" },
    "invariants": { "$ref": "./invariants.schema.json" },
    "outcomes": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": { "$ref": "./outcome.schema.json" }
    },
    "receipts": { "$ref": "./receipts.schema.json" },
    "recovery": {
      "type": "array",
      "items": { "$ref": "./recovery-action.schema.json" }
    },
    "observation": { "$ref": "./observation.schema.json" },
    "uncertainty": { "$ref": "./uncertainty.schema.json" },
    "closure": { "$ref": "./closure.schema.json" },
    "research": { "$ref": "./research-profile.schema.json" }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "interaction": {
            "properties": {
              "class": {
                "enum": [
                  "persistent_mutation",
                  "external_effect",
                  "batch",
                  "workflow",
                  "reversal"
                ]
              }
            }
          }
        }
      },
      "then": {
        "required": ["change", "receipts"]
      }
    },
    {
      "if": {
        "properties": {
          "interaction": {
            "properties": {
              "profile": { "const": "research" }
            }
          }
        }
      },
      "then": {
        "required": ["research", "evidence", "uncertainty"]
      }
    }
  ]
}
```

Schema validity is necessary but not sufficient. Semantic checks require a conformance engine.

---

# 12. Semantic checks

## 12.1 Definition checks

A contract MUST fail definition validation when:

- its stable ID is missing or malformed;
- version metadata is absent;
- no owner is declared;
- no boundary or terminal condition exists;
- outcomes are not exhaustive for declared checks;
- an `onFalse` outcome is undefined;
- a persistent mutation lacks a receipt policy;
- a mutable shared-resource interaction lacks a concurrency policy;
- a retryable effect lacks idempotency;
- verification is omitted rather than explicitly set to `none`;
- a recovery references an unknown action type;
- a compensation interaction references itself without a cycle policy;
- a research contract omits observation, evidence, or uncertainty rules.

## 12.2 Runtime checks

A runtime MUST fail closed when:

- the contract is unknown;
- the requested contract version is unsupported;
- authority cannot be resolved;
- required evidence cannot be verified;
- verification proof is missing, expired, mismatched, or reused;
- expected version does not match;
- idempotency state is ambiguous;
- an invariant cannot be evaluated;
- receipt persistence is required but unavailable;
- an external effect cannot be correlated to its request;
- the runtime is operating in an undeclared degraded mode.

## 12.3 Outcome checks

Every outcome MUST declare:

- stable local ID;
- canonical class;
- severity;
- user-facing title;
- user-facing message;
- whether change occurred;
- presentation default;
- recovery actions or terminal reason.

Messages MUST NOT expose secrets, stack traces, internal identifiers, raw policy details, or evidence that the actor lacks authority to view.

## 12.4 Recovery checks

Every recovery action MUST be:

- typed;
- authorized;
- executable by at least one declared client or runtime;
- testable;
- bounded by the same or a referenced authority policy;
- observable through recovery-started and recovery-completed events.

A text label without executable semantics is not a conforming recovery action.

## 12.5 Receipt checks

For each persistent mutation:

- exactly one canonical receipt MUST be produced per committed effect;
- duplicate idempotent requests MUST return or reference the same effect;
- the receipt MUST identify before and after versions;
- sensitive field values MAY be redacted, but changed paths MUST remain inspectable;
- receipt integrity SHOULD be verifiable;
- reversal MUST create a new receipt rather than delete the original.

## 12.6 Concurrency checks

Concurrency tests MUST include at least:

```text
two actors load version N
actor A commits N → N+1
actor B attempts commit with expected N
actor B receives conflict
no silent overwrite occurs
```

## 12.7 Lifecycle checks

State transitions MUST be explicitly allowed. A union of state labels is insufficient.

```text
current state
+ requested event
+ guards
→ permitted next state or typed outcome
```

## 12.8 Accessibility checks

Client renderers MUST ensure:

- errors are textual, not color-only;
- field errors are programmatically associated with fields;
- status changes are announced appropriately;
- focus moves only when necessary and predictably;
- verification dialogs have accessible names, descriptions, and focus control;
- recovery actions are keyboard and assistive-technology operable;
- motion-dependent feedback has a semantically equivalent reduced-motion representation.

## 12.9 Evidence checks

Evidence MUST preserve:

- source;
- collection time;
- subject;
- integrity where applicable;
- derivation history;
- acceptance or verification actor;
- confidence or uncertainty where applicable;
- status;
- supersession lineage.

Missing evidence MUST be represented as missing or unknown, never as zero or false unless the domain defines that equivalence.

## 12.10 Research checks

A Research Profile contract MUST additionally check:

- participant admission criteria;
- boundary validity;
- timescale;
- coupling relation;
- perturbation;
- uptake;
- recurrence or declared absence;
- event segmentation;
- observation model;
- trace ordering;
- alternative explanations;
- permitted and prohibited claims;
- falsifying conditions;
- uncertainty and missingness;
- distinction between record, event, trace, behavior, interpretation, and claim.

---

# 13. Verification methodology

Verification policy SHOULD be authored as a decision table.

Example:

| Reversible | Authority change | Affects others | Sensitive | Evidence confidence | Session assurance | Result |
|---:|---:|---:|---:|---:|---|---|
| yes | no | no | no | high | normal | none |
| no | no | no | no | high | normal | confirm |
| any | yes | any | any | high | high | reauthenticate |
| any | any | yes | yes | medium | normal | reauthenticate |
| any | any | any | any | low | any | prove |

The verification result MUST be evaluated server-side or by an equivalent trusted policy boundary.

The client MAY preview expected verification, but that preview is not authoritative.

---

# 14. Development methodology

## 14.1 Discover

Inventory every consequential interaction:

- UI actions;
- API mutations;
- background effects;
- administrative actions;
- imports and exports;
- agent tools;
- review decisions;
- recovery and rollback operations.

Do not begin with screens or endpoints. Begin with semantic intent.

## 14.2 Bound

For each interaction, declare:

- start;
- end;
- participants;
- environment;
- relevant state;
- timescale;
- external dependencies;
- what is explicitly outside the boundary.

## 14.3 Classify

Assign:

- interaction class;
- operational or research profile;
- mutation and reversibility class;
- synchronous, asynchronous, or durable execution;
- authority scope;
- evidence requirements;
- risk and verification factors.

## 14.4 Model state and transitions

Define:

- initial states;
- events;
- guards;
- transitions;
- terminal states;
- timeouts;
- retries;
- compensation;
- forbidden transitions.

## 14.5 Define outcomes before implementation

Enumerate:

- success;
- invalid input;
- missing target;
- permission block;
- verification required;
- evidence required;
- conflict;
- dependency failure;
- partial completion;
- cancellation;
- expiration;
- system failure.

Every check MUST map to an outcome.

## 14.6 Define recovery

For every non-terminal non-success outcome:

- identify the next valid action;
- type it;
- authorize it;
- specify its target;
- specify how completion is observed.

## 14.7 Define receipts and evidence lineage

Decide:

- what receipt is produced;
- which audit event is emitted;
- which evidence IDs are referenced;
- which values must be redacted;
- whether integrity signing is required;
- how reversal is linked.

## 14.8 Implement through the runtime

Use the common execution boundary. Do not recreate contract stages in route-local or component-local logic.

## 14.9 Generate adapters

Generate or validate:

- input validators;
- OpenAPI operations;
- client types;
- state-machine definitions;
- outcome renderers;
- problem mappings;
- event types;
- telemetry attributes;
- conformance tests;
- documentation.

## 14.10 Test adversarially

Test:

- direct API bypass;
- stale state;
- duplicate requests;
- missing evidence;
- expired verification;
- proof reuse;
- policy service failure;
- receipt-store failure;
- partial external effect;
- inaccessible rendering;
- invalid lifecycle transitions;
- recovery loops;
- unsupported versions.

## 14.11 Observe

Measure:

- attempts;
- outcome rates;
- verification rates;
- conflict rates;
- recovery-start rate;
- recovery-completion rate;
- time to recovery;
- abandonment;
- repeated failure;
- manual review;
- reversal.

## 14.12 Revise with version discipline

A change to meaning, required fields, outcome semantics, authority, verification, transition behavior, or compatibility requires version review.

Do not silently update a contract already used as evidence or relied on by clients.

---

# 15. Conformance model

## 15.1 Conformance levels

### Level 0 — Vocabulary

Uses canonical terms and IDs but does not execute the schema.

### Level 1 — Schema

Contract definitions and instances validate against normative schemas.

### Level 2 — Contract

Runtime behavior implements declared inputs, checks, outcomes, and closure.

### Level 3 — Governed Runtime

Authority, verification, concurrency, idempotency, receipts, audit, and recovery are enforced.

### Level 4 — Observable Runtime

Events, traces, recovery telemetry, provenance, and coverage reporting are complete and replayable.

### Level 5 — Research Profile

Observation, evidence, uncertainty, segmentation, coupling, recurrence, and claim boundaries conform to the research profile.

### Level 6 — Full Package

Schemas, runtime, clients, examples, migrations, documentation, conformance vectors, and independent review form a reproducible release.

## 15.2 Assurance dimensions

Each contract receives independent assurance states:

```text
declared
schema_valid
implemented
server_enforced
client_integrated
persisted
audited
tested
observed
independently_reviewed
```

These MUST NOT be compressed into one misleading score.

## 15.3 Hard gates

CI MUST fail for:

- unregistered persistent mutation;
- mutation without authority;
- verification-required mutation without trusted enforcement;
- persistent effect without receipt;
- mutable shared-state interaction without conflict policy;
- retryable effect without idempotency;
- blocking outcome without recovery or terminal reason;
- invalid event or outcome reference;
- missing required audit event;
- prohibited lifecycle transition;
- Research Profile claim without required evidence lineage.

## 15.4 Maturity indicators

The following MAY be scored but MUST NOT compensate for hard-gate failure:

- recovery quality;
- evidence richness;
- receipt detail;
- rollback support;
- accessibility evidence;
- observability completeness;
- production outcome coverage;
- independent review.

---

# 16. Coverage report

The canonical coverage report contains:

| Field | Meaning |
|---|---|
| Interaction | Stable ID and version |
| Implementation | Routes, handlers, jobs, components |
| Profile | Operational or research |
| Authority | Declared/enforced |
| Evidence | Declared/persisted |
| Verification | Declared/server-enforced |
| Concurrency | Policy and tests |
| Idempotency | Policy and tests |
| Outcomes | Declared/observed |
| Recovery | Typed/executable/tested |
| Receipt | Emitted/persisted/verifiable |
| Audit | Event emitted |
| Lifecycle | Transitions enforced |
| Accessibility | Renderer conformance |
| Tests | Unit, integration, adversarial |
| Production | Observed outcome coverage |
| Gaps | Critical and maturity gaps |

Recommended summary:

```text
Registered interactions:                    42
Implemented interactions:                   42
Unregistered persistent mutations:           0
Authority-enforced interactions:            42/42
Verification-required server paths:          9/9
Version-protected shared mutations:         18/18
Idempotent retryable effects:               13/13
Receipt-producing persistent effects:       24/24
Executable recovery outcomes:               57/60
Observed production outcome variants:       48/60
Research-profile evidence-complete episodes: 7/10
```

---

# 17. Versioning and compatibility

## 17.1 Independent versions

Version independently:

- protocol specification;
- contract schema;
- individual contract definitions;
- outcome registry;
- recovery registry;
- policy definitions;
- runtime;
- client adapters;
- event schema;
- dataset schema;
- research protocols;
- examples.

Equal version numbers MUST NOT imply compatibility.

## 17.2 Semantic versioning

Major:

- removes or renames required fields;
- changes interaction identity or meaning;
- changes outcome semantics;
- changes authority or verification guarantees;
- changes transition or closure semantics incompatibly.

Minor:

- adds optional fields;
- adds compatible outcome variants;
- adds new recovery capabilities;
- adds non-breaking metadata.

Patch:

- corrects documentation or validation without changing declared meaning.

## 17.3 Compatibility record

Cross-layer compatibility MUST be declared:

```yaml
compatibility:
  protocol: ">=0.1.0 <0.2.0"
  schema: "0.1.x"
  runtime: ">=0.3.0"
  clientProfile: "web-accessible@1"
```

## 17.4 Deprecation

A deprecated contract MUST declare:

- replacement;
- deprecation date;
- removal target;
- migration rule;
- compatibility impact;
- retained aliases;
- provenance.

---

# 18. Governance

## 18.1 Authority order

Recommended controlling order:

1. ratified protocol specification;
2. normative schemas and registries;
3. canonical contract definitions;
4. policy and workflow definitions;
5. conformance specifications;
6. reference implementation;
7. tests;
8. examples;
9. generated documentation;
10. archived material.

Code may reveal a contradiction but MUST NOT silently redefine the specification.

## 18.2 Change process

A normative change requires:

- issue or proposal;
- affected contract inventory;
- compatibility analysis;
- security and accessibility review;
- schema update;
- conformance vectors;
- migration guide;
- release note;
- owner approval.

Research-profile changes additionally require evidence and claim-boundary review.

## 18.3 Registries

Normative registries:

```text
contract registry
outcome registry
recovery-action registry
event registry
invariant registry
policy registry
schema registry
profile registry
```

Each registry entry includes:

- stable ID;
- preferred label;
- definition;
- status;
- version introduced;
- version deprecated;
- replacement;
- owner;
- dependencies;
- aliases;
- machine-readable kind.

---

# 19. Operational Profile

The Operational Profile is the default for software and product systems.

Required additions beyond the root schema:

- actor and target identity;
- capability and permission;
- structural input validation;
- explicit checks;
- verification policy;
- concurrency for shared mutable resources;
- idempotency for retryable effects;
- typed outcomes;
- executable recovery;
- receipts and events for persistent effects;
- accessible presentation;
- closure.

The Operational Profile treats an interaction as a governed state-changing or information-producing process. It does not require scientific evidence of reciprocal coupling.

---

# 20. FCI Research Profile

The FCI Research Profile extends, but does not replace, the Operational Profile.

```yaml
research:
  episodeIdentity:
    tokenId: episode_123
    typeId: icp:interaction/research.projection-choice
  participants:
    admissionRules: [...]
  environment:
    declaredVariables: [...]
  coupling:
    topology: [...]
    channels: [...]
    latencyAssumptions: [...]
  perturbation:
    eventTypes: [...]
  uptake:
    criteria: [...]
  recurrence:
    criteria: [...]
  observation:
    rawSources: [...]
    instrumentation: [...]
    segmentation: [...]
    attribution: [...]
  trace:
    ordering: partial
    replayRequirements: [...]
  evidence:
    lineage: [...]
    alternatives: [...]
    falsifiers: [...]
  uncertainty:
    missingness: [...]
    classificationUncertainty: [...]
  claims:
    permitted:
      - descriptive_event_sequence
      - bounded_transition_effect
    prohibited:
      - intention
      - understanding
      - strategy
      - causal_mechanism
```

The profile MUST preserve distinctions among:

```text
raw record
verified observation
coded event
episode trace
descriptive regularity
measured variable
latent interpretation
bounded claim
```

Claims may stop at any warranted level. They MUST NOT skip unsupported levels.

An Operational contract may be used as an apparatus contract in an FCI study. That does not automatically make its production telemetry scientific evidence. The Research Profile must declare instrumentation, segmentation, attribution, uncertainty, and permitted inference.

---

# 21. Fundamental/FE integration profile

Fundamental should consume ICP as a host-independent interaction declaration while preserving its own canonical lanes.

Recommended mapping:

| ICP | Fundamental/FE |
|---|---|
| Participant | Field body, software actor, host actor, data participant |
| State/context | Host/domain state plus field-readable state |
| Coupling | Forces and declared influence paths |
| Association | Relationships; not automatically physical coupling |
| Projection | Projection registry and host adapters |
| Observation | Query, snapshot, diff, replay, feedback channels |
| Authority | Capability-scoped facade and host policy |
| Trigger/event | Canonical field events or host events |
| Outcome | Host/client outcome renderer |
| Receipt | Snapshot/diff/replay or external signed receipt |
| Invariant | Field, host, accessibility, and policy invariants |

Required FE boundaries:

- agent-readable does not imply agent-writable;
- projection reveals and must not mutate;
- forces couple;
- relationships associate;
- policy limits;
- capability and authority remain distinct;
- host/domain truth is not replaced by field state;
- experimental FE APIs must not be represented as stable ICP guarantees;
- ICP conformance must not be presented as proof of FCI theory.

ICP vocabulary SHOULD remain in adapters and documentation unless a term already belongs in FE’s protected API.

---

# 22. Client runtime

A conforming client runtime SHOULD expose:

```ts
interaction.execute(id, input, options)
interaction.resume(instanceId, recovery)
interaction.cancel(instanceId)
interaction.inspect(instanceId)
interaction.receipt(receiptId)
```

Canonical client states:

```ts
type InteractionClientState =
  | { status: "ready" }
  | { status: "validating" }
  | { status: "verification_required"; challenge: Challenge }
  | { status: "processing"; progress?: Progress }
  | { status: "needs_review"; caseId: string }
  | { status: "conflicted"; problem: Problem }
  | { status: "partially_completed"; outcome: BatchOutcome }
  | { status: "completed"; receipt?: ChangeReceipt }
  | { status: "failed"; problem: Problem }
  | { status: "cancelled" }
  | { status: "expired" };
```

The client MUST NOT independently weaken authority or verification requirements.

---

# 23. Event and trace model

Every meaningful stage SHOULD emit a typed event:

```text
interaction.instantiated
interaction.started
input.invalid
authority.allowed
authority.denied
evidence.resolved
evidence.insufficient
check.passed
check.failed
verification.required
verification.completed
verification.failed
transition.started
transition.committed
transition.compensated
interaction.conflicted
interaction.completed
interaction.failed
recovery.started
recovery.completed
interaction.closed
```

Event requirements:

- globally unique event ID;
- interaction ID and version;
- instance ID;
- request ID;
- trace ID;
- actor or runtime ID;
- timestamp;
- typed payload;
- previous and next state where applicable;
- idempotency key where applicable;
- provenance;
- retention class.

The event log SHOULD be append-only. Corrections SHOULD be new events.

---

# 24. Batch and distributed interactions

A batch interaction is a parent instance containing item instances.

```json
{
  "batchId": "batch_123",
  "attempted": 100,
  "completed": 91,
  "blocked": 3,
  "failed": 2,
  "unchanged": 4,
  "items": [
    {
      "itemId": "item_1",
      "status": "completed",
      "receiptId": "rcpt_1"
    },
    {
      "itemId": "item_2",
      "status": "blocked",
      "problem": {
        "class": "needs_review"
      }
    }
  ]
}
```

Distributed interactions MUST declare:

- coordination boundary;
- participant services;
- delivery semantics;
- timeout;
- retry policy;
- idempotency;
- compensation;
- partial failure;
- finality;
- correlation.

A distributed contract MUST NOT claim atomicity unless the implementation provides it.

---

# 25. Long-running interactions

Long-running interactions require a durable instance:

```ts
type InteractionInstance = {
  id: string;
  contractId: string;
  contractVersion: string;
  state: string;
  actorId: string;
  subjectIds: string[];
  startedAt: string;
  updatedAt: string;
  expiresAt?: string;
  currentStep?: string;
  completedSteps: string[];
  pendingRequirements: Requirement[];
  evidenceIds: string[];
  receiptIds: string[];
  parentInstanceId?: string;
  branchId?: string;
};
```

The runtime MUST support:

- pause;
- resume;
- timeout;
- bounded retry;
- cancellation;
- review;
- evidence replacement;
- compensation;
- explicit terminal closure.

---

# 26. Security model

Required security invariants:

```text
AUTHORITY_FAILS_CLOSED
CAPABILITY_IS_NOT_PERMISSION
SELF_ROLE_MUTATION_PREVENTED
SELF_ELEVATION_PREVENTED
LAST_ADMIN_PROTECTED
CROSS_SCOPE_MUTATION_PREVENTED
STALE_AUTHORITY_REJECTED
PRIVILEGE_CHANGE_INVALIDATES_SESSIONS
DISABLED_ACTOR_CANNOT_MUTATE
VERIFICATION_IS_INPUT_BOUND
VERIFICATION_IS_SINGLE_USE
RECEIPTS_ARE_APPEND_ONLY
READ_CAPABILITY_DOES_NOT_GRANT_WRITE
PROJECTION_DOES_NOT_MUTATE
```

Projects MAY add domain invariants but SHOULD use stable IDs and reusable definitions.

---

# 27. Privacy and evidence lifecycle

Evidence-bearing interactions MUST declare:

- purpose;
- owner or subject;
- classification;
- source;
- collection actor;
- integrity digest;
- storage class;
- encryption requirement;
- access policy;
- retention;
- review status;
- derived artifacts;
- supersession;
- deletion eligibility;
- legal hold if applicable.

Lifecycle example:

```text
received
processing
extracted
needs_review
verified
rejected
superseded
deletion_pending
deleted
```

Valid transitions MUST be declared. Deletion SHOULD be represented as a governed interaction with a receipt.

---

# 28. Anti-patterns

The following are non-conforming or architecturally weak:

- route-local authorization without a shared policy boundary;
- frontend-only verification;
- ad hoc `confirm()` as security enforcement;
- plain string errors;
- HTTP status as the only outcome type;
- generic “something went wrong” messages;
- textual recovery without executable semantics;
- success without a receipt for persistent changes;
- last-write-wins without an explicit conflict policy;
- retryable effects without idempotency;
- lifecycle labels without transition enforcement;
- evidence booleans without provenance;
- external data silently overwriting local decisions;
- deleting failed or abandoned traces;
- treating a checksum as proof of recoverability;
- treating schema validity as behavioral conformance;
- treating test counts as contract coverage;
- treating a trace as direct evidence of strategy or intention;
- forcing incomparable interactions into one score;
- allowing equal version numbers to imply compatibility;
- allowing generated documentation to override normative source.

---

# 29. Repository structure

Recommended package:

```text
/interaction-contract
  /spec
    INTERACTION_CONTRACT_PROTOCOL.md
    VERSIONING.md
    GOVERNANCE.md
    CONFORMANCE.md
  /schema
    *.schema.json
  /registry
    contracts.json
    outcomes.json
    recovery-actions.json
    events.json
    invariants.json
    profiles.json
  /policies
    verification/
    authority/
  /examples
    operational/
    research/
    invalid/
  /conformance
    vectors/
    expected/
    runner/
  /adapters
    openapi/
    rfc9457/
    statecharts/
    frontend/
    workflow/
    fci/
    fundamental/
  /docs
    authoring-guide.md
    migration-guide.md
    implementation-guide.md
```

---

# 30. Initial release gates

Version `0.1.0` is ready when:

- the root and modular schemas validate;
- at least five operational examples validate;
- at least two research-profile examples validate;
- invalid fixtures fail for the intended reason;
- outcome, recovery, event, invariant, and profile registries exist;
- conformance levels are executable;
- a reference runtime executes one atomic, one batch, and one long-running interaction;
- RFC 9457 and OpenAPI adapters are demonstrated;
- verification challenges are actor-, target-, input-, expiry-, and single-use bound;
- concurrency and idempotency adversarial tests pass;
- change receipts are persisted and replayable;
- one Fundamental adapter and one FCI research profile are documented;
- specification, schemas, software, and examples are independently versioned;
- known limitations and non-claims are published.

---

# 31. Canonical concise definition

> **The Interaction Contract Protocol is a versioned composition protocol for declaring, executing, observing, explaining, and governing bounded interactions. It specifies identity, participants, boundaries, state, authority, evidence, inputs, checks, verification, transitions, invariants, outcomes, recovery, receipts, observation, uncertainty, and closure while preserving the distinct authority of domain, policy, evidence, workflow, client, and measurement systems.**

---

# 32. Canonical execution formula

```text
Interaction =
  declared intent
  + bounded participants and state
  + available and authorized opportunity
  + validated input
  + evidence-governed checks
  + consequence-derived verification
  + concurrency-safe transition
  + invariant preservation
  + typed outcome
  + executable recovery
  + receipt and trace
  + explicit closure
```

For the Research Profile:

```text
Research interaction episode =
  operational interaction contract
  + declared coupling
  + perturbation and uptake
  + recurrence criterion
  + observation model
  + evidence lineage
  + uncertainty
  + bounded permitted claims
```

---

# 33. Decision

ICP should proceed as a standalone protocol with adapters for FE/Fundamental and FCI.

It should not be embedded inside either project’s canonical vocabulary because:

- the operational protocol is broader than the strict FCI interaction-episode definition;
- FCI requires evidentiary and scientific constraints that ordinary product interactions do not;
- Fundamental has a protected vocabulary and host/runtime architecture that should consume the protocol through adapters;
- independent versioning prevents a protocol update from silently redefining either theory or runtime behavior.

The correct relationship is:

```text
Interaction Contract Protocol
  ├── Operational Profile
  │     ├── Web/API applications
  │     ├── Administrative systems
  │     ├── Agents and tools
  │     └── Fundamental adapter
  └── Research Profile
        ├── FCI study contracts
        ├── Experimental apparatus
        ├── Evidence and trace packages
        └── Comparison and measurement dependencies
```

========================================================================
## FILE: LICENSE (21 lines, 1.0 KiB)
========================================================================

MIT License

Copyright (c) 2026 Zach Shallbetter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

========================================================================
## FILE: README.md (81 lines, 5.4 KiB)
========================================================================

# Interaction Contract Protocol

ICP is a specification for declaring a consequential interaction before it runs: who takes part, where it starts and ends, what is allowed, which checks and verification it needs, what outcomes it can produce, how it recovers, and what record it leaves. It binds existing standards such as JSON Schema, OpenAPI, RFC 9457 problem details and statecharts into one lifecycle instead of replacing them.

**Identifier:** `icp:protocol/interaction-contract` · **Version:** 0.1.0 · **Status:** Normative candidate · **Date:** 2026-07-24

## What it does

An Interaction Contract is a stable, versioned declaration of a bounded interaction among people, software, services, agents, devices or institutions. It covers identity, participants and roles, boundary, state and context, the actions that are available, permitted, enabled and exposed, required inputs and checks, verification, transitions and effects, invariants, outcomes, failure and recovery, receipts and closure. The protocol defines how to write such a contract, how a runtime must honor it, and how to test that it does.

It has two profiles that share identity, lifecycle, outcome and conformance structures: an **Operational Profile** for products, APIs, workflows, agents and admin tools, and a **Research Profile** for Foundations of Computational Interaction studies, which adds coupling, perturbation, uptake, observation, evidence lineage and bounded claims.

## Features

- A compact formal definition of a contract as a tuple of 21 declared parts, from identity to closure.
- Foundational principles stated as separations: capability is not permission, evidence is not decision, observation is not interpretation, and conformance is not proof of quality.
- A canonical instance lifecycle of 20 states, with required declaration of terminal states (completion is only one valid closure).
- Stable identifier grammar, a canonical authoring format, a field schema, and wire envelopes for requests, success, problems, verification challenges and change receipts.
- Semantic checks grouped by definition, runtime, outcome, recovery, receipts, concurrency, lifecycle, accessibility, evidence and research.
- A development method from discovery and bounding through adversarial testing, observation and versioned revision.
- Seven conformance levels, from vocabulary (0) to a full independently reviewed package (6).
- Sections on batch, distributed and long-running interactions, security, privacy and evidence lifecycle, and named anti-patterns.

## How it works

The specification's execution formula summarizes the model:

```text
Interaction =
  declared intent
  + bounded participants and state
  + available and authorized opportunity
  + validated input
  + evidence-governed checks
  + consequence-derived verification
  + concurrency-safe transition
  + invariant preservation
  + typed outcome
  + executable recovery
  + receipt and trace
  + explicit closure
```

A Research Profile episode adds declared coupling, perturbation and uptake, a recurrence criterion, an observation model, evidence lineage, uncertainty and bounded permitted claims.

ICP takes its epistemic distinctions from Foundations of Computational Interaction. The evidence and verification outputs it emits are what the Evidence Qualification Protocol consumes. Section 33 records the decision to keep ICP standalone, with adapters, instead of embedding it in either FCI or a host runtime's vocabulary.

## What this explores

- Treating failure, partial completion, reversal and recovery as declared parts of an interaction rather than error handling added later.
- Composing existing interface standards under one contract instead of inventing a new wire format.
- Using one contract structure for everyday product flows and for research apparatus without collapsing their different sources of truth.
- Conformance levels that separate "the schema validates" from "the runtime enforces authority and recovery" from "someone else has reviewed it".

## Contents

| File | What it holds |
| :--- | :--- |
| [`INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md`](INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md) | The single normative artifact, sections 0–33, including a reference JSON Schema in section 11 |
| [`protocol-manifest.json`](protocol-manifest.json) | Protocol identity, status, normative artifacts and exports |
| [`package.json`](package.json) | Package metadata |

The companion artifacts the specification names (standalone JSON Schema files, outcome and recovery registries, a conformance suite and a migration guide) are not in this folder. Section 29 describes the recommended package layout for them, and section 30 lists the gates for calling 0.1.0 ready.

## How to read this

The specification is one long document (about 2,250 lines). A practical order:

1. Section 0 (abstract) and section 31 (the one-paragraph definition).
2. Section 4, foundational principles. Most of the design follows from these separations.
3. Sections 5 and 9 for the lifecycle states, interaction classes, verification levels, outcome classes and recovery actions.
4. Section 15 for conformance levels, then section 30 for the release gates.
5. Sections 19–21 for the Operational, FCI Research and integration profiles, and section 28 for anti-patterns.

Status: normative candidate. Schema conformance proves structural validity only (section 4.10). The protocol has not been reviewed outside the author.

## License

MIT © Zach Shallbetter

Built by [Zach Shallbetter](https://zachshallbetter.com).

========================================================================
## FILE: package.json (8 lines, 0.4 KiB)
========================================================================

{
  "name": "interaction-contract-protocol",
  "version": "0.1.0",
  "description": "Interaction Contract Protocol (ICP): declaring and governing consequential interactions. Single normative artifact; see protocol-manifest.json for the identity and export declaration.",
  "license": "UNLICENSED",
  "private": true,
  "files": ["INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md", "protocol-manifest.json"]
}

========================================================================
## FILE: protocol-manifest.json (9 lines, 0.6 KiB)
========================================================================

{
  "id": "icp:protocol/interaction-contract",
  "version": "0.1.0",
  "status": "normative-candidate",
  "normativeArtifacts": ["INTERACTION_CONTRACT_PROTOCOL_v0.1.0.md"],
  "identityRule": "The stable id does not change for editorial corrections or compatible extensions; a semantic replacement receives a new id (spec §7.2).",
  "exports": ["interaction lifecycle", "canonical instance states", "outcome classes", "verification levels", "change receipts", "recovery actions", "conformance levels and assurance dimensions"],
  "license": "unspecified — owner selection pending"
}