#1149

docs(support): reconcile v1 manifest reasons and evidence with current code

Openiamgpwants to merge intofrom

Goal and scope

Make registry/support/v1.json (the v1 scoreboard) truthful and specific so it can track the path to 1.0. This is a reconciliation, not a promotion: it rewrites stale or vague reason and evidence entries so that each incomplete item names the exact missing capability or evidence and cites the real files and workflows.

No gate in gates.status, current_maturity, target_status, scope, profile membership, production.status, artifact_pinning, or any image_reference changed. src/phlo/support_data/v1.json stays byte-identical to registry/support/v1.json.

Change map and risk

Data and documentation only; there are no runtime changes.

  • registry/support/v1.json and src/phlo/support_data/v1.json: rewrote the reason (and, where noted, evidence) for 7 capabilities, 3 packages, and production.reason. Only "reason" lines and evidence array items change; the hand-compacted release_set lines are untouched.
  • docs/reference/packages.md: the durable run-report paragraph (cited as evidence) no longer says the Observatory projection is pending.
  • tests/tooling/test_support_manifest.py: the assertion that pinned the stale "dedicated Observatory UI projection ... pending" wording now requires that the reason names /reports and that the evidence cites routes/_app/reports.tsx.

Audited and left unchanged:

  • iceberg_tables, nessie_branch_write_audit_publish, dbt_transformations, pandera_quality, the remaining blessed_core packages, and the services. Their reasons are generic but accurate.
  • Top-level artifact_pinning: "not_yet_published". The schema pins it as a const alongside release_line: "1.x". No 1.x artifact exists, and the first-party release_set images (phlo-dagster, phlo-api, phlo-observatory, phlo-minio) are tag-only, not digest-pinned. Changing it would need a schema change, not a reconciliation.

Old → new reasons

EntryOld reasonNew reason
capability dlt_ingestiondlt ingestion is implemented and covered by focused tests; run-evidence correlation is not included in this manifest version.dlt ingestion is implemented and covered by focused tests. The provider registers the dlt.ingest contribution to the ADR 0048 WAP run-evidence profile, and its executor emits lifecycle and observed-metric run evidence, marking evidence incomplete when the sink fails instead of rewriting the load result. No dlt-specific gap is known; readiness depends on the shared run_evidence, security, upgrade_restore, and golden_path gates.
capability observatory_run_reportPhlo API exposes the authenticated durable per-run report at alpha maturity. Its dedicated Observatory UI projection and the run_evidence release gate remain pending.Phlo API serves the authenticated durable per-run report at /api/v1/projects/{project}/runs/{run}/attempts/{attempt}/report. The Observatory /reports page projects it for an exact project, logical run, and attempt, and run detail links to it when the run carries phlo/project_id, phlo/run_id, and phlo/attempt tags. The release golden path verifies the report and a scoped-token denial through the API. Missing: the installed-artifact Observatory acceptance visits Overview, Assets, Incidents, Jobs, Query, and Branches but not /reports, so the UI projection has no release evidence.
capability mandatory_authorizationAuthorization enforcement remains mixed between guarded and optional paths; mandatory route classification is required before v1 release.phlo-api classifies every route in its security manifest: startup fails on an unclassified or stale route, and only /health is public. When PHLO_ENVIRONMENT is prod, production, staging, or regulated, or regulated mode is on, every non-public route requires a verified principal and an RBAC allow before its handler runs, an unset authorization mode resolves to required, an explicit optional mode aborts API startup, and the production preflight check http.authorization_required requires a JWT issuer, audience, and JWKS URL with the development bypass off. Missing: (1) fail-closed durable audit of permitted mutations and audit of denials run only when regulated mode is on; a production deployment without regulated mode evaluates RBAC without emitting audit, contrary to ADR 0047 section 6; (2) the ADR 0047 section 8.1 API matrix (anonymous 401, insufficient scope 403, backend unavailable 503, direct-port rejection) has not been demonstrated against a production-shaped deployment; the release golden path only proves a CLI mutation denial.
capability secure_production_deploymentCurrent generated services include development credentials, public ports, or disabled authentication; the secure production profile is not implemented.phlo services init --production rejects bundled, empty, or shared credentials, rejects default or shared workload identity references (missing references are reported by the production preflight), and renders protected backends without host ports. The ADR 0047 Stage A static preflight runs from phlo services preflight --production and before any container contact in phlo services start when PHLO_ENVIRONMENT is production. Missing: (1) Stage B runtime attestation is not implemented (edge TLS probe, live API authorization matrix, external port reachability, observed provider grants and audit, audit canary), so every report has stage static_preflight; (2) the postgres, trino, minio, and nessie readiness adapters return unavailable (evidence_unavailable) because they do not inspect live grants or audit, so the backend.readiness check, and therefore production preflight and a production services start, cannot pass; (3) no live production deployment evidence or production-scope release qualification exists.
capability maintenance_operationsCompaction is implemented and proven through the Iceberg and ref-aware Trino contracts; the broader required maintenance surface remains incomplete.phlo operations maintenance inventory, plan, and apply implement ADR 0049 section 2 compaction and snapshot expiry: apply requires the plan token, rejects a plan whose table snapshot changed, enforces snapshot-expiry object and byte limits, refuses orphan deletion, and records a durable journal entry. The release golden path and the nightly operations-evidence lane run plan-first maintenance on a live table. Missing: (1) maintenance plans carry no expiry, so the required unexpired-plan check is not enforced, and the compaction token is the bare snapshot revision rather than a plan digest; (2) inventory lists only the main ref and silently omits size and snapshot state when table statistics cannot be read; (3) apply journals under the fixed operation ID :: with subject operator, so the durable journal refuses a second apply of the same operation on the same table and ref, and entries are not attributed to the authorized principal.
capability upgrade_restoreA CI recovery drill exercises owned backup and restore, but live PostgreSQL migration evidence remains pending.scripts/recovery_drill.py runs in integration CI: it backs up MinIO objects, the Nessie repository, and a PostgreSQL dump, restores them into a fresh isolated stack, and verifies snapshot, rows, object checksum, and evidence, outside the Phlo CLI. Phlo's own phlo operations restore apply and upgrade apply are fixture substrates: both require --fixture-substrate and only stage files or version markers beneath the target, and upgrade supports only the immutable 0.14.0 to 0.15.0 pair. Missing: provider restore and upgrade adapters that act on a live deployment, and a supported upgrade pair ending at the current release, which production-scope release qualification requires.
capability golden_path_ciRequired CI exercises the release golden-path contract, but installed provider-artifact coverage remains incomplete.Required CI builds the provider wheelhouse and runs the installed provider artifacts jobs, which install the wheels, build and health-check provider images, and scan first-party images. Nightly runs the release golden path, and 0.18.0 passed Release Artifact Acceptance from its staged BOM on amd64 and arm64. That acceptance used artifact qualification scope (alpha, production_ready false), which skips the production_preflight, supported_upgrade, and upgrade_recovery demonstrations. Missing: a production-scope qualification run; it is blocked by the production preflight and live upgrade gaps recorded under secure_production_deployment and upgrade_restore.
package phlo-apiAPI and Observatory integration are implemented and tested, but mandatory authorization remains a release gate.API and Observatory integration are implemented and tested, including mandatory route classification and production fail-closed authorization; the non-regulated production audit gap and missing live authorization evidence recorded under mandatory_authorization still block the security gate.
package phlo-dltdlt ingestion is part of the current core path and has focused tests; run-evidence correlation is not included in this manifest version.dlt ingestion is part of the current core path, has focused tests, and contributes dlt.ingest run evidence to the ADR 0048 WAP profile; the shared release gates still control readiness.
package phlo-observatoryThe API-backed Observatory UI exists and is tested. The authenticated durable per-run report remains available through Phlo API; its dedicated UI projection is pending.The API-backed Observatory UI exists and is tested, including the /reports projection of the authenticated durable per-run report; installed-artifact Observatory acceptance does not yet visit /reports.
productionMandatory HTTP authorization, scoped workload identities, backend-native readiness adapters, and fail-closed durable audit on mutations are implemented and observable through the production preflight; the gate remains open until converged grant/audit evidence is demonstrated on a live deployment and the other release gates pass.Mandatory HTTP authorization, scoped workload identity references, backend readiness adapter registration, and the Stage A static preflight are implemented. The gate stays open: backend readiness adapters cannot yet observe live grants or audit, Stage B runtime attestation is not implemented, fail-closed durable mutation audit is wired only for regulated mode, and no live deployment has demonstrated converged grant and audit evidence.

Code facts behind the new reasons

  • secure_production_deployment: no Stage B (runtime_attestation) implementation exists; run_production_readiness always emits stage="static_preflight". The postgres, trino, minio, and nessie security_readiness adapters return unavailable/evidence_unavailable even when every credential reference is set (checked by calling each adapter's inspect()). As a result, backend.readiness fails, and so do services preflight --production and a production services start.
  • mandatory_authorization: in security_manifest.enforce_http_operation, require_durable_audit and audit emission run only on the is_regulated() branch. The production, non-regulated branch calls backend.explain_decision directly and emits no audit. services init --production sets only PHLO_ENVIRONMENT=production.
  • maintenance_operations: compaction and snapshot-expiry plans have no TTL. The CLI uses the operation ID <operation>:<table>:<ref> with subject operator, and FileOperationJournalStore.claim refuses any existing ID. A scratch check confirmed that a second claim after a successful first one is rejected with conflicting_claim.
  • golden_path_ci: Release Artifact Acceptance succeeded for the v0.18.0 commit ee59cf5 on amd64 and arm64. release_evidence.required_demonstrations("artifact") drops production_preflight, supported_upgrade, and upgrade_recovery.

Verification

  • make validate-support-manifest: validated registry/support/v1.json

  • make docs-reference-generate / make docs-reference-check: Reference documentation already current: 0 file(s). The generated support matrix renders gates, maturity, and blockers, not reasons, so it does not change.

  • uv run --locked pytest tests/tooling/test_support_manifest.py -q: 54 passed

  • make check: all steps passed (exit 0) on the committed tree

  • A semantic diff of the old and new manifests confirms that only the reason and evidence fields listed above changed.

  • cmp registry/support/v1.json src/phlo/support_data/v1.json: identical

  • Not applicable: this changes no behaviour, so no regression test applies. The existing support-manifest test was updated because it pinned stale wording.

Not checked: the claims about live deployments are read from code and workflow definitions, not from running a production-shaped stack.

Recovery and maintainer decisions

Revert the commit to restore the previous wording. Nothing is published, migrated, or promoted. Pending maintainer decision: whether to fix the maintenance journal ID defect (a fixed operation ID blocks repeat applies) in a separate change.

Activity

302
coldtea-pr-lens[bot]8h ago

NOTE

The title starts with docs(support):, so PR Lens left this pull request undrawn. Comment @pr-lens draw to draw it

github.comment.notice: false in .github/pr-lens.yml turns this note off

phlo-agent[bot]8h ago

Reviewed 0d428db against base 7feced4 (4 files). The manifest stays byte-identical to its packaged copy, the /reports route and API client exist, the run-detail link is gated on the three producer tags, required_demonstrations("artifact") does drop the three production demos, and the v0.18.0 acceptance run (38953429752) succeeded on both matrix hosts. docs/reference/packages.md is not generated, so the paragraph edit is in the right place.

Minor accuracy issue: the secure_production_deployment reason overstates init --production (registry/support/v1.json:1256, mirrored at src/phlo/support_data/v1.json:1256):

phlo services init --production ... requires workload identity references ...

ComposeGenerator._validate_workload_identity_references only fails references that are present and default or shared; its docstring says missing references are left to the production preflight (src/phlo/plugins/compose/generator.py:167-185). init separately enforces only non-default, independent POSTGRES_USER and MINIO_ROOT_USER (src/phlo/cli/commands/services/init.py:105-136). A production init that sets those two but omits the DAGSTER_*, TRINO_*, QUARKUS_DATASOURCE_*, or MAINTENANCE_* references succeeds, and identity.workload.* then fails in preflight. The scoreboard currently reads as if init proves workload identity configuration. Suggest rejects default or shared workload identity references; missing references are reported by the production preflight, or move the requirement sentence to the preflight description.

No other accuracy or compatibility findings. Validation remaining: 29 head checks were queued or in progress at review time (successes observed for selection, docs build, mutation, container contracts, and dependency risk; no failures), so the full run still needs to finish. This review is read-only, so make validate-support-manifest, make docs-reference-check, and pytest tests/tooling/test_support_manifest.py are taken from the PR description rather than reproduced here.