work-unit: control plane — shared status model and admin status surface #1414

Activity

1. strawgate

   added

   enhancementNew feature or requestNew feature or request

   productionRequired for production readinessRequired for production readiness

   P2: mediumMinor bug, missing validation, metric inaccuracyMinor bug, missing validation, metric inaccuracy

   work-unitScheduling ticket for one agent runScheduling ticket for one agent run

   architectureSystemic design improvements that eliminate classes of bugsSystemic design improvements that eliminate classes of bugs

   on Apr 6, 2026
2. github-actions commented on Apr 6, 2026

   

   github-actionsBot

   on Apr 6, 2026 – with GitHub Actions

   Contributor

   More actions

   tl;dr: Outcome A (Ready for implementation) — the codebase currently has no shared status snapshot types and no /admin/v1/status; this can be implemented mechanically by introducing shared status models in logfwd-types and wiring a typed admin status endpoint in logfwd-io.

   Recommendation

   Implement this issue now as a focused substrate slice:

   1. Add shared status snapshot types (state, reason, transition timestamp fields, readiness_impact) to logfwd-types.
   2. Add /admin/v1/status in diagnostics server and build payloads from shared types (not ad hoc format!).
   3. Keep /health and /ready for compatibility, but derive readiness status from the same snapshot model.
   4. Add serialization/endpoint tests that assert JSON structure (parsed JSON), not substring checks.

   Findings (evidence)

   • crates/logfwd-types/src/lib.rs:10-24 exports pipeline, diagnostics, etc., but no status module.
   • crates/logfwd-types/src/diagnostics.rs:10 defines pub struct ComponentStats (counters only), no shared status/state model.
   • crates/logfwd-io/src/diagnostics.rs:484-493 router exposes /health, /ready, /api/*; no /admin/v1/status.
   • crates/logfwd-io/src/diagnostics.rs:532-537 serve_health builds ad hoc JSON: {"status":"ok",...}.
   • crates/logfwd-io/src/diagnostics.rs:553-567 serve_ready returns only {"status":"ready|not_ready"}.
   • crates/logfwd-io/src/diagnostics.rs:913-1036 serve_pipelines builds large JSON via format!/string interpolation (not shared typed snapshots).
   • crates/logfwd-io/src/diagnostics.rs:1634-1666 ready endpoint tests assert body.contains(...) instead of schema.
   • Diagnostics runtime wiring entrypoint is crates/logfwd/src/main.rs:932-940 (DiagnosticsServer::new, add_pipeline, start).
   • User docs currently describe /health + /ready only:
     • book/src/config/reference.md:453-454
     • book/src/deployment/monitoring.md:14-15
     • book/src/troubleshooting.md:197-198

   Verification

   I validated current readiness behavior with existing tests (confirms current API shape before planning changes):

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

   Detailed Action Plan (mechanical)

   1. Add shared status types in logfwd-types

      • File: crates/logfwd-types/Cargo.toml
        • Add serde dependency for derives.
      • File: crates/logfwd-types/src/status.rs (new)
        • Add enums/structs (exactly):
          • StatusState (lifecycle/status enum)
          • ReadinessImpact
          • StatusSnapshot { state, reason, state_since_unix_ns, reason_since_unix_ns, readiness_impact }
          • ComponentStatusSnapshot
          • PipelineStatusSnapshot
          • ProcessStatusSnapshot
          • AdminStatusSnapshot
        • Derive Serialize/Deserialize; use stable field names matching IO_CONTRACTS.md — living contract for I/O and control-plane semantics #1303/meta: I/O control-plane substrate — lifecycle, health, readiness, and status #1306 vocabulary.
      • File: crates/logfwd-types/src/lib.rs
        • Export pub mod status;.

   2. Wire canonical admin endpoint from shared model

      • File: crates/logfwd-io/src/diagnostics.rs
        • Extend router at handle_request (:484-493) with "/admin/v1/status".
        • Add serve_admin_status(&self, request: tiny_http::Request) -> Result<...>.
        • Add internal builders:
          • process snapshot builder from server/process state
          • pipeline/component snapshot builders from self.pipelines + PipelineMetrics
        • Serialize with serde_json::to_string from shared structs (avoid ad hoc status JSON assembly for this surface).
        • Keep /ready response behavior (200/503) for compatibility, but derive its decision and status string from the same snapshot source.

   3. Lock payload shape with tests

      • File: crates/logfwd-types/src/status.rs (or adjacent test module)
        • Add serialization tests asserting exact keys and enum string forms.
      • File: crates/logfwd-io/src/diagnostics.rs tests module
        • Add test_admin_status_endpoint_returns_structured_payload.
        • Parse response JSON and assert required fields exist/types for process + pipeline + component snapshots.
        • Add readiness consistency test: /ready status and /admin/v1/status readiness-derived state do not contradict.
        • Update/augment ready tests (:1634-1666) to include structural assertions via serde_json::Value.

   4. Documentation touch-up for endpoint surface

      • Files:
        • book/src/config/reference.md
        • book/src/deployment/monitoring.md
        • book/src/troubleshooting.md
      • Add /admin/v1/status as canonical structured status surface; clarify /health and /ready are probe endpoints.

   5. Verification command sequence for implementation PR

      • cargo test -p logfwd-types
      • cargo test -p logfwd-io diagnostics::tests::
      • cargo fmt --all
      • cargo clippy --all-targets -- -D warnings

   Related Items

   Type	Item	Relevance
   Issue	#1414	This work-unit
   Issue	#1306	Control-plane substrate semantics (/live, /ready, /admin/v1/status)
   Issue	#1303	Contract vocabulary for status payload fields
   File	crates/logfwd-types/src/diagnostics.rs:10	Existing diagnostics type is counters-only (ComponentStats)
   File	crates/logfwd-io/src/diagnostics.rs:484-493	Current route table (no /admin/v1/status)
   File	crates/logfwd/src/main.rs:932-940	Diagnostics server wiring point

   Open PRs in this exact area were not reliably enumerable in this environment due integrity-gated search responses; no directly conflicting approved result was found during this triage.

   Note

   🔒 Integrity filtering filtered 4 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 — 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: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: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".)
   • resource:search_pull_requests (search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".)

   ---

   What is this? | From workflow: Issue Triage

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

   added

   component:diagnosticsDiagnostics endpoints, dashboard, health, probes, and trace explorerDiagnostics endpoints, dashboard, health, probes, and trace explorer

   on Apr 6, 2026
4. strawgate

   changed the title [-]work-unit: logfwd-types + diagnostics — shared status snapshots and admin surface[/-] [+]work-unit: control plane — shared status model and admin status surface[/+] on Apr 6, 2026
5. strawgate commented on Apr 7, 2026

   

   strawgate

   on Apr 7, 2026

   OwnerAuthor

   More actions

   Resolved by PRs #1454, #1509. Verified: typed ComponentHealth, ComponentStats, per-pipeline snapshots.
6. strawgate

   closed this as completedon Apr 7, 2026