diff --git a/.gitignore b/.gitignore index 1367fc7..835ec76 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,9 @@ __pycache__/ .venv/ .runtime/ .evidence-private/ + +# state-hub: track .claude/rules +# Claude Code local state (track shared rules; ignore machine-specific files) +.claude/* +!.claude/rules/ +!.claude/rules/*.md diff --git a/README.md b/README.md index d0e056c..5180a86 100644 --- a/README.md +++ b/README.md @@ -18,5 +18,7 @@ in the Coulomb Forgejo organization; repository registration does not admit a ru - [0003 — Reference implementation](workplans/RCLK-WP-0003-reference-implementation.md) - [0004 — Deployment and consumer adoption](workplans/RCLK-WP-0004-deployment-adoption.md) +- [0005 — Infrastructure as code](workplans/RCLK-WP-0005-infrastructure-as-code.md) + No installation is required to review these documents. Runtime commands and examples will be added only with their implementation and verification. diff --git a/SCOPE.md b/SCOPE.md index 0414fb4..9a3e506 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -25,3 +25,7 @@ The local specification proposes a contract. RCLK-WP-0002 owns cross-repository review before its security use. RCLK-WP-0003 owns reference implementation and RCLK-WP-0004 owns admitted deployment and consumer evidence. Statehub indexes source records; it is not a time source. Forgejo hosts records, not a UTC oracle. + +RCLK-WP-0005 explicitly owns IaC setup, host discipline, authority packaging, +bootstrap sequencing, native deployment and operational handoff. Bootstrap calls +owner automation; ongoing configuration remains in S1 and workload owners. diff --git a/docs/ecosystem.md b/docs/ecosystem.md index 2e7b25a..79795a0 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -6,7 +6,7 @@ production admission or owner assent. | Concern | Existing owner / intended interaction | | --- | --- | | Railiance repository/runtime architecture | railiance-master; confirm source ownership and future rapp/reef packaging | -| Initial authority host | railiance-hosts / railiance-platform / reef-railiance; confirm operational responsibility and UTC discipline | +| Initial authority host | railiance-infra S1 (resolve inherited railiance-hosts source) / platform / reef-railiance; see infrastructure.md | | Source/history | Coulomb organization on Forgejo, operated through railiance-forge; retain policy/source/evidence without assigning clock truth to Git dates | | Shared discovery/work records | Repo Manager + primary Statehub; derive exact pushed source and stable identifiers | | Security architecture | net-kingdom / gate-house; review layer role and trust/validity semantics | @@ -46,8 +46,10 @@ The role declaration is a named RCLK-WP-0002 task, not implied compliance. repo-manager/the-custodian and initial consumers. Store returned message IDs. Request prefix-index reservation and ownership review, without claiming assent. 6. Record final registration receipt in docs/registration.md. Foundation can finish - because implementation/review/deployment residuals already live in 0002–0004. + because implementation/review/deployment residuals already live in 0002–0005. The Coulomb source location and common discovery entry establish ecosystem visibility. Railiance production admission and NetKingdom security adoption remain unresolved until their owners return evidence under RCLK-WP-0002/0004. + +Infrastructure source ownership and bootstrap ordering: [IaC placement](infrastructure.md), tracked by RCLK-WP-0005. diff --git a/docs/infrastructure.md b/docs/infrastructure.md new file mode 100644 index 0000000..1ffff72 --- /dev/null +++ b/docs/infrastructure.md @@ -0,0 +1,55 @@ +# Infrastructure as code and bootstrap placement + +Status: reviewed planning recommendation, 2026-09-14; owner assent and live +implementation are tracked in RCLK-WP-0005. No infrastructure is deployed by seed. + +## Recommended split + +| Concern | Source/operation owner | Bootstrap responsibility | +| --- | --- | --- | +| Host UTC daemon, upstreams, OS baseline, health adapter | railiance-infra S1; resolve inherited railiance-hosts source before editing | Invoke owner convergence before time-sensitive higher layers | +| Cluster/network substrate | railiance-cluster and reef-railiance | Sequence their existing prerequisite gates | +| Application-clock source and contract | railiance-clock | Consume a published version; do not embed a second implementation | +| Workload packaging and placement | Reviewed rapp package / rail-kubernetes / reef-railiance | Invoke admitted deployment after prerequisites | +| Keys, identity, TLS and rotation | Existing platform/NetKingdom owners | Use declared bootstrap trust and retire temporary material | +| UTC quality and operational alerts | Clock operator with railiance-telemetry | Verify and hand off; do not keep operating after bootstrap | + +The current railiance-bootstrap INTENT says it sequences a new estate and hands +off, and explicitly excludes ongoing operations and S1 OS baseline ownership. +railiance-infra owns the declarative substrate. railiance-hosts still contains +historical S1 content; T01 must settle the actual canonical source rather than +copy it. railiance-master owns that boundary decision. + +## Practical deployment choice + +Keep host UTC discipline at host level. Prefer a non-privileged application time +service on the estate's default rail-kubernetes, privately placed on railiance01's +reef. It reports an estimate and host-quality evidence; it never sets host time. +An early host daemon/service alternative must explain its bootstrap advantage, +owned unit/package/config IaC and later handoff. Creating a new execution rail +merely for this small service is not the default. + +The role of Forgejo is committed configuration and audit/review history. Basic +external UTC and transport trust must already work before fetching protected +source, bootstrapping secrets or obtaining Railiance application time. Document +any attended bootstrap action and how it is retired; do not create a circular +clock -> TLS -> secret -> clock prerequisite. + +## Required IaC delivery evidence + +All durable resources and configuration must derive from versioned owner source: +parameterized target inventory, upstream policy, daemon settings, workload manifests, +trust delivery references, exposure/network rules, resources, probes and monitoring. +Secret material stays in admitted custody, not in source or rendered evidence. + +Require preflight/render, exact reviewed diff, scoped apply, live readback, +idempotent reconvergence, drift detection, disposable rebuild and rollback proof. +Every live result names source revision, target, artifact digest and observed time +quality. A temporary emergency correction is evidence to reconcile back into +source, never the completed implementation. Avoid recording unrelated secrets or +assuming read-only health means the clock is accurate. + +RCLK-WP-0005 covers infrastructure setup and operational handoff. RCLK-WP-0004 +covers consumer migration and measured acceptance. Fresh-estate bootstrap includes +clock ordering; an existing railiance01 upgrade uses the steady-state owner path, +not a rerun of whole-estate bootstrap. diff --git a/workplans/RCLK-WP-0001-foundation.md b/workplans/RCLK-WP-0001-foundation.md index 591fd89..2a26e47 100644 --- a/workplans/RCLK-WP-0001-foundation.md +++ b/workplans/RCLK-WP-0001-foundation.md @@ -11,7 +11,7 @@ created: "2026-09-14" updated: "2026-09-14" --- -Seed requested by the operator. Runtime and cross-owner adoption are deliberately future work in RCLK-WP-0002–0004. +Seed requested by the operator. Runtime and cross-owner adoption are deliberately future work in RCLK-WP-0002–0005. ## Establish founding intent and specification @@ -31,7 +31,7 @@ status: done priority: high ``` -Create live 0002–0004 workplans with acceptance gates and dependencies. No unfinished implementation is hidden in a finished foundation plan. +Create live 0002–0005 workplans with acceptance gates and dependencies. No unfinished implementation is hidden in a finished foundation plan. ## Register and verify ecosystem discovery diff --git a/workplans/RCLK-WP-0004-deployment-adoption.md b/workplans/RCLK-WP-0004-deployment-adoption.md index d722665..f1c032a 100644 --- a/workplans/RCLK-WP-0004-deployment-adoption.md +++ b/workplans/RCLK-WP-0004-deployment-adoption.md @@ -11,6 +11,7 @@ created: "2026-09-14" updated: "2026-09-14" depends_on_workplans: - RCLK-WP-0003 + - RCLK-WP-0005 --- Native operation is a separate production-admission decision. This plan also owns explicit later-scale scope so foundation has no untracked residuals. @@ -23,7 +24,7 @@ status: wait priority: high ``` -Depends on 0002/0003. Obtain reviewed rapp/reef placement, host UTC health/error evidence, private exposure, resource budget, signing trust custody and monitoring. Existing owner authorities apply; repository registration grants none of these. +Consume RCLK-WP-0005 infrastructure placement, custody, health and exact-source deployment receipts. Verify they satisfy the adopted 0002/0003 contract before consumer pilot. Infrastructure implementation belongs to 0005 and its owner records, not a duplicate apply here. ## Measure and verify the native authority/client pilot diff --git a/workplans/RCLK-WP-0005-infrastructure-as-code.md b/workplans/RCLK-WP-0005-infrastructure-as-code.md new file mode 100644 index 0000000..47ed059 --- /dev/null +++ b/workplans/RCLK-WP-0005-infrastructure-as-code.md @@ -0,0 +1,143 @@ +--- +id: RCLK-WP-0005 +type: workplan +title: "Deploy clock infrastructure through owner-managed infrastructure as code" +domain: infotech +repo: railiance-clock +status: ready +owner: codex +topic_slug: custodian +created: "2026-09-14" +updated: "2026-09-14" +related_workplans: + - RCLK-WP-0002 + - RCLK-WP-0003 + - RCLK-WP-0004 +--- + +Operator-requested infrastructure plan. Read docs/infrastructure.md. This plan +tracks the cross-owner delivery outcome; each owning repository holds its actual +IaC and any required child work records. Inventory and ownership work can begin +now. Live service deployment depends on the reviewed protocol and built artifact. +Production applies require concrete owner admission, not just this plan's existence. + +## Confirm current host state and canonical IaC ownership + +```task +id: RCLK-WP-0005-T01 +status: todo +priority: high +``` + +Inspect railiance01 time sources/daemon, synchronization health, virtualization, +network egress, permissions and existing IaC without fetching secrets or changing +time. Resolve railiance-infra versus inherited railiance-hosts implementation +ownership with railiance-master; select one canonical baseline and reference it. +Record target inventory, responsibility, current drift and gaps. Create/link owner +work records before handing off any execution; no duplicate configuration trees. + +Acceptance: reviewed source-path/owner matrix, live read-only inventory receipt, +explicit adoption of existing settings or a bounded source diff; no second daemon. + +## Implement declarative host UTC discipline and verification + +```task +id: RCLK-WP-0005-T02 +status: wait +priority: high +``` + +Depends on T01 and RCLK-WP-0002's UTC/leap/quality contract. In the S1 owner, +version the selected existing/supported NTP client, independent upstream selection, +network requirements, boot/restart behavior, holdover limits, drift monitoring and +health export. Prefer existing supported automation over inventing a new daemon. +Do not mix timesyncd/chrony or smeared/unsmeared sources. Restrict listeners; a +server NTP offering is optional and separately justified, not an implicit public +UDP/123 endpoint. Do not modify attached corporate workstation clock policy. + +Acceptance: lint/render and convergence check; idempotent second apply; reboot +and upstream-loss/recovery proof in disposable infrastructure; exact target diff, +rollback procedure and owner review before live convergence. Service liveness +alone does not prove bounded UTC accuracy. + +## Package private authority service and admitted trust delivery + +```task +id: RCLK-WP-0005-T03 +status: wait +priority: high +``` + +Depends on adopted RCLK-WP-0002 trust contract and RCLK-WP-0003 artifact. Use +rail-kubernetes on reef-railiance as the initial packaging candidate; create the +reviewed rapp/deployable declarations under the architecture owner's conventions. +A documented host-service alternative is allowed only if bootstrap dependencies +or measured constraints justify it. The clock app reads host time/health but must +not obtain CAP_SYS_TIME, privileged host access or a host clock-write interface. + +Declare immutable image/build pins, namespace/service identity, private exposure, +network policy, resource requests/limits, health versus usability probes, TLS and +sample-signing key delivery/rotation via admitted owners, non-secret config, +monitoring and state-retention/epoch behavior. No secret values in Git, no raw +kubectl patches or console-created persistent resources as the desired state. + +Acceptance: IaC rendered/validated by native tools, deployment admission and +trust bootstrap reviewed, least-privilege and no-redirect tests, config/source +hashes and exact deployment/rollback plan. Fail if dynamic trust resolution needs +usable Railiance time before the first sample with no independent bootstrap path. + +## Integrate the clock prerequisite into the new-estate bootstrap path + +```task +id: RCLK-WP-0005-T04 +status: wait +priority: high +``` + +Coordinate with railiance-bootstrap after T01 establishes owners. Add ordering: +S1 obtains usable external UTC and basic transport trust; S2/S3 bring up the +required substrate and admitted custody; the authority service is deployed; +protected consumers start only after usable time/identity evidence. Bootstrap +invokes pinned owner automation and verifies its receipts; it does not copy host +roles or retain ongoing clock operation. The external UTC prerequisite must not +require the not-yet-created Forgejo, OpenBao, cluster or clock endpoint. + +Acceptance: fresh-estate rehearsal, existing-estate upgrade path, explicit manual +bootstrap actions and retirement, failed-time gate, versioned handoff to steady +state owners. No unsupported claim that corporate workstations can be converged. + +## Deploy on railiance01 and prove drift, recovery and rollback + +```task +id: RCLK-WP-0005-T05 +status: wait +priority: high +``` + +Depends on T02/T03 readiness and specific live owner authorization. Apply the +reviewed source revision through its normal owner pipeline. Keep clock steps +and effects on existing token consumers within the reviewed rollout window. +Read back daemon configuration, image digest, service/identity/network state and +usable UTC interval. Verify an independently managed workstation obtains a sample +without changing OS clocks. Exercise upstream outage, restart, revoked signing +trust and rollback through safe rehearsals and the approved native scope. + +Acceptance: exact-commit render/apply/readback receipts; repeated convergence is +no-op; drift detection catches a disposable config change; rebuild from committed +source succeeds; rollback restores known-good configuration without falsely +restoring old epochs/trust. No unnoticed unrelated resource or credential changes. + +## Transfer operational responsibility and gate consumer adoption + +```task +id: RCLK-WP-0005-T06 +status: wait +priority: high +``` + +Deliver alert ownership, quality/error budgets, backup/recovery and key-rotation +runbooks, source locations, pipeline/placement identifiers and native evidence to +railiance-telemetry/platform and RCLK-WP-0004. Document what remains single-host. +Keep all unresolved work as live records before finishing this plan. RCLK-WP-0004 +may adopt a protected consumer only after this infrastructure gate AND its own +explicit consumer review/negative tests pass. A deployed endpoint is not a grant.