From ed3ccae8444ecc0dded8a0ecf45be7c908d2b12f Mon Sep 17 00:00:00 2001 From: bellman Date: Thu, 14 May 2026 17:58:45 +0900 Subject: [PATCH] omx(team): auto-checkpoint worker-4 [unknown] --- README.md | 1 + docs/g004-events-reports-contract.md | 67 ++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 docs/g004-events-reports-contract.md diff --git a/README.md b/README.md index 0b090077..3a26301d 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,7 @@ cargo test --workspace - [`PARITY.md`](./PARITY.md) — parity status for the Rust port - [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details - [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work +- [`docs/g004-events-reports-contract.md`](./docs/g004-events-reports-contract.md) — Stream 2 lane event/report contract guidance for consumers - [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated ## Ecosystem diff --git a/docs/g004-events-reports-contract.md b/docs/g004-events-reports-contract.md new file mode 100644 index 00000000..17c1f644 --- /dev/null +++ b/docs/g004-events-reports-contract.md @@ -0,0 +1,67 @@ +# G004 event and report contract guidance + +Captured: 2026-05-14 during the Stream 2 `G004-events-reports` team run. + +Purpose: keep the user/developer-facing contract guidance for ROADMAP Phase 2 in one tracked source that points back to the code and roadmap anchors. This document is intentionally not the implementation map for task 5; it describes the interoperability contract consumers should rely on as the lane-event, report-schema, approval-token, and capability-negotiation lanes land. + +## Source-of-truth anchors + +| Contract family | Roadmap anchor | Current implementation / owner-facing anchor | Consumer guidance | +| --- | --- | --- | --- | +| Canonical lane events | `ROADMAP.md` Phase 2 §4, §4.5, §4.6, §4.7 | `rust/crates/runtime/src/lane_events.rs` (`LaneEventName`, `LaneEventStatus`, `LaneEventMetadata`, terminal reconciliation helpers) | Consume `event`, `status`, `emittedAt`, and `metadata` fields as the canonical state stream; do not infer lane state from terminal text when a structured event is present. | +| Report schema v1 and projections | `ROADMAP.md` §4.25-§4.34 | Stream 2 report-schema lane / fixtures as they land | Treat a report as a versioned canonical payload plus derived projections. A projection may omit or transform fields only with explicit provenance: compatibility downgrade, redaction policy, truncation, or source absence. | +| Policy-blocked handoff and approval-token chain | `ROADMAP.md` §4.37-§4.39 | Stream 2 approval-token lane as it lands | Treat policy blocks and owner approvals as typed artifacts, not prose. Execute an exception only when the approval token matches actor, policy, action, repo/branch/commit scope, expiry, and one-time-use state. | +| Capability negotiation | `ROADMAP.md` §4.25, §4.26, §4.32, §4.34 | Report-schema/projection fixtures and consumer conformance cases as they land | Consumers must advertise supported schema versions, optional field families, projection views, redaction semantics, and downgrade handling before relying on reduced payloads. | + +## Lane event contract + +The lane-event stream is the first machine-trustworthy surface for Stream 2. Consumers should expect these invariants when reading `LaneEvent` payloads: + +- `event` is a typed event name, currently including the core lane lifecycle (`lane.started`, `lane.ready`, `lane.blocked`, `lane.red`, `lane.green`, `lane.finished`, `lane.failed`), branch health (`branch.stale_against_main`, `branch.workspace_mismatch`), reconciliation (`lane.reconciled`, `lane.superseded`, `lane.closed`), and ship provenance (`ship.prepared`, `ship.commits_selected`, `ship.merged`, `ship.pushed_main`). +- `status` is the normalized state for the event; consumers should prefer it over freeform `detail` text for automation. +- `metadata.seq`, `metadata.timestamp_ms`, and terminal fingerprints are the ordering/deduplication hooks. Consumers should use terminal reconciliation output rather than double-reporting contradictory terminal bursts. +- `metadata.provenance`, `metadata.environment_label`, `metadata.emitter_identity`, and `metadata.confidence_level` tell consumers whether an event is live lane truth, test traffic, healthcheck/replay output, or transport-layer evidence. +- `metadata.session_identity` and `metadata.ownership` bind a lane event to the session, workspace, workflow scope, owner, and watcher action. A watcher should not act on events whose ownership says `observe` or `ignore`. + +Minimal consumer rule: if a structured event exists, pane text is supporting evidence only. Pane scraping must not override a higher-confidence typed event with matching session/workflow ownership. + +## Report schema v1 contract + +A Stream 2 report should be treated as a canonical fact record with optional projections. Consumers should preserve these semantics even when they receive only a downgraded view: + +- Every report payload declares a schema version and a stable report identity/content hash for the full-fidelity canonical payload. +- Assertions are labeled as `fact`, `hypothesis`, or another declared evidence class, with confidence and source references. Negative evidence is first-class: `not observed`, `checked and absent`, and `redacted` are distinct states. +- Field deltas name the field, previous value/state, new value/state, attribution, and whether the delta came from source content, projection, downgrade, or redaction policy. +- Projections carry lineage back to the canonical report id/content hash and name the projection view, capability set, schema version, redaction policy, and deterministic rendering inputs. +- Redaction provenance is explicit. A missing field without a redaction/downgrade/source-absence reason is not enough evidence for an automated consumer to conclude the underlying fact is absent. + +Minimal consumer rule: store the canonical identity and projection metadata together. Do not compare two projections as state changes unless their canonical content hash or declared projection inputs differ. + +## Approval-token and policy-blocked contract + +Policy-blocked actions and owner-approved exceptions belong in the same structured event/report family: + +- A policy block names the typed reason, policy source, actor scope, blocked action, and safe fallback path. +- An approval token names the approving actor, policy exception, action, repository/worktree/branch/commit scope, expiry, and allowed use count. +- Token consumption records the exact action and scope that spent the token. Replays, scope expansion, expired tokens, and revoked tokens should surface typed policy errors. +- Delegation traceability stays attached when another worker/lane executes the approved action; the executor must be able to prove which approval artifact authorized the exception. + +Minimal consumer rule: prose such as "approved" is not an executable approval. Require the structured token and verify that it is unconsumed and scoped to the exact action before proceeding. + +## Capability negotiation and conformance + +Mixed-version consumers are expected during Stream 2 rollout. Producers and consumers should negotiate instead of silently dropping fields: + +- Consumers advertise supported report schema versions, field families, projection views, redaction states, downgrade semantics, and fixture/conformance suite version. +- Producers preserve one canonical full-fidelity report and emit downgraded projections only with `downgraded_for_compatibility` metadata. +- Deterministic projection inputs include schema version, consumer capability set, projection policy version, redaction policy version, and canonical content hash. +- Consumer conformance should distinguish syntax acceptance from semantic correctness, especially for `redacted` vs `missing`, stale vs current projections, negative evidence, and approval-token replay states. + +Minimal consumer rule: an older consumer may accept a downgraded projection, but it must surface the downgrade as a capability limitation rather than treating omitted fields as canonical absence. + +## Documentation maintenance rules + +- Keep ROADMAP Phase 2 as the product requirement source and this file as the contract-reading guide. +- Keep Rust type names and event names aligned with `rust/crates/runtime/src/lane_events.rs`; update this document in the same change when public event names or metadata semantics change. +- Keep report-schema examples/fixtures aligned with this guide once the schema lane lands; fixture updates should explain intentional schema or projection changes. +- Do not mutate `.omx/ultragoal` from worker lanes. Leader-owned Ultragoal checkpointing consumes commits and verification evidence from task results.