Start rail/rapp/reef fabric adaptation
This commit is contained in:
codex
parent
488a7bbf42
commit
fff9d0c9fc
11 changed files with 321 additions and 15 deletions
12
AGENTS.md
12
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-<slug>.md`
|
||||
**File location:** `workplans/RAIL-FAB-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** finished workplans may move to
|
||||
`workplans/archived/YYMMDD-RAILIANCE-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
|
||||
`workplans/archived/YYMMDD-RAIL-FAB-WP-NNNN-<slug>.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: "<uuid>" # written by fix-consistency — do not edit
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
25
SCOPE.md
25
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`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
15
WORK-RECORDS.md
Normal file
15
WORK-RECORDS.md
Normal file
|
|
@ -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 |
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
100
docs/rail-rapp-reef-adaptation.md
Normal file
100
docs/rail-rapp-reef-adaptation.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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` |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
124
workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md
Normal file
124
workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue