From 6b314644a9db85963b288644a4b1e0b9b947b315 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 26 Jul 2026 13:35:05 +0200 Subject: [PATCH] Bootstrap derived Knative rail --- .repo-classification.yaml | 19 ++++++ AGENTS.md | 12 ++++ CLAUDE.md | 3 + INTENT.md | 7 +++ README.md | 10 +++ SCOPE.md | 13 ++++ WORK-RECORDS.md | 15 +++++ declarations/rail.yaml | 45 +++++++++++++ docs/runtime-contract.md | 15 +++++ ...-KNATIVE-WP-0001-bootstrap-derived-rail.md | 63 +++++++++++++++++++ 10 files changed, 202 insertions(+) create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 INTENT.md create mode 100644 README.md create mode 100644 SCOPE.md create mode 100644 WORK-RECORDS.md create mode 100644 declarations/rail.yaml create mode 100644 docs/runtime-contract.md create mode 100644 workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..e8a31de --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,19 @@ +repo_classification: + standard: Repo Classification Standard + version: "1.0" + classified_at: "2026-07-26" + classified_by: agent + category: project + domain: financials + secondary_domains: + - infotech + capability_tags: + - platform + - operations + - configuration + business_stake: + - technology + - operations + business_mechanics: + - coordination + - operation diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..70f598b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# rail-knative — Agent Instructions + +Keep this repo a derived rail. + +- Inherit the versioned common contract from `rail-kubernetes`. +- Do not copy generic lifecycle semantics. +- Keep cluster-scoped installation in `railiance-cluster`. +- Keep Qonto packaging in `rapp-qonto`. +- Never promote readiness without source-linked evidence. +- Route credentials with `warden plan`; never expose values in output. + +After workplan changes, run `statehub fix-consistency`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a7670f9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# CLAUDE + +Follow `AGENTS.md`. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..42025ad --- /dev/null +++ b/INTENT.md @@ -0,0 +1,7 @@ +# INTENT + +Provide an automation-ready Knative specialization without weakening +`rail-kubernetes` as the default platform workload path. + +This repo must never become a second Kubernetes substrate owner or a home for +Qonto-specific packaging. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ae8a32d --- /dev/null +++ b/README.md @@ -0,0 +1,10 @@ +# rail-knative + +Derived Railiance execution rail for Knative Serving workloads. + +This rail inherits the versioned `rail-kubernetes` common workload contract and +owns only Knative-specific activation, scale-to-zero, revision, traffic, +cold-start, and rollback semantics. + +The repo is currently at `declared` readiness. It does not claim that Knative +is installed or production-approved on any reef. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..8256930 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,13 @@ +# SCOPE + +In scope: + +- Knative Service, revision, traffic, autoscaling, activation, and rollback contracts +- derived-rail compatibility and conformance +- generic Knative workload templates and probes + +Out of scope: + +- Kubernetes or Knative operator installation +- cluster ingress, DNS, certificates, or generic network ownership +- workload-specific policy and packaging diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..056a0fd --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,15 @@ +# Work Records — rail-knative + +> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record +> stage 3). Do not edit by hand — edit the source file/block listed for +> each record and re-run fix-consistency to refresh this index. Archived +> workplans are omitted; closed decisions/intakes/engagements stay listed +> so recently-resolved work is still visible. [auto] + +| Kind | ID | Status | Lane | Source | +| --- | --- | --- | --- | --- | +| workplan | RAIL-KNATIVE-WP-0001 | active | — | workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md | +| task | RAIL-KNATIVE-WP-0001-T01 | done | — | workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md | +| task | RAIL-KNATIVE-WP-0001-T02 | done | — | workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md | +| task | RAIL-KNATIVE-WP-0001-T03 | todo | — | workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md | +| task | RAIL-KNATIVE-WP-0001-T04 | todo | — | workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md | diff --git a/declarations/rail.yaml b/declarations/rail.yaml new file mode 100644 index 0000000..9c59565 --- /dev/null +++ b/declarations/rail.yaml @@ -0,0 +1,45 @@ +kind: execution-rail +rail_id: rail-knative +repo: rail-knative +ownership_repo: railiance-cluster +contract_version: 1.0.0 +composition_kind: derived +base_rail: rail-kubernetes +base_rail_contract: 1.0.0 +execution_architecture: knative-serving-on-kubernetes +readiness_state: declared +required_substrate_capabilities: + - kubernetes-api + - knative-serving + - knative-networking + - dns-and-tls + - workload-identity + - restricted-egress-enforcement +inherited_semantics: + - workload-identity + - criticality + - dependency-declaration + - health-and-smoke + - promotion-vocabulary + - audit-and-evidence + - recovery-requirements +overridden_semantics: + - request-activation + - scale-to-zero + - concurrency-and-autoscaling + - revision-traffic + - cold-start-readiness + - revision-rollback +compatibility_constraints: + - rail-kubernetes contract must equal 1.0.0 + - substrate must publish Knative Serving and networking versions + - unrestricted HTTPS egress is not production-approved for critical workloads +supported_rollout_modes: + - revision-canary + - revision-traffic-split + - previous-revision-rollback +source_documents: + - repo: railiance-master + path: docs/rail-composition-contract.md + - repo: railiance-master + path: docs/qonto-knative-runtime-contract.md diff --git a/docs/runtime-contract.md b/docs/runtime-contract.md new file mode 100644 index 0000000..cc48ddd --- /dev/null +++ b/docs/runtime-contract.md @@ -0,0 +1,15 @@ +# Knative Runtime Contract + +The rail owns: + +- authenticated-entry integration points +- request activation and bounded buffering +- scale-to-zero and optional temporary minimum scale +- revisions, concurrency, autoscaling, and traffic splitting +- cold-start readiness and revision rollback + +It inherits workload identity, criticality, dependencies, health, evidence, +promotion vocabulary, and recovery requirements from `rail-kubernetes` 1.0.0. + +Production values for timeouts, concurrency, and scaling are workload bindings +backed by measured evidence; the rail must not invent one universal value. diff --git a/workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md b/workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md new file mode 100644 index 0000000..9ba7b19 --- /dev/null +++ b/workplans/RAIL-KNATIVE-WP-0001-bootstrap-derived-rail.md @@ -0,0 +1,63 @@ +--- +id: RAIL-KNATIVE-WP-0001 +type: workplan +title: "Bootstrap the derived Knative rail" +domain: financials +repo: rail-knative +status: active +owner: codex +topic_slug: railiance +created: "2026-07-26" +updated: "2026-07-26" +state_hub_workstream_id: "b939eaac-c16a-4434-b4ba-3d4995f141a9" +--- + +# RAIL-KNATIVE-WP-0001 - Bootstrap the derived Knative rail + +## T01 - Establish the derived declaration + +```task +id: RAIL-KNATIVE-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "3692f7e9-3fc2-434e-8176-0ae8d63ac850" +``` + +The baseline and versioned derived-rail declaration are present. + +## T02 - Add derived-rail conformance + +```task +id: RAIL-KNATIVE-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "095b9796-e274-4822-8559-d6f7ca9423eb" +``` + +Validate against `rail-kubernetes/schemas/derived-rail-v1.schema.json`. + +2026-07-26: The declared rail passes the base-rail conformance validator. + +## T03 - Add generic Knative templates and lifecycle tests + +```task +id: RAIL-KNATIVE-WP-0001-T03 +status: todo +priority: high +state_hub_task_id: "ffad44ca-394b-4092-90d7-fb9a070374c6" +``` + +Add generic Service, revision, traffic, scale, cold-start, and rollback +artifacts without Qonto-specific content. + +## T04 - Register and reconcile + +```task +id: RAIL-KNATIVE-WP-0001-T04 +status: todo +priority: medium +state_hub_task_id: "e3ca4415-f1c7-4839-bc13-b17f6497f71c" +``` + +Register in State Hub and Fabric, publish the base-rail relation, then create +and push the remote repository through an autonomous sanctioned lane.