diff --git a/.ssot/adr/ADR-0001-canonical-json-registry.md b/.ssot/adr/ADR-0001-canonical-json-registry.md new file mode 100644 index 00000000..46d57549 --- /dev/null +++ b/.ssot/adr/ADR-0001-canonical-json-registry.md @@ -0,0 +1,11 @@ +# ADR-0001: Canonical registry is a single JSON document + +## Status +Accepted + +## Decision +The only authored machine-readable source of truth is `.ssot/registry.json`. + +## Consequences +- Split manifests, spreadsheets, and parallel mapping files are non-canonical. +- Reports, graphs, CSV projections, Markdown summaries, and SQLite mirrors are generated. diff --git a/.ssot/adr/ADR-0002-features-are-targetable-units.md b/.ssot/adr/ADR-0002-features-are-targetable-units.md new file mode 100644 index 00000000..f852dcaa --- /dev/null +++ b/.ssot/adr/ADR-0002-features-are-targetable-units.md @@ -0,0 +1,11 @@ +# ADR-0002: Features are the targetable units + +## Status +Accepted + +## Decision +Features are the only targetable implementation units. There is no separate `targets[]` section. + +## Consequences +- Planning horizon and target claim tier live on feature rows. +- Scope is defined by selected feature IDs inside boundaries. diff --git a/.ssot/adr/ADR-0003-issues-are-plannable-work-items.md b/.ssot/adr/ADR-0003-issues-are-plannable-work-items.md new file mode 100644 index 00000000..b050f028 --- /dev/null +++ b/.ssot/adr/ADR-0003-issues-are-plannable-work-items.md @@ -0,0 +1,11 @@ +# ADR-0003: Issues are plannable work items + +## Status +Accepted + +## Decision +Issues and tickets can be planned as current, next, future, explicit, backlog, or out-of-bounds, but they are not substitute targets for features. + +## Consequences +- Delivery scope and remediation scope remain distinct. +- Issues may still block certification and release. diff --git a/.ssot/adr/ADR-0004-entity-centric-registry-derived-graph.md b/.ssot/adr/ADR-0004-entity-centric-registry-derived-graph.md new file mode 100644 index 00000000..4327debe --- /dev/null +++ b/.ssot/adr/ADR-0004-entity-centric-registry-derived-graph.md @@ -0,0 +1,11 @@ +# ADR-0004: Entity-centric registry with a derived graph export + +## Status +Accepted + +## Decision +The canonical registry is entity-centric JSON with explicit references. A graph export is derived from it. + +## Consequences +- Authoring stays practical in Git. +- Programmatic graph traversal remains available. diff --git a/.ssot/adr/ADR-0005-normalized-prefixed-ids.md b/.ssot/adr/ADR-0005-normalized-prefixed-ids.md new file mode 100644 index 00000000..7fa9aeac --- /dev/null +++ b/.ssot/adr/ADR-0005-normalized-prefixed-ids.md @@ -0,0 +1,11 @@ +# ADR-0005: Normalized prefixed IDs + +## Status +Accepted + +## Decision +Every first-class entity uses a normalized prefixed ID. + +## Consequences +- Stable references across repositories and generated artifacts. +- Easy namespace validation and filesystem-safe projection. diff --git a/.ssot/adr/ADR-0006-claim-status-vs-tier.md b/.ssot/adr/ADR-0006-claim-status-vs-tier.md new file mode 100644 index 00000000..8afd3fa2 --- /dev/null +++ b/.ssot/adr/ADR-0006-claim-status-vs-tier.md @@ -0,0 +1,11 @@ +# ADR-0006: Claim status and claim tier are orthogonal + +## Status +Accepted + +## Decision +Claim status expresses lifecycle progression. Claim tier expresses assurance strength. + +## Consequences +- Workflow and assurance are not conflated. +- Tiers remain stable while statuses advance. diff --git a/.ssot/adr/ADR-0007-feature-implementation-vs-lifecycle.md b/.ssot/adr/ADR-0007-feature-implementation-vs-lifecycle.md new file mode 100644 index 00000000..4a44e00d --- /dev/null +++ b/.ssot/adr/ADR-0007-feature-implementation-vs-lifecycle.md @@ -0,0 +1,11 @@ +# ADR-0007: Feature implementation state is separate from lifecycle state + +## Status +Accepted + +## Decision +`implementation_status` and `lifecycle.stage` are distinct fields. + +## Consequences +- Deprecation, obsolescence, and removal are modeled cleanly. +- Implementation readiness is not overloaded with support-state semantics. diff --git a/.ssot/adr/ADR-0008-immutable-boundary-and-release-snapshots.md b/.ssot/adr/ADR-0008-immutable-boundary-and-release-snapshots.md new file mode 100644 index 00000000..868905f8 --- /dev/null +++ b/.ssot/adr/ADR-0008-immutable-boundary-and-release-snapshots.md @@ -0,0 +1,11 @@ +# ADR-0008: Immutable boundary and release snapshots + +## Status +Accepted + +## Decision +Frozen boundaries and promoted/published releases emit immutable snapshots with hashes. + +## Consequences +- Auditable, reproducible release state. +- Clear separation between authored truth and frozen evidence. diff --git a/.ssot/adr/ADR-0009-fail-closed-guards.md b/.ssot/adr/ADR-0009-fail-closed-guards.md new file mode 100644 index 00000000..ef873cd9 --- /dev/null +++ b/.ssot/adr/ADR-0009-fail-closed-guards.md @@ -0,0 +1,11 @@ +# ADR-0009: Fail-closed guards + +## Status +Accepted + +## Decision +Validation, certification, promotion, publication, and lifecycle transitions refuse to proceed on guard violations. + +## Consequences +- No silent drift. +- No optimistic release progression. diff --git a/.ssot/adr/ADR-0010-generated-projections-are-non-canonical.md b/.ssot/adr/ADR-0010-generated-projections-are-non-canonical.md new file mode 100644 index 00000000..201140d0 --- /dev/null +++ b/.ssot/adr/ADR-0010-generated-projections-are-non-canonical.md @@ -0,0 +1,11 @@ +# ADR-0010: Generated projections are non-canonical + +## Status +Accepted + +## Decision +DOT, JSON graph exports, CSV files, Markdown summaries, and SQLite mirrors are generated views. + +## Consequences +- Canonical authorship remains singular. +- Regeneration is deterministic. diff --git a/.ssot/adr/ADR-0011-explicit-schema-versioning.md b/.ssot/adr/ADR-0011-explicit-schema-versioning.md new file mode 100644 index 00000000..2edff98a --- /dev/null +++ b/.ssot/adr/ADR-0011-explicit-schema-versioning.md @@ -0,0 +1,11 @@ +# ADR-0011: Explicit schema versioning + +## Status +Accepted + +## Decision +Breaking schema changes increment `schema_version` and require migration. + +## Consequences +- No compatibility shims. +- No ambiguous reader behavior. diff --git a/.ssot/adr/ADR-0012-portable-core-repo-specific-evidence-adapters.md b/.ssot/adr/ADR-0012-portable-core-repo-specific-evidence-adapters.md new file mode 100644 index 00000000..5e5b569c --- /dev/null +++ b/.ssot/adr/ADR-0012-portable-core-repo-specific-evidence-adapters.md @@ -0,0 +1,11 @@ +# ADR-0012: Portable core with repo-specific evidence generation outside the core + +## Status +Accepted + +## Decision +The core package validates and governs the registry graph, while repository-specific evidence generation remains external or adapter-driven. + +## Consequences +- The package stays portable. +- Evidence generation does not hard-code repository-specific build logic. diff --git a/docs/adr/0001-preserve-asgi-boundary.md b/.ssot/adr/ADR-1001-preserve-asgi-boundary.md similarity index 68% rename from docs/adr/0001-preserve-asgi-boundary.md rename to .ssot/adr/ADR-1001-preserve-asgi-boundary.md index 104cf103..f646f4ee 100644 --- a/docs/adr/0001-preserve-asgi-boundary.md +++ b/.ssot/adr/ADR-1001-preserve-asgi-boundary.md @@ -1,4 +1,6 @@ -# ADR 0001 — preserve the ASGI boundary +# ADR-1001: preserve the ASGI boundary + +# ADR 1001 — preserve the ASGI boundary Decision: TigrCorn remains an ASGI server at its public boundary. diff --git a/docs/adr/0002-transport-protocol-separation.md b/.ssot/adr/ADR-1002-transport-protocol-separation.md similarity index 72% rename from docs/adr/0002-transport-protocol-separation.md rename to .ssot/adr/ADR-1002-transport-protocol-separation.md index a5369c71..8717b460 100644 --- a/docs/adr/0002-transport-protocol-separation.md +++ b/.ssot/adr/ADR-1002-transport-protocol-separation.md @@ -1,4 +1,6 @@ -# ADR 0002 — separate transport and protocol +# ADR-1002: separate transport and protocol + +# ADR 1002 — separate transport and protocol Decision: transport code and protocol code live in separate module trees. diff --git a/docs/adr/0003-scheduler-and-backpressure.md b/.ssot/adr/ADR-1003-scheduler-and-backpressure.md similarity index 55% rename from docs/adr/0003-scheduler-and-backpressure.md rename to .ssot/adr/ADR-1003-scheduler-and-backpressure.md index 76894d27..5effe316 100644 --- a/docs/adr/0003-scheduler-and-backpressure.md +++ b/.ssot/adr/ADR-1003-scheduler-and-backpressure.md @@ -1,4 +1,6 @@ -# ADR 0003 — scheduler and backpressure are separate concerns +# ADR-1003: scheduler and backpressure are separate concerns + +# ADR 1003 — scheduler and backpressure are separate concerns Decision: concurrency and flow control belong in explicit scheduler and flow modules. diff --git a/docs/adr/0004-custom-scope-types.md b/.ssot/adr/ADR-1004-custom-scope-types.md similarity index 64% rename from docs/adr/0004-custom-scope-types.md rename to .ssot/adr/ADR-1004-custom-scope-types.md index 5bd767d4..ca93a497 100644 --- a/docs/adr/0004-custom-scope-types.md +++ b/.ssot/adr/ADR-1004-custom-scope-types.md @@ -1,4 +1,6 @@ -# ADR 0004 — custom scope types are allowed behind the ASGI surface +# ADR-1004: custom scope types are allowed behind the ASGI surface + +# ADR 1004 — custom scope types are allowed behind the ASGI surface Decision: custom transports may expose custom scope types in the future. diff --git a/docs/adr/0005-doc-gov.md b/.ssot/adr/ADR-1005-doc-gov.md similarity index 90% rename from docs/adr/0005-doc-gov.md rename to .ssot/adr/ADR-1005-doc-gov.md index 31447b91..dc3e2fb2 100644 --- a/docs/adr/0005-doc-gov.md +++ b/.ssot/adr/ADR-1005-doc-gov.md @@ -1,4 +1,6 @@ -# ADR 0005 — doc governance tree +# ADR-1005: doc governance tree + +# ADR 1005 — doc governance tree ## Status diff --git a/docs/adr/0006-mutable.md b/.ssot/adr/ADR-1006-mutable.md similarity index 86% rename from docs/adr/0006-mutable.md rename to .ssot/adr/ADR-1006-mutable.md index af0cf59f..3df610a4 100644 --- a/docs/adr/0006-mutable.md +++ b/.ssot/adr/ADR-1006-mutable.md @@ -1,4 +1,6 @@ -# ADR 0006 — mutable and immutable marks +# ADR-1006: mutable and immutable marks + +# ADR 1006 — mutable and immutable marks ## Status diff --git a/docs/adr/0007-gov-auth.md b/.ssot/adr/ADR-1007-gov-auth.md similarity index 75% rename from docs/adr/0007-gov-auth.md rename to .ssot/adr/ADR-1007-gov-auth.md index b1953c16..d13da41f 100644 --- a/docs/adr/0007-gov-auth.md +++ b/.ssot/adr/ADR-1007-gov-auth.md @@ -1,4 +1,6 @@ -# ADR 0007: Governance Authority +# ADR-1007: : Governance Authority + +# ADR 1007: Governance Authority Status: accepted diff --git a/docs/adr/0008-gate-graph.md b/.ssot/adr/ADR-1008-gate-graph.md similarity index 78% rename from docs/adr/0008-gate-graph.md rename to .ssot/adr/ADR-1008-gate-graph.md index 95c56afd..2d762271 100644 --- a/docs/adr/0008-gate-graph.md +++ b/.ssot/adr/ADR-1008-gate-graph.md @@ -1,4 +1,6 @@ -# ADR 0008: Release Gate Graph +# ADR-1008: : Release Gate Graph + +# ADR 1008: Release Gate Graph Status: accepted diff --git a/.ssot/registry.json b/.ssot/registry.json new file mode 100644 index 00000000..b600584f --- /dev/null +++ b/.ssot/registry.json @@ -0,0 +1,1270 @@ +{ + "schema_version": 4, + "repo": { + "id": "repo:tigrcorn", + "name": "tigrcorn", + "version": "0.3.9" + }, + "tooling": { + "ssot_registry_version": "0.2.2", + "initialized_with_version": "0.2.2", + "last_upgraded_from_version": "0.2.2" + }, + "paths": { + "ssot_root": ".ssot", + "schema_root": ".ssot/schemas", + "adr_root": ".ssot/adr", + "spec_root": ".ssot/specs", + "graph_root": ".ssot/graphs", + "evidence_root": ".ssot/evidence", + "release_root": ".ssot/releases", + "report_root": ".ssot/reports", + "cache_root": ".ssot/cache" + }, + "program": { + "active_boundary_id": "bnd:default", + "active_release_id": "rel:0.3.9" + }, + "guard_policies": { + "claim_closure": { + "require_implemented_features": true, + "require_linked_tests_passing": true, + "require_linked_evidence_passing": true, + "require_claim_evidence_tier_alignment": true, + "forbid_failed_or_stale_evidence": true + }, + "certification": { + "require_release_status_draft_or_candidate": true, + "require_frozen_boundary": true, + "require_release_claim_coverage_for_boundary_features": true, + "require_boundary_features_current_or_explicit": true, + "require_feature_target_tiers_met": true, + "forbid_open_release_blocking_issues": true, + "forbid_active_release_blocking_risks": true + }, + "promotion": { + "require_release_status_certified": true, + "require_release_snapshot_hashes": true + }, + "publication": { + "require_release_status_promoted": true + }, + "lifecycle": { + "require_replacement_or_note_for_deprecation": true, + "forbid_obsolete_or_removed_in_active_boundary": true, + "require_feature_absent_for_removed": true + } + }, + "document_id_reservations": { + "adr": [ + { + "owner": "ssot-core", + "start": 1, + "end": 999, + "immutable": true, + "deletable": false, + "assignable_by_repo": false + }, + { + "owner": "repo-local-default", + "start": 1000, + "end": 4999, + "immutable": false, + "deletable": true, + "assignable_by_repo": true + } + ], + "spec": [ + { + "owner": "ssot-core", + "start": 1, + "end": 999, + "immutable": true, + "deletable": false, + "assignable_by_repo": false + }, + { + "owner": "repo-local-default", + "start": 1000, + "end": 4999, + "immutable": false, + "deletable": true, + "assignable_by_repo": true + } + ] + }, + "features": [ + { + "id": "feat:tigrcorn-http1", + "title": "HTTP/1.1 protocol surface", + "description": "RFC 9112 certification surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-http1" + ], + "test_ids": [ + "tst:tigrcorn-http1" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-http2", + "title": "HTTP/2 protocol surface", + "description": "RFC 9113 certification surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-http2" + ], + "test_ids": [ + "tst:tigrcorn-http2" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-http3", + "title": "HTTP/3 protocol surface", + "description": "RFC 9114 certification surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-http3" + ], + "test_ids": [ + "tst:tigrcorn-http3" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-quic", + "title": "QUIC transport surface", + "description": "RFC 9000/9001/9002 certification surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-quic" + ], + "test_ids": [ + "tst:tigrcorn-quic" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-websocket", + "title": "WebSocket protocol surface", + "description": "RFC 6455/8441/9220 certification surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-websocket" + ], + "test_ids": [ + "tst:tigrcorn-websocket" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-custom-transports", + "title": "Custom transport family", + "description": "Custom transport conformance surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-custom-transports" + ], + "test_ids": [ + "tst:tigrcorn-custom-transports" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-public-api", + "title": "Public API surface", + "description": "Public API conformance surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-public-api" + ], + "test_ids": [ + "tst:tigrcorn-public-api" + ], + "requires": [] + }, + { + "id": "feat:tigrcorn-cli", + "title": "CLI operator surface", + "description": "CLI contract conformance surface", + "implementation_status": "implemented", + "lifecycle": { + "stage": "active", + "replacement_feature_ids": [], + "note": null + }, + "plan": { + "horizon": "current", + "slot": null, + "target_claim_tier": "T2", + "target_lifecycle_stage": "active" + }, + "claim_ids": [ + "clm:tigrcorn-cli" + ], + "test_ids": [ + "tst:tigrcorn-cli" + ], + "requires": [] + } + ], + "tests": [ + { + "id": "tst:tigrcorn-http1", + "title": "HTTP/1.1 protocol surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_http1_rfc9112.py", + "feature_ids": [ + "feat:tigrcorn-http1" + ], + "claim_ids": [ + "clm:tigrcorn-http1" + ], + "evidence_ids": [ + "evd:tigrcorn-http1" + ] + }, + { + "id": "tst:tigrcorn-http2", + "title": "HTTP/2 protocol surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_http2_rfc9113.py", + "feature_ids": [ + "feat:tigrcorn-http2" + ], + "claim_ids": [ + "clm:tigrcorn-http2" + ], + "evidence_ids": [ + "evd:tigrcorn-http2" + ] + }, + { + "id": "tst:tigrcorn-http3", + "title": "HTTP/3 protocol surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_http3_rfc9114.py", + "feature_ids": [ + "feat:tigrcorn-http3" + ], + "claim_ids": [ + "clm:tigrcorn-http3" + ], + "evidence_ids": [ + "evd:tigrcorn-http3" + ] + }, + { + "id": "tst:tigrcorn-quic", + "title": "QUIC transport surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_quic_packets_rfc9000.py", + "feature_ids": [ + "feat:tigrcorn-quic" + ], + "claim_ids": [ + "clm:tigrcorn-quic" + ], + "evidence_ids": [ + "evd:tigrcorn-quic" + ] + }, + { + "id": "tst:tigrcorn-websocket", + "title": "WebSocket protocol surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_websocket_rfc6455.py", + "feature_ids": [ + "feat:tigrcorn-websocket" + ], + "claim_ids": [ + "clm:tigrcorn-websocket" + ], + "evidence_ids": [ + "evd:tigrcorn-websocket" + ] + }, + { + "id": "tst:tigrcorn-custom-transports", + "title": "Custom transport family test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_pipe_and_inproc.py", + "feature_ids": [ + "feat:tigrcorn-custom-transports" + ], + "claim_ids": [ + "clm:tigrcorn-custom-transports" + ], + "evidence_ids": [ + "evd:tigrcorn-custom-transports" + ] + }, + { + "id": "tst:tigrcorn-public-api", + "title": "Public API surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_import.py", + "feature_ids": [ + "feat:tigrcorn-public-api" + ], + "claim_ids": [ + "clm:tigrcorn-public-api" + ], + "evidence_ids": [ + "evd:tigrcorn-public-api" + ] + }, + { + "id": "tst:tigrcorn-cli", + "title": "CLI operator surface test coverage", + "status": "passing", + "kind": "pytest", + "path": "tests/test_cli_and_asgi3.py", + "feature_ids": [ + "feat:tigrcorn-cli" + ], + "claim_ids": [ + "clm:tigrcorn-cli" + ], + "evidence_ids": [ + "evd:tigrcorn-cli" + ] + } + ], + "claims": [ + { + "id": "clm:tigrcorn-http1", + "title": "HTTP/1.1 protocol surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "RFC 9112 certification surface", + "feature_ids": [ + "feat:tigrcorn-http1" + ], + "test_ids": [ + "tst:tigrcorn-http1" + ], + "evidence_ids": [ + "evd:tigrcorn-http1" + ] + }, + { + "id": "clm:tigrcorn-http2", + "title": "HTTP/2 protocol surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "RFC 9113 certification surface", + "feature_ids": [ + "feat:tigrcorn-http2" + ], + "test_ids": [ + "tst:tigrcorn-http2" + ], + "evidence_ids": [ + "evd:tigrcorn-http2" + ] + }, + { + "id": "clm:tigrcorn-http3", + "title": "HTTP/3 protocol surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "RFC 9114 certification surface", + "feature_ids": [ + "feat:tigrcorn-http3" + ], + "test_ids": [ + "tst:tigrcorn-http3" + ], + "evidence_ids": [ + "evd:tigrcorn-http3" + ] + }, + { + "id": "clm:tigrcorn-quic", + "title": "QUIC transport surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "RFC 9000/9001/9002 certification surface", + "feature_ids": [ + "feat:tigrcorn-quic" + ], + "test_ids": [ + "tst:tigrcorn-quic" + ], + "evidence_ids": [ + "evd:tigrcorn-quic" + ] + }, + { + "id": "clm:tigrcorn-websocket", + "title": "WebSocket protocol surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "RFC 6455/8441/9220 certification surface", + "feature_ids": [ + "feat:tigrcorn-websocket" + ], + "test_ids": [ + "tst:tigrcorn-websocket" + ], + "evidence_ids": [ + "evd:tigrcorn-websocket" + ] + }, + { + "id": "clm:tigrcorn-custom-transports", + "title": "Custom transport family", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "Custom transport conformance surface", + "feature_ids": [ + "feat:tigrcorn-custom-transports" + ], + "test_ids": [ + "tst:tigrcorn-custom-transports" + ], + "evidence_ids": [ + "evd:tigrcorn-custom-transports" + ] + }, + { + "id": "clm:tigrcorn-public-api", + "title": "Public API surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "Public API conformance surface", + "feature_ids": [ + "feat:tigrcorn-public-api" + ], + "test_ids": [ + "tst:tigrcorn-public-api" + ], + "evidence_ids": [ + "evd:tigrcorn-public-api" + ] + }, + { + "id": "clm:tigrcorn-cli", + "title": "CLI operator surface", + "status": "implemented", + "tier": "T2", + "kind": "conformance", + "description": "CLI contract conformance surface", + "feature_ids": [ + "feat:tigrcorn-cli" + ], + "test_ids": [ + "tst:tigrcorn-cli" + ], + "evidence_ids": [ + "evd:tigrcorn-cli" + ] + } + ], + "evidence": [ + { + "id": "evd:tigrcorn-http1", + "title": "HTTP/1.1 protocol surface evidence", + "status": "planned", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/external_matrix.release.json", + "claim_ids": [ + "clm:tigrcorn-http1" + ], + "test_ids": [ + "tst:tigrcorn-http1" + ] + }, + { + "id": "evd:tigrcorn-http2", + "title": "HTTP/2 protocol surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/external_matrix.release.json", + "claim_ids": [ + "clm:tigrcorn-http2" + ], + "test_ids": [ + "tst:tigrcorn-http2" + ] + }, + { + "id": "evd:tigrcorn-http3", + "title": "HTTP/3 protocol surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/external_matrix.release.json", + "claim_ids": [ + "clm:tigrcorn-http3" + ], + "test_ids": [ + "tst:tigrcorn-http3" + ] + }, + { + "id": "evd:tigrcorn-quic", + "title": "QUIC transport surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/external_matrix.release.json", + "claim_ids": [ + "clm:tigrcorn-quic" + ], + "test_ids": [ + "tst:tigrcorn-quic" + ] + }, + { + "id": "evd:tigrcorn-websocket", + "title": "WebSocket protocol surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/external_matrix.release.json", + "claim_ids": [ + "clm:tigrcorn-websocket" + ], + "test_ids": [ + "tst:tigrcorn-websocket" + ] + }, + { + "id": "evd:tigrcorn-custom-transports", + "title": "Custom transport family evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/corpus.json", + "claim_ids": [ + "clm:tigrcorn-custom-transports" + ], + "test_ids": [ + "tst:tigrcorn-custom-transports" + ] + }, + { + "id": "evd:tigrcorn-public-api", + "title": "Public API surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/claims_registry.json", + "claim_ids": [ + "clm:tigrcorn-public-api" + ], + "test_ids": [ + "tst:tigrcorn-public-api" + ] + }, + { + "id": "evd:tigrcorn-cli", + "title": "CLI operator surface evidence", + "status": "passed", + "kind": "conformance", + "tier": "T2", + "path": "docs/review/conformance/flag_contracts.json", + "claim_ids": [ + "clm:tigrcorn-cli" + ], + "test_ids": [ + "tst:tigrcorn-cli" + ] + } + ], + "issues": [], + "risks": [], + "boundaries": [ + { + "id": "bnd:default", + "title": "Default boundary", + "status": "draft", + "frozen": false, + "feature_ids": [] + } + ], + "releases": [ + { + "id": "rel:0.3.9", + "version": "0.3.9", + "status": "draft", + "boundary_id": "bnd:default", + "claim_ids": [], + "evidence_ids": [] + } + ], + "adrs": [ + { + "id": "adr:0001", + "number": 1, + "slug": "canonical-json-registry", + "title": "Canonical registry is a single JSON document", + "path": ".ssot/adr/ADR-0001-canonical-json-registry.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "9f5bb7d2ee345837ed30579c9e494a239f470855776ba5dc10e1e5285ec75997", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0002", + "number": 2, + "slug": "features-are-targetable-units", + "title": "Features are the targetable units", + "path": ".ssot/adr/ADR-0002-features-are-targetable-units.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "c088e2e19d94b2751b170bff365d71361ee505e67c6467718b9dba9819fa98cb", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0003", + "number": 3, + "slug": "issues-are-plannable-work-items", + "title": "Issues are plannable work items", + "path": ".ssot/adr/ADR-0003-issues-are-plannable-work-items.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "5f9facd077de1b597cd92f881be2f24e7d2a84c53fbafadaa8d90e5a6fd43d36", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0004", + "number": 4, + "slug": "entity-centric-registry-derived-graph", + "title": "Entity-centric registry with a derived graph export", + "path": ".ssot/adr/ADR-0004-entity-centric-registry-derived-graph.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "9070a9343059aeb88c9c814eb6b09779259655b64db1c72c8dc87b67a5e0208b", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0005", + "number": 5, + "slug": "normalized-prefixed-ids", + "title": "Normalized prefixed IDs", + "path": ".ssot/adr/ADR-0005-normalized-prefixed-ids.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "1b3ac2ec39ede1aa4f393d70ba284d76e5fb8be43aaf76bed3461b5c0d8bf790", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0006", + "number": 6, + "slug": "claim-status-vs-tier", + "title": "Claim status and claim tier are orthogonal", + "path": ".ssot/adr/ADR-0006-claim-status-vs-tier.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "77b436414b489d834b4cfc3c9e73d3109253c1e69e4c5177773ba1b2e1a049b9", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0007", + "number": 7, + "slug": "feature-implementation-vs-lifecycle", + "title": "Feature implementation state is separate from lifecycle state", + "path": ".ssot/adr/ADR-0007-feature-implementation-vs-lifecycle.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "1d9827f1d9ac80e21c9eb01860525546a12414b6d4dd59f85e2d1bfe3d9386f2", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0008", + "number": 8, + "slug": "immutable-boundary-and-release-snapshots", + "title": "Immutable boundary and release snapshots", + "path": ".ssot/adr/ADR-0008-immutable-boundary-and-release-snapshots.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "05cdcfecdd0291bf70d83df6f759234a6e030bee813f9ffccc281339f1020020", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0009", + "number": 9, + "slug": "fail-closed-guards", + "title": "Fail-closed guards", + "path": ".ssot/adr/ADR-0009-fail-closed-guards.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "b3e4968a2407889f0a369cb4cd09aa6b22e25a6404d4aeda17ef9d8b39f639b8", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0010", + "number": 10, + "slug": "generated-projections-are-non-canonical", + "title": "Generated projections are non-canonical", + "path": ".ssot/adr/ADR-0010-generated-projections-are-non-canonical.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "9384cc13dad85dc2ee3d65405edf92ae0cb8c90874db52beba33fa63f1fb1aad", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0011", + "number": 11, + "slug": "explicit-schema-versioning", + "title": "Explicit schema versioning", + "path": ".ssot/adr/ADR-0011-explicit-schema-versioning.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "476d6d2c6e8bd6f6775492f11f2de3f26b77545dda62bd6e78e34ff37b53ed4e", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:0012", + "number": 12, + "slug": "portable-core-repo-specific-evidence-adapters", + "title": "Portable core with repo-specific evidence generation outside the core", + "path": ".ssot/adr/ADR-0012-portable-core-repo-specific-evidence-adapters.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "ba8ea2c1e20eda7094c2cf92c9fd63427c1ef3edf9c18d2f43357e761101ba79", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1001", + "number": 1001, + "slug": "preserve-asgi-boundary", + "title": "preserve the ASGI boundary", + "path": ".ssot/adr/ADR-1001-preserve-asgi-boundary.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "430d2f4fa5b83d61992d6a5d317ce37e0e955d7c2b777ed2bea07ba316d35482", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1002", + "number": 1002, + "slug": "transport-protocol-separation", + "title": "separate transport and protocol", + "path": ".ssot/adr/ADR-1002-transport-protocol-separation.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "9be9b9cbd18c271dfc708f41919588e68e0d143b3c7828c2119ebfac31c67cf5", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1003", + "number": 1003, + "slug": "scheduler-and-backpressure", + "title": "scheduler and backpressure are separate concerns", + "path": ".ssot/adr/ADR-1003-scheduler-and-backpressure.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "a29be99c50f621002a2af38e002ec0826253464da98178c3782985c7d23acddf", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1004", + "number": 1004, + "slug": "custom-scope-types", + "title": "custom scope types are allowed behind the ASGI surface", + "path": ".ssot/adr/ADR-1004-custom-scope-types.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "d6e94558cef990cd83442281460273f4ac6b67faf04b62ec51caee5b42f0df1b", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1005", + "number": 1005, + "slug": "doc-gov", + "title": "doc governance tree", + "path": ".ssot/adr/ADR-1005-doc-gov.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "373352003f497e5bea0482f6ee2f34e70dc115b5be5a8db2d5ac573002ec8fae", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1006", + "number": 1006, + "slug": "mutable", + "title": "mutable and immutable marks", + "path": ".ssot/adr/ADR-1006-mutable.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "8ea13e784c3a4ba92ad3f5cb5085e90bc5c13c86086d77c38031ec62cced8b60", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1007", + "number": 1007, + "slug": "gov-auth", + "title": ": Governance Authority", + "path": ".ssot/adr/ADR-1007-gov-auth.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "74e7f01728d696aed0ae9d6d0b8253cdbaa9e37c3a14fafeac2a1a5decdb6b71", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + }, + { + "id": "adr:1008", + "number": 1008, + "slug": "gate-graph", + "title": ": Release Gate Graph", + "path": ".ssot/adr/ADR-1008-gate-graph.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "3e145b27726e557f5b28cf1c9ee441a15a3609d0fb821b1fd4eb7cf5123747cf", + "status": "accepted", + "supersedes": [], + "superseded_by": [] + } + ], + "specs": [ + { + "id": "spc:0001", + "number": 1, + "slug": "registry-core", + "title": "Registry core", + "path": ".ssot/specs/SPEC-0001-registry-core.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "2244e964a2e98cbb8c96959e80f94fbb6684825aa41f64e34d9bc918cb229b35", + "kind": "normative" + }, + { + "id": "spc:0002", + "number": 2, + "slug": "cli", + "title": "CLI", + "path": ".ssot/specs/SPEC-0002-cli.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "921aecf6cf292ef841c49c73b45ab8a38bdae817ef850097a870dc5241473c39", + "kind": "operational" + }, + { + "id": "spc:0003", + "number": 3, + "slug": "graph-model", + "title": "Graph model", + "path": ".ssot/specs/SPEC-0003-graph-model.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "dbf7093288b63b1fd3a1f38d60b66147d93c27511487de992ee0d59efb43b744", + "kind": "normative" + }, + { + "id": "spc:0004", + "number": 4, + "slug": "feature-lifecycle", + "title": "Feature lifecycle", + "path": ".ssot/specs/SPEC-0004-feature-lifecycle.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "93f42169b551989e38f00598f899e6bfd9fc443a15467da77ead51c5bd01d02e", + "kind": "normative" + }, + { + "id": "spc:0005", + "number": 5, + "slug": "claim-statuses", + "title": "Claim statuses", + "path": ".ssot/specs/SPEC-0005-claim-statuses.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "a22501ba039e61a6f438d50685a3e33a7928fb37179f4a8da31c8c3420ed9683", + "kind": "normative" + }, + { + "id": "spc:0006", + "number": 6, + "slug": "claim-tiers", + "title": "Claim tiers", + "path": ".ssot/specs/SPEC-0006-claim-tiers.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "a86608fc0ae4b045cdf59257e666f0254df9a26f2dd93897628fafc142169163", + "kind": "normative" + }, + { + "id": "spc:0007", + "number": 7, + "slug": "snapshots-and-reports", + "title": "Snapshots and reports", + "path": ".ssot/specs/SPEC-0007-snapshots-and-reports.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "47d3d3298a978e525b315a779db920714946011ccda92a0caf2e2a5d72cd21cb", + "kind": "operational" + }, + { + "id": "spc:0008", + "number": 8, + "slug": "repo-policy", + "title": "Repository policy", + "path": ".ssot/specs/SPEC-0008-repo-policy.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "6e80832275da7d4c3609cbef3e39c1128bd14d559cdf315f78982dcc8f91edbf", + "kind": "operational" + }, + { + "id": "spc:0009", + "number": 9, + "slug": "gates-and-fences", + "title": "Gates and fences", + "path": ".ssot/specs/SPEC-0009-gates-and-fences.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "20ad0cb68eafaef7c0095136eef6ebe9b0704b5ad3d81211039ef73745bc02af", + "kind": "normative" + }, + { + "id": "spc:0010", + "number": 10, + "slug": "id-normalization", + "title": "ID normalization", + "path": ".ssot/specs/SPEC-0010-id-normalization.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "a217c496f8534f78906cf589ec07f14f3babfbf900d848a94bb58202ea06044f", + "kind": "normative" + }, + { + "id": "spc:0011", + "number": 11, + "slug": "file-tree", + "title": "File tree", + "path": ".ssot/specs/SPEC-0011-file-tree.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "739d774289548e1d10e9c20dd88d24e774b1ddfd68cdc16bf8424481ef4b705b", + "kind": "normative" + }, + { + "id": "spc:0012", + "number": 12, + "slug": "planning-horizons", + "title": "Planning horizons", + "path": ".ssot/specs/SPEC-0012-planning-horizons.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "bd748f1d15321d770410ed04ebfe4e6e558e02a30bfbd4e4bddce327f2f7f2d0", + "kind": "normative" + }, + { + "id": "spc:0013", + "number": 13, + "slug": "python-api", + "title": "Python API", + "path": ".ssot/specs/SPEC-0013-python-api.md", + "origin": "ssot-core", + "managed": true, + "immutable": true, + "package_version": "0.2.2", + "content_sha256": "a18bcc7c72373487d8cd4a88b93b605ca6a46703dbd8d5fa5d9f8c86937348da", + "kind": "operational" + }, + { + "id": "spc:2001", + "number": 2001, + "slug": "http1", + "title": "HTTP/1.1", + "path": ".ssot/specs/SPEC-2001-http1.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "974ec6d9c3fac81dcd7b9b056ce273fe19a45ecfe19d03cfba4b8bca62572c38", + "kind": "repo-local" + }, + { + "id": "spc:2002", + "number": 2002, + "slug": "http2", + "title": "HTTP/2", + "path": ".ssot/specs/SPEC-2002-http2.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "1b0ecdae4b0e30e881eed18df6d5eb29f1f1feb84fe5e74f5bc9fca64b02e85f", + "kind": "repo-local" + }, + { + "id": "spc:2003", + "number": 2003, + "slug": "http3", + "title": "HTTP/3", + "path": ".ssot/specs/SPEC-2003-http3.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "8740cd8f8b8164da3b8b78aef251d46a8736b9ebf3748ead902522e599bef4d4", + "kind": "repo-local" + }, + { + "id": "spc:2004", + "number": 2004, + "slug": "quic", + "title": "QUIC", + "path": ".ssot/specs/SPEC-2004-quic.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "ea159d02a27dccccb64b7a0edb4f6cadc1e9ad80f2b7e9fc791e8e4e20ca24fb", + "kind": "repo-local" + }, + { + "id": "spc:2005", + "number": 2005, + "slug": "websocket", + "title": "WebSocket", + "path": ".ssot/specs/SPEC-2005-websocket.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "89560f61c4c2680485b8a799e1a98b4ac54ef3baf5dff4f0220360e685659e2b", + "kind": "repo-local" + }, + { + "id": "spc:2006", + "number": 2006, + "slug": "custom-transports", + "title": "Custom transports", + "path": ".ssot/specs/SPEC-2006-custom-transports.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "cb2d3cca84b5877a0efc3e19f8b8e0c5710024b81eb5cc701c84079fc83562b9", + "kind": "repo-local" + }, + { + "id": "spc:2007", + "number": 2007, + "slug": "public", + "title": "Public operator and programmatic surface reference", + "path": ".ssot/specs/SPEC-2007-public.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "82ce5937517d4423b044ba960dd733986d19173079d90b4387245820c1c8f105", + "kind": "repo-local" + }, + { + "id": "spc:2008", + "number": 2008, + "slug": "tigrcorn-cli", + "title": "CLI", + "path": ".ssot/specs/SPEC-2008-tigrcorn-cli.md", + "origin": "repo-local", + "managed": false, + "immutable": false, + "package_version": "0.2.2", + "content_sha256": "de995e4e1061844aa26a685dd71930a847932a7718a4b99858978578241e7439", + "kind": "repo-local" + } + ] +} diff --git a/.ssot/reports/upgrade.report.json b/.ssot/reports/upgrade.report.json new file mode 100644 index 00000000..7cb23384 --- /dev/null +++ b/.ssot/reports/upgrade.report.json @@ -0,0 +1,50 @@ +{ + "passed": true, + "registry_path": ".ssot/registry.json", + "from_schema_version": 4, + "to_schema_version": 4, + "from_version": "0.2.2", + "to_version": "0.2.2", + "migrations": [], + "renamed_specs": [], + "sync": { + "adr": { + "created": [], + "updated": [], + "unchanged": [ + "adr:0001", + "adr:0002", + "adr:0003", + "adr:0004", + "adr:0005", + "adr:0006", + "adr:0007", + "adr:0008", + "adr:0009", + "adr:0010", + "adr:0011", + "adr:0012" + ] + }, + "spec": { + "created": [], + "updated": [], + "unchanged": [ + "spc:0001", + "spc:0002", + "spc:0003", + "spc:0004", + "spc:0005", + "spc:0006", + "spc:0007", + "spc:0008", + "spc:0009", + "spc:0010", + "spc:0011", + "spc:0012", + "spc:0013" + ] + } + }, + "changed": true +} diff --git a/.ssot/schemas/boundary.snapshot.schema.json b/.ssot/schemas/boundary.snapshot.schema.json new file mode 100644 index 00000000..370fa3ea --- /dev/null +++ b/.ssot/schemas/boundary.snapshot.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/boundary.snapshot.schema.json", + "type": "object", + "required": [ + "schema_version", + "kind", + "generated_at", + "registry_path", + "registry_sha256", + "boundary", + "features", + "summary" + ] +} diff --git a/.ssot/schemas/certification.report.schema.json b/.ssot/schemas/certification.report.schema.json new file mode 100644 index 00000000..e737294e --- /dev/null +++ b/.ssot/schemas/certification.report.schema.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/certification.report.schema.json", + "type": "object", + "required": [ + "passed", + "registry_path", + "release", + "summary" + ] +} diff --git a/.ssot/schemas/graph.export.schema.json b/.ssot/schemas/graph.export.schema.json new file mode 100644 index 00000000..d68656ef --- /dev/null +++ b/.ssot/schemas/graph.export.schema.json @@ -0,0 +1,54 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/graph.export.schema.json", + "type": "object", + "required": [ + "nodes", + "edges" + ], + "properties": { + "nodes": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "kind" + ], + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string" + } + }, + "additionalProperties": false + } + }, + "edges": { + "type": "array", + "items": { + "type": "object", + "required": [ + "type", + "from", + "to" + ], + "properties": { + "type": { + "type": "string" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +} diff --git a/.ssot/schemas/published.snapshot.schema.json b/.ssot/schemas/published.snapshot.schema.json new file mode 100644 index 00000000..10a10e3b --- /dev/null +++ b/.ssot/schemas/published.snapshot.schema.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/published.snapshot.schema.json", + "type": "object", + "required": [ + "schema_version", + "kind", + "generated_at", + "registry_path", + "registry_sha256", + "release", + "boundary", + "claims", + "evidence", + "summary" + ] +} diff --git a/.ssot/schemas/registry.schema.json b/.ssot/schemas/registry.schema.json new file mode 100644 index 00000000..e4d86233 --- /dev/null +++ b/.ssot/schemas/registry.schema.json @@ -0,0 +1,965 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/registry.schema.json", + "title": "ssot-registry canonical registry", + "type": "object", + "required": [ + "schema_version", + "repo", + "tooling", + "paths", + "program", + "guard_policies", + "document_id_reservations", + "features", + "tests", + "claims", + "evidence", + "issues", + "risks", + "boundaries", + "releases", + "adrs", + "specs" + ], + "properties": { + "schema_version": { + "const": 4 + }, + "repo": { + "$ref": "#/$defs/repo" + }, + "tooling": { + "$ref": "#/$defs/tooling" + }, + "paths": { + "$ref": "#/$defs/paths" + }, + "program": { + "$ref": "#/$defs/program" + }, + "guard_policies": { + "$ref": "#/$defs/guardPolicies" + }, + "document_id_reservations": { + "$ref": "#/$defs/documentIdReservations" + }, + "features": { + "type": "array", + "items": { + "$ref": "#/$defs/feature" + } + }, + "tests": { + "type": "array", + "items": { + "$ref": "#/$defs/test" + } + }, + "claims": { + "type": "array", + "items": { + "$ref": "#/$defs/claim" + } + }, + "evidence": { + "type": "array", + "items": { + "$ref": "#/$defs/evidence" + } + }, + "issues": { + "type": "array", + "items": { + "$ref": "#/$defs/issue" + } + }, + "risks": { + "type": "array", + "items": { + "$ref": "#/$defs/risk" + } + }, + "boundaries": { + "type": "array", + "items": { + "$ref": "#/$defs/boundary" + } + }, + "releases": { + "type": "array", + "items": { + "$ref": "#/$defs/release" + } + }, + "adrs": { + "type": "array", + "items": { + "$ref": "#/$defs/adr" + } + }, + "specs": { + "type": "array", + "items": { + "$ref": "#/$defs/spec" + } + } + }, + "$defs": { + "normalizedId": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9._-]*$" + }, + "stringList": { + "type": "array", + "items": { + "type": "string" + } + }, + "repo": { + "type": "object", + "required": [ + "id", + "name", + "version" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "name": { + "type": "string", + "minLength": 1 + }, + "version": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": true + }, + "tooling": { + "type": "object", + "required": [ + "ssot_registry_version", + "initialized_with_version", + "last_upgraded_from_version" + ], + "properties": { + "ssot_registry_version": { + "type": "string", + "minLength": 1 + }, + "initialized_with_version": { + "type": "string", + "minLength": 1 + }, + "last_upgraded_from_version": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": true + }, + "paths": { + "type": "object", + "required": [ + "ssot_root", + "schema_root", + "adr_root", + "spec_root", + "graph_root", + "evidence_root", + "release_root", + "report_root", + "cache_root" + ], + "properties": { + "ssot_root": { + "type": "string", + "minLength": 1 + }, + "schema_root": { + "type": "string", + "minLength": 1 + }, + "adr_root": { + "type": "string", + "minLength": 1 + }, + "spec_root": { + "type": "string", + "minLength": 1 + }, + "graph_root": { + "type": "string", + "minLength": 1 + }, + "evidence_root": { + "type": "string", + "minLength": 1 + }, + "release_root": { + "type": "string", + "minLength": 1 + }, + "report_root": { + "type": "string", + "minLength": 1 + }, + "cache_root": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": true + }, + "program": { + "type": "object", + "required": [ + "active_boundary_id", + "active_release_id" + ], + "properties": { + "active_boundary_id": { + "$ref": "#/$defs/normalizedId" + }, + "active_release_id": { + "$ref": "#/$defs/normalizedId" + } + }, + "additionalProperties": true + }, + "guardPolicies": { + "type": "object", + "additionalProperties": true + }, + "documentReservationRange": { + "type": "object", + "required": [ + "owner", + "start", + "end", + "immutable", + "deletable", + "assignable_by_repo" + ], + "properties": { + "owner": { + "type": "string", + "minLength": 1 + }, + "start": { + "type": "integer", + "minimum": 1 + }, + "end": { + "type": "integer", + "minimum": 1 + }, + "immutable": { + "type": "boolean" + }, + "deletable": { + "type": "boolean" + }, + "assignable_by_repo": { + "type": "boolean" + } + }, + "additionalProperties": true + }, + "documentIdReservations": { + "type": "object", + "required": [ + "adr", + "spec" + ], + "properties": { + "adr": { + "type": "array", + "items": { + "$ref": "#/$defs/documentReservationRange" + } + }, + "spec": { + "type": "array", + "items": { + "$ref": "#/$defs/documentReservationRange" + } + } + }, + "additionalProperties": false + }, + "featurePlan": { + "type": "object", + "required": [ + "horizon", + "slot", + "target_claim_tier", + "target_lifecycle_stage" + ], + "properties": { + "horizon": { + "enum": [ + "current", + "next", + "future", + "explicit", + "backlog", + "out_of_bounds" + ] + }, + "slot": { + "type": [ + "string", + "null" + ] + }, + "target_claim_tier": { + "type": [ + "string", + "null" + ], + "enum": [ + "T0", + "T1", + "T2", + "T3", + "T4", + null + ] + }, + "target_lifecycle_stage": { + "enum": [ + "active", + "deprecated", + "obsolete", + "removed" + ] + } + }, + "additionalProperties": true + }, + "issuePlan": { + "type": "object", + "required": [ + "horizon", + "slot" + ], + "properties": { + "horizon": { + "enum": [ + "current", + "next", + "future", + "explicit", + "backlog", + "out_of_bounds" + ] + }, + "slot": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": true + }, + "featureLifecycle": { + "type": "object", + "required": [ + "stage", + "replacement_feature_ids", + "note" + ], + "properties": { + "stage": { + "enum": [ + "active", + "deprecated", + "obsolete", + "removed" + ] + }, + "replacement_feature_ids": { + "$ref": "#/$defs/stringList" + }, + "note": { + "type": [ + "string", + "null" + ] + }, + "effective_release_id": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": true + }, + "feature": { + "type": "object", + "required": [ + "id", + "title", + "description", + "implementation_status", + "lifecycle", + "plan", + "claim_ids", + "test_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string" + }, + "implementation_status": { + "enum": [ + "absent", + "partial", + "implemented" + ] + }, + "lifecycle": { + "$ref": "#/$defs/featureLifecycle" + }, + "plan": { + "$ref": "#/$defs/featurePlan" + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "test_ids": { + "$ref": "#/$defs/stringList" + }, + "requires": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "test": { + "type": "object", + "required": [ + "id", + "title", + "status", + "kind", + "path", + "feature_ids", + "claim_ids", + "evidence_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "planned", + "passing", + "failing", + "blocked", + "skipped" + ] + }, + "kind": { + "type": "string", + "minLength": 1 + }, + "path": { + "type": "string", + "minLength": 1 + }, + "feature_ids": { + "$ref": "#/$defs/stringList" + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "evidence_ids": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "claim": { + "type": "object", + "required": [ + "id", + "title", + "status", + "tier", + "kind", + "description", + "feature_ids", + "test_ids", + "evidence_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "proposed", + "declared", + "implemented", + "asserted", + "evidenced", + "certified", + "promoted", + "published", + "blocked", + "retired" + ] + }, + "tier": { + "enum": [ + "T0", + "T1", + "T2", + "T3", + "T4" + ] + }, + "kind": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string" + }, + "feature_ids": { + "$ref": "#/$defs/stringList" + }, + "test_ids": { + "$ref": "#/$defs/stringList" + }, + "evidence_ids": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "evidence": { + "type": "object", + "required": [ + "id", + "title", + "status", + "kind", + "tier", + "path", + "claim_ids", + "test_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "planned", + "collected", + "passed", + "failed", + "stale" + ] + }, + "kind": { + "type": "string", + "minLength": 1 + }, + "tier": { + "enum": [ + "T0", + "T1", + "T2", + "T3", + "T4" + ] + }, + "path": { + "type": "string", + "minLength": 1 + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "test_ids": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "issue": { + "type": "object", + "required": [ + "id", + "title", + "status", + "severity", + "description", + "plan", + "feature_ids", + "claim_ids", + "test_ids", + "evidence_ids", + "risk_ids", + "release_blocking" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "open", + "in_progress", + "blocked", + "resolved", + "closed" + ] + }, + "severity": { + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "description": { + "type": "string" + }, + "plan": { + "$ref": "#/$defs/issuePlan" + }, + "feature_ids": { + "$ref": "#/$defs/stringList" + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "test_ids": { + "$ref": "#/$defs/stringList" + }, + "evidence_ids": { + "$ref": "#/$defs/stringList" + }, + "risk_ids": { + "$ref": "#/$defs/stringList" + }, + "release_blocking": { + "type": "boolean" + } + }, + "additionalProperties": true + }, + "risk": { + "type": "object", + "required": [ + "id", + "title", + "status", + "severity", + "description", + "feature_ids", + "claim_ids", + "test_ids", + "evidence_ids", + "issue_ids", + "release_blocking" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "active", + "mitigated", + "accepted", + "retired" + ] + }, + "severity": { + "enum": [ + "low", + "medium", + "high", + "critical" + ] + }, + "description": { + "type": "string" + }, + "feature_ids": { + "$ref": "#/$defs/stringList" + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "test_ids": { + "$ref": "#/$defs/stringList" + }, + "evidence_ids": { + "$ref": "#/$defs/stringList" + }, + "issue_ids": { + "$ref": "#/$defs/stringList" + }, + "release_blocking": { + "type": "boolean" + } + }, + "additionalProperties": true + }, + "boundary": { + "type": "object", + "required": [ + "id", + "title", + "status", + "frozen", + "feature_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "draft", + "active", + "frozen", + "retired" + ] + }, + "frozen": { + "type": "boolean" + }, + "feature_ids": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "release": { + "type": "object", + "required": [ + "id", + "version", + "status", + "boundary_id", + "claim_ids", + "evidence_ids" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "version": { + "type": "string", + "minLength": 1 + }, + "status": { + "enum": [ + "draft", + "candidate", + "certified", + "promoted", + "published", + "revoked" + ] + }, + "boundary_id": { + "$ref": "#/$defs/normalizedId" + }, + "claim_ids": { + "$ref": "#/$defs/stringList" + }, + "evidence_ids": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "adr": { + "type": "object", + "required": [ + "id", + "number", + "slug", + "title", + "path", + "origin", + "managed", + "immutable", + "package_version", + "content_sha256", + "status", + "supersedes", + "superseded_by" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "number": { + "type": "integer", + "minimum": 1 + }, + "slug": { + "type": "string", + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "path": { + "type": "string", + "minLength": 1 + }, + "origin": { + "enum": [ + "ssot-core", + "repo-local" + ] + }, + "managed": { + "type": "boolean" + }, + "immutable": { + "type": "boolean" + }, + "package_version": { + "type": "string", + "minLength": 1 + }, + "content_sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "status": { + "enum": [ + "proposed", + "accepted", + "superseded", + "retired" + ] + }, + "supersedes": { + "$ref": "#/$defs/stringList" + }, + "superseded_by": { + "$ref": "#/$defs/stringList" + } + }, + "additionalProperties": true + }, + "spec": { + "type": "object", + "required": [ + "id", + "number", + "slug", + "title", + "path", + "origin", + "managed", + "immutable", + "package_version", + "content_sha256", + "kind" + ], + "properties": { + "id": { + "$ref": "#/$defs/normalizedId" + }, + "number": { + "type": "integer", + "minimum": 1 + }, + "slug": { + "type": "string", + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "path": { + "type": "string", + "minLength": 1 + }, + "origin": { + "enum": [ + "ssot-core", + "repo-local" + ] + }, + "managed": { + "type": "boolean" + }, + "immutable": { + "type": "boolean" + }, + "package_version": { + "type": "string", + "minLength": 1 + }, + "content_sha256": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "kind": { + "enum": [ + "normative", + "operational", + "repo-local" + ] + } + }, + "additionalProperties": true + } + }, + "additionalProperties": false +} diff --git a/.ssot/schemas/release.snapshot.schema.json b/.ssot/schemas/release.snapshot.schema.json new file mode 100644 index 00000000..c1f64eb6 --- /dev/null +++ b/.ssot/schemas/release.snapshot.schema.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/release.snapshot.schema.json", + "type": "object", + "required": [ + "schema_version", + "kind", + "generated_at", + "registry_path", + "registry_sha256", + "release", + "boundary", + "features", + "claims", + "tests", + "evidence", + "file_hashes", + "summary" + ] +} diff --git a/.ssot/schemas/validation.report.schema.json b/.ssot/schemas/validation.report.schema.json new file mode 100644 index 00000000..76810db9 --- /dev/null +++ b/.ssot/schemas/validation.report.schema.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.invalid/ssot-registry/validation.report.schema.json", + "type": "object", + "required": [ + "passed", + "registry_path", + "failures", + "warnings", + "summary" + ] +} diff --git a/.ssot/specs/SPEC-0001-registry-core.md b/.ssot/specs/SPEC-0001-registry-core.md new file mode 100644 index 00000000..e594f56f --- /dev/null +++ b/.ssot/specs/SPEC-0001-registry-core.md @@ -0,0 +1,22 @@ +# Registry core + +The canonical registry is `.ssot/registry.json`. + +Top-level sections: +- `schema_version` +- `repo` +- `tooling` +- `paths` +- `program` +- `guard_policies` +- `document_id_reservations` +- `features` +- `tests` +- `claims` +- `evidence` +- `issues` +- `risks` +- `boundaries` +- `releases` +- `adrs` +- `specs` diff --git a/.ssot/specs/SPEC-0002-cli.md b/.ssot/specs/SPEC-0002-cli.md new file mode 100644 index 00000000..8d583b2a --- /dev/null +++ b/.ssot/specs/SPEC-0002-cli.md @@ -0,0 +1,21 @@ +# CLI + +Public commands: +- `ssot-registry init` +- `ssot-registry validate` +- `ssot-registry upgrade` +- `ssot-registry adr create|get|list|update|delete|sync` +- `ssot-registry adr reserve create|list` +- `ssot-registry spec create|get|list|update|delete|sync` +- `ssot-registry spec reserve create|list` +- `ssot-registry feature plan` +- `ssot-registry feature lifecycle set` +- `ssot-registry issue plan` +- `ssot-registry claim evaluate` +- `ssot-registry evidence verify` +- `ssot-registry boundary freeze` +- `ssot-registry release certify` +- `ssot-registry release promote` +- `ssot-registry release publish` +- `ssot-registry release revoke` +- `ssot-registry graph export` diff --git a/.ssot/specs/SPEC-0003-graph-model.md b/.ssot/specs/SPEC-0003-graph-model.md new file mode 100644 index 00000000..c0b0d490 --- /dev/null +++ b/.ssot/specs/SPEC-0003-graph-model.md @@ -0,0 +1,15 @@ +# Graph model + +The authored registry is entity-centric JSON. +The graph export is derived and consists of nodes and typed edges. + +Representative edge types: +- `SCOPES` +- `USES_BOUNDARY` +- `ASSERTS` +- `VERIFIES` +- `SUPPORTS` +- `DERIVES_FROM` +- `AFFECTS` +- `PUBLISHES` +- `INCLUDES` diff --git a/.ssot/specs/SPEC-0004-feature-lifecycle.md b/.ssot/specs/SPEC-0004-feature-lifecycle.md new file mode 100644 index 00000000..89cba173 --- /dev/null +++ b/.ssot/specs/SPEC-0004-feature-lifecycle.md @@ -0,0 +1,9 @@ +# Feature lifecycle + +Supported lifecycle stages: +- `active` +- `deprecated` +- `obsolete` +- `removed` + +Lifecycle answers support state. It is distinct from planning horizon and implementation status. diff --git a/.ssot/specs/SPEC-0005-claim-statuses.md b/.ssot/specs/SPEC-0005-claim-statuses.md new file mode 100644 index 00000000..c26fe1a3 --- /dev/null +++ b/.ssot/specs/SPEC-0005-claim-statuses.md @@ -0,0 +1,13 @@ +# Claim statuses + +Supported statuses: +- `proposed` +- `declared` +- `implemented` +- `asserted` +- `evidenced` +- `certified` +- `promoted` +- `published` +- `blocked` +- `retired` diff --git a/.ssot/specs/SPEC-0006-claim-tiers.md b/.ssot/specs/SPEC-0006-claim-tiers.md new file mode 100644 index 00000000..4a9698cb --- /dev/null +++ b/.ssot/specs/SPEC-0006-claim-tiers.md @@ -0,0 +1,8 @@ +# Claim tiers + +Supported tiers: +- `T0` declared intent or inventory-level +- `T1` maintainer-asserted with local evidence +- `T2` reproducible project-controlled verification +- `T3` release-grade certified claim +- `T4` independently reviewed or externally attested claim diff --git a/.ssot/specs/SPEC-0007-snapshots-and-reports.md b/.ssot/specs/SPEC-0007-snapshots-and-reports.md new file mode 100644 index 00000000..1ab9bac4 --- /dev/null +++ b/.ssot/specs/SPEC-0007-snapshots-and-reports.md @@ -0,0 +1,9 @@ +# Snapshots and reports + +Generated artifacts: +- boundary snapshots +- release snapshots +- published snapshots +- validation reports +- certification reports +- graph exports diff --git a/.ssot/specs/SPEC-0008-repo-policy.md b/.ssot/specs/SPEC-0008-repo-policy.md new file mode 100644 index 00000000..52e2bade --- /dev/null +++ b/.ssot/specs/SPEC-0008-repo-policy.md @@ -0,0 +1,4 @@ +# Repository policy + +Repository-local policy belongs in `.ssot/specs/SPEC-0008-repo-policy.md`. +The portable defaults are strict and fail closed. diff --git a/.ssot/specs/SPEC-0009-gates-and-fences.md b/.ssot/specs/SPEC-0009-gates-and-fences.md new file mode 100644 index 00000000..923223be --- /dev/null +++ b/.ssot/specs/SPEC-0009-gates-and-fences.md @@ -0,0 +1,10 @@ +# Gates and fences + +The system enforces: +- claim closure guards +- certification gates +- promotion gates +- publication fences +- lifecycle guards +- boundary freezing +- release-blocking issue and risk fences diff --git a/.ssot/specs/SPEC-0010-id-normalization.md b/.ssot/specs/SPEC-0010-id-normalization.md new file mode 100644 index 00000000..138a97b7 --- /dev/null +++ b/.ssot/specs/SPEC-0010-id-normalization.md @@ -0,0 +1,18 @@ +# ID normalization + +Grammar: + +```text +^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9._-]*$ +``` + +Prefixes: +- `repo:` +- `feat:` +- `tst:` +- `clm:` +- `evd:` +- `iss:` +- `rsk:` +- `bnd:` +- `rel:` diff --git a/.ssot/specs/SPEC-0011-file-tree.md b/.ssot/specs/SPEC-0011-file-tree.md new file mode 100644 index 00000000..d8798c68 --- /dev/null +++ b/.ssot/specs/SPEC-0011-file-tree.md @@ -0,0 +1,18 @@ +# File tree + +Embedded repository tree: + +```text +.ssot/ + registry.json + schemas/ + adr/ + ADR-0001-canonical-json-registry.md + specs/ + SPEC-0001-registry-core.md + evidence/ + graphs/ + reports/ + releases/ + cache/ +``` diff --git a/.ssot/specs/SPEC-0012-planning-horizons.md b/.ssot/specs/SPEC-0012-planning-horizons.md new file mode 100644 index 00000000..6c68c295 --- /dev/null +++ b/.ssot/specs/SPEC-0012-planning-horizons.md @@ -0,0 +1,11 @@ +# Planning horizons + +Supported horizons: +- `current` +- `next` +- `future` +- `explicit` +- `backlog` +- `out_of_bounds` + +Horizons answer *when* a feature or issue is targeted. They do not answer support lifecycle. diff --git a/.ssot/specs/SPEC-0013-python-api.md b/.ssot/specs/SPEC-0013-python-api.md new file mode 100644 index 00000000..d1129690 --- /dev/null +++ b/.ssot/specs/SPEC-0013-python-api.md @@ -0,0 +1,22 @@ +# Python API + +Stable imports: + +```python +from ssot_registry.api import ( + load_registry, + save_registry, + validate_registry, + plan_features, + set_feature_lifecycle, + plan_issues, + evaluate_claims, + verify_evidence_rows, + freeze_boundary, + certify_release, + promote_release, + publish_release, + revoke_release, + export_graph, +) +``` diff --git a/.ssot/specs/SPEC-2001-http1.md b/.ssot/specs/SPEC-2001-http1.md new file mode 100644 index 00000000..88d8980e --- /dev/null +++ b/.ssot/specs/SPEC-2001-http1.md @@ -0,0 +1,28 @@ +# HTTP/1.1 + +# HTTP/1.1 + +Implemented in this build: + +- request line and header parsing +- origin-form, absolute-form, authority-form, and asterisk-form request targets +- `Content-Length` and `Transfer-Encoding: chunked` request bodies +- request-body streaming onto ASGI `http.request` events for the TCP/Unix server path +- request-trailer exposure through a custom `http.request.trailers` extension event on the chunked HTTP/1.1 path +- `Expect: 100-continue` on the HTTP/1.1 server path +- keep-alive handling for HTTP/1.0 and HTTP/1.1 requests +- chunked response bodies for streaming ASGI responses +- CONNECT relay tunneling on the HTTP/1.1 server path + +A formal intermediary/proxy corpus is now bundled under `docs/review/conformance/intermediary_proxy_corpus/`. +That seed corpus preserves the current third-party HTTP/1.1 `curl` artifact plus carrier-specific CONNECT relay vector metadata. + +Still incomplete relative to a stricter intermediary/proxy evidence program: + +- broader multi-carrier third-party intermediary/proxy interoperability evidence is still not bundled +- CONNECT relay tunneling is also implemented on the HTTP/2 and HTTP/3 carriers, but the bundled corpus still relies on local vector metadata for those carriers until additional third-party artifacts are preserved + +The authoritative certification boundary for package-wide RFC claims is `docs/review/conformance/CERTIFICATION_BOUNDARY.md`. + + +A minimum certified intermediary/proxy-adjacent corpus now lives under `docs/review/conformance/intermediary_proxy_corpus_minimum_certified/`; the older seed corpus remains preserved for provenance. diff --git a/.ssot/specs/SPEC-2002-http2.md b/.ssot/specs/SPEC-2002-http2.md new file mode 100644 index 00000000..ec06ccee --- /dev/null +++ b/.ssot/specs/SPEC-2002-http2.md @@ -0,0 +1,38 @@ +# HTTP/2 + +# HTTP/2 + +This build includes a pure-Python HTTP/2 prior-knowledge server path with an explicit RFC 9113 stream-state machine. + +## Implemented and validated in this build + +- frame encoding and decoding +- SETTINGS, HEADERS, CONTINUATION, DATA, WINDOW_UPDATE, PING, GOAWAY, PRIORITY, and RST_STREAM handling +- explicit stream lifecycle tracking for `idle`, `reserved-local`, `reserved-remote`, `open`, `half-closed-local`, `half-closed-remote`, and `closed` +- first-frame `SETTINGS` enforcement after the client connection preface +- stream-state-specific legality checks for HEADERS, DATA, WINDOW_UPDATE, CONTINUATION, PRIORITY, GOAWAY, and RST_STREAM +- max concurrent stream enforcement +- monotonic GOAWAY handling and rejection of new inbound streams after GOAWAY +- receive-side flow-control accounting with thresholded WINDOW_UPDATE emission instead of immediate echo updates +- bounded request buffering using configured header/body size limits +- CONTINUATION/header-block lifecycle enforcement, including strict same-stream continuation sequencing +- request-header validation for pseudo-header ordering, duplicates, lowercase field names, and forbidden connection-specific fields +- HPACK dynamic table support with differential coverage +- RFC 8441 extended CONNECT bootstrap for WebSocket-over-HTTP/2 +- outbound server push via `PUSH_PROMISE` and promised response streams on the HTTP/2 carrier +- per-stream request dispatch onto the ASGI boundary +- generic CONNECT tunnel relay integration on the HTTP/2 carrier + +## Release evidence shipped with this archive + +Historical preserved evidence remains bundled: + +- `curl --http2-prior-knowledge` request/response artifacts under `docs/review/conformance/releases/0.3.2/.../http2-server-curl-client/` +- `curl` HTTPS + ALPN HTTP/2 request/response artifacts under `docs/review/conformance/releases/0.3.6-rfc-hardening/.../http2-tls-server-curl-client/` +- third-party `h2` WebSocket extended CONNECT artifacts under `docs/review/conformance/releases/0.3.6-rfc-hardening/.../websocket-http2-server-h2-client/` + +The committed current-release bundle at `docs/review/conformance/releases/0.3.6-current/release-0.3.6-current/tigrcorn-current-release-matrix/` additionally includes replayable `python-h2` request/response artifacts for both cleartext and TLS hosting. + +## Evidence status + +The documentation for the HTTP/2 carrier is aligned with the implemented code and the committed release bundle. HPACK dynamic state, RFC 8441, TLS hosting, and CONNECT relay are all represented in preserved and current evidence. diff --git a/.ssot/specs/SPEC-2003-http3.md b/.ssot/specs/SPEC-2003-http3.md new file mode 100644 index 00000000..c830eda5 --- /dev/null +++ b/.ssot/specs/SPEC-2003-http3.md @@ -0,0 +1,43 @@ +# HTTP/3 + +# HTTP/3 + +This repository includes a stdlib-only HTTP/3 core integrated with the bundled QUIC transport. + +## Implemented and locally validated in this build + +- frame codec +- settings codec +- request-stream parsing and control-stream validation +- QPACK encoder stream, decoder stream, and dynamic table state +- UDP server integration over the bundled QUIC transport core +- public API / CLI startup for certificate-driven QUIC-TLS listeners +- QUIC Retry exposure through the public configuration surface +- QUIC-TLS session-ticket issuance, resumption, and 0-RTT handling in the runtime +- request-trailer propagation on the ASGI request path +- response content-coding negotiation for buffered responses +- generic CONNECT tunnel relay integration on the HTTP/3 carrier +- RFC 9220 WebSocket bootstrap and framed carrier integration on HTTP/3 request streams + +## Evidence tiers + +The canonical certification boundary for this carrier is `docs/review/conformance/CERTIFICATION_BOUNDARY.md`. + +HTTP/3 evidence is split explicitly: + +- **local conformance** — `tests/test_http3_rfc9114.py`, `tests/test_qpack_completion.py`, `tests/test_http3_websocket_rfc9220.py`, `tests/test_connect_rfc9110.py`, `tests/test_trailers_rfc9110.py`, and `tests/test_http_content_coding_rfc9110.py` +- **same-stack replay** — `docs/review/conformance/external_matrix.same_stack_replay.json` and the canonical same-stack bundle under `docs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-same-stack-replay-matrix/` +- **independent certification** — `docs/review/conformance/external_matrix.release.json` and the canonical independent bundle under `docs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-independent-certification-release-matrix/` + +## Current certification status + +The independent matrix now contains preserved passing third-party HTTP/3 request/response, mTLS, Retry, resumption, 0-RTT, migration, GOAWAY / QPACK, and RFC 9220 scenarios. + +Under the authoritative certification boundary, the HTTP/3 carrier is now satisfied at the required tier: + +- RFC 9114 is satisfied at `independent_certification` +- RFC 9204 is satisfied at `independent_certification` +- the related QUIC transport RFCs used by the HTTP/3 carrier are satisfied at `independent_certification` +- package-owned TCP/TLS condition in the certification boundary is satisfied separately + +The stricter all-surfaces-independent overlay remains a separate non-authoritative follow-on profile. diff --git a/.ssot/specs/SPEC-2004-quic.md b/.ssot/specs/SPEC-2004-quic.md new file mode 100644 index 00000000..9e4b7f4d --- /dev/null +++ b/.ssot/specs/SPEC-2004-quic.md @@ -0,0 +1,37 @@ +# QUIC + +# QUIC + +This repository includes a concrete QUIC transport core rather than only packet helpers. + +## Implemented and locally validated in this build + +- QUIC packet helpers for long-header packets, short-header packets, Version Negotiation, Retry, and Stateless Reset parsing/encoding +- QUIC-TLS packet protection helpers for Initial, Handshake, 0-RTT, and 1-RTT packet protection +- a binary TLS 1.3 handshake driver with certificate verification, transport-parameter negotiation, session tickets, resumption, and 0-RTT support +- AES-based QUIC header protection helpers +- Retry integrity-tag computation and validation +- multiplexed stream frames, ACK ranges, RESET_STREAM / STOP_SENDING / CRYPTO / MAX_DATA / MAX_STREAM_DATA / MAX_STREAMS / PATH_CHALLENGE / PATH_RESPONSE / HANDSHAKE_DONE / CONNECTION_CLOSE frame handling in the codec +- connection-ID-based runtime session routing in the HTTP/3 UDP server path +- live recovery, ACK, loss, PTO, and pacing integration in the runtime +- public API / CLI startup for certificate-driven QUIC-TLS listeners over UDP +- UDP listener client-certificate verification through `ssl_ca_certs` and `ssl_require_client_cert` +- UDP listener Retry configuration through `quic_require_retry` / `--quic-require-retry` + +## Evidence tiers + +The canonical package-wide target for this transport is defined in `docs/review/conformance/CERTIFICATION_BOUNDARY.md`. + +QUIC evidence is now split explicitly: + +- **local conformance** — RFC 9000, RFC 9001, RFC 9002, RFC 7301, and local TLS / X.509 fixtures in `corpus.json` +- **same-stack replay** — `docs/review/conformance/external_matrix.same_stack_replay.json` and the canonical same-stack bundle under `docs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-same-stack-replay-matrix/` +- **independent certification** — `docs/review/conformance/external_matrix.release.json` and the canonical independent bundle under `docs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-independent-certification-release-matrix/` + +## Current certification status + +The independent matrix proves that the UDP listener can complete an OpenSSL QUIC handshake and negotiate `h3`, and it now preserves passing third-party HTTP/3 feature-axis scenarios for Retry, resumption, 0-RTT, migration, mTLS, and GOAWAY / QPACK. + +Under the authoritative certification boundary, the QUIC transport now satisfies the required independent evidence for RFC 9000, RFC 9001, RFC 9002, and the HTTP/3 carrier that depends on them. The package-wide RFC 8446 target is no longer blocked by the public TCP/TLS listener path. + +Broader flow-control and strict all-surfaces-independent follow-on work remains tracked separately and does not change the current passing release-gate result. diff --git a/.ssot/specs/SPEC-2005-websocket.md b/.ssot/specs/SPEC-2005-websocket.md new file mode 100644 index 00000000..2e07d28e --- /dev/null +++ b/.ssot/specs/SPEC-2005-websocket.md @@ -0,0 +1,33 @@ +# WebSocket + +# WebSocket + +This build implements WebSocket handling across the HTTP/1.1, HTTP/2, and HTTP/3 carriers. + +## Implemented and locally validated in this build + +- HTTP/1.1 upgrade validation and handshake +- ASGI `websocket.connect`, `websocket.accept`, `websocket.receive`, `websocket.send`, and `websocket.close` +- masking validation for client frames +- control-frame validation +- close-code and close-reason validation +- UTF-8 validation for text messages and close reasons +- fragmented-message tracking with aggregate message-size enforcement +- HTTP denial responses before upgrade acceptance +- permessage-deflate negotiation and RSV1 handling on the HTTP/1.1, HTTP/2, and HTTP/3 paths +- RFC 8441 WebSocket bootstrap on the HTTP/2 carrier +- RFC 9220 WebSocket bootstrap on the HTTP/3 carrier + +## Evidence tiers + +The canonical package-wide target for WebSocket is defined in `docs/review/conformance/CERTIFICATION_BOUNDARY.md`. + +- **local conformance** — `tests/test_websocket_rfc6455.py`, `tests/test_websocket_rfc7692.py`, `tests/test_http2_websocket_rfc8441.py`, and `tests/test_http3_websocket_rfc9220.py` +- **same-stack replay** — `docs/review/conformance/external_matrix.same_stack_replay.json` and the canonical `0.3.9` same-stack bundle under `docs/review/conformance/releases/0.3.9/release-0.3.9/tigrcorn-same-stack-replay-matrix/` +- **independent certification** — the canonical independent matrix at `docs/review/conformance/external_matrix.release.json` + +## Current certification status + +HTTP/1.1 WebSocket, RFC 8441 WebSocket-over-HTTP/2, and RFC 9220 WebSocket-over-HTTP/3 all now have preserved passing third-party artifacts in the canonical independent release bundle. + +RFC 7692 across carriers is handled explicitly by the authoritative boundary rather than by narrative implication. The current release gate intentionally keeps RFC 7692 at `local_conformance`, so it is not an independent-certification blocker in the current bundle. A stricter all-surfaces-independent profile would still need additional third-party permessage-deflate artifacts. The package-owned TCP/TLS condition is satisfied separately, and the authoritative RFC 9220 requirement is now closed. diff --git a/.ssot/specs/SPEC-2006-custom-transports.md b/.ssot/specs/SPEC-2006-custom-transports.md new file mode 100644 index 00000000..649f8eee --- /dev/null +++ b/.ssot/specs/SPEC-2006-custom-transports.md @@ -0,0 +1,14 @@ +# Custom transports + +# Custom transports + +TigrCorn reserves a native extension surface for custom transports and scope types. + +Examples: + +- raw framed RPC over TCP +- raw framed RPC over QUIC +- in-process transports for test harnesses +- custom stream and datagram scope types + +These extensions must not change the standard ASGI behavior for HTTP, WebSocket, or lifespan. diff --git a/.ssot/specs/SPEC-2007-public.md b/.ssot/specs/SPEC-2007-public.md new file mode 100644 index 00000000..b71086eb --- /dev/null +++ b/.ssot/specs/SPEC-2007-public.md @@ -0,0 +1,714 @@ +# Public operator and programmatic surface reference + +# Public operator and programmatic surface reference + +This page documents Tigrcorn's public import surfaces for developers, embedders, implementers, maintainers, and release tooling owners. + +Read alongside: + +- `README.md` +- `docs/ops/cli.md` +- `docs/LIFECYCLE_AND_EMBEDDED_SERVER.md` +- `docs/review/conformance/CERTIFICATION_BOUNDARY.md` +- `docs/review/conformance/BOUNDARY_NON_GOALS.md` +- `docs/review/conformance/state/CURRENT_REPOSITORY_STATE.md` + +## Table of contents + +- [Import surface map](#import-surface-map) +- [Entry points and helpers](#entry-points-and-helpers) +- [Usage snippets](#usage-snippets) +- [Config model](#config-model) +- [Release and promotion evaluators](#release-and-promotion-evaluators) +- [Advanced lifecycle server surface](#advanced-lifecycle-server-surface) +- [Non-goals and exclusions](#non-goals-and-exclusions) + +## Import surface map + +| Import surface | Kind | When to use | Notes | +|---|---|---|---| +| `tigrcorn.run` | sync convenience entrypoint | start a server from sync code | Accepts an ASGI app or import string and chooses the configured runtime. | +| `tigrcorn.serve` | async entrypoint | start a server inside an existing async runtime | Takes a concrete ASGI app object. | +| `tigrcorn.serve_import_string` | async entrypoint | load and run an import-string target inside an existing runtime | Supports `factory=True`. | +| `tigrcorn.EmbeddedServer` | embedder helper | control lifecycle explicitly inside a host process | Idempotent `start()`, no-op `close()` before start, exposes `listeners` and `bound_endpoints()`. | +| `tigrcorn.StaticFilesApp` | ASGI app | serve static assets directly | Supports ETag, conditional/range semantics, content coding, and precompressed sidecars. | +| `tigrcorn.static.mount_static_app` | composition helper | mount static delivery under a route | Wraps another ASGI app with mounted static delivery. | +| `tigrcorn.static.normalize_static_route` | utility | normalize user-supplied static routes | Useful when assembling config or wrappers. | +| `tigrcorn.config.build_config` | constructor | build a `ServerConfig` from explicit keyword arguments | Good fit for code-driven startup. | +| `tigrcorn.config.build_config_from_namespace` | constructor | turn an argparse namespace into `ServerConfig` | Used by the CLI. | +| `tigrcorn.config.build_config_from_sources` | constructor | merge CLI overrides, config file, and environment | Implements the public precedence contract. | +| `tigrcorn.config.config_to_dict` | serializer | inspect/export a config object | Useful in tooling and tests. | +| `tigrcorn.config.load_env_config` | loader | load prefixed environment variables | Default prefix is `TIGRCORN`. | +| `tigrcorn.config.load_config_file` | loader | load TOML / JSON / optional YAML config files | YAML requires `config-yaml`. | +| `tigrcorn.server.TigrCornServer` | advanced server class | work with the underlying server object directly | Advanced lifecycle/embedding surface; see lifecycle doc. | +| `tigrcorn.compat.release_gates.evaluate_release_gates` | maintainer/operator evaluator | evaluate the current source tree against release-gate contracts | Returns `ReleaseGateReport`. | +| `tigrcorn.compat.release_gates.evaluate_promotion_target` | maintainer/operator evaluator | evaluate the current source tree against the promotion target contract | Returns `PromotionTargetReport`. | +| `tigrcorn.compat.release_gates.assert_release_ready` | maintainer/operator assertion | fail fast when release gates are not satisfied | Raises `ReleaseGateError`. | +| `tigrcorn.compat.release_gates.assert_promotion_target_ready` | maintainer/operator assertion | fail fast when promotion target is not satisfied | Raises `PromotionTargetError`. | + + +## Entry points and helpers + +### `run` + +```python +run(app: 'ASGIApp | str', *, profile: 'str | None' = None, host: 'str' = '127.0.0.1', port: 'int' = 8000, uds: 'str | None' = None, transport: 'str' = 'tcp', lifespan: 'str' = 'auto', log_level: 'str' = 'info', access_log: 'bool' = True, ssl_certfile: 'str | None' = None, ssl_keyfile: 'str | None' = None, ssl_keyfile_password: 'str | bytes | None' = None, ssl_ca_certs: 'str | None' = None, ssl_require_client_cert: 'bool | None' = None, ssl_ciphers: 'str | None' = None, ssl_crl: 'str | None' = None, http_versions: 'list[str] | None' = None, websocket: 'bool | None' = None, enable_h2c: 'bool' = False, max_body_size: 'int | None' = None, protocols: 'list[str] | None' = None, quic_secret: 'bytes | None' = None, quic_require_retry: 'bool | None' = None, pipe_mode: 'str' = 'rawframed', factory: 'bool' = False, config: 'ServerConfig | None' = None) -> 'None' +``` + +### `serve` + +```python +serve(app: 'ASGIApp', *, profile: 'str | None' = None, host: 'str' = '127.0.0.1', port: 'int' = 8000, uds: 'str | None' = None, transport: 'str' = 'tcp', lifespan: 'str' = 'auto', log_level: 'str' = 'info', access_log: 'bool' = True, ssl_certfile: 'str | None' = None, ssl_keyfile: 'str | None' = None, ssl_keyfile_password: 'str | bytes | None' = None, ssl_ca_certs: 'str | None' = None, ssl_require_client_cert: 'bool | None' = None, ssl_ciphers: 'str | None' = None, ssl_crl: 'str | None' = None, http_versions: 'list[str] | None' = None, websocket: 'bool | None' = None, enable_h2c: 'bool' = False, max_body_size: 'int | None' = None, protocols: 'list[str] | None' = None, quic_secret: 'bytes | None' = None, quic_require_retry: 'bool | None' = None, pipe_mode: 'str' = 'rawframed', config: 'ServerConfig | None' = None) -> 'None' +``` + +### `serve_import_string` + +```python +serve_import_string(app_target: 'str | None' = None, *, profile: 'str | None' = None, host: 'str' = '127.0.0.1', port: 'int' = 8000, uds: 'str | None' = None, transport: 'str' = 'tcp', lifespan: 'str' = 'auto', log_level: 'str' = 'info', access_log: 'bool' = True, ssl_certfile: 'str | None' = None, ssl_keyfile: 'str | None' = None, ssl_keyfile_password: 'str | bytes | None' = None, ssl_ca_certs: 'str | None' = None, ssl_require_client_cert: 'bool | None' = None, ssl_ciphers: 'str | None' = None, ssl_crl: 'str | None' = None, http_versions: 'list[str] | None' = None, websocket: 'bool | None' = None, enable_h2c: 'bool' = False, max_body_size: 'int | None' = None, protocols: 'list[str] | None' = None, quic_secret: 'bytes | None' = None, quic_require_retry: 'bool | None' = None, pipe_mode: 'str' = 'rawframed', factory: 'bool' = False, config: 'ServerConfig | None' = None) -> 'None' +``` + +### `EmbeddedServer` + +```python +EmbeddedServer(app: 'ASGIApp', config: 'ServerConfig') -> None +``` + +### `StaticFilesApp` + +```python +StaticFilesApp(directory: 'str | Path', *, index_file: 'str | None' = 'index.html', dir_to_file: 'bool' = True, expires: 'int | None' = None, default_headers: 'Iterable[tuple[bytes, bytes] | tuple[str, str]]' = (), apply_content_coding: 'bool' = True, content_coding_policy: 'str' = 'allowlist', content_codings: 'Iterable[str]' = ('br', 'gzip', 'deflate'), use_precompressed_sidecars: 'bool' = True, precompressed_codings: 'Iterable[str]' = ('br', 'gzip')) -> 'None' +``` + +### `mount_static_app` + +```python +mount_static_app(app: 'ASGIApp | None', *, route: 'str', directory: 'str | Path', dir_to_file: 'bool' = True, index_file: 'str | None' = 'index.html', expires: 'int | None' = None, apply_content_coding: 'bool' = True, content_coding_policy: 'str' = 'allowlist', content_codings: 'Iterable[str]' = ('br', 'gzip', 'deflate'), use_precompressed_sidecars: 'bool' = True, precompressed_codings: 'Iterable[str]' = ('br', 'gzip')) -> 'ASGIApp' +``` + +### `normalize_static_route` + +```python +normalize_static_route(route: 'str | None') -> 'str' +``` + +### `build_config` + +```python +build_config(*, profile: 'str | None' = None, app: 'str | None' = None, host: 'str' = '127.0.0.1', port: 'int' = 8000, uds: 'str | None' = None, transport: 'str' = 'tcp', lifespan: 'str' = 'auto', log_level: 'str' = 'info', access_log: 'bool' = True, ssl_certfile: 'str | None' = None, ssl_keyfile: 'str | None' = None, ssl_keyfile_password: 'str | bytes | None' = None, ssl_ca_certs: 'str | None' = None, ssl_require_client_cert: 'bool | None' = None, ssl_ciphers: 'str | None' = None, ssl_crl: 'str | None' = None, http_versions: 'list[str] | None' = None, websocket: 'bool | None' = None, static_path_route: 'str | None' = None, static_path_mount: 'str | None' = None, static_path_dir_to_file: 'bool' = True, static_path_index_file: 'str | None' = 'index.html', static_path_expires: 'int | None' = None, enable_h2c: 'bool' = False, max_body_size: 'int | None' = None, max_header_size: 'int | None' = None, http1_max_incomplete_event_size: 'int | None' = None, http1_buffer_size: 'int | None' = None, http1_header_read_timeout: 'float | None' = None, http1_keep_alive: 'bool | None' = None, http2_max_concurrent_streams: 'int | None' = None, http2_max_headers_size: 'int | None' = None, http2_max_frame_size: 'int | None' = None, http2_adaptive_window: 'bool | None' = None, http2_initial_connection_window_size: 'int | None' = None, http2_initial_stream_window_size: 'int | None' = None, http2_keep_alive_interval: 'float | None' = None, http2_keep_alive_timeout: 'float | None' = None, websocket_max_queue: 'int | None' = None, protocols: 'list[str] | None' = None, quic_secret: 'bytes | None' = None, quic_require_retry: 'bool | None' = None, pipe_mode: 'str' = 'rawframed', config: 'Mapping[str, Any] | None' = None, default_headers: 'list[str] | list[tuple[str, str]] | None' = None, include_date_header: 'bool' = True, include_server_header: 'bool' = False, server_header: 'str | bytes | None' = None, env_file: 'str | None' = None, server_names: 'list[str] | None' = None, alt_svc: 'list[str] | list[tuple[str, str]] | None' = None, alt_svc_auto: 'bool | None' = None, alt_svc_max_age: 'int | None' = None, alt_svc_persist: 'bool' = False, runtime: 'str' = 'auto', worker_healthcheck_timeout: 'float | None' = None, use_colors: 'bool | None' = None) -> 'ServerConfig' +``` + +### `build_config_from_namespace` + +```python +build_config_from_namespace(ns: 'Namespace') -> 'ServerConfig' +``` + +### `build_config_from_sources` + +```python +build_config_from_sources(*, cli_overrides: 'Mapping[str, Any] | None' = None, config_source: 'str | Path | Mapping[str, Any] | Any | None' = None, config_path: 'str | Path | None' = None, env_prefix: 'str | None' = None, env_file: 'str | Path | None' = None, profile: 'str | None' = None) -> 'ServerConfig' +``` + +### `config_to_dict` + +```python +config_to_dict(config: 'ServerConfig') -> 'dict[str, Any]' +``` + +### `load_env_config` + +```python +load_env_config(prefix: 'str' = 'TIGRCORN', *, environ: 'Mapping[str, str] | None' = None) -> 'dict[str, Any]' +``` + +### `load_config_file` + +```python +load_config_file(path: 'str | Path | None') -> 'dict[str, Any]' +``` + +### `evaluate_release_gates` + +```python +evaluate_release_gates(source_root: 'str | Path', *, boundary_path: 'str | Path | None' = None, corpus_path: 'str | Path | None' = None, independent_matrix_path: 'str | Path | None' = None, same_stack_matrix_path: 'str | Path | None' = None) -> 'ReleaseGateReport' +``` + +### `evaluate_promotion_target` + +```python +evaluate_promotion_target(source_root: 'str | Path', *, target_path: 'str | Path | None' = None) -> 'PromotionTargetReport' +``` + +### `assert_release_ready` + +```python +assert_release_ready(source_root: 'str | Path', *, boundary_path: 'str | Path | None' = None, corpus_path: 'str | Path | None' = None, independent_matrix_path: 'str | Path | None' = None, same_stack_matrix_path: 'str | Path | None' = None) -> 'None' +``` + +### `assert_promotion_target_ready` + +```python +assert_promotion_target_ready(source_root: 'str | Path', *, target_path: 'str | Path | None' = None) -> 'None' +``` + + +### `TigrCornServer` + +```python +TigrCornServer(app: 'ASGIApp', config: 'ServerConfig') -> 'None' +``` + +Public instance methods: + +- `await start()` +- `await serve_forever()` +- `request_shutdown()` +- `await close()` + +This is the advanced underlying server surface used by `EmbeddedServer` and by the lifecycle contract documented in `docs/LIFECYCLE_AND_EMBEDDED_SERVER.md`. + +## Usage snippets + +### Sync entrypoint from application code + +```python +from tigrcorn import run + +run( + "examples.echo_http.app:app", + host="127.0.0.1", + port=8000, + http_versions=["1.1", "2"], + log_level="info", +) +``` + +### Async entrypoint from an existing event loop + +```python +from tigrcorn import serve + +async def app(scope, receive, send): + if scope["type"] == "lifespan": + message = await receive() + if message["type"] == "lifespan.startup": + await send({"type": "lifespan.startup.complete"}) + message = await receive() + await send({"type": "lifespan.shutdown.complete"}) + return + + await receive() + await send({ + "type": "http.response.start", + "status": 200, + "headers": [(b"content-type", b"text/plain")], + }) + await send({"type": "http.response.body", "body": b"ok", "more_body": False}) + +await serve(app, host="127.0.0.1", port=8000) +``` + +### Import-string loading inside async code + +```python +from tigrcorn import serve_import_string + +await serve_import_string( + "examples.echo_http.app:app", + host="127.0.0.1", + port=8000, + factory=False, +) +``` + +### Embedded server inside a host process + +```python +from tigrcorn import EmbeddedServer +from tigrcorn.config import build_config + +config = build_config(host="127.0.0.1", port=0, lifespan="on") + +async with EmbeddedServer(app, config) as embedded: + print(embedded.listeners) + print(embedded.bound_endpoints()) +``` + +Contract summary: + +- `start()` is idempotent and returns the underlying `TigrCornServer` +- `close()` is a no-op before startup +- the async context manager calls `start()` on entry and `close()` on exit +- `listeners` and `bound_endpoints()` expose the current runtime/listener bindings + +### Static delivery as a first-class ASGI app + +```python +from tigrcorn import StaticFilesApp + +static = StaticFilesApp( + "./public", + expires=3600, + apply_content_coding=True, + content_coding_policy="allowlist", + use_precompressed_sidecars=True, +) +``` + +### Static mounting around another ASGI app + +```python +from tigrcorn.static import mount_static_app + +app = mount_static_app( + app, + route="/assets", + directory="./public", + dir_to_file=True, + index_file="index.html", + expires=3600, + apply_content_coding=True, + content_codings=("br", "gzip", "deflate"), +) +``` + +### Config building from explicit kwargs + +```python +from tigrcorn.config import build_config + +config = build_config( + app="examples.echo_http.app:app", + host="127.0.0.1", + port=8000, + http_versions=["1.1", "2"], + runtime="auto", + alt_svc_auto=False, +) +``` + +### Config building from file + environment + CLI overrides + +```python +from tigrcorn.config import build_config_from_sources + +config = build_config_from_sources( + config_path="./tigrcorn.toml", + env_prefix="TIGRCORN", + env_file=".env", + cli_overrides={ + "app": {"target": "examples.echo_http.app:app"}, + "logging": {"level": "debug"}, + "metrics": {"enabled": True}, + }, +) +``` + +### Release/promotion evaluation from tooling + +```python +from tigrcorn.compat.release_gates import ( + assert_promotion_target_ready, + assert_release_ready, + evaluate_promotion_target, + evaluate_release_gates, +) + +release_report = evaluate_release_gates(".") +promotion_report = evaluate_promotion_target(".") + +if release_report.passed: + assert_release_ready(".") + +if promotion_report.passed: + assert_promotion_target_ready(".") +``` + +## Config model + +Publicly exported config dataclasses: + +| Dataclass | Exported from | Key fields | +|---|---|---| +| `AppConfig` | `tigrcorn.config` | `target`, `factory`, `profile`, `app_dir`, `config_file`, `env_prefix`, `env_file`, `lifespan`, `reload`, `reload_dirs`, `reload_include`, … | +| `ProcessConfig` | `tigrcorn.config` | `workers`, `worker_class`, `runtime`, `pid_file`, `worker_healthcheck_timeout`, `limit_max_requests`, `max_requests_jitter` | +| `TLSConfig` | `tigrcorn.config` | `certfile`, `keyfile`, `keyfile_password`, `ca_certs`, `require_client_cert`, `ciphers`, `resolved_cipher_suites`, `alpn_protocols`, `ocsp_mode`, `ocsp_soft_fail`, … | +| `ProxyConfig` | `tigrcorn.config` | `proxy_headers`, `forwarded_allow_ips`, `root_path`, `server_header`, `include_server_header`, `include_date_header`, `default_headers`, `server_names` | +| `HTTPConfig` | `tigrcorn.config` | `http_versions`, `enable_h2c`, `keep_alive_timeout`, `read_timeout`, `write_timeout`, `shutdown_timeout`, `idle_timeout`, `max_body_size`, `max_header_size`, `http1_max_incomplete_event_size`, … | +| `WebSocketConfig` | `tigrcorn.config` | `enabled`, `max_message_size`, `max_queue`, `ping_interval`, `ping_timeout`, `compression` | +| `ListenerConfig` | `tigrcorn.config` | `kind`, `bind`, `host`, `port`, `path`, `fd`, `endpoint`, `insecure_bind`, `quic_bind`, `backlog`, … | +| `QUICConfig` | `tigrcorn.config` | `quic_secret`, `require_retry`, `max_datagram_size`, `idle_timeout`, `early_data_policy` | +| `LoggingConfig` | `tigrcorn.config` | `level`, `access_log`, `access_log_file`, `access_log_format`, `error_log_file`, `log_config`, `structured`, `use_colors`, `explicit_fields` | +| `MetricsConfig` | `tigrcorn.config` | `enabled`, `bind`, `statsd_host`, `otel_endpoint` | +| `SchedulerConfig` | `tigrcorn.config` | `limit_concurrency`, `max_connections`, `max_tasks`, `max_streams` | +| `ServerConfig` | `tigrcorn.config` | `app`, `process`, `listeners`, `tls`, `proxy`, `http`, `websocket`, `static`, `quic`, `logging`, … | + + +Nested config dataclasses that are still relevant at runtime even though they are not top-level exports: + +| Dataclass | Reachable from | Key fields | +|---|---|---| +| `StaticConfig` | `ServerConfig.static` | `route`, `mount`, `dir_to_file`, `index_file`, `expires` | +| `HooksConfig` | `ServerConfig.hooks` | `on_startup`, `on_shutdown`, `on_reload` | + +### Exported config dataclass field reference + +
+AppConfig + +| Field | Default | +|---|---| +| `target` | `None` | +| `factory` | `False` | +| `profile` | `None` | +| `app_dir` | `None` | +| `config_file` | `None` | +| `env_prefix` | `'TIGRCORN'` | +| `env_file` | `None` | +| `lifespan` | `'auto'` | +| `reload` | `False` | +| `reload_dirs` | `list()` | +| `reload_include` | `list()` | +| `reload_exclude` | `list()` | + +
+ +
+ProcessConfig + +| Field | Default | +|---|---| +| `workers` | `1` | +| `worker_class` | `'local'` | +| `runtime` | `'auto'` | +| `pid_file` | `None` | +| `worker_healthcheck_timeout` | `30.0` | +| `limit_max_requests` | `None` | +| `max_requests_jitter` | `0` | + +
+ +
+TLSConfig + +| Field | Default | +|---|---| +| `certfile` | `None` | +| `keyfile` | `None` | +| `keyfile_password` | `None` | +| `ca_certs` | `None` | +| `require_client_cert` | `False` | +| `ciphers` | `None` | +| `resolved_cipher_suites` | `()` | +| `alpn_protocols` | `()` | +| `ocsp_mode` | `'off'` | +| `ocsp_soft_fail` | `False` | +| `ocsp_cache_size` | `128` | +| `ocsp_max_age` | `43200.0` | +| `crl_mode` | `'off'` | +| `crl` | `None` | +| `revocation_fetch` | `True` | + +
+ +
+ProxyConfig + +| Field | Default | +|---|---| +| `proxy_headers` | `False` | +| `forwarded_allow_ips` | `list()` | +| `root_path` | `''` | +| `server_header` | `b'tigrcorn'` | +| `include_server_header` | `False` | +| `include_date_header` | `True` | +| `default_headers` | `list()` | +| `server_names` | `list()` | + +
+ +
+HTTPConfig + +| Field | Default | +|---|---| +| `http_versions` | `()` | +| `enable_h2c` | `False` | +| `keep_alive_timeout` | `5.0` | +| `read_timeout` | `30.0` | +| `write_timeout` | `30.0` | +| `shutdown_timeout` | `30.0` | +| `idle_timeout` | `30.0` | +| `max_body_size` | `16777216` | +| `max_header_size` | `65536` | +| `http1_max_incomplete_event_size` | `65536` | +| `http1_buffer_size` | `65536` | +| `http1_header_read_timeout` | `None` | +| `http1_keep_alive` | `True` | +| `http2_max_concurrent_streams` | `None` | +| `http2_max_headers_size` | `None` | +| `http2_max_frame_size` | `None` | +| `http2_adaptive_window` | `False` | +| `http2_initial_connection_window_size` | `65535` | +| `http2_initial_stream_window_size` | `65535` | +| `http2_keep_alive_interval` | `None` | +| `http2_keep_alive_timeout` | `None` | +| `connect_policy` | `'deny'` | +| `connect_allow` | `list()` | +| `trailer_policy` | `'pass'` | +| `content_coding_policy` | `'allowlist'` | +| `content_codings` | `()` | +| `alt_svc_headers` | `list()` | +| `alt_svc_auto` | `False` | +| `alt_svc_max_age` | `86400` | +| `alt_svc_persist` | `False` | + +
+ +
+WebSocketConfig + +| Field | Default | +|---|---| +| `enabled` | `True` | +| `max_message_size` | `16777216` | +| `max_queue` | `32` | +| `ping_interval` | `None` | +| `ping_timeout` | `None` | +| `compression` | `'off'` | + +
+ +
+ListenerConfig + +| Field | Default | +|---|---| +| `kind` | `'tcp'` | +| `bind` | `None` | +| `host` | `'127.0.0.1'` | +| `port` | `8000` | +| `path` | `None` | +| `fd` | `None` | +| `endpoint` | `None` | +| `insecure_bind` | `None` | +| `quic_bind` | `None` | +| `backlog` | `2048` | +| `ssl_certfile` | `None` | +| `ssl_keyfile` | `None` | +| `ssl_keyfile_password` | `None` | +| `ssl_ca_certs` | `None` | +| `ssl_require_client_cert` | `False` | +| `ssl_ciphers` | `None` | +| `resolved_cipher_suites` | `()` | +| `alpn_protocols` | `list()` | +| `ocsp_mode` | `'off'` | +| `ocsp_soft_fail` | `False` | +| `ocsp_cache_size` | `128` | +| `ocsp_max_age` | `43200.0` | +| `crl_mode` | `'off'` | +| `ssl_crl` | `None` | +| `revocation_fetch` | `True` | +| `http_versions` | `()` | +| `websocket` | `True` | +| `reuse_port` | `False` | +| `reuse_address` | `True` | +| `nodelay` | `True` | +| `protocols` | `list()` | +| `quic_secret` | `None` | +| `quic_require_retry` | `False` | +| `max_datagram_size` | `1200` | +| `pipe_mode` | `'rawframed'` | +| `user` | `None` | +| `group` | `None` | +| `umask` | `None` | +| `scheme` | `None` | + +
+ +
+QUICConfig + +| Field | Default | +|---|---| +| `quic_secret` | `None` | +| `require_retry` | `False` | +| `max_datagram_size` | `1200` | +| `idle_timeout` | `30.0` | +| `early_data_policy` | `'deny'` | + +
+ +
+LoggingConfig + +| Field | Default | +|---|---| +| `level` | `'info'` | +| `access_log` | `True` | +| `access_log_file` | `None` | +| `access_log_format` | `None` | +| `error_log_file` | `None` | +| `log_config` | `None` | +| `structured` | `False` | +| `use_colors` | `None` | +| `explicit_fields` | `list()` | + +
+ +
+MetricsConfig + +| Field | Default | +|---|---| +| `enabled` | `False` | +| `bind` | `None` | +| `statsd_host` | `None` | +| `otel_endpoint` | `None` | + +
+ +
+SchedulerConfig + +| Field | Default | +|---|---| +| `limit_concurrency` | `None` | +| `max_connections` | `None` | +| `max_tasks` | `None` | +| `max_streams` | `None` | + +
+ +
+ServerConfig + +| Field | Default | +|---|---| +| `app` | `AppConfig()` | +| `process` | `ProcessConfig()` | +| `listeners` | `()` | +| `tls` | `TLSConfig()` | +| `proxy` | `ProxyConfig()` | +| `http` | `HTTPConfig()` | +| `websocket` | `WebSocketConfig()` | +| `static` | `StaticConfig()` | +| `quic` | `QUICConfig()` | +| `logging` | `LoggingConfig()` | +| `metrics` | `MetricsConfig()` | +| `scheduler` | `SchedulerConfig()` | +| `hooks` | `HooksConfig()` | +| `debug` | `False` | + +
+ +### Nested config dataclass field reference + +
+StaticConfig + +| Field | Default | +|---|---| +| `route` | `None` | +| `mount` | `None` | +| `dir_to_file` | `True` | +| `index_file` | `'index.html'` | +| `expires` | `None` | + +
+ +
+HooksConfig + +| Field | Default | +|---|---| +| `on_startup` | `list()` | +| `on_shutdown` | `list()` | +| `on_reload` | `list()` | + +
+ +### Useful computed properties + +- `ListenerConfig.ssl_enabled` +- `ListenerConfig.label` +- `ListenerConfig.enabled_protocols` +- `ServerConfig.lifespan` +- `ServerConfig.log_level` +- `ServerConfig.access_log` +- `ServerConfig.read_timeout` +- `ServerConfig.write_timeout` +- `ServerConfig.shutdown_timeout` +- `ServerConfig.max_body_size` +- `ServerConfig.max_header_size` +- `ServerConfig.websocket_max_message_size` +- `ServerConfig.websocket_max_queue` +- `ServerConfig.server_header` +- `ServerConfig.server_header_value` +- `ServerConfig.include_date_header` +- `ServerConfig.default_response_headers` +- `ServerConfig.allowed_server_names` +- `ServerConfig.alt_svc_values` +- `ServerConfig.enable_h2c` +- `ServerConfig.static_mount_enabled` + +These convenience properties are useful when inspecting a merged configuration from tooling or lifecycle hooks. + +## Release and promotion evaluators + +Primary public evaluator functions: + +- `evaluate_release_gates` +- `evaluate_promotion_target` +- `assert_release_ready` +- `assert_promotion_target_ready` + +Report dataclasses: + +| Report type | Fields | +|---|---| +| `ReleaseGateReport` | `passed`, `failures`, `checked_files`, `rfc_status`, `artifact_status` | +| `PromotionTargetReport` | `passed`, `failures`, `checked_files`, `authoritative_boundary`, `strict_target_boundary`, `flag_surface`, `operator_surface`, `performance`, `documentation` | +| `IndependentBundleReport` | `passed`, `failures`, `checked_files`, `scenario_status` | +| `PromotionSectionReport` | `name`, `passed`, `failures`, `checked_files`, `details` | + + +Default contract paths exposed by the module: + +- `DEFAULT_BOUNDARY_PATH` +- `DEFAULT_CORPUS_PATH` +- `DEFAULT_INDEPENDENT_MATRIX_PATH` +- `DEFAULT_SAME_STACK_MATRIX_PATH` +- `DEFAULT_STRICT_TARGET_BOUNDARY_PATH` +- `DEFAULT_PROMOTION_TARGET_PATH` + +Use the evaluator functions when you need a **supported, package-owned** answer to whether the current tree is ready for release or promotion. + +## Advanced lifecycle server surface + +`TigrCornServer` is the advanced package-owned server object. `EmbeddedServer` wraps it for embedder-friendly lifecycle control. Prefer: + +- `run` for sync process entry +- `serve` or `serve_import_string` inside an existing async runtime +- `EmbeddedServer` when you need explicit startup/shutdown control plus endpoint introspection +- `TigrCornServer` only when you need the underlying advanced lifecycle object directly + +Lifecycle hooks and ordering rules are defined in `docs/LIFECYCLE_AND_EMBEDDED_SERVER.md`. + +## Non-goals and exclusions + +This page documents the public surface that exists **now**. It is not a promise that every adjacent server feature family is supported. + +Explicit exclusions and/or outside-boundary families include: + +- Trio runtime as a supported public runtime +- ASGI2, WSGI, and RSGI compatibility layers +- parser pluggability +- WebSocket engine pluggability +- JOSE / COSE +- RFC 9111 caching +- RFC 9530 +- RFC 9421 +- broader gateway-style signature/integrity products + +Use `docs/review/conformance/BOUNDARY_NON_GOALS.md` when in doubt. diff --git a/.ssot/specs/SPEC-2008-tigrcorn-cli.md b/.ssot/specs/SPEC-2008-tigrcorn-cli.md new file mode 100644 index 00000000..ae8b3539 --- /dev/null +++ b/.ssot/specs/SPEC-2008-tigrcorn-cli.md @@ -0,0 +1,891 @@ +# CLI + +# CLI operator reference + +This page is the human operator reference for Tigrcorn's public CLI surfaces. It complements, and does not replace, the canonical current-state and conformance material. + +Canonical supporting sources: + +- `README.md` +- `docs/review/conformance/CLI_FLAG_SURFACE.md` +- `docs/review/conformance/cli_flag_surface.json` +- `docs/review/conformance/DEPLOYMENT_PROFILES.md` +- `docs/review/conformance/cli_help.current.txt` +- `docs/review/conformance/tigrcorn_interop_help.current.txt` +- `docs/review/conformance/state/CURRENT_REPOSITORY_STATE.md` + +## Table of contents + +- [Command surfaces](#command-surfaces) +- [Config precedence and source merging](#config-precedence-and-source-merging) +- [Common launch recipes](#common-launch-recipes) +- [Deployment profiles](#deployment-profiles) +- [Flag families at a glance](#flag-families-at-a-glance) +- [Exhaustive public flag reference](#exhaustive-public-flag-reference) +- [Help snapshots](#help-snapshots) +- [Notes on hidden or non-public flags](#notes-on-hidden-or-non-public-flags) + +## Command surfaces + +| Command | Role | Primary audience | Notes | +|---|---|---|---| +| `tigrcorn` | main server launcher | operators, developers, CI | Loads an ASGI target, binds listeners, and exposes the full public flag surface. | +| `python -m tigrcorn` | equivalent module entrypoint | operators, developers, CI | Useful when invoking from an interpreter-managed environment. | +| `tigrcorn-interop` | external interoperability runner | maintainers, release owners, auditors | Executes preserved scenario matrices and writes evidence bundles. | + +## Config precedence and source merging + +Tigrcorn's public precedence contract is: + +```text +CLI > env > config file > defaults +``` + +Public config-loading surfaces: + +- `--config`, `--env-file`, and `--env-prefix` on the CLI +- `tigrcorn.config.load_config_file` +- `tigrcorn.config.load_env_config` +- `tigrcorn.config.build_config_from_sources` + +Use this model whenever you document or debug configuration behavior. The CLI is allowed to override everything else; defaults are the last resort. + +## Common launch recipes + +### Minimal HTTP/1.1 + HTTP/2 launch + +```bash +tigrcorn examples.echo_http.app:app --host 127.0.0.1 --port 8000 +``` + +### App factory launch + +```bash +tigrcorn examples.echo_http.app:create_app --factory --host 127.0.0.1 --port 8000 +``` + +### Explicit config file + env file + env prefix + +```bash +tigrcorn examples.echo_http.app:app \ + --config ./tigrcorn.toml \ + --env-file ./.env \ + --env-prefix TIGRCORN +``` + +### HTTP/2 over TLS + +```bash +tigrcorn examples.echo_http.app:app \ + --bind 127.0.0.1:8443 \ + --http 2 \ + --ssl-certfile ./certs/server.pem \ + --ssl-keyfile ./certs/server.key +``` + +### HTTP/3 / QUIC over UDP + +```bash +tigrcorn examples.echo_http.app:app \ + --quic-bind 127.0.0.1:8443 \ + --http 3 \ + --protocol http3 \ + --protocol quic \ + --ssl-certfile ./certs/server.pem \ + --ssl-keyfile ./certs/server.key +``` + +### HTTP/3 / QUIC with client-certificate verification + +```bash +tigrcorn examples.echo_http.app:app \ + --quic-bind 127.0.0.1:8443 \ + --http 3 \ + --protocol http3 \ + --protocol quic \ + --ssl-certfile ./certs/server.pem \ + --ssl-keyfile ./certs/server.key \ + --ssl-ca-certs ./certs/ca.pem \ + --ssl-require-client-cert +``` + +### HTTP/1.1 and WebSocket echo + +```bash +tigrcorn examples.websocket_echo.app:app \ + --host 127.0.0.1 \ + --port 9000 \ + --http 1.1 +``` + +### WebSocket permessage-deflate + +```bash +tigrcorn examples.websocket_echo.app:app \ + --host 127.0.0.1 \ + --port 9000 \ + --websocket-compression permessage-deflate +``` + +### Static route with cache headers + +```bash +tigrcorn examples.http_entity_static.app:app \ + --static-path-route /assets \ + --static-path-mount ./public \ + --static-path-dir-to-file \ + --static-path-index-file index.html \ + --static-path-expires 3600 +``` + +### CONNECT, trailer, and content-coding policies + +```bash +tigrcorn examples.echo_http.app:app \ + --connect-policy allowlist \ + --connect-allow 127.0.0.1:5432 \ + --trailer-policy strict \ + --content-coding-policy allowlist \ + --content-codings br,gzip,deflate +``` + +### Automatic Alt-Svc advertisement + +```bash +tigrcorn examples.advanced_protocol_delivery.alt_svc_app:app \ + --bind 127.0.0.1:8080 \ + --quic-bind 127.0.0.1:8443 \ + --http 1.1 --http 2 --http 3 \ + --alt-svc-auto \ + --alt-svc-ma 86400 \ + --alt-svc-persist +``` + +### Metrics, log files, and structured logging + +```bash +tigrcorn examples.echo_http.app:app \ + --log-level info \ + --structured-log \ + --access-log-file ./logs/access.log \ + --error-log-file ./logs/error.log \ + --metrics \ + --metrics-bind 127.0.0.1:9100 \ + --statsd-host 127.0.0.1:8125 \ + --otel-endpoint http://127.0.0.1:4318 +``` + +### Runtime selection, reload, and worker supervision + +```bash +tigrcorn examples.echo_http.app:app \ + --workers 4 \ + --runtime auto \ + --reload \ + --reload-dir ./src \ + --reload-include '*.py' \ + --reload-exclude '*.tmp' \ + --limit-max-requests 10000 \ + --max-requests-jitter 500 +``` + +### Unix domain socket and ownership controls + +```bash +tigrcorn examples.echo_http.app:app \ + --transport unix \ + --uds /tmp/tigrcorn.sock \ + --user www-data \ + --group www-data \ + --umask 18 +``` + +### Pipe / custom operator transports + +```bash +tigrcorn examples.echo_http.app:app \ + --transport pipe \ + --pipe-mode rawframed \ + --protocol rawframed +``` + +```bash +tigrcorn examples.echo_http.app:app \ + --transport inproc \ + --protocol custom +``` + +These operator transports are part of the public operator surface but sit outside the strict RFC claim where the boundary docs say so. + +### External interoperability matrix execution + +```bash +tigrcorn-interop \ + --matrix docs/review/conformance/external_matrix.release.json \ + --output ./artifacts/interop +``` + +```bash +tigrcorn-interop \ + --matrix docs/review/conformance/external_matrix.current_release.json \ + --output ./artifacts/current-release \ + --strict +``` + +```bash +tigrcorn-interop \ + --matrix docs/review/conformance/external_matrix.same_stack_replay.json \ + --output ./artifacts/same-stack \ + --only websocket-http3-server-aioquic-client +``` + +## Deployment profiles + +The deployment profiles are the normalized, machine-readable public profile map for the CLI and operator surface. + +| Profile | Claim class | RFC targets | Description | +|---|---|---|---| +| `http1_baseline` | `rfc_scoped` | RFC 9112 | Single-listener HTTP/1.1 baseline profile. | +| `http1_proxy` | `hybrid` | RFC 9112 | HTTP/1.1 behind a reverse proxy with trusted forwarded headers. | +| `http2_cleartext` | `rfc_scoped` | RFC 9113 | HTTP/2 cleartext / h2c profile. | +| `http2_tls` | `rfc_scoped` | RFC 9113, RFC 8446, RFC 7301 | HTTP/2 over TLS with ALPN. | +| `http3_quic` | `rfc_scoped` | RFC 9000, RFC 9001, RFC 9002, RFC 9114 | HTTP/3 over QUIC. | +| `http3_quic_mtls` | `rfc_scoped` | RFC 9000, RFC 9001, RFC 9114, RFC 8446, RFC 5280 | HTTP/3 over QUIC with client-certificate verification. | +| `websocket_http11` | `rfc_scoped` | RFC 6455 | WebSocket over HTTP/1.1. | +| `websocket_http11_permessage_deflate` | `rfc_scoped` | RFC 6455, RFC 7692 | WebSocket over HTTP/1.1 with permessage-deflate. | +| `websocket_http2` | `rfc_scoped` | RFC 8441 | WebSocket over HTTP/2 extended CONNECT. | +| `websocket_http2_permessage_deflate` | `rfc_scoped` | RFC 8441, RFC 7692 | WebSocket over HTTP/2 with permessage-deflate. | +| `websocket_http3` | `rfc_scoped` | RFC 9220 | WebSocket over HTTP/3 extended CONNECT. | +| `websocket_http3_permessage_deflate` | `rfc_scoped` | RFC 9220, RFC 7692 | WebSocket over HTTP/3 with permessage-deflate. | +| `connect_http11` | `rfc_scoped` | RFC 9110 §9.3.6, RFC 9112 | CONNECT relay over HTTP/1.1. | +| `connect_http2` | `rfc_scoped` | RFC 9110 §9.3.6, RFC 9113 | CONNECT relay over HTTP/2. | +| `connect_http3` | `rfc_scoped` | RFC 9110 §9.3.6, RFC 9114 | CONNECT relay over HTTP/3. | +| `trailers_http11` | `rfc_scoped` | RFC 9110 §6.5, RFC 9112 | Trailers over HTTP/1.1. | +| `trailers_http2` | `rfc_scoped` | RFC 9110 §6.5, RFC 9113 | Trailers over HTTP/2. | +| `trailers_http3` | `rfc_scoped` | RFC 9110 §6.5, RFC 9114 | Trailers over HTTP/3. | +| `content_coding_http11` | `rfc_scoped` | RFC 9110 §8, RFC 9112 | Content coding over HTTP/1.1. | +| `content_coding_http2` | `rfc_scoped` | RFC 9110 §8, RFC 9113 | Content coding over HTTP/2. | +| `content_coding_http3` | `rfc_scoped` | RFC 9110 §8, RFC 9114 | Content coding over HTTP/3. | +| `tls_ocsp_strict` | `rfc_scoped` | RFC 8446, RFC 5280, RFC 6960 | TLS listener with strict OCSP policy. | +| `worker_prefork_proxy` | `pure_operator` | — | Worker-prefork deployment behind a proxy. | +| `unix_socket_proxy` | `pure_operator` | — | Unix-socket deployment behind a reverse proxy. | +| `fd_inherited_worker` | `pure_operator` | — | FD-inherited listener with worker supervision. | +| `custom_pipe_rawframed` | `non_rfc_custom` | — | Pipe/rawframed custom transport outside the strict RFC-certified surface. | + + +## Flag families at a glance + +| Family | Flag groups | Public flag strings | +|---|---:|---:| +| `App / process / development` | 6 | 17 | +| `Listener / binding` | 1 | 15 | +| `Logging / observability` | 1 | 14 | +| `Protocol / transport` | 1 | 20 | +| `Resource / timeouts / concurrency` | 1 | 29 | +| `Static / delivery` | 1 | 6 | +| `TLS / security` | 2 | 23 | + + +## Exhaustive public flag reference + +The rows below mirror the current public flag truth in `docs/review/conformance/cli_flag_surface.json`. + +## App / process / development + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `factory` | `--factory` | `app.factory` | `pure_operator` | — | +| `app_dir` | `--app-dir` | `app.app_dir` | `pure_operator` | — | +| `reload` | `--reload`, `--reload-dir`, `--reload-include`, `--reload-exclude` | `app.reload*` | `pure_operator` | — | +| `workers` | `--workers`, `--worker-class`, `--pid`, `--limit-max-requests`, `--max-requests-jitter`, `--runtime`, `--worker-healthcheck-timeout` | `process.*` | `pure_operator` | — | +| `config_source` | `--config`, `--env-prefix`, `--env-file` | `app.config_file / app.env_prefix` | `pure_operator` | — | +| `lifespan` | `--lifespan` | `app.lifespan` | `pure_operator` | — | + +### `factory` + +| Field | Value | +|---|---| +| Flags | `--factory` | +| Family | `App / process / development` | +| Config path | `app.factory` | +| Claim class | `pure_operator` | +| Default | `False` | +| RFC targets | — | +| Validation rules | `boolean` | +| Deployment profiles | `http1_baseline` | +| Unit tests | `tests/test_cli_and_asgi3.py::CLIAndASGI3Tests::test_parser` | +| Interop scenarios | — | +| Performance profiles | — | + +### `app_dir` + +| Field | Value | +|---|---| +| Flags | `--app-dir` | +| Family | `App / process / development` | +| Config path | `app.app_dir` | +| Claim class | `pure_operator` | +| Default | `None` (loads from current working directory when unset) | +| RFC targets | — | +| Validation rules | `path string` | +| Deployment profiles | `http1_baseline` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_app_dir_round_trip` | +| Interop scenarios | — | +| Performance profiles | — | + +### `reload` + +| Field | Value | +|---|---| +| Flags | `--reload`, `--reload-dir`, `--reload-include`, `--reload-exclude` | +| Family | `App / process / development` | +| Config path | `app.reload*` | +| Claim class | `pure_operator` | +| Default | `False` | +| RFC targets | — | +| Validation rules | `boolean + repeatable globs/paths` | +| Deployment profiles | `worker_prefork_proxy` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_parser_accepts_grouped_phase2_flags` | +| Interop scenarios | — | +| Performance profiles | — | + +### `workers` + +| Field | Value | +|---|---| +| Flags | `--workers`, `--worker-class`, `--pid`, `--limit-max-requests`, `--max-requests-jitter`, `--runtime`, `--worker-healthcheck-timeout` | +| Family | `App / process / development` | +| Config path | `process.*` | +| Claim class | `pure_operator` | +| Default | `None` | +| RFC targets | — | +| Validation rules | `workers positive integer`, `worker_class in supported set`, `runtime in {auto, asyncio, uvloop}`, `healthcheck timeout positive float` | +| Deployment profiles | `worker_prefork_proxy`, `fd_inherited_worker` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_parser_accepts_grouped_phase2_flags` | +| Interop scenarios | — | +| Performance profiles | `worker_scale` | + +### `config_source` + +| Field | Value | +|---|---| +| Flags | `--config`, `--env-prefix`, `--env-file` | +| Family | `App / process / development` | +| Config path | `app.config_file / app.env_prefix` | +| Claim class | `pure_operator` | +| Default | `None` | +| RFC targets | — | +| Validation rules | `config file path`, `env prefix string`, `optional env-file bootstrap` | +| Deployment profiles | `http1_baseline` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_config_source_precedence_cli_over_env_over_file` | +| Interop scenarios | — | +| Performance profiles | — | + +### `lifespan` + +| Field | Value | +|---|---| +| Flags | `--lifespan` | +| Family | `App / process / development` | +| Config path | `app.lifespan` | +| Claim class | `pure_operator` | +| Default | `auto` | +| RFC targets | — | +| Validation rules | `one of auto,on,off` | +| Deployment profiles | `http1_baseline` | +| Unit tests | `tests/test_config_matrix.py::ConfigMatrixTests::test_tcp_defaults` | +| Interop scenarios | — | +| Performance profiles | — | + + +## Listener / binding + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `binds` | `--bind`, `--host`, `--port`, `--uds`, `--fd`, `--endpoint`, `--insecure-bind`, `--quic-bind`, `--transport`, `--reuse-port`, `--reuse-address`, `--backlog`, `--user`, `--group`, `--umask` | `listeners[]` | `hybrid` | RFC 9112, RFC 9113, RFC 9114, RFC 9000, RFC 9001 | + +### `binds` + +| Field | Value | +|---|---| +| Flags | `--bind`, `--host`, `--port`, `--uds`, `--fd`, `--endpoint`, `--insecure-bind`, `--quic-bind`, `--transport`, `--reuse-port`, `--reuse-address`, `--backlog`, `--user`, `--group`, `--umask` | +| Family | `Listener / binding` | +| Config path | `listeners[]` | +| Claim class | `hybrid` | +| Default | `defaults file` | +| RFC targets | RFC 9112, RFC 9113, RFC 9114, RFC 9000, RFC 9001 | +| Validation rules | `listener kinds validated`, `ports in range`, `paths/FDs typed`, `unix socket ownership controls only apply to unix listeners` | +| Deployment profiles | `http1_baseline`, `http2_tls`, `http3_quic`, `fd_inherited_worker`, `unix_socket_proxy`, `custom_pipe_rawframed` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_build_config_from_namespace_maps_nested_submodels` | +| Interop scenarios | — | +| Performance profiles | `http1_baseline`, `http3_clean` | + + +## Static / delivery + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `static_path` | `--static-path-route`, `--static-path-mount`, `--static-path-dir-to-file`, `--no-static-path-dir-to-file`, `--static-path-index-file`, `--static-path-expires` | `static.*` | `pure_operator` | — | + +### `static_path` + +| Field | Value | +|---|---| +| Flags | `--static-path-route`, `--static-path-mount`, `--static-path-dir-to-file`, `--no-static-path-dir-to-file`, `--static-path-index-file`, `--static-path-expires` | +| Family | `Static / delivery` | +| Config path | `static.*` | +| Claim class | `pure_operator` | +| Default | `{'route': None, 'mount': None, 'dir_to_file': True, 'index_file': 'index.html', 'expires': None}` | +| RFC targets | — | +| Validation rules | `route string`, `path string`, `boolean toggle`, `string or null`, `non-negative integer or null` | +| Deployment profiles | `http1_baseline`, `http2_tls`, `http3_quic` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_parser_accepts_grouped_phase2_flags`, `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_build_config_from_namespace_maps_nested_submodels`, `tests/test_phase2_static_delivery_surface.py::StaticAndPathsendSurfaceTests::test_cli_main_allows_static_only_mount_without_app_import_string` | +| Interop scenarios | — | +| Performance profiles | — | + + +## TLS / security + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `tls` | `--ssl-certfile`, `--ssl-keyfile`, `--ssl-keyfile-password`, `--ssl-ca-certs`, `--ssl-require-client-cert`, `--ssl-ciphers`, `--ssl-alpn`, `--ssl-ocsp-mode`, `--ssl-ocsp-soft-fail`, `--ssl-ocsp-cache-size`, `--ssl-ocsp-max-age`, `--ssl-crl-mode`, `--ssl-crl`, `--ssl-revocation-fetch` | `tls.*` | `rfc_scoped` | RFC 8446, RFC 5280, RFC 6960, RFC 7301 | +| `proxy_security` | `--proxy-headers`, `--forwarded-allow-ips`, `--root-path`, `--server-header`, `--no-server-header`, `--date-header`, `--no-date-header`, `--header`, `--server-name` | `proxy.*` | `pure_operator` | — | + +### `tls` + +| Field | Value | +|---|---| +| Flags | `--ssl-certfile`, `--ssl-keyfile`, `--ssl-keyfile-password`, `--ssl-ca-certs`, `--ssl-require-client-cert`, `--ssl-ciphers`, `--ssl-alpn`, `--ssl-ocsp-mode`, `--ssl-ocsp-soft-fail`, `--ssl-ocsp-cache-size`, `--ssl-ocsp-max-age`, `--ssl-crl-mode`, `--ssl-crl`, `--ssl-revocation-fetch` | +| Family | `TLS / security` | +| Config path | `tls.*` | +| Claim class | `rfc_scoped` | +| Default | `defaults file` | +| RFC targets | RFC 8446, RFC 5280, RFC 6960, RFC 7301 | +| Validation rules | `cert/key pairing`, `encrypted key password requires ssl_keyfile`, `CA required for client cert mode`, `OCSP mode enum`, `ocsp max age positive`, `CRL mode enum`, `local CRL path exists and parses`, `revocation fetch toggle` | +| Deployment profiles | `http2_tls`, `http3_quic`, `http3_quic_mtls`, `tls_ocsp_strict` | +| Unit tests | `tests/test_public_api_cli_mtls_surface.py::PublicRunAndCLIClientCertificateSurfaceTests::test_cli_main_forwards_client_certificate_options`, `tests/test_config_matrix.py::ConfigMatrixTests::test_udp_client_auth_is_accepted_with_a_trust_store`, `tests/test_phase5_tls_operator_material_surface.py::Phase5TLSOperatorMaterialSurfaceTests::test_cli_and_env_wiring_accept_ssl_keyfile_password_and_ssl_crl`, `tests/test_phase5_tls_operator_material_surface.py::Phase5TLSOperatorMaterialSurfaceTests::test_encrypted_private_key_material_loads_through_server_tls_context`, `tests/test_phase5_tls_operator_material_surface.py::Phase5TLSOperatorMaterialSurfaceTests::test_local_crl_material_is_loaded_and_revoked_client_cert_is_rejected` | +| Interop scenarios | `http3-server-aioquic-client-mtls`, `tls-server-ocsp-validation-openssl-client` | +| Performance profiles | `tls_handshake` | + +### `proxy_security` + +| Field | Value | +|---|---| +| Flags | `--proxy-headers`, `--forwarded-allow-ips`, `--root-path`, `--server-header`, `--no-server-header`, `--date-header`, `--no-date-header`, `--header`, `--server-name` | +| Family | `TLS / security` | +| Config path | `proxy.*` | +| Claim class | `pure_operator` | +| Default | `defaults file` | +| RFC targets | — | +| Validation rules | `root_path empty or leading /`, `default headers use name:value syntax`, `server names repeatable / comma-separated allowlist` | +| Deployment profiles | `http1_proxy`, `unix_socket_proxy` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_build_config_from_namespace_maps_nested_submodels` | +| Interop scenarios | — | +| Performance profiles | — | + + +## Logging / observability + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `logging` | `--log-level`, `--access-log`, `--no-access-log`, `--access-log-file`, `--access-log-format`, `--error-log-file`, `--log-config`, `--structured-log`, `--metrics`, `--metrics-bind`, `--statsd-host`, `--otel-endpoint`, `--use-colors`, `--no-use-colors` | `logging.* / metrics.*` | `pure_operator` | — | + +### `logging` + +| Field | Value | +|---|---| +| Flags | `--log-level`, `--access-log`, `--no-access-log`, `--access-log-file`, `--access-log-format`, `--error-log-file`, `--log-config`, `--structured-log`, `--metrics`, `--metrics-bind`, `--statsd-host`, `--otel-endpoint`, `--use-colors`, `--no-use-colors` | +| Family | `Logging / observability` | +| Config path | `logging.* / metrics.*` | +| Claim class | `pure_operator` | +| Default | `defaults file` | +| RFC targets | — | +| Validation rules | `path/string/bool parsing`, `optional colorized stream logging toggle` | +| Deployment profiles | `http1_baseline` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_parser_accepts_grouped_phase2_flags` | +| Interop scenarios | — | +| Performance profiles | — | + + +## Resource / timeouts / concurrency + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `limits` | `--timeout-keep-alive`, `--read-timeout`, `--write-timeout`, `--timeout-graceful-shutdown`, `--limit-concurrency`, `--max-connections`, `--max-tasks`, `--max-streams`, `--max-body-size`, `--max-header-size`, `--http1-max-incomplete-event-size`, `--http1-buffer-size`, `--http1-header-read-timeout`, `--http1-keep-alive`, `--no-http1-keep-alive`, `--http2-max-concurrent-streams`, `--http2-max-headers-size`, `--http2-max-frame-size`, `--http2-adaptive-window`, `--no-http2-adaptive-window`, `--http2-initial-connection-window-size`, `--http2-initial-stream-window-size`, `--http2-keep-alive-interval`, `--http2-keep-alive-timeout`, `--websocket-max-message-size`, `--websocket-max-queue`, `--websocket-ping-interval`, `--websocket-ping-timeout`, `--idle-timeout` | `http.* / websocket.* / scheduler.*` | `hybrid` | RFC 9110, RFC 9112, RFC 9113, RFC 9114, RFC 6455, RFC 8441, RFC 9220 | + +### `limits` + +| Field | Value | +|---|---| +| Flags | `--timeout-keep-alive`, `--read-timeout`, `--write-timeout`, `--timeout-graceful-shutdown`, `--limit-concurrency`, `--max-connections`, `--max-tasks`, `--max-streams`, `--max-body-size`, `--max-header-size`, `--http1-max-incomplete-event-size`, `--http1-buffer-size`, `--http1-header-read-timeout`, `--http1-keep-alive`, `--no-http1-keep-alive`, `--http2-max-concurrent-streams`, `--http2-max-headers-size`, `--http2-max-frame-size`, `--http2-adaptive-window`, `--no-http2-adaptive-window`, `--http2-initial-connection-window-size`, `--http2-initial-stream-window-size`, `--http2-keep-alive-interval`, `--http2-keep-alive-timeout`, `--websocket-max-message-size`, `--websocket-max-queue`, `--websocket-ping-interval`, `--websocket-ping-timeout`, `--idle-timeout` | +| Family | `Resource / timeouts / concurrency` | +| Config path | `http.* / websocket.* / scheduler.*` | +| Claim class | `hybrid` | +| Default | `defaults file` | +| RFC targets | RFC 9110, RFC 9112, RFC 9113, RFC 9114, RFC 6455, RFC 8441, RFC 9220 | +| Validation rules | `positive numeric values` | +| Deployment profiles | `http1_baseline`, `http2_tls`, `http3_quic`, `websocket_http11` | +| Unit tests | `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_build_config_from_namespace_maps_nested_submodels`, `tests/test_phase3_h1_websocket_operator_surface.py::Phase3H1WebSocketOperatorSurfaceTests::test_build_config_from_namespace_maps_phase3_submodels`, `tests/test_phase4_http2_operator_surface.py::Phase4HTTP2OperatorSurfaceTests::test_build_config_from_namespace_maps_phase4_submodels`, `tests/test_phase4_http2_operator_surface.py::Phase4HTTP2OperatorSurfaceTests::test_http2_server_advertises_configured_local_settings` | +| Interop scenarios | — | +| Performance profiles | `http1_baseline`, `http2_multiplexing`, `http3_clean`, `websocket_echo` | + + +## Protocol / transport + +| Flag group | Flags | Config path | Claim class | RFC targets | +|---|---|---|---|---| +| `protocols` | `--http`, `--protocol`, `--disable-websocket`, `--disable-h2c`, `--websocket-compression`, `--connect-policy`, `--connect-allow`, `--trailer-policy`, `--content-coding-policy`, `--content-codings`, `--alt-svc`, `--alt-svc-auto`, `--no-alt-svc-auto`, `--alt-svc-ma`, `--alt-svc-persist`, `--quic-require-retry`, `--quic-max-datagram-size`, `--quic-idle-timeout`, `--quic-early-data-policy`, `--pipe-mode` | `http.* / websocket.* / quic.* / listeners[].protocols` | `rfc_scoped` | RFC 9112, RFC 9113, RFC 9114, RFC 9000, RFC 9001, RFC 9002, RFC 6455, RFC 7692, RFC 8441, RFC 9220, RFC 9110 §9.3.6, RFC 9110 §6.5, RFC 9110 §8 | + +### `protocols` + +| Field | Value | +|---|---| +| Flags | `--http`, `--protocol`, `--disable-websocket`, `--disable-h2c`, `--websocket-compression`, `--connect-policy`, `--connect-allow`, `--trailer-policy`, `--content-coding-policy`, `--content-codings`, `--alt-svc`, `--alt-svc-auto`, `--no-alt-svc-auto`, `--alt-svc-ma`, `--alt-svc-persist`, `--quic-require-retry`, `--quic-max-datagram-size`, `--quic-idle-timeout`, `--quic-early-data-policy`, `--pipe-mode` | +| Family | `Protocol / transport` | +| Config path | `http.* / websocket.* / quic.* / listeners[].protocols` | +| Claim class | `rfc_scoped` | +| Default | `defaults file` | +| RFC targets | RFC 9112, RFC 9113, RFC 9114, RFC 9000, RFC 9001, RFC 9002, RFC 6455, RFC 7692, RFC 8441, RFC 9220, RFC 9110 §9.3.6, RFC 9110 §6.5, RFC 9110 §8 | +| Validation rules | `enum values`, `positive numeric values` | +| Deployment profiles | `http1_baseline`, `http2_cleartext`, `http2_tls`, `http3_quic`, `websocket_http11_permessage_deflate`, `connect_http11`, `trailers_http11`, `content_coding_http11`, `custom_pipe_rawframed`, `websocket_http2_permessage_deflate`, `websocket_http3_permessage_deflate`, `connect_http2`, `connect_http3`, `trailers_http2`, `trailers_http3`, `content_coding_http2`, `content_coding_http3` | +| Unit tests | `tests/test_cli_and_asgi3.py::CLIAndASGI3Tests::test_parser`, `tests/test_phase2_cli_config_surface.py::Phase2CLIConfigSurfaceTests::test_build_config_from_namespace_maps_nested_submodels`, `tests/test_phase3_strict_rfc_surface.py::Phase3StrictRFCSurfaceTests::test_cli_phase3_flags_round_trip_into_config` | +| Interop scenarios | `websocket-http11-server-websockets-client-permessage-deflate`, `http11-connect-relay-curl-client`, `http11-trailer-fields-curl-client`, `http11-content-coding-curl-client`, `http3-server-aioquic-client-post-retry`, `http3-server-aioquic-client-post-zero-rtt`, `websocket-http2-server-h2-client-permessage-deflate`, `websocket-http3-server-aioquic-client-permessage-deflate`, `http2-connect-relay-h2-client`, `http3-connect-relay-aioquic-client`, `http2-trailer-fields-h2-client`, `http3-trailer-fields-aioquic-client`, `http2-content-coding-curl-client`, `http3-content-coding-aioquic-client` | +| Performance profiles | `http1_baseline`, `http2_multiplexing`, `http3_clean`, `websocket_compressed`, `websocket_compression`, `connect_tunnel`, `trailers_under_load`, `content_coding_under_load` | + + +## Help snapshots + +
+`tigrcorn --help` snapshot + +```text +usage: tigrcorn [-h] [--factory] [--app-dir APP_DIR] [--reload] + [--reload-dir RELOAD_DIR] [--reload-include RELOAD_INCLUDE] + [--reload-exclude RELOAD_EXCLUDE] [--workers WORKERS] + [--worker-class WORKER_CLASS] + [--runtime {auto,asyncio,uvloop}] [--pid PID] + [--worker-healthcheck-timeout WORKER_HEALTHCHECK_TIMEOUT] + [--config CONFIG] [--env-file ENV_FILE] + [--env-prefix ENV_PREFIX] [--lifespan {auto,on,off}] + [--limit-max-requests LIMIT_MAX_REQUESTS] + [--max-requests-jitter MAX_REQUESTS_JITTER] [--bind BIND] + [--host HOST] [--port PORT] [--uds UDS] [--fd FD] + [--endpoint ENDPOINT] [--insecure-bind INSECURE_BIND] + [--quic-bind QUIC_BIND] + [--transport {tcp,udp,unix,pipe,inproc}] [--reuse-port] + [--reuse-address] [--backlog BACKLOG] [--user USER] + [--group GROUP] [--umask UMASK] + [--static-path-route STATIC_PATH_ROUTE] + [--static-path-mount STATIC_PATH_MOUNT] + [--static-path-dir-to-file] [--no-static-path-dir-to-file] + [--static-path-index-file STATIC_PATH_INDEX_FILE] + [--static-path-expires STATIC_PATH_EXPIRES] + [--ssl-certfile SSL_CERTFILE] [--ssl-keyfile SSL_KEYFILE] + [--ssl-keyfile-password SSL_KEYFILE_PASSWORD] + [--ssl-ca-certs SSL_CA_CERTS] [--ssl-require-client-cert] + [--ssl-ciphers SSL_CIPHERS] [--ssl-alpn SSL_ALPN] + [--ssl-ocsp-mode {off,soft-fail,require}] + [--ssl-ocsp-soft-fail] + [--ssl-ocsp-cache-size SSL_OCSP_CACHE_SIZE] + [--ssl-ocsp-max-age SSL_OCSP_MAX_AGE] + [--ssl-crl-mode {off,soft-fail,require}] [--ssl-crl SSL_CRL] + [--ssl-revocation-fetch {off,on}] [--proxy-headers] + [--forwarded-allow-ips FORWARDED_ALLOW_IPS] + [--root-path ROOT_PATH] [--server-header [SERVER_HEADER]] + [--no-server-header] [--date-header] [--no-date-header] + [--header HEADERS] [--server-name SERVER_NAME] + [--log-level LOG_LEVEL] [--access-log] [--no-access-log] + [--access-log-file ACCESS_LOG_FILE] + [--access-log-format ACCESS_LOG_FORMAT] + [--error-log-file ERROR_LOG_FILE] [--log-config LOG_CONFIG] + [--structured-log] [--use-colors] [--no-use-colors] + [--metrics] [--metrics-bind METRICS_BIND] + [--statsd-host STATSD_HOST] [--otel-endpoint OTEL_ENDPOINT] + [--timeout-keep-alive TIMEOUT_KEEP_ALIVE] + [--read-timeout READ_TIMEOUT] [--write-timeout WRITE_TIMEOUT] + [--timeout-graceful-shutdown TIMEOUT_GRACEFUL_SHUTDOWN] + [--limit-concurrency LIMIT_CONCURRENCY] + [--max-connections MAX_CONNECTIONS] [--max-tasks MAX_TASKS] + [--max-streams MAX_STREAMS] [--max-body-size MAX_BODY_SIZE] + [--max-header-size MAX_HEADER_SIZE] + [--http1-max-incomplete-event-size HTTP1_MAX_INCOMPLETE_EVENT_SIZE] + [--http1-buffer-size HTTP1_BUFFER_SIZE] + [--http1-header-read-timeout HTTP1_HEADER_READ_TIMEOUT] + [--http1-keep-alive] [--no-http1-keep-alive] + [--http2-max-concurrent-streams HTTP2_MAX_CONCURRENT_STREAMS] + [--http2-max-headers-size HTTP2_MAX_HEADERS_SIZE] + [--http2-max-frame-size HTTP2_MAX_FRAME_SIZE] + [--http2-adaptive-window] [--no-http2-adaptive-window] + [--http2-initial-connection-window-size HTTP2_INITIAL_CONNECTION_WINDOW_SIZE] + [--http2-initial-stream-window-size HTTP2_INITIAL_STREAM_WINDOW_SIZE] + [--http2-keep-alive-interval HTTP2_KEEP_ALIVE_INTERVAL] + [--http2-keep-alive-timeout HTTP2_KEEP_ALIVE_TIMEOUT] + [--websocket-max-message-size WEBSOCKET_MAX_MESSAGE_SIZE] + [--websocket-max-queue WEBSOCKET_MAX_QUEUE] + [--websocket-ping-interval WEBSOCKET_PING_INTERVAL] + [--websocket-ping-timeout WEBSOCKET_PING_TIMEOUT] + [--idle-timeout IDLE_TIMEOUT] [--http {1.1,2,3}] + [--protocol {http1,http2,http3,quic,websocket,rawframed,custom}] + [--disable-websocket] [--disable-h2c] + [--websocket-compression {off,permessage-deflate}] + [--connect-policy {relay,deny,allowlist}] + [--connect-allow CONNECT_ALLOW] + [--trailer-policy {pass,drop,strict}] + [--content-coding-policy {allowlist,identity-only,strict}] + [--content-codings CONTENT_CODINGS] [--alt-svc ALT_SVC] + [--alt-svc-auto] [--no-alt-svc-auto] [--alt-svc-ma ALT_SVC_MA] + [--alt-svc-persist] [--quic-require-retry] + [--quic-max-datagram-size QUIC_MAX_DATAGRAM_SIZE] + [--quic-idle-timeout QUIC_IDLE_TIMEOUT] + [--quic-early-data-policy {allow,deny,require}] + [--pipe-mode {rawframed,stream}] + [app] + +ASGI3-compatible transport server + +positional arguments: + app Application import string in module:attr form + +options: + -h, --help show this help message and exit + +App / process / development: + --factory Treat APP as an application factory + --app-dir APP_DIR Add a directory to sys.path before loading the app + --reload Enable development autoreload + --reload-dir RELOAD_DIR + Directory to watch for reload + --reload-include RELOAD_INCLUDE + Glob to include in reload watch set + --reload-exclude RELOAD_EXCLUDE + Glob to exclude from reload watch set + --workers WORKERS Worker process count + --worker-class WORKER_CLASS + Worker implementation class + --runtime {auto,asyncio,uvloop} + Runtime backend for sync entrypoints and worker + processes + --pid PID PID file path + --worker-healthcheck-timeout WORKER_HEALTHCHECK_TIMEOUT + Worker startup healthcheck timeout in seconds + --config CONFIG Config source: file path (.json, .toml, .yaml, .yml, + .py), module:, or object:: + --env-file ENV_FILE Load additional prefixed config values from a dotenv + file + --env-prefix ENV_PREFIX + Environment variable prefix for config loading + --lifespan {auto,on,off} + --limit-max-requests LIMIT_MAX_REQUESTS + --max-requests-jitter MAX_REQUESTS_JITTER + +Listener / binding: + --bind BIND Bind listener as host:port + --host HOST Bind host for TCP/UDP listeners + --port PORT Bind port for TCP/UDP listeners + --uds UDS Bind Unix domain socket or pipe path + --fd FD Use an inherited file descriptor listener + --endpoint ENDPOINT Endpoint / raw listener description + --insecure-bind INSECURE_BIND + Additional insecure bind alongside TLS listener(s) + --quic-bind QUIC_BIND + Additional UDP/QUIC bind + --transport {tcp,udp,unix,pipe,inproc} + --reuse-port + --reuse-address + --backlog BACKLOG + --user USER User name or uid to own Unix sockets + --group GROUP Group name or gid to own Unix sockets + --umask UMASK Umask applied while creating Unix sockets (octal or + integer) + +Static / delivery: + --static-path-route STATIC_PATH_ROUTE + HTTP route prefix served from the mounted static + directory + --static-path-mount STATIC_PATH_MOUNT + Filesystem directory mounted at --static-path-route + --static-path-dir-to-file + directory index resolution for the mounted static path + --no-static-path-dir-to-file + Disable directory index resolution for the mounted + static path + --static-path-index-file STATIC_PATH_INDEX_FILE + Index file name served when directory index resolution + is enabled + --static-path-expires STATIC_PATH_EXPIRES + Static-response cache TTL in seconds; 0 disables + caching headers + +TLS / security: + --ssl-certfile SSL_CERTFILE + Certificate for TLS on TCP/Unix or QUIC-TLS on UDP + --ssl-keyfile SSL_KEYFILE + Private key for TLS on TCP/Unix or QUIC-TLS on UDP + --ssl-keyfile-password SSL_KEYFILE_PASSWORD + Password for an encrypted private key PEM used by + package-owned TLS/QUIC-TLS listeners + --ssl-ca-certs SSL_CA_CERTS + Trusted CA bundle for client-certificate verification + --ssl-require-client-cert + Require peer client certificates + --ssl-ciphers SSL_CIPHERS + --ssl-alpn SSL_ALPN ALPN protocol(s); repeat or use comma-separated values + --ssl-ocsp-mode {off,soft-fail,require} + --ssl-ocsp-soft-fail + --ssl-ocsp-cache-size SSL_OCSP_CACHE_SIZE + --ssl-ocsp-max-age SSL_OCSP_MAX_AGE + --ssl-crl-mode {off,soft-fail,require} + --ssl-crl SSL_CRL Local CRL file (PEM or DER) loaded into the package- + owned revocation material set + --ssl-revocation-fetch {off,on} + --proxy-headers + --forwarded-allow-ips FORWARDED_ALLOW_IPS + Trusted forwarded-header peers; repeat or use comma- + separated values + --root-path ROOT_PATH + ASGI root_path mount prefix + --server-header [SERVER_HEADER] + Enable or override the Server header value + --no-server-header Disable the Server header + --date-header Date header injection + --no-date-header Disable date header injection + --header HEADERS Default response header in name:value form; repeat to + add multiple headers + --server-name SERVER_NAME + Allowed Host/:authority value; repeat or use comma- + separated values + +Logging / observability: + --log-level LOG_LEVEL + --access-log Access logging + --no-access-log Disable access logging + --access-log-file ACCESS_LOG_FILE + --access-log-format ACCESS_LOG_FORMAT + --error-log-file ERROR_LOG_FILE + --log-config LOG_CONFIG + --structured-log + --use-colors Colorized logging + --no-use-colors Disable colorized logging + --metrics + --metrics-bind METRICS_BIND + --statsd-host STATSD_HOST + --otel-endpoint OTEL_ENDPOINT + +Resource / timeouts / concurrency: + --timeout-keep-alive TIMEOUT_KEEP_ALIVE + --read-timeout READ_TIMEOUT + --write-timeout WRITE_TIMEOUT + --timeout-graceful-shutdown TIMEOUT_GRACEFUL_SHUTDOWN + --limit-concurrency LIMIT_CONCURRENCY + --max-connections MAX_CONNECTIONS + --max-tasks MAX_TASKS + --max-streams MAX_STREAMS + --max-body-size MAX_BODY_SIZE + --max-header-size MAX_HEADER_SIZE + --http1-max-incomplete-event-size HTTP1_MAX_INCOMPLETE_EVENT_SIZE + Cap buffered incomplete HTTP/1.1 request-head bytes + before the parser rejects the request + --http1-buffer-size HTTP1_BUFFER_SIZE + Read-buffer size used for HTTP/1.1 request-head/body + incremental reads + --http1-header-read-timeout HTTP1_HEADER_READ_TIMEOUT + HTTP/1.1 request-head read timeout in seconds; when + set it tightens the generic read/keep-alive timeout + --http1-keep-alive HTTP/1.1 connection persistence + --no-http1-keep-alive + Disable http/1.1 connection persistence + --http2-max-concurrent-streams HTTP2_MAX_CONCURRENT_STREAMS + Advertised HTTP/2 MAX_CONCURRENT_STREAMS value for + inbound peer-created streams + --http2-max-headers-size HTTP2_MAX_HEADERS_SIZE + HTTP/2-specific request-header and decoded header-list + size cap + --http2-max-frame-size HTTP2_MAX_FRAME_SIZE + Advertised HTTP/2 MAX_FRAME_SIZE for inbound peer + frames + --http2-adaptive-window + HTTP/2 adaptive receive-window growth + --no-http2-adaptive-window + Disable http/2 adaptive receive-window growth + --http2-initial-connection-window-size HTTP2_INITIAL_CONNECTION_WINDOW_SIZE + HTTP/2 connection-level receive window target; values + below 65535 are clamped to the protocol default + --http2-initial-stream-window-size HTTP2_INITIAL_STREAM_WINDOW_SIZE + Advertised HTTP/2 INITIAL_WINDOW_SIZE for peer-created + streams + --http2-keep-alive-interval HTTP2_KEEP_ALIVE_INTERVAL + Idle interval before the server sends an HTTP/2 + connection-level PING + --http2-keep-alive-timeout HTTP2_KEEP_ALIVE_TIMEOUT + HTTP/2 keep-alive PING acknowledgement timeout in + seconds + --websocket-max-message-size WEBSOCKET_MAX_MESSAGE_SIZE + --websocket-max-queue WEBSOCKET_MAX_QUEUE + Maximum queued inbound WebSocket messages before + transport backpressure is applied + --websocket-ping-interval WEBSOCKET_PING_INTERVAL + --websocket-ping-timeout WEBSOCKET_PING_TIMEOUT + --idle-timeout IDLE_TIMEOUT + +Protocol / transport: + --http {1.1,2,3} Enable an HTTP version + --protocol {http1,http2,http3,quic,websocket,rawframed,custom} + Enable a listener protocol + --disable-websocket + --disable-h2c + --websocket-compression {off,permessage-deflate} + --connect-policy {relay,deny,allowlist} + --connect-allow CONNECT_ALLOW + Repeat or use comma-separated host:port, host, or CIDR + entries + --trailer-policy {pass,drop,strict} + --content-coding-policy {allowlist,identity-only,strict} + --content-codings CONTENT_CODINGS + Repeat or use comma-separated values + --alt-svc ALT_SVC Advertise Alt-Svc values; repeat or use comma- + separated values + --alt-svc-auto automatic Alt-Svc advertisement for HTTP/3-capable UDP + listeners + --no-alt-svc-auto Disable automatic alt-svc advertisement for + http/3-capable udp listeners + --alt-svc-ma ALT_SVC_MA + Alt-Svc max-age for automatic advertisement + --alt-svc-persist Set persist=1 on automatic Alt-Svc advertisements + --quic-require-retry Require a QUIC Retry before completing the initial + handshake + --quic-max-datagram-size QUIC_MAX_DATAGRAM_SIZE + --quic-idle-timeout QUIC_IDLE_TIMEOUT + --quic-early-data-policy {allow,deny,require} + --pipe-mode {rawframed,stream} +``` + +
+ +
+`tigrcorn-interop --help` snapshot + +```text +usage: tigrcorn-interop [-h] --matrix MATRIX --output OUTPUT + [--source-root SOURCE_ROOT] [--only SCENARIO_IDS] + [--strict] + +Run the tigrcorn external interoperability matrix and write evidence bundles + +options: + -h, --help show this help message and exit + --matrix MATRIX Path to the external interop matrix JSON file + --output OUTPUT Root directory for result bundles + --source-root SOURCE_ROOT + Repository root used for manifest hashing and commit + detection + --only SCENARIO_IDS Run only the named scenario id (may be given multiple + times) + --strict Stop after the first failed scenario +``` + +
+ +## Notes on hidden or non-public flags + +- `--quic-secret` exists in the parser but is intentionally hidden from the public help and excluded from the public certified CLI surface. +- When public CLI behavior changes, maintainers must update code, tests, `cli_flag_surface.json`, the human CLI docs, and current-state/promotion docs together. diff --git a/MUT.json b/MUT.json index 9e4fcaf0..0220e8f9 100644 --- a/MUT.json +++ b/MUT.json @@ -11,10 +11,6 @@ "LEGACY_UNITTEST_INVENTORY.json", "docs/review/conformance/", "docs/reference/risk_register.schema.json", - "docs/adr/0001-preserve-asgi-boundary.md", - "docs/adr/0002-transport-protocol-separation.md", - "docs/adr/0003-scheduler-and-backpressure.md", - "docs/adr/0004-custom-scope-types.md", "examples/advanced_protocol_delivery/", "docs/LIFECYCLE_AND_EMBEDDED_SERVER.md", "examples/http_entity_static/", @@ -33,6 +29,7 @@ ".github/", "docs/architecture/", "assets/tigrcorn_brand_frag_light.png", - "assets/tigrcorn_brand_frag_dark.png" + "assets/tigrcorn_brand_frag_dark.png", + ".ssot/" ] } diff --git a/README.md b/README.md index badb17b1..219d0fec 100644 --- a/README.md +++ b/README.md @@ -614,7 +614,7 @@ python tools/govchk.py state docs/review/conformance/releases/0.3.9 python tools/govchk.py scan ``` -Repository cleanliness is governed by `MUT.json`, `docs/gov/tree.md`, `docs/gov/mut.md`, `docs/gov/code.md`, and ADR `docs/adr/0005-doc-gov.md`. +Repository cleanliness is governed by `MUT.json`, `docs/gov/tree.md`, `docs/gov/mut.md`, `docs/gov/code.md`, and ADR `.ssot/adr/ADR-1005-doc-gov.md`. ## Current-state and historical planning diff --git a/docs/adr/README.md b/docs/adr/README.md index 201b4e75..216df823 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,15 +1,16 @@ # ADR index -Existing ADRs: +Canonical ADR documents live under `.ssot/adr/` and are prefixed `ADR-`. -- `0001-preserve-asgi-boundary.md` -- `0002-transport-protocol-separation.md` -- `0003-scheduler-and-backpressure.md` -- `0004-custom-scope-types.md` +Repo-local ADR set: -New ADRs: +- `.ssot/adr/ADR-1001-preserve-asgi-boundary.md` +- `.ssot/adr/ADR-1002-transport-protocol-separation.md` +- `.ssot/adr/ADR-1003-scheduler-and-backpressure.md` +- `.ssot/adr/ADR-1004-custom-scope-types.md` +- `.ssot/adr/ADR-1005-doc-gov.md` +- `.ssot/adr/ADR-1006-mutable.md` +- `.ssot/adr/ADR-1007-gov-auth.md` +- `.ssot/adr/ADR-1008-gate-graph.md` -- `0005-doc-gov.md` -- `0006-mutable.md` -- `0007-gov-auth.md` -- `0008-gate-graph.md` +Core ADR set synced from `ssot-registry` also lives in `.ssot/adr/` as `ADR-0001` through `ADR-0012`. diff --git a/docs/review/conformance/state/checkpoints/P8_GOV.md b/docs/review/conformance/state/checkpoints/P8_GOV.md index b36c372c..f0394c7c 100644 --- a/docs/review/conformance/state/checkpoints/P8_GOV.md +++ b/docs/review/conformance/state/checkpoints/P8_GOV.md @@ -7,7 +7,7 @@ This checkpoint records the mutable-tree completion of Phase 8 governance, relea What was added: - governance authority docs under `docs/governance/` -- ADRs `0007-gov-auth.md` and `0008-gate-graph.md` +- ADRs `.ssot/adr/ADR-1007-gov-auth.md` and `.ssot/adr/ADR-1008-gate-graph.md` - `docs/reference/risk_register.schema.json` - `docs/conformance/risk/RISK_REGISTER.json` - `docs/conformance/risk/RISK_TRACEABILITY.json`