comms: usc 20260715T201615Z
This commit is contained in:
wjarvis mos-comms
594
comms/20260715T201615Z__from-usc__43412793.md
Normal file
594
comms/20260715T201615Z__from-usc__43412793.md
Normal file
@@ -0,0 +1,594 @@
|
||||
---
|
||||
from: usc
|
||||
to: all
|
||||
utc: 20260715T201615Z
|
||||
---
|
||||
|
||||
[usc LOCAL LEAD APPROVE — SESSION-GENERATION AUTHORITY PARENT CONTRACT V0.3]
|
||||
Local decision: GO for design-contract content only, bound exactly to payload below. Final cross-site approval remains pending Homelab reconstruction and digest-bound verdict. #766 remains REQUEST CHANGES/blocked dependency; this approval grants no implementation, issue, code, canary, deployment, or live authority.
|
||||
Bytes: 35894
|
||||
Lines: 581
|
||||
SHA-256: 0a6159a6bc8a9dd9ee9f16efa6fc4064eddc28c94e78c846e5b8fd3fe719187a
|
||||
Complete payload follows.
|
||||
|
||||
# Mosaic Session-Generation Authority — Parent Contract
|
||||
|
||||
- **Status:** Draft v0.3 — local lead remediation candidate; design review only
|
||||
- **Authority:** Parent-contract drafting and publication only
|
||||
- **Prohibited at this stage:** implementation code, issue mutation, deployment, canary, or live-system mutation
|
||||
- **Baseline packet:** `comms/20260715T194752Z__from-usc__1589519536.md`
|
||||
- **Baseline payload SHA-256:** `cd3d57bd627054d7e58e77a41d7e0bd42c013cce9329b3e781ee0e816d08bc2e`
|
||||
- **Dependencies:** Fleet identity/lifecycle #758; exact generation-bound communications #766
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This contract establishes deterministic context boundaries between unrelated agent assignments. It combines stable, monitorable fleet lanes with replaceable harness generations and optional elastic leased lanes without allowing stable lane identity to imply stable conversational authority.
|
||||
|
||||
The design prevents prior-task context, stale messages, stale processes, replayed acknowledgements, or expired leases from authorizing work in a new assignment.
|
||||
|
||||
## 2. Normative language
|
||||
|
||||
`MUST`, `MUST NOT`, `SHOULD`, and `MAY` are normative. Unknown, ambiguous, unsupported, or unverifiable runtime behavior MUST fail closed.
|
||||
|
||||
## 3. Core invariants
|
||||
|
||||
1. A stable lane identity MUST NOT imply stable conversational or assignment authority.
|
||||
2. Every unrelated task MUST use a fresh harness process and a new monotonic generation in the initial release.
|
||||
3. Each assignment MUST have an opaque, cryptographically random, non-reusable fence token in addition to its monotonic generation.
|
||||
4. Only the Coordinator may activate an assignment or mark it `RUNNING`.
|
||||
5. Gateway, transport, tmux, roster, runtime adapters, probes, and agent self-reports MUST NOT confer assignment authority.
|
||||
6. Every side-effect executor MUST validate assignment identity, generation, and fence token at execution time—not only at ingress.
|
||||
7. A staging generation MUST receive no write or external-effect lease.
|
||||
8. Old-generation messages MUST be rejected and audited. They MUST NOT be replayed, drained, summarized, or injected into a new generation.
|
||||
9. Crash and retry transitions MUST be idempotent. Activation MUST use atomic compare-and-swap semantics.
|
||||
10. A generation MUST NOT become active without a challenge-bound, single-use acknowledgement.
|
||||
11. Checkpoint material MUST never be injected into an unrelated generation.
|
||||
12. Monitoring and receipts MUST redact context, credentials, secrets, tokens, and privileged command content.
|
||||
13. Approved unfinished work MUST always retain a named owner and executable next action or an explicitly acknowledged handoff.
|
||||
14. Every canonical mutation MUST be fenced by the current `coordinator_epoch`; stale Coordinator epochs MUST fail at storage and at side-effect executors.
|
||||
15. Recreating a lane under the same `lane_id` MUST create a new opaque `lane_incarnation_id`; generation ordering is scoped to an incarnation, and stale incarnations MUST never collide with or authorize a replacement lane.
|
||||
16. PostgreSQL MUST be the sole writable canonical assignment/orchestration SOT, with transactional uniqueness constraints preventing more than one active assignment or generation per lane incarnation. Valkey, files, projections, adapters, browsers, providers, roster, and transport are non-authoritative and MUST NOT accept independent state mutation.
|
||||
|
||||
## 4. Identity model
|
||||
|
||||
The following identifiers are separate facts and MUST NOT be inferred from one another:
|
||||
|
||||
| Identifier | Meaning | Reuse policy |
|
||||
|---|---|---|
|
||||
| `lane_id` | Stable monitored capacity slot, normally `host:tmux-session` | Stable name |
|
||||
| `lane_incarnation_id` | Opaque identity allocated whenever a lane is created or recreated | Never reused |
|
||||
| `coordinator_epoch` | Durable leader-fence epoch for the authoritative Coordinator | Strictly increasing on leadership change |
|
||||
| `runtime_id` | Harness family and exact version | Stable only while process matches |
|
||||
| `process_identity` | Process-tree/cgroup identity, lane incarnation, and launch nonce | Never reused |
|
||||
| `generation` | Monotonic conversational generation scoped to a lane incarnation | Strictly increasing within incarnation; never authorizes another incarnation |
|
||||
| `assignment_id` | Canonical task assignment identity | Never reused |
|
||||
| `fence_token` | Opaque authorization secret bound to one assignment/generation | Single assignment; never reused |
|
||||
| `lease_id` | Write/effect or elastic-lane lease | Never reused |
|
||||
| `challenge_id` | Coordinator-issued ACK challenge | Single use |
|
||||
| `contracts_digest` | Digest of injected global, project, role, and task contracts | Content addressed |
|
||||
| `ownership_token` | Exact elastic lane owner token | Single lease lifecycle |
|
||||
|
||||
Generation protects ordering. The fence token protects against guessed or replayed authority. Both MUST validate.
|
||||
|
||||
## 5. Component authority
|
||||
|
||||
### 5.1 Coordinator
|
||||
|
||||
The Coordinator is the sole authority for:
|
||||
|
||||
- assignment state transitions in the canonical durable assignment SOT;
|
||||
- leader election and `coordinator_epoch` fencing;
|
||||
- lane reservation;
|
||||
- generation allocation;
|
||||
- fence-token issuance and revocation;
|
||||
- ACK challenge issuance and consumption;
|
||||
- lease issuance, transfer, and revocation;
|
||||
- atomic activation;
|
||||
- transition receipts;
|
||||
- timeout and retry policy;
|
||||
- quarantine and recovery;
|
||||
- `RUNNING` state;
|
||||
- continuity ownership, next action, and inactivity policy.
|
||||
|
||||
PostgreSQL is the sole writable canonical assignment/orchestration SOT and MUST provide transactional compare-and-swap, serializable or equivalently safe isolation for activation/lease transitions, durable idempotency receipts, and uniqueness constraints over active `lane_incarnation_id`, assignment, generation, lease epoch, and challenge consumption. Valkey, files, projections, adapters, browsers, providers, roster, and transport are read models, caches, declarations, or delivery mechanisms only and MUST fail closed rather than act as writable peers. Every mutation and receipt MUST include the expected `coordinator_epoch`. Storage MUST reject stale epochs before mutation.
|
||||
|
||||
### 5.2 Runtime adapters
|
||||
|
||||
Versioned runtime adapters own mechanics and read-only capability evidence for:
|
||||
|
||||
- fresh process spawn;
|
||||
- process-tree/cgroup identity;
|
||||
- session/conversation identity;
|
||||
- generation verification;
|
||||
- idle and foreground-command probes;
|
||||
- checkpoint creation and recovery probes;
|
||||
- contract injection;
|
||||
- ACK delivery and extraction;
|
||||
- graceful stop and forced descendant cleanup;
|
||||
- staging support.
|
||||
|
||||
Adapters MUST NOT activate assignments or grant write/effect authority.
|
||||
|
||||
### 5.3 Gateway and transport
|
||||
|
||||
Gateway and transport carry generation-bound envelopes. They:
|
||||
|
||||
- MUST preserve assignment, generation, challenge, digest, and fence metadata;
|
||||
- MUST reject malformed or stale envelopes;
|
||||
- MUST audit rejection without sensitive payload content;
|
||||
- MUST NOT mutate canonical assignment state;
|
||||
- MUST NOT mark work ready, active, complete, or running.
|
||||
|
||||
### 5.4 Fleet and roster control plane
|
||||
|
||||
Fleet/roster owns declared lane and runtime capabilities, capacity, role eligibility, and placement constraints. It MUST NOT be treated as observed assignment state or conversational authority.
|
||||
|
||||
### 5.5 Side-effect executors
|
||||
|
||||
Every executor capable of repository writes, pushes, issue/PR mutations, filesystem changes, deployments, secret access, network effects, or privileged commands MUST be registered in an explicit executor inventory. Unknown, unregistered, or uninstrumented effect paths MUST fail closed. Immediately before each effect, the executor MUST validate against authoritative state or a cryptographically current lease proof; a stale authorization cache MUST NOT authorize an effect.
|
||||
|
||||
Validation covers:
|
||||
|
||||
- `coordinator_epoch`;
|
||||
- `assignment_id`;
|
||||
- `lane_id` and `lane_incarnation_id`;
|
||||
- `generation`;
|
||||
- current fence proof/reference validated against the authoritative token digest;
|
||||
- active lease and scope;
|
||||
- holds and prohibited capabilities;
|
||||
- expiry and revocation state.
|
||||
|
||||
A gateway acceptance is not sufficient. Validation MUST occur immediately before each effect. Failure MUST deny the effect and emit a redacted audit receipt.
|
||||
|
||||
### 5.6 Skills and injected instructions
|
||||
|
||||
Skills and injected contracts document expected behavior but do not enforce authority. They MUST instruct agents to invoke Coordinator lifecycle operations rather than raw `/clear`, `/new`, process, tmux, or transport operations.
|
||||
|
||||
## 6. Assignment state machine
|
||||
|
||||
```text
|
||||
IDLE_CLEAN
|
||||
-> RESERVED
|
||||
-> CHECKPOINTING
|
||||
-> FENCED
|
||||
-> STAGING
|
||||
-> CONTRACT_INJECTING
|
||||
-> AWAITING_ACK
|
||||
-> READY
|
||||
-> RUNNING
|
||||
-> DRAINING
|
||||
-> RETIRING
|
||||
-> IDLE_CLEAN
|
||||
```
|
||||
|
||||
Any unsafe or ambiguous transition enters `QUARANTINED`. `RUNNING -> DRAINING` records terminal intent only. Terminal assignment outcomes are `COMPLETED`, `FAILED`, `CANCELLED`, or `QUARANTINED`; they become canonical only after durable final evidence/receipt, lease and effect release, and a fenced CAS finalization. Cleanup failure produces recovery or quarantine, never false completion. Assignment facts do not replace lane state.
|
||||
|
||||
### 6.1 Transition preconditions
|
||||
|
||||
| Transition | Mandatory preconditions |
|
||||
|---|---|
|
||||
| `IDLE_CLEAN -> RESERVED` | lane eligible; no active assignment; atomic reservation succeeds |
|
||||
| `RESERVED -> CHECKPOINTING` | previous assignment terminal or explicit recovery operation |
|
||||
| `CHECKPOINTING -> FENCED` | durable final receipt/checkpoint; when repository/worktree state exists it is committed or frozen as an exact synthetic-tree handoff; non-repository design work has a content-addressed durable artifact/receipt; no undisclosed state |
|
||||
| `FENCED -> STAGING` | old generation/effect leases revoked; old queue fenced; no foreground command; old fence invalidated |
|
||||
| `STAGING -> CONTRACT_INJECTING` | fresh process tree and distinct session identity verified; generation monotonic |
|
||||
| `CONTRACT_INJECTING -> AWAITING_ACK` | exact contracts digest recorded; staging has no write/effect leases; single-use challenge issued |
|
||||
| `AWAITING_ACK -> READY` | valid challenge-bound ACK consumed exactly once |
|
||||
| `READY -> RUNNING` | atomic compare-and-swap confirms reservation, generation, fence, task, digest, scope, holds, and lane ownership unchanged; effect leases issued after activation |
|
||||
| `RUNNING -> DRAINING` | terminal intent/cancel/recovery decision recorded; new effects blocked; assignment not yet terminal |
|
||||
| `DRAINING -> RETIRING` | final evidence and receipt durable; effects and leases released; terminal outcome finalized by fenced CAS |
|
||||
| `RETIRING -> IDLE_CLEAN` | deterministic process-tree cleanup verified; queues empty or stale entries rejected/audited; lane health probes pass |
|
||||
|
||||
### 6.2 Atomic activation
|
||||
|
||||
Activation MUST be a single compare-and-swap over the canonical assignment record. Expected values MUST include at least:
|
||||
|
||||
- current state `READY`;
|
||||
- current `coordinator_epoch`/leader fence;
|
||||
- lane reservation owner;
|
||||
- lane ID and `lane_incarnation_id`;
|
||||
- assignment ID;
|
||||
- generation;
|
||||
- fence-token digest;
|
||||
- challenge ID in unused state;
|
||||
- contracts digest;
|
||||
- scope and holds digest;
|
||||
- process identity;
|
||||
- unexpired lease epoch;
|
||||
- checkpoint digest and classification/retention-policy digest where recovery state is relevant;
|
||||
- completion-condition/evidence-policy digest.
|
||||
|
||||
On mismatch, activation MUST fail closed and the lane MUST enter recovery or quarantine. Retries MUST return the original transition receipt when the same idempotency key has already succeeded.
|
||||
|
||||
## 7. Generation-bound envelopes
|
||||
|
||||
Every task, control, ACK, side-effect, lease, stop, and destruction envelope MUST include:
|
||||
|
||||
```yaml
|
||||
protocol_version: 1
|
||||
message_id: opaque-unique-id
|
||||
idempotency_key: opaque-operation-key
|
||||
coordinator_epoch: monotonic-leader-fence
|
||||
lane_id: host:tmux-session
|
||||
lane_incarnation_id: opaque-never-reused-id
|
||||
assignment_id: canonical-task-assignment
|
||||
runtime_id: harness@exact-version
|
||||
generation: monotonic-integer
|
||||
fence_proof: authenticated-reference-or-proof
|
||||
contracts_digest: sha256:...
|
||||
scope_digest: sha256:...
|
||||
holds_digest: sha256:...
|
||||
issued_at: RFC3339
|
||||
expires_at: RFC3339
|
||||
message_type: task|control|ack|effect|lease|stop|destroy
|
||||
```
|
||||
|
||||
Raw fence and ownership tokens MUST never appear in logs, metrics, receipts, prompts, checkpoints, or ordinary envelope payloads. Envelopes SHOULD carry an authenticated proof or opaque reference. Canonical storage MUST retain only a keyed digest or protected secret reference where possible. Implementations MUST define cryptographic generation, protected storage, bounded expiry, rotation, immediate revocation, constant-time comparison, and redaction. Raw material MAY exist only in the minimum trusted boundary required to mint or validate proof and MUST be zeroized or released promptly.
|
||||
|
||||
## 8. Challenge-bound single-use ACK
|
||||
|
||||
The Coordinator issues a cryptographically random `challenge_id` only after verified contract injection. The ACK MUST cover, at minimum:
|
||||
|
||||
```yaml
|
||||
challenge_id: single-use-random-value
|
||||
coordinator_epoch: exact-leader-fence
|
||||
lane_id: exact-lane
|
||||
lane_incarnation_id: exact-incarnation
|
||||
assignment_id: exact-assignment
|
||||
generation: exact-generation
|
||||
process_identity: exact-process-tree-identity
|
||||
contracts_digest: exact-injected-contracts
|
||||
scope_digest: exact-authorized-scope
|
||||
holds_digest: exact-prohibitions-and-holds
|
||||
runtime_id: harness@exact-version
|
||||
acknowledged_at: RFC3339
|
||||
proof: adapter-defined-authenticated-proof
|
||||
```
|
||||
|
||||
ACK acceptance requires:
|
||||
|
||||
- challenge exists, is unexpired, and unused;
|
||||
- all bound fields exactly match Coordinator state, including current Coordinator epoch and lane incarnation;
|
||||
- proof validates through the versioned adapter;
|
||||
- process and session identity probes still match;
|
||||
- ACK consumption and `READY` transition occur atomically.
|
||||
|
||||
A replayed, duplicated, late, or mismatched ACK MUST be rejected and audited. It MUST NOT refresh or recreate a challenge.
|
||||
|
||||
### 8.1 Handoff challenge and ACK
|
||||
|
||||
Handoff acknowledgement is a separate protocol from activation acknowledgement. The Coordinator MUST issue a cryptographically random, single-use handoff challenge. The target ACK MUST bind:
|
||||
|
||||
```yaml
|
||||
handoff_challenge_id: single-use-random-value
|
||||
coordinator_epoch: exact-leader-fence
|
||||
assignment_id: exact-assignment
|
||||
current_owner: exact-current-owner
|
||||
handoff_target: exact-target
|
||||
next_action_digest: sha256:...
|
||||
scope_digest: sha256:...
|
||||
holds_digest: sha256:...
|
||||
contracts_digest: sha256:...
|
||||
lane_incarnation_id: exact-incarnation-if-applicable
|
||||
generation: exact-generation-if-applicable
|
||||
expires_at: authoritative-RFC3339
|
||||
idempotency_key: opaque-operation-key
|
||||
proof: authenticated-target-proof
|
||||
```
|
||||
|
||||
Challenge consumption and ownership transfer MUST occur in one PostgreSQL CAS transaction that verifies current owner, target, Coordinator epoch, assignment, challenge unused/unexpired state, all bound digests, and applicable lane incarnation/generation. Replay, mismatch, expiry, or concurrent ownership change fails closed. The resulting handoff receipt transfers responsibility only; it MUST NOT grant `READY`, `RUNNING`, lease, or effect authority and MUST NOT substitute for the fresh-generation activation ACK.
|
||||
|
||||
## 9. Fresh-process policy and runtime capability registry
|
||||
|
||||
Fresh-process replacement is mandatory for Pi, Claude, Codex, OpenCode, and unknown harnesses in the initial release. Command names MUST NOT be assumed to imply semantics.
|
||||
|
||||
Registry entries are keyed by exact runtime and version and MUST include:
|
||||
|
||||
- fresh process command/template;
|
||||
- process-tree/cgroup strategy;
|
||||
- session and conversation identity probes;
|
||||
- generation probe;
|
||||
- idle probe;
|
||||
- foreground-command probe;
|
||||
- checkpoint and recovery probes;
|
||||
- contract injection method;
|
||||
- ACK protocol/proof method;
|
||||
- graceful and forced stop behavior;
|
||||
- deterministic descendant cleanup probe;
|
||||
- staging support;
|
||||
- minimum/maximum validated versions;
|
||||
- adversarial test evidence digest;
|
||||
- in-band reset status, default `disabled`.
|
||||
|
||||
Unknown version, probe disagreement, forged/unverifiable output, or missing evidence MUST fail closed.
|
||||
|
||||
Pi lifecycle hooks are defense-in-depth only. `session_shutdown` may not run on SIGKILL, crash, host loss, or abrupt process termination. Interactive `session_before_switch` and `session_before_fork` guards do not cover all RPC, SDK, supervisor, or external process-replacement paths. Independent process-supervisor observation, Coordinator watchdogs, process-tree cleanup, and recovery are mandatory.
|
||||
|
||||
In-process `/clear` or `/new` MAY be enabled in a later contract revision only when adversarial evidence proves equivalence to replacement, including distinct conversation identity, no retained task context, checkpoint/recovery safety, queue isolation, descendant handling, and stale-generation rejection.
|
||||
|
||||
## 10. Process-tree isolation and cleanup
|
||||
|
||||
Process authority MUST bind to a process tree or cgroup plus launch nonce, not PID alone. The adapter MUST:
|
||||
|
||||
1. create an isolated process group/cgroup where supported;
|
||||
2. record root PID, start time, executable identity, cgroup/process-group identity, and launch nonce;
|
||||
3. enumerate descendants before and after stop;
|
||||
4. perform graceful stop within a bounded interval;
|
||||
5. revoke effects before forced termination;
|
||||
6. deterministically terminate remaining descendants;
|
||||
7. verify no descendant retains lane resources, sockets, locks, credentials, worktree handles, or effect leases;
|
||||
8. reject PID reuse as identity continuity.
|
||||
|
||||
Cleanup ambiguity requires quarantine.
|
||||
|
||||
### 10.1 Generation-bound termination receipt
|
||||
|
||||
Every graceful, forced, crashed, replaced, or externally observed termination MUST produce or reconcile a durable generation-bound termination receipt in PostgreSQL:
|
||||
|
||||
```yaml
|
||||
receipt_id: opaque-unique-id
|
||||
coordinator_epoch: exact-leader-fence
|
||||
lane_id: exact-lane
|
||||
lane_incarnation_id: exact-incarnation
|
||||
assignment_id: exact-assignment
|
||||
generation: exact-generation
|
||||
process_identity: exact-process-tree-identity
|
||||
observation_source: runtime-hook|adapter|supervisor|watchdog|coordinator
|
||||
termination_reason: quit|new|resume|fork|replace|crash|sigkill|timeout|host-loss|unknown
|
||||
observed_at: authoritative-RFC3339
|
||||
unfinished_status: true|false
|
||||
next_action_digest: sha256-or-null
|
||||
checkpoint_digest: sha256-or-null
|
||||
handoff_state_digest: sha256-or-null
|
||||
last_validated_progress_at: authoritative-RFC3339-or-null
|
||||
last_progress_receipt_digest: sha256-or-null
|
||||
idempotency_key: opaque-operation-key
|
||||
```
|
||||
|
||||
Runtime hooks and adapters MAY contribute observations, but supervisor/Coordinator watchdog observation is mandatory whenever hooks do not fire or cannot be verified. A missing receipt blocks lane reuse until recovery reconciles process death, effects, descendants, checkpoint/handoff state, and assignment outcome. Receipt creation and state reconciliation MUST be idempotent and Coordinator-epoch fenced.
|
||||
|
||||
## 11. Checkpoint security and isolation
|
||||
|
||||
Checkpoints MUST be:
|
||||
|
||||
- access-controlled by assignment and recovery role;
|
||||
- encrypted in transit and at rest when they contain sensitive material;
|
||||
- content-addressed and integrity verified;
|
||||
- retention-bounded with explicit deletion policy;
|
||||
- redacted of credentials and unnecessary command payloads;
|
||||
- inaccessible to unrelated assignments and generations;
|
||||
- auditable without logging checkpoint content.
|
||||
|
||||
Checkpoint state MUST bind the checkpoint digest, data classification, retention-policy digest, assignment, lane incarnation, generation, and authorized recovery purpose. Handoff and activation state MUST carry these digests when checkpoint recovery is relevant. Completion conditions MUST be machine-verifiable or require a named independent-review receipt whose digest is recorded; narrative completion and agent self-claim are insufficient.
|
||||
|
||||
Checkpoint recovery MUST require an explicit recovery operation bound to the same assignment or an approved remediation assignment. General task dispatch MUST NOT inject previous checkpoint content.
|
||||
|
||||
## 12. Queue isolation
|
||||
|
||||
When a generation is fenced:
|
||||
|
||||
- all queued messages for that generation become permanently stale;
|
||||
- stale messages MUST be rejected before delivery and recorded as redacted audit events;
|
||||
- stale messages MUST NOT be replayed, drained, summarized, transformed, or copied into a new generation;
|
||||
- queue cleanup MAY delete stale payloads after audit and retention requirements are met;
|
||||
- a new generation begins with an empty assignment queue except for its own contract and challenge envelopes.
|
||||
|
||||
## 13. Elastic lane leasing and destruction
|
||||
|
||||
Elastic lanes require:
|
||||
|
||||
- opaque `ownership_token` whose raw value remains inside the minimum trusted validation boundary;
|
||||
- lease ID and epoch;
|
||||
- exact lane ID, `lane_incarnation_id`, and generation;
|
||||
- owner Coordinator identity and `coordinator_epoch`;
|
||||
- TTL, renewal deadline, and maximum lifetime;
|
||||
- capacity and role constraints;
|
||||
- destruction idempotency key.
|
||||
|
||||
Destruction MUST compare the exact ownership token/proof, Coordinator epoch, lane ID, lane incarnation, generation, and lease epoch atomically. A TTL worker MUST NOT destroy a lane whose ownership or generation changed. Collision or ambiguity MUST fail closed and quarantine for reconciliation.
|
||||
|
||||
## 14. Continuity and no-silent-parking contract
|
||||
|
||||
Every approved work item MUST persist:
|
||||
|
||||
```yaml
|
||||
work_status: active|blocked|handoff|done
|
||||
owner: exact-agent-or-service
|
||||
next_action: executable-action
|
||||
authority_allowed: [capabilities]
|
||||
authority_prohibited: [capabilities]
|
||||
completion_condition: evidence-required
|
||||
handoff_target: exact-target-or-null
|
||||
handoff_ack: null-or-coordinator-transfer-receipt
|
||||
blocker_code: canonical-code-or-null
|
||||
blocker_evidence_digest: sha256-or-null
|
||||
last_progress_at: RFC3339-from-validated-progress-receipt
|
||||
inactivity_policy: versioned-policy-id
|
||||
inactivity_ttl: resolved-duration
|
||||
inactivity_deadline: authoritative-RFC3339
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. A prohibited capability restricts only that capability.
|
||||
2. Authorized unfinished work MUST continue or be transferred through an explicit ACK.
|
||||
3. Sending a message does not transfer ownership. A `handoff_ack` transfers responsibility only through Coordinator CAS; it does not grant `RUNNING`, lease, or effect authority. A replacement worker still requires fresh process/generation contract injection and the separate activation ACK from section 8.
|
||||
4. `aligned`, `awaiting`, `no code authority`, and similar narrative states are not terminal states.
|
||||
5. The Coordinator MUST reject approved unfinished work with no owner or next action.
|
||||
6. `last_progress_at` advances only from a Coordinator-validated progress receipt bound to Coordinator epoch, assignment, lane incarnation, generation, and fence proof with objective next-action evidence. Heartbeats, token output, narrative status, and agent self-claims are not progress.
|
||||
7. Each versioned inactivity policy MUST freeze warning, escalation, retry, reassignment, and quarantine thresholds; idempotency behavior; maximum attempts; and retry-exhaustion outcome. `blocked` still requires an owner, objective blocker evidence, and an executable unblock or next action. Policy exhaustion enters explicit blocked/quarantine review rather than silent parking.
|
||||
8. Runtime adapters SHOULD emit an `authorized_work_unfinished` lifecycle event only at the runtime's verified settled boundary—not merely at turn or low-level agent-run end.
|
||||
9. For Pi, continuity evaluation MUST use `agent_settled`, not `agent_end` or `turn_end`, because retries, compaction retries, and queued follow-ups may remain after `agent_end`. A turn-end heartbeat such as `ok` means only that no turn is currently active; it MUST NOT imply assignment completion.
|
||||
10. Pi `session_shutdown` MAY report `quit`, `new`, `resume`, or `fork` for audit and cleanup, but MUST NOT be treated as a cancellable guard. Unsafe `/new` or `/resume` replacement MUST be blocked through `session_before_switch`; unsafe `/fork` or `/clone` MUST be blocked through `session_before_fork`.
|
||||
11. A Pi extension MUST NOT compose or infer continuation content. It MAY deliver exactly one already validated Coordinator-signed continuation envelope/challenge per idempotency key for a settled authorized work item. The envelope MUST bind Coordinator epoch, assignment, lane incarnation, generation, fence proof, next action, authority scope, completion condition, expiry, loop budget, and result/ACK destination. Repeated self-triggering, duplicate delivery after extension restart, or unsigned continuation is forbidden. Delivery result returns through the generation-bound Coordinator ACK/result path; injection failure or extension crash leaves recovery to the Coordinator watchdog.
|
||||
12. Pi extension errors are non-fatal; therefore, extension signals are advisory evidence and MUST NOT become canonical authority or the sole continuity mechanism.
|
||||
13. Claude, Codex, and OpenCode adapters MUST provide continuity semantics equivalent to Pi: verified settled/idle evidence, abrupt-termination observation independent of optional hooks, one bounded Coordinator-signed continuation where supported, duplicate suppression across adapter restart, partial-authority continuation, and strict separation of handoff from activation. Unknown lifecycle semantics fail closed to supervisor/watchdog replacement, quarantine, or reassignment.
|
||||
14. The Coordinator, not the harness, decides whether continuation, restart, or reassignment occurs.
|
||||
|
||||
## 15. Authoritative time and expiry
|
||||
|
||||
The canonical SOT/Coordinator time service is authoritative for issued-at, expiry, lease, challenge, TTL, and watchdog decisions. Adapter, agent, executor, and host wall clocks MUST NOT create, renew, or extend authority.
|
||||
|
||||
- Persist absolute authoritative deadlines for durable recovery.
|
||||
- Use monotonic clocks for in-process elapsed durations and timeout scheduling.
|
||||
- Define and version a maximum accepted transport clock skew; skew affects rejection tolerance only and MUST NOT extend lease or token validity beyond the authoritative deadline.
|
||||
- On clock rollback, discontinuity, disagreement, or unavailable authoritative time, new activation/effects MUST fail closed while already expired authority remains expired.
|
||||
- Expiry, renewal, transfer, destruction, and activation races MUST resolve by fenced CAS against authoritative time and current Coordinator epoch.
|
||||
|
||||
## 16. Threat model
|
||||
|
||||
### Protected assets
|
||||
|
||||
- assignment authority;
|
||||
- repository and external side-effect authority;
|
||||
- task and checkpoint confidentiality;
|
||||
- lane availability;
|
||||
- audit integrity;
|
||||
- scope and hold enforcement;
|
||||
- cross-site coordination integrity.
|
||||
|
||||
### Adversaries and failure sources
|
||||
|
||||
- stale or contaminated agent context;
|
||||
- compromised or hallucinating agent;
|
||||
- replaying transport participant;
|
||||
- stale gateway or executor;
|
||||
- forged runtime probe;
|
||||
- PID reuse and orphan descendants;
|
||||
- Coordinator crash or duplicate Coordinator;
|
||||
- lease races and delayed TTL cleanup;
|
||||
- accidental checkpoint disclosure;
|
||||
- operator or automation message sent to the wrong lane/generation.
|
||||
|
||||
### Required controls
|
||||
|
||||
- monotonic generation and opaque fence token;
|
||||
- challenge-bound single-use ACK;
|
||||
- executor-local fence validation;
|
||||
- authenticated/versioned probes;
|
||||
- atomic CAS transitions and idempotency keys;
|
||||
- process-tree/cgroup identity;
|
||||
- least-privilege staging;
|
||||
- queue isolation;
|
||||
- encrypted, scoped, retention-bounded checkpoints;
|
||||
- redacted receipts;
|
||||
- split-brain Coordinator fencing at storage and executor boundaries;
|
||||
- lane-incarnation fencing across delete/recreate cycles;
|
||||
- authoritative time and monotonic timeout handling;
|
||||
- registered executor inventory with no stale-cache authority;
|
||||
- deterministic quarantine and recovery.
|
||||
|
||||
## 17. Mandatory adversarial tests
|
||||
|
||||
Implementation authorization MUST NOT be granted until test specifications exist for all cases. Canary authorization MUST NOT be granted until all tests pass in isolated environments.
|
||||
|
||||
| Test | Required assertion |
|
||||
|---|---|
|
||||
| Replayed ACK | second/late ACK rejected; no state or lease change |
|
||||
| PID reuse | reused PID cannot satisfy process identity or generation probe |
|
||||
| Orphan child process | descendant detected, effects revoked, cleanup completed or lane quarantined |
|
||||
| Stale executor request | executor rejects stale generation/fence even if gateway previously accepted it |
|
||||
| Coordinator crash at every swap step | recovery is idempotent; never two active generations; no ambiguous RUNNING |
|
||||
| Lease-transfer race | only CAS winner receives authority; loser is fenced and audited |
|
||||
| Checkpoint disclosure | unrelated generation cannot enumerate, read, infer, or receive checkpoint material |
|
||||
| Forged idle/identity probe | conflicting or unauthenticated probe fails closed |
|
||||
| TTL destroy collision | stale TTL worker cannot destroy renewed/reassigned lane |
|
||||
| Old queued message | old message rejected/audited and never delivered to new generation |
|
||||
| Forged ACK fields | mismatch in task, generation, digest, scope, holds, process, or runtime rejected |
|
||||
| Staging write attempt | side-effect executor denies all staging effects |
|
||||
| Fence revocation race | revoked token denied at executor despite in-flight transport |
|
||||
| Duplicate activation request | idempotent receipt returned; no duplicate leases/effects |
|
||||
| Split-brain Coordinator | only fenced leader can reserve/activate |
|
||||
| Partial-authority continuation | design work continues when code/issue/live capabilities are prohibited |
|
||||
| Unacknowledged handoff | ownership remains with sender and inactivity watchdog fires |
|
||||
| Stale Coordinator epoch | split-brain storage mutation, lease, ACK consumption, receipt, and executor effect are rejected |
|
||||
| Lane reincarnation | delete/recreate under same lane name cannot reset generation or accept stale incarnation authority |
|
||||
| Raw token leakage/timing | no raw token appears in observability; comparisons are constant-time within defined boundary |
|
||||
| Premature completion | completion before final receipt/effect release is rejected; cleanup failure quarantines |
|
||||
| Fake progress heartbeat | heartbeat/narrative/token output cannot advance `last_progress_at` |
|
||||
| Blocked without evidence | blocked claim rejected without owner, objective evidence, and executable next action; retry exhaustion is explicit |
|
||||
| Handoff/activation confusion | handoff ACK cannot activate generation or grant effect lease |
|
||||
| Clock rollback/skew | rollback, excessive skew, and expiry race cannot extend authority |
|
||||
| Unknown executor | unregistered effect path and stale authorization cache both fail closed |
|
||||
| SIGKILL lifecycle loss | absence of `session_shutdown` is detected by supervisor/watchdog and recovered safely |
|
||||
| Duplicate Pi continuation | extension restart cannot redeliver same continuation idempotency key or exceed loop budget |
|
||||
| Cross-harness settled/idle parity | Claude, Codex, Pi, and OpenCode cannot report completion while retry, compaction, follow-up, foreground work, or queued continuation remains |
|
||||
| Cross-harness abrupt termination | missing/optional hooks cannot suppress supervisor/watchdog termination receipt and recovery |
|
||||
| Cross-harness bounded continuation | only exact Coordinator-signed continuation is delivered; loop budget and expiry are enforced |
|
||||
| Adapter restart duplicate suppression | persisted idempotency state prevents duplicate continuation after any adapter restart |
|
||||
| Cross-harness partial authority | authorized design/contract work continues while prohibited code/issue/live capabilities remain denied |
|
||||
| Cross-harness handoff separation | handoff ACK never grants activation or effects for any harness |
|
||||
| Unknown lifecycle semantics | unknown runtime/version fails closed to supervised replacement, quarantine, or reassignment |
|
||||
|
||||
## 18. Observability and receipts
|
||||
|
||||
Required metrics and events include:
|
||||
|
||||
- active generation per lane;
|
||||
- generation replacement count and latency;
|
||||
- stale envelope rejection count by type;
|
||||
- ACK rejection reason category;
|
||||
- executor fence denials;
|
||||
- checkpoint creation/recovery/deletion receipts;
|
||||
- generation-bound termination receipts by observation source and reason;
|
||||
- orphan descendant detection;
|
||||
- quarantine entry/recovery;
|
||||
- lease expiry, renewal, transfer, and collision;
|
||||
- authorized-work inactivity and reassignment;
|
||||
- token usage before and after context-boundary enforcement.
|
||||
|
||||
Logs and receipts MUST NOT contain raw prompts, context, fence/ownership tokens, credentials, secrets, checkpoint bodies, or privileged command bodies. Correlation uses opaque IDs and digests.
|
||||
|
||||
## 19. Delivery sequence
|
||||
|
||||
1. Approve this parent contract and threat model by content digest.
|
||||
2. Define child contract for capability registry and fake-harness probes.
|
||||
3. Define child contract for Coordinator FSM, CAS transitions, fencing, ACKs, receipts, and continuity watchdog.
|
||||
4. Define child contract for stable-lane fresh-process replacement.
|
||||
5. Define child contract for elastic TTL leases and exact-token destruction.
|
||||
6. Define monitoring, runbook, and cross-harness adversarial E2E contracts.
|
||||
7. Authorize isolated canary and rollback only after all prerequisite evidence is terminal green.
|
||||
|
||||
The eventual parent epic MUST remain separate from #758 and #766 while linking both as prerequisites/dependencies.
|
||||
|
||||
## 20. Acceptance criteria for parent-contract approval
|
||||
|
||||
- [ ] Local and Homelab leads reconstruct identical content and verify its digest.
|
||||
- [ ] Component authority boundaries are explicit and non-overlapping.
|
||||
- [ ] PostgreSQL is explicitly the sole writable canonical assignment/orchestration SOT; all caches, projections, adapters, providers, files, browsers, roster, and transport are non-authoritative.
|
||||
- [ ] Transaction isolation, uniqueness, and Coordinator-epoch fencing are defined.
|
||||
- [ ] Lane reincarnation prevents generation collision after delete/recreate.
|
||||
- [ ] Token/proof storage, rotation, revocation, comparison, expiry, and redaction are defined.
|
||||
- [ ] FSM and CAS activation preconditions are complete.
|
||||
- [ ] Fence validation covers every side-effect executor.
|
||||
- [ ] Challenge-bound ACK is single-use and replay resistant.
|
||||
- [ ] Process-tree/cgroup and descendant cleanup requirements are explicit.
|
||||
- [ ] Staging has no write/effect leases.
|
||||
- [ ] Checkpoint security, retention, and assignment isolation are defined.
|
||||
- [ ] Old queues cannot contaminate new generations.
|
||||
- [ ] Elastic destruction requires exact ownership token and generation.
|
||||
- [ ] Monitoring and receipts are redacted.
|
||||
- [ ] All mandatory adversarial tests have required assertions.
|
||||
- [ ] Continuity/no-silent-parking behavior is included for Pi and other harnesses.
|
||||
- [ ] Canonical continuity state persists resolved TTL/deadline, handoff target, blocker code, and blocker evidence in addition to policy identity.
|
||||
- [ ] Progress truth, blocked evidence, retry limits, and watchdog policy are deterministic.
|
||||
- [ ] Handoff uses a single-use Coordinator challenge and atomic ownership-transfer CAS; handoff and activation ACKs are distinct.
|
||||
- [ ] Authoritative time, skew, rollback, and expiry races fail closed.
|
||||
- [ ] Executor inventory is complete and stale caches cannot authorize.
|
||||
- [ ] Every termination path produces or reconciles the mandatory generation-bound receipt; abrupt termination recovery does not depend on lifecycle hooks.
|
||||
- [ ] Pi continuation provenance, ACK/result path, idempotency, and loop budget are bounded.
|
||||
- [ ] Claude, Codex, Pi, and OpenCode pass equivalent continuity and handoff/activation conformance cases; unknown semantics fail closed.
|
||||
- [ ] Checkpoint and completion evidence digests are bound into relevant state.
|
||||
- [ ] No implementation, issue, or live authority is inferred from contract approval.
|
||||
|
||||
## 21. Non-goals
|
||||
|
||||
This contract does not:
|
||||
|
||||
- authorize implementation;
|
||||
- authorize issue creation or mutation;
|
||||
- authorize deployment or canary activity;
|
||||
- standardize one harness’s slash commands;
|
||||
- permit in-process reset in the initial release;
|
||||
- make tmux, transport, Valkey, or roster the canonical assignment authority;
|
||||
- expose checkpoint or conversational content through monitoring.
|
||||
Reference in New Issue
Block a user