About the process contract
A process describes how a team works. The harness runs it. The process contract is the agreement between them: what any process must declare, and what the harness guarantees in return.
The contract is fixed by the product. A process fills it in through its declaration; it cannot change the rules.
How it works
- 1
The process declares
It supplies schemas for its elements and declares its scope, lifecycle, effects, events and extensions.
- 2
The harness owns the Run
The harness drives one Intent version under one pinned process and policy version, and holds identity and authority.
- 3
The harness checks every link
It validates links, versions and freshness between objects. When something they depend on changes, the objects that bound it go stale.
- 4
Gates decide what may happen next
Gates evaluate the contract state at four points and return one result shape, whichever process is running.
The six elements
| Element | Meaning |
|---|---|
| Intent | What is to be achieved: constraints, authorized scope, acceptance conditions |
| Execution | Work by an actor against an Intent. A planning Execution may produce or amend Intent |
| Change | The exact proposed revision: base, head, patch identity |
| Evidence | Checks performed on an exact Change, with their results |
| Review | An assessment of an exact Change against an exact Intent and policy |
| Decision | Whether the current Intent, Change, Evidence and Review satisfy the conditions for the next controlled action |
The Run
The Run is owned by the harness, not the process. It is the container that drives one Intent version under one pinned process version and policy version.
It is the unit for execution control, attempts, traces, outcomes and telemetry.
Identities
Every object binds the identities of what it depends on.
| Object | Binds |
|---|---|
| Run | run_id, intent_id, intent_version, process_version, policy_version |
| Change | base_revision, head_revision, patch_identity |
| Review | Adds review_ |
| Decision | Adds evidence_ids, review_ids |
The process supplies the schemas. The harness validates links, versions and freshness.
Lifecycle
An object is current only while every identity it binds is current. A new Intent version, a new revision, a new policy or a ruling makes the objects that bound the old one stale.
Each leg ends in one of five outcomes:
| Outcome | Terminal |
|---|---|
completed | Yes |
paused | No |
failed | Yes |
cancelled | Yes |
exhausted | Yes |
A pause names who acts: the Operator (for the environment) or the Principal (for a ruling). See Pauses and rulings.
Authority
The harness owns identity and authority: to rule, to waive, to change policy and to merge. A process declares which acts need authority; it cannot grant it.
The declaration
A process makes twelve declarations: identity, Intent, Execution, Change, Evidence, Review, Decision, scope, lifecycle, effects, events and extensions.
Every fact in it is one of known, absent, unavailable, invalid or inapplicable. Missing is never success.
Generic gates
A gate is a deterministic evaluation of contract state. Generic gates are the questions every process must answer, such as "is the evidence current?" or "is the review valid?". There are twelve generic gate families:
| Family | Question |
|---|---|
| Contract validity | Are required objects well formed and compatible? |
| Authorization | Was the actor authorized for this Execution or effect? |
| Provenance | Can the Change be traced to its producing Executions and actors? |
| Scope | Are protected or forbidden paths untouched unless authorized, and is every path beyond the declared boundary recorded and presented to Review? |
| Evidence completeness | Is all policy-required Evidence present and applicable? |
| Evidence freshness | Does the Evidence apply to the current Change? |
| Review validity | Is each required Review complete, independent and correctly bound? |
| Intent freshness | Was the Change reviewed against the current Intent? |
| Decision validity | Is the Decision derived from current inputs and pinned policy? |
| Terminal completeness | Did every stopped execution leg record a typed outcome? |
| Effect safety | Is a consequential operation authorized and reconcilable? |
| Traceability | Can the outcome be traced through the complete contract graph? |
An inapplicable gate must be declared and is recorded. An unavailable gate never satisfies a required one.
A process may add gates of its own. It can never bypass the generic ones.
The gate result
Every gate, generic or process-specific, returns one result shape:
| Field | Carries |
|---|---|
gate_id | Which gate ran |
gate_version | Which version of it |
enforcement_ | Where it ran |
authority | The authority it ran under |
| Bound identities | The identities of the objects it evaluated |
| Outcome | pass, fail, unavailable or inapplicable |
| Reason | Why |
The four enforcement points
Gates run at four points:
- Before execution or action: validate input, authority and capability.
- Before commit or publication: validate the Change and local Evidence.
- At the code host: re-evaluate required conditions on the current revision. This point enforces; it is the backstop for every writer the first two cannot reach.
- Continuous audit: after the action, surface drift and continuing obligations.
How Vinaya maps onto them
The Vinaya process enforces its gates in three rings. Each ring sits on the enforcement points:
| Vinaya ring | Enforcement points | Where it runs |
|---|---|---|
| Ring 0 | 1 and 2 | On your machine, at commit and push |
| Ring 1 | 3 | On the pull request and at Issue and pull-request writes |
| Ring 2 | 4 | After merge, on every merge and once a day |
Of Vinaya's 37 checks, 17 implement generic gate families and 20 are Vinaya-specific.
See Gates for the rings and every check.
Adapters
Adapters connect the harness to external systems. There are seven kinds. Adapters perform and observe; authorization, idempotency and reconciliation stay with the harness. See Adapters.
The Log
There is one portable event contract. Common events are written by the harness function that owns the act. A process adds its own events, namespaced. The Log never authorizes or recovers a Run. See Logging for what a process supplies, and Log for the feature.
Conformance
A process conforms when:
- its declaration activates with no hidden defaults;
- every object links;
- generic gates cover all four outcomes;
- invalidation is transitive;
- events suffice for Mission Control and statistics;
- unsupported behaviour is refused precisely;
- semantics hold across adapters.
See Conformance.
Configuration
None. The contract is fixed by the product. A process parameterizes it through its declaration.