From bea7a0cf925005749ba149251c643f0be38fc5f8 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 16 May 2026 00:29:39 +0200 Subject: [PATCH] Established repo intent --- INTENT.md | 485 +++++++++ README.md | 4 +- wiki/HelixForgeVision.md | 29 + wiki/OrthogonalArchitectureSchema.md | 1470 ++++++++++++++++++++++++++ 4 files changed, 1985 insertions(+), 3 deletions(-) create mode 100644 INTENT.md create mode 100644 wiki/HelixForgeVision.md create mode 100644 wiki/OrthogonalArchitectureSchema.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..bbfb491 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,485 @@ +\--- + +project: helix-forge +product: HelixForge +status: draft +intent\_version: 0.1.0 +date: 2026-05-15 +standard: OrthogonalArchitectureStandard +standard\_version: 1.0.1 +architecture\_framework: Viable Systems Model inspired Orthogonal Architecture Dimensions +--- + +# INTENT.md — helix-forge + +> \*\*HelixForge envisions a world where software capabilities evolve with understanding, not guesswork.\*\* + +## 1\. Repository intent + +`helix-forge` exists to make **HelixForge** executable: a capability-first development ecosystem where real-world demands are discovered in natural language, shaped into reusable software capabilities, and delivered through validated architecture and implementation artifacts. + +HelixForge treats software creation as a forge rather than a factory. A capability is not merely coded; it is refined through dialogue, structural modeling, validation, implementation, feedback, and reuse. The repository should therefore preserve both strands of the HelixForge double helix: + +1. **Human understanding** — discovery, intent, problem framing, language, ownership, value, and fitness. +2. **Executable precision** — contracts, schemas, validators, services, tests, automation, governance, and runtime evidence. + +The purpose of this repository is to turn intent into structure, structure into capability, and capability into lasting progress. + +## 2\. Vision alignment + +HelixForge empowers a global ecosystem of users, builders, and investors to collaboratively forge reusable software capabilities from real-world problems. It intertwines the natural-language art of discovery with the precise science of delivery, accumulating a battle-tested repository of composable intelligence that accelerates innovation for all. + +This repository should advance that vision by ensuring that every meaningful contribution can answer the following questions: + +* **What human or organizational intent does this serve?** +* **What reusable capability does it strengthen or create?** +* **Where does it belong in the Orthogonal Architecture Dimensions?** +* **Which Viable Systems Model function does it support?** +* **How is its correctness, safety, and usefulness validated?** +* **How does it improve the capability repository rather than merely add code?** + +## 3\. Operating thesis + +HelixForge is built on the belief that software capabilities evolve best when discovery and delivery are part of one continuous system. + +Discovery without delivery produces insight that may never become useful. Delivery without discovery produces software that may work but may not matter. HelixForge connects them through an architecture-aware process where demands mature into capabilities, capabilities become contracts and realizations, and realizations are validated against both human intent and machine-checkable standards. + +The repository should therefore prefer work that: + +* explores problems before prescribing solutions; +* captures capability intent before implementation detail; +* expresses architecture using controlled vocabulary; +* keeps independent dimensions orthogonal instead of mixing concerns; +* uses executable schemas and semantic rules as truth-bearing artifacts; +* treats AI assistance as governed, observable, and architecturally placed; +* improves reuse, composability, and accumulated capability value. + +## 4\. Primary outcomes + +The repository is successful when it supports these outcomes: + +### 4.1 Capability discovery + +HelixForge must help users, builders, and investors describe problems, demands, constraints, and opportunities in natural language while progressively clarifying scope, ownership, value, and architectural fit. + +### 4.2 Capability modeling + +HelixForge must model capabilities as stable architectural units. A capability should have a purpose, boundary, contract, quality expectations, ownership, and relationship to other capabilities. + +### 4.3 Capability realization + +HelixForge must support implementation artifacts that realize capabilities through services, applications, platform services, integrations, automations, data stores, policies, and intelligence components. + +### 4.4 Capability validation + +HelixForge must validate architecture descriptions structurally and semantically using the Orthogonal Architecture Standard and its semantic rule profile. + +### 4.5 Capability evolution + +HelixForge must preserve feedback, learning, and architectural evidence so that capabilities improve through use rather than merely accumulate as static assets. + +## 5\. Architectural foundation + +HelixForge uses the **Orthogonal Architecture Standard** and an **OAS-compatible Orthogonal Architecture Dimensions information architecture**. The standard describes architectures as elements, placements, relations, principles, sources, and metadata. + +The architectural foundation has three layers: + +1. **Controlled vocabulary** — stable codes, names, verbs, and explanations for architecture dimensions and viable-system functions. +2. **Structural validation** — JSON Schema validation for the shape of architecture documents. +3. **Semantic validation** — architectural rules that check whether the model is meaningful, not merely syntactically valid. + +The current standard reference is **Orthogonal Architecture Standard Schema v1.0.1**. Architecture documents should use: + +```yaml +standard: OrthogonalArchitectureStandard +version: "1.0.1" +``` + +## 6\. Orthogonal Architecture Dimensions + +HelixForge uses six independent dimensions. A single architectural element may be placed in multiple dimensions, but each placement must remain clear about which concern it expresses. + +> Vocabulary note: the codes, short labels, verbs, and explanations are taken from the current OAD workbook. Minor obvious spelling is normalized in this prose, while the controlled codes remain unchanged. + +### 6.1 Plane dimension + +The Plane dimension describes operational responsibility. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|P|Plane|Plane Dimension|reign|Operational responsibility|—| +|P1|Workload|Workload Plane|operate|Contains operational services and applications|—| +|P2|Control|Control Plane|control|Maintains system state|Kubernetes control plane, GitOps controllers, policy engines, platform APIs| +|P3|Management|Management Plane|manage|Provides administrative interfaces|CLI tools, web portals, automation scripts, audit reporting| + +### 6.2 Stack dimension + +The Stack dimension describes the technical hosting substrate. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|S|Stack|Stack Dimension|implement|Technical hosting substrate|—| +|S1|Infrastructure|Infrastructure Substrate|carry|Defines the physical or cloud infrastructure|Cloud accounts, network foundations, compute nodes, operating systems, container runtimes| +|S2|Runtime|Cluster Runtime|run|Defines the orchestration runtime|Kubernetes scheduler, service discovery, ingress, admission controllers, service mesh, operators| +|S3|Services|Platform Services|service|Shared services supporting workloads|Databases, message brokers, caches, object storage, secret management, identity systems| +|S4|Enablement|Developer Enablement|enable|Tools that allow system evolution|CI/CD pipelines, developer portals, platform templates, SDKs, buildpacks| +|S5|Workloads|Workloads \& Experience Endpoints|apply|Functional applications delivering value|APIs, web frontends, workers, integration endpoints, administrative interfaces| + +### 6.3 Quality dimension + +The Quality dimension describes cross-cutting architectural qualities. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|Q|Quality|Quality Dimension|qualify|Defines cross-cutting architectural qualities|—| +|Q1|Compliance|Security \& Compliance|secure|Identity, access control, compliance|—| +|Q2|Observability|Observability|observe|Telemetry and monitoring|Metrics, logs, traces| +|Q3|Resilience|Resilience \& Operability|stabilize|Deployment, scaling, and disaster recovery|—| +|Q4|Isolation|Isolation \& Tenancy|isolate|Workload separation strategies|—| +|Q5|Performance|Performance \& Scalability|improve|Latency, throughput, and scaling|—| +|Q6|Efficiency|Cost \& Efficiency|optimize|Resource optimization|—| +|Q7|Governance|Governance \& Change|govern|Policies and architecture governance|—| + +### 6.4 Logic dimension + +The Logic dimension describes functional decomposition. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|L|Logic|Logic Dimension|structure|Functional decomposition|—| +|L1|Domain|Capability Domain|define|Defines stable functional areas|Billing, identity, catalog, order management| +|L2|Realization|Service Realization|realize|Implementation of capabilities|APIs, worker services, event processors, adapters| +|L3|Composition|Composition \& Integration|compose|Defines orchestration between services|Workflow engines, orchestration pipelines, API gateways, integration pipelines| +|L4|Solution|Solution Layer|solve|End-user solutions and applications|SaaS products, internal systems, partner solutions| + +### 6.5 Intelligence dimension + +The Intelligence dimension describes assisted system behavior. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|I|Intelligence|Intelligence Dimension|automate|Defines assisted system behavior|—| +|I1|Deterministic|Deterministic Automation|script|Scripts and rule engines|—| +|I2|Language|Language Interaction|prompt|Natural language interfaces|—| +|I3|Reasoning|Knowledge \& Reasoning|reason|Semantic processing and recommendation systems|—| +|I4|Fitting|Assisted Fitting \& Adaptation|fit|AI-assisted system configuration|—| +|I5|Agents|Agentic Delegation|delegate|Autonomous AI agents acting within governance policies|—| + +### 6.6 Capability dimension + +The Capability dimension describes capabilities as stable architectural units. + +|Code|Short|Name|Verb|Explanation|Examples| +|-|-|-|-|-|-| +|C|Capability|Capability Dimension|define|Defines capabilities as stable architectural units|—| +|C1|Model|Capability Model|model|Defines purpose, scope, ownership|—| +|C2|Contract|Capability Contract|contract|Defines interfaces|APIs, events, SLOs| +|C3|Implementation|Capability Implementation|implement|Technical implementations|Services, databases, workflows| +|C4|Reusables|Shared Platform Capabilities|reuse|Platform-level services|Identity, messaging, observability| +|C5|Business|Business Capabilities|business|Business functionality|Billing, onboarding, support| + +## 7\. Viable Systems Model inspired information architecture + +HelixForge uses a Viable Systems Model inspired subsystem vocabulary to describe what each architectural element does for the living system. These VSM-inspired functions should be used to classify capabilities, elements, relations, validation rules, and repository concerns. + +Code context matters: the Stack dimension uses `S1` through `S5` as placement levels, while VSM also uses `System 1` through `System 5` as viable-system tags. Use OAD codes inside dimensional `placements`; use VSM mappings inside OAS `vsm\_tags`. The workbook abbreviations such as `OPS`, `SYN`, and `CTL` are vocabulary labels; they do not replace the OAS `vsm\_tags` enum. `ENV` describes boundary/environment concerns and should be represented through metadata or an explicit extension if it is used outside the current OAS enum. + +|Code|Short|Name|Verb|Explanation|VSM mapping| +|-|-|-|-|-|-| +|OPS|Operations|Operations \& Activities|does|Do the primary work|System 1| +|SYN|Synchronization|Synchronization \& Coordination|aligns|Prevent friction, oscillation, and local conflict|System 2| +|CTL|Control|Internal Control \& Regulation|governs|Manage current performance, resources, priorities, and constraints|System 3| +|AUD|Audit|Audit \& Monitoring|verifies|Check what is really happening|System 3\*| +|INT|Intelligence|Intelligence \& Adaptation|scans|Sense the environment and future|System 4| +|POL|Policy|Policy \& Identity|defines|Define identity, values, and ultimate direction|System 5| +|ENV|Environment|Boundary \& Surface|interacts|Provides interfaces, adapters, sensors, and actors|Environment| + +### 7.1 VSM usage intent + +* **OPS** marks the operational work of software capabilities and runtime value delivery. +* **SYN** marks coordination mechanisms that reduce friction between capabilities, services, teams, or workflows. +* **CTL** marks internal control, resource regulation, policy enforcement, and current-state management. +* **AUD** marks observability, monitoring, evidence collection, and independent checking. +* **INT** marks sensing, forecasting, learning, reasoning, adaptation, and future-state exploration. +* **POL** marks identity, direction, governance, values, and ultimate constraints. +* **ENV** marks the boundary between HelixForge and users, external systems, markets, investors, builders, and real-world problem contexts. + +## 8\. OAS model commitments + +Architecture descriptions in `helix-forge` should be compatible with the Orthogonal Architecture Standard. + +### 8.1 Architecture documents + +An OAS architecture document should contain: + +* `standard` — the constant `OrthogonalArchitectureStandard`; +* `version` — a semantic version string; +* `architecture.id` — a stable identifier; +* `architecture.name` — a human-readable architecture name; +* `architecture.description` — an explanation of architectural purpose; +* `architecture.dimensions` — the six Orthogonal Architecture Dimensions; +* `architecture.elements` — capability, service, platform, policy, automation, and intelligence elements; +* `architecture.relations` — typed relationships between elements; +* `architecture.principles` — architectural principles relevant to the model; +* `architecture.sources` — source references when applicable; +* `architecture.metadata` — tool and repository metadata. + +### 8.2 Element types + +OAS-compatible element types are: + +```text +Capability +Service +Application +PlatformService +DataStore +ControlComponent +ManagementInterface +Integration +Policy +Automation +IntelligenceComponent +``` + +Every element must have a stable `id`, `name`, `type`, and at least one dimensional `placement`. + +### 8.3 Relation types + +OAS-compatible relation types are: + +```text +realizes +depends\_on +composes +exposes +governs +observes +hosted\_on +isolated\_by +augmented\_by +``` + +Relations should be used to explain architectural meaning, not merely technical adjacency. In particular: + +* `realizes` connects an implementation to a capability; +* `depends\_on` expresses operational or architectural dependency; +* `composes` expresses higher-order assembly; +* `exposes` expresses an available surface or interface; +* `governs` expresses control, policy, or regulation; +* `observes` expresses audit, telemetry, or monitoring; +* `hosted\_on` connects runtime elements to stack substrate; +* `isolated\_by` explains tenancy or separation; +* `augmented\_by` connects an element to intelligence support. + +### 8.4 Placement intent + +Placements should answer: **where does this element belong by architectural concern?** + +A `Service` might be placed at `Logic/L2`, `Plane/P1`, `Stack/S5`, and `Capability/C3`. A `Capability` might be placed at `Logic/L1` and `Capability/C5`. A `ControlComponent` should be placed in `Plane/P2`. An `IntelligenceComponent` should be placed in `Intelligence/I1` through `I5` and governed according to its autonomy. + +## 9\. Semantic validation posture + +HelixForge should treat semantic validation as architecture hygiene. A document can be structurally valid and still architecturally weak; semantic validation closes that gap. + +The repository should support two validation profiles: + +* **Draft profile** — suitable for exploration, discovery, and early modeling. Warnings are allowed when intent is still forming. +* **Production profile** — suitable for published or operational models. Key warnings become errors. + +### 9.1 Normative semantic rules + +The OAS semantic rule profile should be treated as the baseline for architecture validation: + +|Rule|Intent| +|-|-| +|R1|Every `Service` must include `Logic/L2` and `Plane/P1` placements.| +|R2|Every `Capability` must include `Logic/L1` and one of `Capability/C1`, `Capability/C4`, or `Capability/C5`.| +|R3|Every `ControlComponent` must include `Plane/P2`.| +|R4|Every `ManagementInterface` must include `Plane/P3`.| +|R5|Every `IntelligenceComponent` must include an `Intelligence/I1` through `I5` placement.| +|R6|Every `Service` or `Application` should realize at least one `Capability`; production models should require this.| +|R7|Every `Intelligence/I5` element must be governed through a path to a `ControlComponent`.| +|R8|Every `Service`, `Application`, and `PlatformService` should reference `Q2` observability; production models should require this.| +|R9|Every `ControlComponent`, `ManagementInterface`, and `IntelligenceComponent` must reference `Q1` and `Q7`.| +|R10|Every hostable runtime element should have a `Stack` placement or `hosted\_on` relation; production models should require this.| +|R11|A `realizes` relation must connect a `Service` or `Application` to a `Capability`.| +|R12|A `governs` relation must originate from a `ControlComponent` or `Policy` and target a governed element.| +|R13|An `augmented\_by` relation must point to an `IntelligenceComponent`.| +|R14|Duplicate placements with the same dimension and level are forbidden.| +|R15|`Intelligence/I4` and `Intelligence/I5` elements should link to a control, management, or policy element; production models should require this.| +|R16|Only control, management, or policy elements should be placed directly in `Plane/P2` or `Plane/P3`.| + +### 9.2 Validator behavior + +A HelixForge validator should process models in four phases: + +1. **Structural validation** against the OAS JSON Schema. +2. **Semantic indexing** of elements, placements, relations, sources, targets, and quality requirements. +3. **Semantic checks** using the rule profile. +4. **Report output** containing errors, warnings, and informational findings. + +Production validation should upgrade R6, R8, R10, and R15 from warnings to errors. + +## 10\. AI and intelligence governance + +HelixForge may use deterministic automation, language interaction, reasoning systems, assisted fitting, and agentic delegation. These are architectural elements, not magic exceptions. + +Any AI-assisted component must be placed in the Intelligence dimension and governed according to its autonomy: + +* `I1` deterministic automation may execute scripted or rule-based actions. +* `I2` language interaction may translate between users and system models. +* `I3` knowledge and reasoning may infer, classify, recommend, or explain. +* `I4` assisted fitting may propose or configure system changes under governance. +* `I5` agentic delegation may act autonomously only within explicit policy, control-plane, and audit boundaries. + +AI must not bypass the control plane. Agentic behavior must be observable, policy-bound, reversible where possible, and traceable to capability intent. + +## 11\. Design principles + +1. **Capability first.** Capabilities are stable intent; services and applications are realizations. +2. **Discovery and delivery co-evolve.** Natural language understanding and formal implementation must inform each other continuously. +3. **Dimensions stay orthogonal.** Plane, Stack, Quality, Logic, Intelligence, and Capability describe different concerns and must not be collapsed into one hierarchy. +4. **Validation is part of design.** Schemas and semantic rules are design instruments, not after-the-fact checks. +5. **Governance before autonomy.** Intelligence components must operate through control, management, policy, and audit structures. +6. **Reuse over accumulation.** The repository should grow by strengthening composable capabilities, not by collecting disconnected artifacts. +7. **Evidence over assertion.** Runtime behavior, telemetry, tests, contracts, and validation reports should back claims of readiness. +8. **Environment matters.** Users, builders, investors, external systems, markets, and real-world problems are part of the viable system boundary. + +## 12\. Contribution intent + +A contribution belongs in `helix-forge` when it strengthens at least one of these areas: + +* capability discovery; +* capability modeling; +* OAS/OAD vocabulary or schema support; +* semantic validation; +* reusable capability contracts; +* reusable capability implementations; +* governed automation or intelligence; +* observability, audit, policy, or control; +* developer enablement; +* documentation that clarifies the forge process. + +A contribution should be challenged when it: + +* adds implementation without capability intent; +* introduces AI behavior without governance and observability; +* mixes architectural dimensions in a way that weakens model clarity; +* creates one-off assets that cannot be reused or composed; +* avoids validation despite being modelable; +* bypasses controlled vocabulary without proposing an explicit vocabulary change. + +## 13\. Expected repository knowledge areas + +The following knowledge areas should be represented in the repository or linked from the wiki once the supporting files are added: + +|Area|Purpose| +|-|-| +|HelixForge vision|Defines why the project exists and what world it is trying to create.| +|Orthogonal Architecture Standard|Defines the structural schema for architecture descriptions.| +|OAS semantic validation|Defines the semantic rule profile and validation behavior.| +|Orthogonal Architecture Dimensions|Defines controlled architecture dimension vocabulary.| +|VSM-inspired information architecture|Defines viable-system functions and system roles.| +|Capability catalog|Captures reusable capabilities and their maturity.| +|Capability contracts|Defines interfaces, events, SLOs, ownership, and boundaries.| +|Validators|Turns architectural intent into executable checks.| +|Intelligence governance|Defines how automation, copilots, and agents are placed, governed, and audited.| + +## 14\. Definition of done + +A HelixForge artifact is done when it satisfies the appropriate level of intent, architecture, and validation for its maturity stage. + +For a **draft** artifact: + +* the problem or demand is understandable; +* the target capability is named; +* initial OAD placements are present; +* relevant VSM functions are identified; +* open questions and unresolved assumptions are explicit. + +For a **production** artifact: + +* capability intent, scope, ownership, and contract are documented; +* OAS structural validation passes; +* OAS semantic validation passes under the production profile; +* `Q1` security/compliance, `Q2` observability, and `Q7` governance/change are addressed where required; +* runtime or implementation artifacts realize the capability; +* relations to dependencies, hosting, governance, observation, and augmentation are explicit; +* AI or automation is governed and auditable; +* evidence exists through tests, telemetry, validation reports, or review records. + +## 15\. Machine-readable intent anchor + +```yaml +intent: + repository: helix-forge + product: HelixForge + purpose: > + Forge reusable software capabilities from real-world problems by uniting + human understanding with executable precision. + + vision: + tagline: Evolving software capabilities + statement: > + Software capabilities should evolve with understanding, not guesswork. + + architecture: + standard: OrthogonalArchitectureStandard + version: "1.0.1" + dimensions: + - Stack + - Logic + - Plane + - Quality + - Capability + - Intelligence + validation\_layers: + - structural\_schema + - semantic\_rules + validation\_profiles: + - draft + - production + + oad\_codes: + plane: \[P1, P2, P3] + stack: \[S1, S2, S3, S4, S5] + quality: \[Q1, Q2, Q3, Q4, Q5, Q6, Q7] + logic: \[L1, L2, L3, L4] + intelligence: \[I1, I2, I3, I4, I5] + capability: \[C1, C2, C3, C4, C5] + + vsm\_functions: + OPS: System 1 operations and activities + SYN: System 2 synchronization and coordination + CTL: System 3 internal control and regulation + AUD: System 3\* audit and monitoring + INT: System 4 intelligence and adaptation + POL: System 5 policy and identity + ENV: Environment boundary and surface + + contribution\_test: + must\_strengthen\_one\_of: + - capability\_discovery + - capability\_modeling + - capability\_validation + - capability\_realization + - capability\_evolution + must\_not\_bypass: + - controlled\_vocabulary + - semantic\_validation + - governance\_for\_intelligence + - observability\_for\_runtime\_behavior +``` + +## 16\. Source inputs for this intent file + +This file was drafted from the following project inputs: + +* **HelixForgeVision** — project vision statement provided for this repository. +* **OrthogonalArchitectureSchema** — Orthogonal Architecture Standard Schema v1.0.1 and semantic validation profile. +* **260525-schema-orthogonalArchitecture.xlsx** — current OAD and VSM controlled vocabulary workbook. + +When these materials are moved into the repository wiki, this file should be updated with stable wiki links. + + diff --git a/README.md b/README.md index fcd7b8f..8b563e3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1 @@ -# repo-seed - -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +Evolving capabilities from intent to code diff --git a/wiki/HelixForgeVision.md b/wiki/HelixForgeVision.md new file mode 100644 index 0000000..5fe4fb2 --- /dev/null +++ b/wiki/HelixForgeVision.md @@ -0,0 +1,29 @@ +HelixForgeVision + +*Evolving software capabilities* + +## **HelixForge — Vision Statement** + +**HelixForge envisions a world where software capabilities evolve with understanding, not guesswork.** + +**HelixForge empowers a global ecosystem of users, builders, and investors to collaboratively forge reusable software capabilities from real-world problems—intertwining the natural-language art of discovery with the precise science of delivery in an evolving double helix, accumulating a battle-tested repository of composable intelligence that accelerates innovation for all.** + +We believe the most powerful software is not merely built — it is *forged*: +through continuous dialogue between human meaning and machine precision. + +HelixForge exists to unite **discovery and delivery** into a single evolutionary process, where natural-language understanding and formal implementation co-develop as two strands of the same helix. In this world, every demand can mature into a reusable capability, every capability can be assessed for both conceptual clarity and technical rigor, and every iteration strengthens the whole system. + +Our vision is a capability-first development ecosystem where: + +* problems are explored before they are solved, +* solutions are shaped for reuse from the start, +* implementation is guided by executable truth, +* and software assets grow in value through evolution, not accumulation. + +HelixForge aims to become the forge where intent becomes structure, +structure becomes capability, +and capability becomes lasting progress. + +**We evolve software capabilities by uniting human understanding and executable precision.** + +xxx diff --git a/wiki/OrthogonalArchitectureSchema.md b/wiki/OrthogonalArchitectureSchema.md new file mode 100644 index 0000000..ee5e4aa --- /dev/null +++ b/wiki/OrthogonalArchitectureSchema.md @@ -0,0 +1,1470 @@ +OrthogonalArchitectureSchema + +*A schema to validate compute architectures* + +# Orthogonal Architecture Standard Schema v1.0.1 + +## Structural Validation + +Below is a machine-readable schema for the **Orthogonal Architecture Standard** in **JSON Schema 2020-12** form, followed by a compact **YAML example** that validates against its structure. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/orthogonal-architecture-standard.schema.json", + "title": "Orthogonal Architecture Standard", + "description": "Machine-readable schema for describing architectures with the Orthogonal Architecture Standard.", + "type": "object", + "additionalProperties": false, + "required": [ + "standard", + "version", + "architecture" + ], + "properties": { + "standard": { + "type": "string", + "const": "OrthogonalArchitectureStandard" + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" + }, + "architecture": { + "$ref": "#/$defs/Architecture" + } + }, + "$defs": { + "Identifier": { + "type": "string", + "pattern": "^[A-Za-z][A-Za-z0-9_.:-]*$" + }, + "VsmSystem": { + "type": "string", + "enum": [ + "S1", + "S2", + "S3", + "S3*", + "S4", + "S5" + ] + }, + "DimensionName": { + "type": "string", + "enum": [ + "Stack", + "Logic", + "Plane", + "Quality", + "Capability", + "Intelligence" + ] + }, + "StackLevel": { + "type": "string", + "enum": [ + "S1", + "S2", + "S3", + "S4", + "S5" + ] + }, + "LogicLevel": { + "type": "string", + "enum": [ + "L1", + "L2", + "L3", + "L4" + ] + }, + "PlaneLevel": { + "type": "string", + "enum": [ + "P1", + "P2", + "P3" + ] + }, + "QualityLevel": { + "type": "string", + "enum": [ + "Q1", + "Q2", + "Q3", + "Q4", + "Q5", + "Q6", + "Q7" + ] + }, + "CapabilityLevel": { + "type": "string", + "enum": [ + "C1", + "C2", + "C3", + "C4", + "C5" + ] + }, + "IntelligenceLevel": { + "type": "string", + "enum": [ + "I1", + "I2", + "I3", + "I4", + "I5" + ] + }, + "RelationType": { + "type": "string", + "enum": [ + "realizes", + "depends_on", + "composes", + "exposes", + "governs", + "observes", + "hosted_on", + "isolated_by", + "augmented_by" + ] + }, + "ElementType": { + "type": "string", + "enum": [ + "Capability", + "Service", + "Application", + "PlatformService", + "DataStore", + "ControlComponent", + "ManagementInterface", + "Integration", + "Policy", + "Automation", + "IntelligenceComponent" + ] + }, + "TagMap": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "DimensionPlacement": { + "type": "object", + "additionalProperties": false, + "required": [ + "dimension", + "level" + ], + "properties": { + "dimension": { + "$ref": "#/$defs/DimensionName" + }, + "level": { + "type": "string" + } + }, + "allOf": [ + { + "if": { + "properties": { + "dimension": { + "const": "Stack" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/StackLevel" + } + } + } + }, + { + "if": { + "properties": { + "dimension": { + "const": "Logic" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/LogicLevel" + } + } + } + }, + { + "if": { + "properties": { + "dimension": { + "const": "Plane" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/PlaneLevel" + } + } + } + }, + { + "if": { + "properties": { + "dimension": { + "const": "Quality" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/QualityLevel" + } + } + } + }, + { + "if": { + "properties": { + "dimension": { + "const": "Capability" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/CapabilityLevel" + } + } + } + }, + { + "if": { + "properties": { + "dimension": { + "const": "Intelligence" + } + } + }, + "then": { + "properties": { + "level": { + "$ref": "#/$defs/IntelligenceLevel" + } + } + } + } + ] + }, + "ElementRef": { + "type": "object", + "additionalProperties": false, + "required": [ + "id" + ], + "properties": { + "id": { + "$ref": "#/$defs/Identifier" + } + } + }, + "Relation": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "source", + "target" + ], + "properties": { + "id": { + "$ref": "#/$defs/Identifier" + }, + "type": { + "$ref": "#/$defs/RelationType" + }, + "source": { + "$ref": "#/$defs/Identifier" + }, + "target": { + "$ref": "#/$defs/Identifier" + }, + "description": { + "type": "string" + }, + "vsm_tags": { + "type": "array", + "items": { + "$ref": "#/$defs/VsmSystem" + }, + "uniqueItems": true + }, + "tags": { + "$ref": "#/$defs/TagMap" + } + } + }, + "Element": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "type", + "placements" + ], + "properties": { + "id": { + "$ref": "#/$defs/Identifier" + }, + "name": { + "type": "string" + }, + "type": { + "$ref": "#/$defs/ElementType" + }, + "description": { + "type": "string" + }, + "placements": { + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/DimensionPlacement" + } + }, + "vsm_tags": { + "type": "array", + "items": { + "$ref": "#/$defs/VsmSystem" + }, + "uniqueItems": true + }, + "owners": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "contracts": { + "type": "array", + "items": { + "$ref": "#/$defs/Identifier" + }, + "uniqueItems": true + }, + "quality_requirements": { + "type": "array", + "items": { + "$ref": "#/$defs/QualityLevel" + }, + "uniqueItems": true + }, + "tags": { + "$ref": "#/$defs/TagMap" + }, + "metadata": { + "type": "object" + } + } + }, + "DimensionDefinition": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "levels" + ], + "properties": { + "name": { + "$ref": "#/$defs/DimensionName" + }, + "levels": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "name" + ], + "properties": { + "code": { + "type": "string" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "vsm_tags": { + "type": "array", + "items": { + "$ref": "#/$defs/VsmSystem" + }, + "uniqueItems": true + } + } + } + } + } + }, + "Architecture": { + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "name", + "dimensions", + "elements", + "relations" + ], + "properties": { + "id": { + "$ref": "#/$defs/Identifier" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "dimensions": { + "type": "array", + "minItems": 6, + "items": { + "$ref": "#/$defs/DimensionDefinition" + } + }, + "elements": { + "type": "array", + "items": { + "$ref": "#/$defs/Element" + } + }, + "relations": { + "type": "array", + "items": { + "$ref": "#/$defs/Relation" + } + }, + "principles": { + "type": "array", + "items": { + "type": "string" + } + }, + "sources": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "title" + ], + "properties": { + "title": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "author": { + "type": "string" + }, + "notes": { + "type": "string" + } + } + } + }, + "metadata": { + "type": "object" + } + } + } + } +} +``` + +Example instance in YAML: + +```yaml +standard: OrthogonalArchitectureStandard +version: "1.0" + +architecture: + id: orthogonal-architecture-example + name: Orthogonal Architecture Example + description: Example instance for a Kubernetes-based SaaS platform. + + dimensions: + - name: Stack + levels: + - code: S1 + name: Infrastructure Substrate + vsm_tags: [S1] + - code: S2 + name: Cluster Runtime + vsm_tags: [S2] + - code: S3 + name: Platform Services + vsm_tags: [S1] + - code: S4 + name: Developer Enablement + vsm_tags: [S4] + - code: S5 + name: Workloads & Experience Endpoints + vsm_tags: [S1] + + - name: Logic + levels: + - code: L1 + name: Capability Domain + vsm_tags: [S5] + - code: L2 + name: Service Realization + vsm_tags: [S1] + - code: L3 + name: Composition & Integration + vsm_tags: [S2] + - code: L4 + name: Solution Layer + vsm_tags: [S1] + + - name: Plane + levels: + - code: P1 + name: Workload Plane + vsm_tags: [S1] + - code: P2 + name: Control Plane + vsm_tags: [S3] + - code: P3 + name: Management Plane + vsm_tags: [S5] + + - name: Quality + levels: + - code: Q1 + name: Security & Compliance + vsm_tags: [S5] + - code: Q2 + name: Observability + vsm_tags: [S3*] + - code: Q3 + name: Operability & Resilience + vsm_tags: [S3] + - code: Q4 + name: Isolation & Tenancy + vsm_tags: [S2] + - code: Q5 + name: Performance & Scalability + vsm_tags: [S3] + - code: Q6 + name: Cost & Efficiency + vsm_tags: [S3] + - code: Q7 + name: Governance & Change + vsm_tags: [S5] + + - name: Capability + levels: + - code: C1 + name: Capability Model + vsm_tags: [S5] + - code: C2 + name: Capability Contract + vsm_tags: [S2] + - code: C3 + name: Capability Realization + vsm_tags: [S1] + - code: C4 + name: Shared Platform Capabilities + vsm_tags: [S3] + - code: C5 + name: Business Capabilities + vsm_tags: [S1] + + - name: Intelligence + levels: + - code: I1 + name: Deterministic Automation + vsm_tags: [S3] + - code: I2 + name: Language Interaction + vsm_tags: [S4] + - code: I3 + name: Knowledge & Reasoning + vsm_tags: [S4] + - code: I4 + name: Assisted Adaptation + vsm_tags: [S4] + - code: I5 + name: Agentic Delegation + vsm_tags: [S4, S5] + + elements: + - id: capability.customer-billing + name: Customer Billing + type: Capability + description: Billing capability for customer subscriptions and invoices. + placements: + - dimension: Logic + level: L1 + - dimension: Capability + level: C5 + vsm_tags: [S1, S5] + owners: [Finance Platform Team] + quality_requirements: [Q1, Q3, Q7] + + - id: service.billing-api + name: Billing API + type: Service + placements: + - dimension: Stack + level: S5 + - dimension: Logic + level: L2 + - dimension: Plane + level: P1 + - dimension: Capability + level: C3 + vsm_tags: [S1] + owners: [Finance Platform Team] + quality_requirements: [Q1, Q2, Q3, Q5] + + - id: datastore.billing-postgres + name: Billing PostgreSQL + type: DataStore + placements: + - dimension: Stack + level: S3 + - dimension: Plane + level: P1 + vsm_tags: [S1, S3] + quality_requirements: [Q1, Q3, Q4, Q5] + + - id: control.gitops + name: GitOps Controller + type: ControlComponent + placements: + - dimension: Plane + level: P2 + - dimension: Stack + level: S4 + vsm_tags: [S3] + quality_requirements: [Q1, Q3, Q7] + + - id: mgmt.developer-portal + name: Developer Portal + type: ManagementInterface + placements: + - dimension: Plane + level: P3 + - dimension: Stack + level: S4 + vsm_tags: [S5] + quality_requirements: [Q1, Q7] + + - id: intelligence.deployment-copilot + name: Deployment Copilot + type: IntelligenceComponent + placements: + - dimension: Intelligence + level: I4 + - dimension: Plane + level: P3 + vsm_tags: [S4] + quality_requirements: [Q1, Q2, Q7] + + relations: + - id: r1 + type: realizes + source: service.billing-api + target: capability.customer-billing + vsm_tags: [S1] + + - id: r2 + type: depends_on + source: service.billing-api + target: datastore.billing-postgres + vsm_tags: [S1] + + - id: r3 + type: governs + source: control.gitops + target: service.billing-api + vsm_tags: [S3] + + - id: r4 + type: augmented_by + source: mgmt.developer-portal + target: intelligence.deployment-copilot + vsm_tags: [S4] + + principles: + - Separate dimensions. + - Capabilities are stable intent; services are realizations. + - AI must operate through the control plane. + + sources: + - title: Kubernetes Components + url: https://kubernetes.io/docs/concepts/overview/components/ + - title: Kubernetes Multi-Tenancy + url: https://kubernetes.io/docs/concepts/security/multi-tenancy/ + - title: Platform Strategy + author: Gregor Hohpe +``` + +A useful next step is to add a second schema layer for stricter semantic validation, such as requiring at least one `Logic` placement for every `Service`, or requiring every `IntelligenceComponent` at `I5` to have a `governs` or `operates_via` style relation through a control component. + +## Semantic Validation + +Below is a **second schema layer** for stricter semantic validation. + +The cleanest way to do this is to keep: + +* **Layer 1** = structural schema in JSON Schema +* **Layer 2** = semantic rule layer in JSON Schema as far as possible, plus a small set of explicit validation rules that most validators can implement easily + +Because plain JSON Schema is good at structure but limited at graph-style cross-reference semantics, I’ll give you: + +1. an **extended JSON Schema layer** with stronger constraints +2. a **semantic rule profile** for validators +3. an updated **machine-readable convention block** you can attach to the standard + +--- + +# Orthogonal Architecture Standard + +## Semantic Validation Layer (Layer 2) + +## 1. Purpose + +The second schema layer defines **semantic consistency rules** beyond basic structural validation. + +It ensures that architecture descriptions are not only syntactically valid, but also **architecturally meaningful**. + +This layer validates: + +* placement consistency +* required dimension participation by element type +* governance constraints +* intelligence/control-plane coupling +* relation sanity rules + +--- + +## 2. Validation approach + +Use a **two-layer validation model**: + +### Layer 1 — Structural validation + +Validate JSON/YAML documents against the base JSON Schema. + +### Layer 2 — Semantic validation + +Validate the same document against: + +* extended JSON Schema constraints where possible +* explicit semantic rules for cross-element consistency + +--- + +# 3. Extended JSON Schema Layer + +This schema is intended as a companion to the first schema. +It assumes the base schema already exists. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://example.org/schemas/orthogonal-architecture-standard.semantic-layer.schema.json", + "title": "Orthogonal Architecture Standard - Semantic Validation Layer", + "description": "Second-layer semantic constraints for the Orthogonal Architecture Standard.", + "type": "object", + "allOf": [ + { + "$ref": "https://example.org/schemas/orthogonal-architecture-standard.schema.json" + } + ], + "$defs": { + "ServiceElement": { + "type": "object", + "properties": { + "type": { "const": "Service" } + }, + "required": ["type"] + }, + "ApplicationElement": { + "type": "object", + "properties": { + "type": { "const": "Application" } + }, + "required": ["type"] + }, + "CapabilityElement": { + "type": "object", + "properties": { + "type": { "const": "Capability" } + }, + "required": ["type"] + }, + "ControlComponentElement": { + "type": "object", + "properties": { + "type": { "const": "ControlComponent" } + }, + "required": ["type"] + }, + "ManagementInterfaceElement": { + "type": "object", + "properties": { + "type": { "const": "ManagementInterface" } + }, + "required": ["type"] + }, + "IntelligenceComponentElement": { + "type": "object", + "properties": { + "type": { "const": "IntelligenceComponent" } + }, + "required": ["type"] + } + }, + "properties": { + "architecture": { + "type": "object", + "properties": { + "elements": { + "type": "array", + "items": { + "allOf": [ + { + "if": { + "properties": { + "type": { "const": "Service" } + } + }, + "then": { + "allOf": [ + { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Logic" }, + "level": { "const": "L2" } + }, + "required": ["dimension", "level"] + } + } + } + }, + { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Plane" }, + "level": { "const": "P1" } + }, + "required": ["dimension", "level"] + } + } + } + } + ] + } + }, + { + "if": { + "properties": { + "type": { "const": "Application" } + } + }, + "then": { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Logic" }, + "level": { "enum": ["L2", "L4"] } + }, + "required": ["dimension", "level"] + } + } + } + } + }, + { + "if": { + "properties": { + "type": { "const": "Capability" } + } + }, + "then": { + "allOf": [ + { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Logic" }, + "level": { "const": "L1" } + }, + "required": ["dimension", "level"] + } + } + } + }, + { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Capability" } + }, + "required": ["dimension"] + } + } + } + } + ] + } + }, + { + "if": { + "properties": { + "type": { "const": "ControlComponent" } + } + }, + "then": { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Plane" }, + "level": { "const": "P2" } + }, + "required": ["dimension", "level"] + } + } + } + } + }, + { + "if": { + "properties": { + "type": { "const": "ManagementInterface" } + } + }, + "then": { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Plane" }, + "level": { "const": "P3" } + }, + "required": ["dimension", "level"] + } + } + } + } + }, + { + "if": { + "properties": { + "type": { "const": "IntelligenceComponent" } + } + }, + "then": { + "properties": { + "placements": { + "contains": { + "type": "object", + "properties": { + "dimension": { "const": "Intelligence" } + }, + "required": ["dimension"] + } + } + } + } + } + ] + } + }, + "relations": { + "type": "array", + "items": { + "allOf": [ + { + "if": { + "properties": { + "type": { "const": "realizes" } + } + }, + "then": { + "required": ["source", "target"] + } + }, + { + "if": { + "properties": { + "type": { "const": "governs" } + } + }, + "then": { + "required": ["source", "target"] + } + }, + { + "if": { + "properties": { + "type": { "const": "augmented_by" } + } + }, + "then": { + "required": ["source", "target"] + } + } + ] + } + } + } + } + } +} +``` + +--- + +# 4. Semantic rule profile + +These rules go beyond what JSON Schema can fully guarantee on its own. + +They should be treated as **normative semantic constraints**. + +## R1. Service placement rule + +Every element of type `Service` MUST have: + +* one `Logic/L2` placement +* one `Plane/P1` placement + +## R2. Capability placement rule + +Every element of type `Capability` MUST have: + +* one `Logic/L1` placement +* one `Capability/C1`, `C4`, or `C5` placement + +## R3. Control component rule + +Every element of type `ControlComponent` MUST have: + +* one `Plane/P2` placement + +## R4. Management interface rule + +Every element of type `ManagementInterface` MUST have: + +* one `Plane/P3` placement + +## R5. Intelligence placement rule + +Every element of type `IntelligenceComponent` MUST have: + +* one `Intelligence/I1–I5` placement + +## R6. Realization rule + +Every `Service` or `Application` SHOULD participate in at least one `realizes` relation pointing to a `Capability`. + +Normative strength: + +* **MUST** for production models +* **SHOULD** for drafts + +## R7. Governance rule + +Every element placed at: + +* `Intelligence/I5` + MUST be governed through at least one relation to a `ControlComponent`. + +Acceptable patterns: + +* `ControlComponent governs IntelligenceComponent` +* `IntelligenceComponent depends_on ControlComponent` +* `ManagementInterface augmented_by IntelligenceComponent` plus `ManagementInterface depends_on ControlComponent` + +More strictly: + +* an I5 component MUST have at least one path to a P2 control component + +## R8. Observability rule + +Every `Service`, `Application`, and `PlatformService` SHOULD reference `Q2` in `quality_requirements`. + +## R9. Security rule + +Every `ControlComponent`, `ManagementInterface`, and `IntelligenceComponent` MUST reference `Q1` and `Q7` in `quality_requirements`. + +## R10. Hosted workload rule + +Every element of type: + +* `Service` +* `Application` +* `PlatformService` +* `DataStore` + +SHOULD have at least one `hosted_on` relation or a `Stack` placement. + +## R11. Relation typing rule + +`realizes` relations MUST connect: + +* source: `Service` or `Application` +* target: `Capability` + +## R12. Governance relation typing rule + +`governs` relations MUST originate from: + +* `ControlComponent` +* `Policy` + +and MUST target one of: + +* `Service` +* `Application` +* `PlatformService` +* `ManagementInterface` +* `IntelligenceComponent` + +## R13. Augmentation typing rule + +`augmented_by` relations MUST point to an `IntelligenceComponent`. + +## R14. Unique placement rule + +An element MUST NOT contain duplicate placements with the same dimension and level. + +## R15. Intelligence-control rule + +Any element with `Intelligence/I4` or `Intelligence/I5` SHOULD be linked to at least one of: + +* `ControlComponent` +* `ManagementInterface` +* `Policy` + +## R16. Plane consistency rule + +No element except `ControlComponent`, `ManagementInterface`, or `Policy` SHOULD be placed directly in `Plane/P2` or `Plane/P3`. + +--- + +# 5. Machine-readable semantic rules block + +This block is not a full validator by itself, but it gives you a machine-readable policy profile that tools can interpret. + +```yaml +semantic_rules: + version: "1.0" + profile: orthogonal-architecture-semantic-rules + + rules: + - id: R1 + name: service-placement + severity: error + applies_to: Service + requires_placements: + - { dimension: Logic, level: L2 } + - { dimension: Plane, level: P1 } + + - id: R2 + name: capability-placement + severity: error + applies_to: Capability + requires_placements: + - { dimension: Logic, level: L1 } + requires_one_of_placements: + - { dimension: Capability, level: C1 } + - { dimension: Capability, level: C4 } + - { dimension: Capability, level: C5 } + + - id: R3 + name: control-component-plane + severity: error + applies_to: ControlComponent + requires_placements: + - { dimension: Plane, level: P2 } + + - id: R4 + name: management-interface-plane + severity: error + applies_to: ManagementInterface + requires_placements: + - { dimension: Plane, level: P3 } + + - id: R5 + name: intelligence-placement + severity: error + applies_to: IntelligenceComponent + requires_dimension: Intelligence + + - id: R6 + name: service-realizes-capability + severity: warning + applies_to_any_of: + - Service + - Application + requires_relation: + type: realizes + direction: outgoing + target_type: Capability + + - id: R7 + name: i5-governed-through-control-plane + severity: error + applies_to: IntelligenceComponent + when_has_placement: + dimension: Intelligence + level: I5 + requires_relation_any: + - type: depends_on + direction: outgoing + target_type: ControlComponent + - type: governs + direction: incoming + source_type: ControlComponent + - type: augmented_by + direction: incoming + source_type: ManagementInterface + + - id: R8 + name: runtime-observability + severity: warning + applies_to_any_of: + - Service + - Application + - PlatformService + requires_quality: + - Q2 + + - id: R9 + name: governed-sensitive-components + severity: error + applies_to_any_of: + - ControlComponent + - ManagementInterface + - IntelligenceComponent + requires_quality: + - Q1 + - Q7 + + - id: R10 + name: hostable-runtime-element + severity: warning + applies_to_any_of: + - Service + - Application + - PlatformService + - DataStore + requires_any: + placements_in_dimension: + - Stack + outgoing_relations: + - type: hosted_on + + - id: R11 + name: realizes-typing + severity: error + applies_to_relation: realizes + source_type_any_of: + - Service + - Application + target_type: Capability + + - id: R12 + name: governs-typing + severity: error + applies_to_relation: governs + source_type_any_of: + - ControlComponent + - Policy + target_type_any_of: + - Service + - Application + - PlatformService + - ManagementInterface + - IntelligenceComponent + + - id: R13 + name: augmented-by-typing + severity: error + applies_to_relation: augmented_by + target_type: IntelligenceComponent + + - id: R14 + name: unique-placements + severity: error + applies_to: "*" + forbids_duplicate_placements: true + + - id: R15 + name: adaptive-intelligence-governance-link + severity: warning + applies_to: IntelligenceComponent + when_has_placement_any: + - { dimension: Intelligence, level: I4 } + - { dimension: Intelligence, level: I5 } + requires_relation_any: + - type: depends_on + direction: outgoing + target_type: ControlComponent + - type: depends_on + direction: outgoing + target_type: ManagementInterface + - type: governs + direction: incoming + source_type: Policy + + - id: R16 + name: restricted-plane-placement + severity: warning + applies_to_any_of: + - Service + - Application + - PlatformService + - DataStore + forbids_placements: + - { dimension: Plane, level: P2 } + - { dimension: Plane, level: P3 } +``` + +--- + +# 6. Recommended validator behavior + +A validator should process the document in this order: + +## Phase 1 — structural validation + +Validate against the base JSON Schema. + +## Phase 2 — semantic indexing + +Build in-memory indexes for: + +* elements by id +* elements by type +* placements by dimension +* relations by source/target + +## Phase 3 — semantic checks + +Apply rules R1–R16. + +## Phase 4 — report output + +Return: + +* `errors` +* `warnings` +* `info` + +Recommended format: + +```yaml +validation_result: + valid: false + errors: + - rule: R1 + element: service.billing-api + message: "Service must include Logic/L2 and Plane/P1 placements." + - rule: R11 + relation: r7 + message: "Relation 'realizes' must target a Capability." + warnings: + - rule: R8 + element: service.billing-api + message: "Runtime service should include Q2 Observability." +``` + +--- + +# 7. Optional stricter production profile + +For production-grade architecture models, I recommend upgrading some SHOULD-like checks to MUST. + +## Production profile changes + +* R6 becomes `error` +* R8 becomes `error` +* R10 becomes `error` +* R15 becomes `error` + +Machine-readable profile: + +```yaml +validation_profiles: + draft: + overrides: {} + + production: + overrides: + R6: { severity: error } + R8: { severity: error } + R10: { severity: error } + R15: { severity: error } +``` + +--- + +# 8. Practical note + +If you want full automated semantic validation, JSON Schema alone is not ideal for all graph constraints. The best practical combination is: + +* **JSON Schema** for structure +* **custom semantic validator** for graph rules +* optionally **SHACL** later if you want RDF/knowledge-graph style validation + +That gives you a robust path without overcomplicating the first implementation. + +The next useful step would be a **reference validator implementation in Python** that reads YAML and applies both layers. + + +xxx