work-unit: control-plane contracts — probe, status, and roll-up semantics

Purpose

Finish the contract layer for the new control plane so implementation work has one current-truth target. Keep this batch doc-focused: define the final semantics for /live, /ready, and /admin/v1/status, plus shared state vocabulary, readiness impact, roll-up rules, quiet-source behavior, and drain/shutdown semantics.

Repo footprint

dev-docs/IO_CONTRACTS.md
adjacent cross-links in dev-docs/DESIGN.md, dev-docs/VERIFICATION.md, or dev-docs/CHANGE_MAP.md only if needed to keep the contract discoverable and non-contradictory

In scope

#	Type	Why included
#1303	architecture	owns the living contract for I/O and control-plane semantics
#1306	architecture	contract must match the implementation substrate it will drive

Related metas / phases

Narrow execution slice under #1315
Should land before deeper lifecycle and status plumbing so later work can follow one written contract

Non-goals

no runtime behavior changes
no endpoint implementation work
no receiver/sink lifecycle wiring
no broad doc rewrite outside the control-plane contract and necessary cross-links

Done when

dev-docs/IO_CONTRACTS.md defines the final meaning of /live, /ready, and /admin/v1/status
shared state vocabulary is explicit: starting, healthy, degraded, stopping, stopped, failed
readiness impact and roll-up rules are documented, including the default fail-open stance for degraded
quiet sources are explicitly non-blocking for readiness
drain/shutdown semantics are documented honestly
enforcement status is called out where the implementation has not caught up yet

tl;dr: Outcome A — Ready for implementation as a mechanical docs-contract task; the canonical control-plane contract file is missing, while runtime probe behavior is already concrete enough to document with explicit “enforcement status” gaps.

Recommendation

Create dev-docs/IO_CONTRACTS.md as the single source of truth for control-plane semantics (/live, /ready, /admin/v1/status) and link it from core dev docs. Keep this docs-only; do not change runtime behavior in this issue.

Findings (evidence)

dev-docs/ currently has no IO_CONTRACTS.md (repo listing includes ADAPTER_CONTRACT.md, SCANNER_CONTRACT.md, etc., but not IO_CONTRACTS.md).
crates/logfwd-io/src/diagnostics.rs:484-493 routes include /health, /ready, /api/*; no /live or /admin/v1/status.
crates/logfwd-io/src/diagnostics.rs:532-541 /health always returns 200 with {"status":"ok"...}.
crates/logfwd-io/src/diagnostics.rs:545-552 readiness docs in code explicitly say quiet sources are not a readiness gate.
crates/logfwd-io/src/diagnostics.rs:553-565 /ready is currently !pipelines.is_empty() (200 ready / 503 not_ready).
crates/logfwd-io/src/diagnostics.rs:1634-1665 tests lock in current readiness semantics (no pipeline => 503; pipeline registered => 200).
crates/logfwd-types/src/pipeline/lifecycle.rs:3,19-26 lifecycle typestate is Starting -> Running -> Draining -> Stopped (different vocabulary than issue’s target control-plane states).
book/src/config/reference.md:453-455 and book/src/deployment/monitoring.md:14-16 document /health, /ready, /api/pipelines only.
dev-docs/references/production-patterns.md:223-230 uses /healthz and /readyz wording, showing doc-surface drift.

Verification

Ran targeted readiness tests to confirm current behavior before drafting the spec:

$ cargo test -p logfwd-io ready_endpoint -- --nocapture
running 2 tests
test diagnostics::tests::test_ready_endpoint_with_pipeline_returns_200 ... ok
test diagnostics::tests::test_ready_endpoint_no_pipelines_returns_503 ... ok

test result: ok. 2 passed; 0 failed

Detailed Action Plan (mechanical implementation spec)

Create canonical contract doc
- File: dev-docs/IO_CONTRACTS.md (new)
- Add sections (in this order, explicit headings):
  1. Control-plane endpoints — define contract meaning for:
    - GET /live (process liveness contract)
    - GET /ready (readiness contract)
    - GET /admin/v1/status (structured status snapshot contract)
  2. Shared state vocabulary — exact enum values: starting, healthy, degraded, stopping, stopped, failed.
  3. Readiness impact + roll-up semantics — include default fail-open for degraded; define precedence/roll-up rules explicitly.
  4. Quiet-source behavior — explicitly non-blocking for readiness.
  5. Drain/shutdown semantics — document graceful drain vs forced stop truthfully.
  6. Enforcement status — table with columns: Contract item, Current implementation, Status (enforced/partial/not yet), Evidence.
- Use current runtime evidence anchors in that enforcement table:
  - crates/logfwd-io/src/diagnostics.rs:532-565
  - crates/logfwd-io/src/diagnostics.rs:1634-1665
  - crates/logfwd-types/src/pipeline/lifecycle.rs:3,19-26
Add discoverability cross-links (minimal, no broad rewrites)
- File: dev-docs/DESIGN.md (architecture overview section near crate/runtime discussion)
  - Add one link sentence pointing to dev-docs/IO_CONTRACTS.md as control-plane contract source of truth.
- File: dev-docs/CHANGE_MAP.md (Documentation-only changes section around lines 40-45)
  - Add one bullet: control-plane/probe/status semantics must be updated in dev-docs/IO_CONTRACTS.md (canonical doc) rather than duplicated.
- Optional (only if needed for consistency): one short note in dev-docs/VERIFICATION.md pointing to IO_CONTRACTS.md for contract-level semantics.
Test to write
- For this issue scope (docs-only), no new Rust test file is required.
- Add one short “enforcement status” subsection in IO_CONTRACTS.md that references existing diagnostics tests as contract witnesses:
  - crates/logfwd-io/src/diagnostics.rs:1634-1665.
Verification commands
- cargo test -p logfwd-io ready_endpoint -- --nocapture
- rg -n "(/live|/ready|/admin/v1/status|starting|healthy|degraded|stopping|stopped|failed|fail-open|quiet)" dev-docs/IO_CONTRACTS.md

Related Items

Type	Link	Relevance
Issue	#1412	Current work-unit
Issue	#1303	Defines `IO_CONTRACTS.md` as living contract target
Issue	#1306	Substrate implementation that contract must align with
Issue	#1413	Process phase/probe truth implementation slice
Issue	#1414	Shared status snapshots and `/admin/v1/status` payload slice
Issue	#1415	Input lifecycle wiring feeding status semantics
Issue	#1315	Umbrella for I/O correctness refactor
PR	#610	Prior `/ready` semantics stabilization (quiet-source non-blocking behavior reflected in code/tests)
File	`crates/logfwd-io/src/diagnostics.rs:484-565`	Current probe routes and semantics
File	`crates/logfwd-io/src/diagnostics.rs:1634-1665`	Readiness behavior tests
File	`crates/logfwd-types/src/pipeline/lifecycle.rs:3,19-26`	Runtime lifecycle phases for drain/shutdown truth
File	`book/src/config/reference.md:453-455`	User-facing probe/API docs today

Note

🔒 Integrity filtering filtered 17 items

Integrity filtering activated and filtered the following items during workflow execution.
This happens when a tool call accesses a resource that does not meet the required integrity or secrecy level of the workflow.

issue:work-unit: control-plane contracts — probe, status, and roll-up semantics #1412 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control plane — shared status model and admin status surface #1414 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:meta: I/O control-plane substrate — lifecycle, health, readiness, and status #1306 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control plane — input lifecycle status wiring #1415 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:IO_CONTRACTS.md — living contract for I/O and control-plane semantics #1303 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control plane — process phase, drain, and probe truth #1413 (issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
resource:search_pull_requests (search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control plane — input lifecycle status wiring #1415 (list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control-plane contracts — probe, status, and roll-up semantics #1412 (list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:research: pipeline — stateful processor emission checkpoint contract #1404 (list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:meta: I/O control-plane substrate — lifecycle, health, readiness, and status #1306 (list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
issue:work-unit: control plane — output lifecycle status wiring #1416 (list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
pr:Fix Loki sink null timestamp and JSON escape correctness #1380 (pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
pr:Fix OTLP receiver thread leak and graceful shutdown mechanism #1378 (pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
pr:fix(parsing): apply timezone offset in parse_timestamp_nanos; preserve oversized integers as strings #1386 (pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
pr:fix: resolve config validation regressions (ArrowIPC, Hostnames, Generators) #1381 (pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)
... and 1 more item

What is this? | From workflow: Issue Triage

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

This stays the canonical contract/documentation slice for the control-plane cluster. It should remain separate from the implementation work-units so later runtime work has one written source of truth to follow.

Resolved by PRs #1454, #1509. Verified: /live, /ready, /admin/v1/status with ComponentHealth vocabulary, readiness impact rules, drain semantics.

Navigation Menu

Repository navigation

work-unit: control-plane contracts — probe, status, and roll-up semantics #1412

Purpose

Repo footprint

In scope

Related metas / phases

Non-goals

Done when

Recommendation

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

work-unit: control-plane contracts — probe, status, and roll-up semantics #1412

Description

Purpose

Repo footprint

In scope

Related metas / phases

Non-goals

Done when

Activity

github-actions commented on Apr 6, 2026

Recommendation

strawgate commented on Apr 6, 2026

strawgate commented on Apr 7, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions