From fff9d0c9fc69dfa59e9f6ab5e030b06636a85cc7 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 25 Jul 2026 15:42:53 +0200 Subject: [PATCH] Start rail/rapp/reef fabric adaptation --- AGENTS.md | 12 +- README.md | 8 ++ SCOPE.md | 25 ++-- WORK-RECORDS.md | 15 +++ catalog/capability-types.yaml | 12 ++ docs/declaration-schema.md | 23 ++++ docs/rail-rapp-reef-adaptation.md | 100 ++++++++++++++ docs/registry-onboarding.md | 4 + docs/type-catalog.md | 1 + registry/railiance-repos.yaml | 12 ++ ...P-0025-rail-rapp-reef-fabric-adaptation.md | 124 ++++++++++++++++++ 11 files changed, 321 insertions(+), 15 deletions(-) create mode 100644 WORK-RECORDS.md create mode 100644 docs/rail-rapp-reef-adaptation.md create mode 100644 workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md diff --git a/AGENTS.md b/AGENTS.md index f850b99..b3755b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,12 +2,12 @@ ## Repo Identity -**Purpose:** railiance-fabric - (fill in purpose) +**Purpose:** Railiance ecosystem graph, registry, and State Hub export model **Domain:** financials **Repo slug:** railiance-fabric **Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38` -**Workplan prefix:** `RAILIANCE-WP-` +**Workplan prefix:** `RAIL-FAB-WP-` --- @@ -169,10 +169,10 @@ get wrong. Work items originate as files in this repo — not in the hub. The hub is a read/cache/index layer that rebuilds from files. -**File location:** `workplans/RAILIANCE-WP-NNNN-.md` +**File location:** `workplans/RAIL-FAB-WP-NNNN-.md` **Archived location:** finished workplans may move to -`workplans/archived/YYMMDD-RAILIANCE-WP-NNNN-.md`. The `YYMMDD` prefix is +`workplans/archived/YYMMDD-RAIL-FAB-WP-NNNN-.md`. The `YYMMDD` prefix is the completion/archive date; the frontmatter `id` does not change. **Ad Hoc Tasks:** small opportunistic fixes discovered during a session use @@ -184,7 +184,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases. ```yaml --- -id: RAILIANCE-WP-NNNN +id: RAIL-FAB-WP-NNNN type: workplan title: "..." domain: financials @@ -208,7 +208,7 @@ derived health labels, not frontmatter statuses. ## Task Title ` ` `task -id: RAILIANCE-WP-NNNN-T01 +id: RAIL-FAB-WP-NNNN-T01 status: wait | todo | progress | done | cancel priority: high | medium | low state_hub_task_id: "" # written by fix-consistency — do not edit diff --git a/README.md b/README.md index ea27a04..d5428e3 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ Hub export contracts for services, machines, repositories, deployables, endpoints, ownership, dependencies, and bindings across Railiance deployment realities. +The current compatibility-first adaptation wave also prepares Fabric for the +new `rail-*`, `rapp-*`, and `reef-*` repo families so they can become visible +registry and graph entities instead of remaining architecture-only terms. + See `docs/FabricDiscoveryAndUpdate.md` for the current architecture direction for fabric boundaries, king/lord/tenant ownership, discovery, rebuilds, and update loops. @@ -120,6 +124,10 @@ onboarding manifest: railiance-fabric registry sync-manifest registry/railiance-repos.yaml ``` +That manifest should include the current ownership-family architecture repos +even when they do not yet publish local `fabric/` declarations. Registration is +still useful before full graph evidence exists. + To onboard every active State Hub repo with an available local checkout on this host: diff --git a/SCOPE.md b/SCOPE.md index f80a156..37b3e25 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -68,13 +68,17 @@ read model. ## Current State -- Status: active planning -- Implementation: intent and first workplan present -- Stability: evolving -- Usage: internal Railiance ecosystem modeling +- Status: active implementation +- Implementation: registry service, graph validation and query tooling, graph + explorer, State Hub export contract, financial-fabric reset flow, and local + onboarding manifests are all present +- Stability: evolving but operational +- Usage: internal Railiance ecosystem modeling, registry onboarding, and graph + export work -The first workplan is `RAIL-FAB-WP-0001`, which establishes vocabulary, schema, -seed examples, validator/query tooling, and State Hub integration. +The current adaptation wave for new Railiance repo families is +`RAIL-FAB-WP-0025`, which prepares the first compatibility-first Fabric support +for `rail-*`, `rapp-*`, and `reef-*`. --- @@ -116,9 +120,12 @@ seed examples, validator/query tooling, and State Hub integration. ## Getting Oriented -- Start with: `INTENT.md` -- Key files / directories: `workplans/` -- Entry points: `workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md` +- Start with: `README.md`, `INTENT.md` +- Key files / directories: `catalog/`, `fabric/`, `registry/`, `schemas/`, + `workplans/` +- Entry points: `docs/registry-onboarding.md`, + `docs/rail-rapp-reef-adaptation.md`, + `workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md` --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..e3e1b43 --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,15 @@ +# Work Records — railiance-fabric + +> 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-FAB-WP-0025 | active | — | workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md | +| task | RAIL-FAB-WP-0025-T01 | done | — | workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md | +| task | RAIL-FAB-WP-0025-T02 | done | — | workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md | +| task | RAIL-FAB-WP-0025-T03 | done | — | workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md | +| task | RAIL-FAB-WP-0025-T04 | wait | — | workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md | diff --git a/catalog/capability-types.yaml b/catalog/capability-types.yaml index e9122b4..1eb9e28 100644 --- a/catalog/capability-types.yaml +++ b/catalog/capability-types.yaml @@ -98,6 +98,18 @@ spec: - kubernetes-crd tags: [kubernetes, cluster, runtime] + - id: workload-execution-contract + name: Workload execution contract + lifecycle: planned + description: Publishes the rollout, runtime, and substrate-facing execution contract that managed workloads depend on. + default_criticality: high + default_data_classification: internal + expected_interface_types: + - kubernetes-api + - kubernetes-crd + - helm-release + tags: [runtime, rail, workload, contract] + - id: ci-cd-template-catalog name: CI/CD template catalog lifecycle: planned diff --git a/docs/declaration-schema.md b/docs/declaration-schema.md index 2e2f46f..1538ba6 100644 --- a/docs/declaration-schema.md +++ b/docs/declaration-schema.md @@ -87,6 +87,13 @@ Optional relationship fields: Schema: `schemas/service.schema.yaml` +Recommended compatibility-first `spec.service_type` values for the new +Railiance repo families are: + +- `execution-rail` +- `managed-workload-package` +- `substrate-boundary` + ### CapabilityDeclaration A stable semantic ability that consumers depend on. @@ -163,6 +170,22 @@ Schema: `schemas/dependency.schema.yaml` type catalogs. Unknown types are allowed by the document schema but should fail graph validation. +## Repository-Family Starter Guidance + +Until stronger repo-family metadata exists in registry and export projections, +future repo-local declarations should start with these minimal shapes: + +- `rail-*`: one `ServiceDeclaration` using `spec.service_type: + execution-rail`, plus one `CapabilityDeclaration` using + `spec.capability_type: workload-execution-contract` +- `rapp-*`: one `ServiceDeclaration` using `spec.service_type: + managed-workload-package` +- `reef-*`: one `ServiceDeclaration` using `spec.service_type: + substrate-boundary` + +This is a compatibility-first convention, not a claim that the full repo-family +graph model is complete. + ### BindingAssertion A source-controlled assertion that resolves a dependency to a provider diff --git a/docs/rail-rapp-reef-adaptation.md b/docs/rail-rapp-reef-adaptation.md new file mode 100644 index 0000000..64a129f --- /dev/null +++ b/docs/rail-rapp-reef-adaptation.md @@ -0,0 +1,100 @@ +# Rail Rapp Reef Adaptation + +Date: 2026-07-25 + +## Purpose + +Define the first compatibility-first Fabric conventions for the new +`rail-*`, `rapp-*`, and `reef-*` repo families without pretending the registry +or export model is already fully adapted. + +This document is intentionally narrower than the framework architecture in +`railiance-master`. It answers one question: + +> What should Fabric accept and publish first so the new repo families can +> start existing as graph entities? + +## Immediate Compatibility Stance + +The first adaptation wave is deliberately small: + +- onboard the missing current Railiance repos in the seed manifest +- add the first rail-specific capability type +- define canonical `service_type` values for future declarations +- avoid inventing full repo-family metadata or new export relations before the + first repos exist + +This keeps Fabric aligned with the architecture without forcing a premature +schema redesign. + +## Canonical First-Use Conventions + +### `rail-*` + +Initial Fabric shape: + +- one `ServiceDeclaration` with `spec.service_type: execution-rail` +- one `CapabilityDeclaration` with + `spec.capability_type: workload-execution-contract` + +Typical evidence should describe: + +- the execution architecture +- substrate prerequisites +- rollout modes or workload lifecycle expectations +- which ownership repo governs the rail + +### `rapp-*` + +Initial Fabric shape: + +- one `ServiceDeclaration` with `spec.service_type: managed-workload-package` + +Optional follow-on declarations may later capture runtime dependencies, +verification interfaces, or artifact evidence, but the first requirement is +simply to make the package queryable as a distinct ecosystem entity. + +### `reef-*` + +Initial Fabric shape: + +- one `ServiceDeclaration` with `spec.service_type: substrate-boundary` + +The first declarations should make the substrate boundary visible before Fabric +tries to model every machine or placement relation in detail. + +## First New Capability Type + +Fabric now reserves: + +- `workload-execution-contract` + +Meaning: + +- a stable execution contract that workloads depend on +- usually published by a `rail-*` repo +- expected to expose Kubernetes-, rollout-, or runtime-facing interfaces over + time + +This is intentionally rail-focused. `rapp-*` and `reef-*` can start with +service-level visibility before they need their own dedicated capability types. + +## What Is Still Missing + +The following are not done by this adaptation slice: + +- repo-level `repo_family` metadata in the registry +- `ownership_repo`, `supported_rails`, `primary_rail`, or `substrate_kind` + registry metadata +- export relations such as `supports_rail`, `hosts_rail`, `binds_rapp`, or + `governed_by` +- validator rules for repo-family-specific declaration completeness + +Those require a second wave after the first real `rail-*`, `rapp-*`, and +`reef-*` repos exist. + +## Outcome + +Fabric can now move from "the new repo families exist only in architecture +docs" to "the registry and declaration guidance are ready for the first repo +instances" without overcommitting to a premature graph redesign. diff --git a/docs/registry-onboarding.md b/docs/registry-onboarding.md index ab85019..35c51ed 100644 --- a/docs/registry-onboarding.md +++ b/docs/registry-onboarding.md @@ -54,6 +54,10 @@ repositories: `declaration_paths` is optional; when omitted, the repo path is scanned for a `fabric/` directory. Relative paths are resolved from the manifest file. +`state_hub_repo_id` is optional. Include it when known so registry consumers can +link back to State Hub repo views, but do not block onboarding when a repo is +registered in Fabric before that ID is wired in here. + `sbom` or `sboms` may point to CycloneDX JSON/YAML files. When present, the command ingests them as queryable library inventory after repository registration. diff --git a/docs/type-catalog.md b/docs/type-catalog.md index 3552062..77cec7a 100644 --- a/docs/type-catalog.md +++ b/docs/type-catalog.md @@ -25,6 +25,7 @@ Machine-readable catalog files: | `redis-compatible-cache` | active | medium | internal | `database-connection`, `kubernetes-secret` | | `object-storage` | planned | high | confidential | `object-storage-bucket`, `http-api` | | `object-storage-credential-vending` | planned | high | secret | `http-api`, `openbao-dynamic-credential-role`, `sts-token` | +| `workload-execution-contract` | planned | high | internal | `kubernetes-api`, `kubernetes-crd`, `helm-release` | | `audit-event-sink` | planned | high | confidential | `event-stream`, `http-api` | | `scope-generation` | active | medium | internal | `cli`, `http-api` | | `coordination-read-model` | active | high | internal | `http-api`, `event-stream` | diff --git a/registry/railiance-repos.yaml b/registry/railiance-repos.yaml index 36e3da5..bdc8a38 100644 --- a/registry/railiance-repos.yaml +++ b/registry/railiance-repos.yaml @@ -10,6 +10,18 @@ repositories: declaration_paths: - .. + - slug: railiance-master + name: railiance-master + path: /home/worsch/railiance-master + remote_url: forgejo-remote:coulomb/railiance-master.git + default_branch: main + + - slug: railiance-forge + name: railiance-forge + path: /home/worsch/railiance-forge + remote_url: forgejo-remote:coulomb/railiance-forge.git + default_branch: main + - slug: railiance-infra name: railiance-infra path: /home/worsch/railiance-infra diff --git a/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md b/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md new file mode 100644 index 0000000..ad99956 --- /dev/null +++ b/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md @@ -0,0 +1,124 @@ +--- +id: RAIL-FAB-WP-0025 +type: workplan +title: "Rail Rapp Reef Fabric Adaptation" +domain: financials +repo: railiance-fabric +status: active +owner: codex +topic_slug: railiance +created: "2026-07-25" +updated: "2026-07-25" +state_hub_workstream_id: "e6080e39-d60c-4a29-bc1f-adf1875461b2" +--- + +# RAIL-FAB-WP-0025 - Rail Rapp Reef Fabric Adaptation + +## Goal + +Adapt `railiance-fabric` so the new `rail-*`, `rapp-*`, and `reef-*` repo +families can become visible ecosystem entities in the registry and graph model, +instead of remaining naming conventions documented only in `railiance-master`. + +This follows: + +- `/home/worsch/railiance-master/docs/fabric-state-hub-adaptation.md` +- `/home/worsch/railiance-master/docs/repository-axes.md` + +## Boundaries + +This workplan may: + +- update repo-local documentation and workplan conventions +- update onboarding manifests +- extend compatibility-first Fabric vocabulary and declaration guidance +- define the next implementation gaps for registry and graph support + +It must not: + +- invent full `rail-*`, `rapp-*`, or `reef-*` declarations before those repos + exist +- redesign the financial Fabric model just to accommodate repo-family rollout +- treat repo-family metadata as done before registry and export support exist + +## T01 - Fix Fabric repo-local orientation for the adaptation wave + +```task +id: RAIL-FAB-WP-0025-T01 +status: done +priority: high +state_hub_task_id: "5424575c-4dc8-45d2-bfb5-623a32114962" +``` + +Bring the live repo docs in line with actual repository maturity and the local +workplan prefix so the new adaptation work lands on the real repo shape. + +Done when `SCOPE.md`, `AGENTS.md`, and orientation docs no longer describe +Fabric as only early planning with `RAILIANCE-WP-*` workplans. + +2026-07-25: Updated `SCOPE.md` and `AGENTS.md` to reflect current registry, +validator, and graph-explorer maturity, and corrected the local workplan +prefix to `RAIL-FAB-WP-*`. + +## T02 - Onboard missing Railiance architecture repos in the seed manifest + +```task +id: RAIL-FAB-WP-0025-T02 +status: done +priority: high +state_hub_task_id: "d8a5db60-f8ce-4c86-80a5-21eef6b85f5f" +``` + +Add the missing architecture-home and forge repos to the Railiance onboarding +manifest so registry sync can see the full current ownership family before new +repo families are introduced. + +Done when `registry/railiance-repos.yaml` includes `railiance-master` and +`railiance-forge`. + +2026-07-25: Added `railiance-master` and `railiance-forge` to +`registry/railiance-repos.yaml`. + +## T03 - Publish the first compatibility-first Fabric vocabulary for rails + +```task +id: RAIL-FAB-WP-0025-T03 +status: done +priority: high +state_hub_task_id: "6067ab7d-a9cb-4db3-8a01-f910f3142728" +``` + +Record the minimum graph conventions future `rail-*`, `rapp-*`, and `reef-*` +repos should use before stronger first-class schema support exists. + +Done when Fabric has a documented first-use convention for: + +- `execution-rail` +- `managed-workload-package` +- `substrate-boundary` +- `workload-execution-contract` + +2026-07-25: Added `workload-execution-contract` to the capability catalog and +documented the initial declaration guidance in +`docs/rail-rapp-reef-adaptation.md`, `docs/declaration-schema.md`, and +`docs/type-catalog.md`. + +## T04 - Define the follow-on registry and export gaps + +```task +id: RAIL-FAB-WP-0025-T04 +status: wait +priority: medium +state_hub_task_id: "dbfd3000-0204-473e-b1b8-eeb44d3fcd06" +``` + +Blocked on T01-T03. + +Define the next implementation slice for: + +- repo-family-aware registry metadata +- rail or reef relation projection +- State Hub export extensions needed for repo-family visibility + +Done when the next repo-local implementation wave can start without reopening +the compatibility-first vocabulary decisions above.