From 3fa58bccb7f9fa63956605e2b9c660155f510aaf Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 9 Mar 2026 23:32:42 +0100 Subject: [PATCH] feat(canon): add Orthogonal Architecture Standard v1.0 and schema v1.0.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OAS defines a multidimensional architecture model for compute systems: - 6 canonical dimensions: Stack, Logic, Plane, Quality, Capability, Intelligence - VSM (Viable System Model) tagging throughout - Canonical element types and 9 relation types - Intelligence dimension I1-I5 with governance constraint: I5 agents MUST operate through the control plane (P3 — directly governs Custodian design) Schema provides two-layer validation: - Layer 1: JSON Schema 2020-12 structural validation - Layer 2: semantic rule profile R1-R16 (placement, governance, intelligence coupling, relation typing rules) + YAML machine-readable rule block - Draft and production validation profiles Terminology and dimensions will guide state-hub and Custodian implementation. Co-Authored-By: Claude Sonnet 4.6 --- .../orthogonal-architecture-schema_v1.0.1.md | 1470 +++++++++++++++++ .../standards/orthogonal-architecture_v1.0.md | 669 ++++++++ 2 files changed, 2139 insertions(+) create mode 100644 canon/standards/orthogonal-architecture-schema_v1.0.1.md create mode 100644 canon/standards/orthogonal-architecture_v1.0.md diff --git a/canon/standards/orthogonal-architecture-schema_v1.0.1.md b/canon/standards/orthogonal-architecture-schema_v1.0.1.md new file mode 100644 index 0000000..ee5e4aa --- /dev/null +++ b/canon/standards/orthogonal-architecture-schema_v1.0.1.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 diff --git a/canon/standards/orthogonal-architecture_v1.0.md b/canon/standards/orthogonal-architecture_v1.0.md new file mode 100644 index 0000000..12f8a75 --- /dev/null +++ b/canon/standards/orthogonal-architecture_v1.0.md @@ -0,0 +1,669 @@ +OrthogonalArchitecture + +*A framework for compute systems design* + +# Orthogonal Architecture Standard (OAS) + +### Format Specification + +**Version:** 1.0 +**Status:** Draft Standard +**Scope:** Cloud-native compute systems and Kubernetes platforms + +--- + +# 1. Introduction + +*(VSM System 5 — Identity and Policy)* + +The Orthogonal Architecture Standard (OAS) defines a **structured format for describing modern compute systems** using a multidimensional architecture model. + +The standard establishes: + +* a consistent architecture vocabulary +* a canonical set of architectural dimensions +* a modeling format for systems, services, and capabilities +* relationships between architecture components + +The goal is to enable **consistent architecture descriptions across teams and organizations**. + +The standard is especially suited for: + +* Kubernetes-based platforms +* internal developer platforms +* SaaS architectures +* distributed systems +* AI-integrated platforms + +--- + +# 2. Normative Principles + +*(VSM System 5 — Identity and Policy)* + +The Orthogonal Architecture Standard is based on the following normative principles. + +### P1 Separation of Dimensions + +Architecture descriptions MUST separate independent perspectives into **orthogonal dimensions**. + +### P2 Stable Capability Core + +Capabilities represent **stable system intent** and MUST be distinguished from implementation. + +### P3 Control Plane Governance + +All configuration and operational changes MUST occur through a **control plane**. + +Automation and AI MUST NOT bypass governance mechanisms. + +### P4 Cross-Cutting Quality Constraints + +Quality properties apply across all architecture layers and MUST NOT be modeled as stack layers. + +### P5 Explicit Relationships + +Architecture elements MUST declare explicit relations with other elements. + +--- + +# 3. Architecture Meta-Model + +*(VSM System 3 — Internal Control)* + +The meta-model defines the structural components used in architecture descriptions. + +--- + +## 3.1 Architecture + +An **Architecture** describes a system through: + +* Dimensions +* Levels +* Elements +* Relations +* Quality constraints + +--- + +## 3.2 Dimension + +A **Dimension** is a classification axis used to analyze architecture. + +Each dimension contains **levels**. + +--- + +## 3.3 Level + +A **Level** represents an ordered stratum within a dimension. + +Example: + +``` +Infrastructure → Runtime → Platform Services → Applications +``` + +--- + +## 3.4 Element + +An **Element** is a concrete architectural component. + +Examples: + +* Service +* API +* Database +* Workflow engine +* Policy engine +* AI component + +--- + +## 3.5 Relation + +A **Relation** describes how two elements interact. + +Example relation types: + +* realizes +* depends_on +* composes +* governs +* observes +* exposes + +--- + +# 4. Canonical Architecture Dimensions + +*(VSM System 1 — Operational Units)* + +The Orthogonal Architecture Standard defines **six canonical dimensions**. + +| Dimension | Purpose | +| ------------ | ------------------------------------- | +| Stack | technical hosting substrate | +| Logic | functional decomposition | +| Plane | operational responsibility | +| Quality | cross-cutting architecture properties | +| Capability | stable capability modeling | +| Intelligence | degree of intelligent automation | + +Each architecture description MUST use these dimensions. + +--- + +# 5. Stack Dimension Specification + +*(VSM System 1 — Operations, System 2 — Coordination)* + +The Stack dimension describes the **technical substrate of the system**. + +--- + +## S1 Infrastructure Substrate + +*(VSM System 1)* + +Defines the physical or cloud infrastructure. + +Examples: + +* cloud accounts +* network foundations +* compute nodes +* node operating systems +* container runtimes + +--- + +## S2 Cluster Runtime + +*(VSM System 2 — Coordination)* + +Defines the orchestration runtime. + +Examples: + +* Kubernetes scheduler +* service discovery +* ingress +* admission controllers +* service mesh +* operators + +These mechanisms coordinate workload interaction. + +--- + +## S3 Platform Services + +*(VSM System 1)* + +Shared services supporting workloads. + +Examples: + +* databases +* message brokers +* caches +* object storage +* secret management +* identity systems + +--- + +## S4 Developer Enablement + +*(VSM System 4 — Adaptation)* + +Tools that allow system evolution. + +Examples: + +* CI/CD pipelines +* developer portals +* platform templates +* SDKs +* buildpacks + +--- + +## S5 Workloads and Experience Endpoints + +*(VSM System 1)* + +Functional applications delivering value. + +Examples: + +* APIs +* web frontends +* workers +* integration endpoints +* administrative interfaces + +--- + +# 6. Logic Dimension Specification + +*(VSM System 1 — Operational Recursion)* + +The Logic dimension describes **functional system structure**. + +--- + +## L1 Capability Domain + +*(VSM System 5 — Identity)* + +Defines stable functional areas. + +Examples: + +* billing +* identity +* catalog +* order management + +Capabilities align with **bounded contexts**. + +--- + +## L2 Service Realization + +*(VSM System 1)* + +Implementation of capabilities. + +Examples: + +* APIs +* worker services +* event processors +* adapters + +--- + +## L3 Composition and Integration + +*(VSM System 2 — Coordination)* + +Defines orchestration between services. + +Examples: + +* workflow engines +* orchestration pipelines +* API gateways +* integration pipelines + +--- + +## L4 Solution Layer + +*(VSM System 1)* + +End-user solutions and applications. + +Examples: + +* SaaS products +* internal systems +* partner solutions + +--- + +# 7. Plane Dimension Specification + +*(VSM Systems 2–3)* + +The Plane dimension defines **control and governance structure**. + +--- + +## P1 Workload Plane + +*(VSM System 1)* + +Contains operational services and applications. + +--- + +## P2 Control Plane + +*(VSM System 3 — Internal Regulation)* + +Maintains system state. + +Examples: + +* Kubernetes control plane +* GitOps controllers +* policy engines +* platform APIs + +--- + +## P3 Management Plane + +*(VSM System 5 — Policy & Governance)* + +Provides administrative interfaces. + +Examples: + +* CLI tools +* web portals +* automation scripts +* audit reporting + +--- + +# 8. Quality Dimension Specification + +*(VSM Systems 3 and 3*)* + +Defines cross-cutting architectural qualities. + +--- + +## Q1 Security and Compliance + +*(VSM System 5)* + +Identity, access control, compliance. + +--- + +## Q2 Observability + +*(VSM System 3*)* + +Telemetry and monitoring. + +Examples: + +* metrics +* logs +* traces + +--- + +## Q3 Operability and Resilience + +*(VSM System 3)* + +Deployment, scaling, and disaster recovery. + +--- + +## Q4 Isolation and Tenancy + +*(VSM System 2)* + +Workload separation strategies. + +--- + +## Q5 Performance and Scalability + +*(VSM System 3)* + +Latency, throughput, and scaling. + +--- + +## Q6 Cost and Efficiency + +*(VSM System 3)* + +Resource optimization. + +--- + +## Q7 Governance and Change Management + +*(VSM System 5)* + +Policies and architecture governance. + +--- + +# 9. Capability Dimension Specification + +*(VSM System 5 — Identity)* + +Defines capabilities as stable architectural units. + +--- + +## C1 Capability Model + +Defines purpose, scope, ownership. + +--- + +## C2 Capability Contract + +Defines interfaces: + +* APIs +* events +* SLOs + +--- + +## C3 Capability Realization + +Technical implementations. + +Examples: + +* services +* databases +* workflows + +--- + +## C4 Shared Platform Capabilities + +Platform-level services. + +Examples: + +* identity +* messaging +* observability + +--- + +## C5 Business Capabilities + +Business functionality. + +Examples: + +* billing +* onboarding +* support + +--- + +# 10. Intelligence Dimension Specification + +*(VSM System 4 — Adaptation and Future Planning)* + +Defines AI-assisted system behavior. + +--- + +## I1 Deterministic Automation + +Scripts and rule engines. + +--- + +## I2 Language Interaction + +Natural language interfaces. + +--- + +## I3 Knowledge and Reasoning + +Semantic processing and recommendation systems. + +--- + +## I4 Assisted Adaptation + +AI-assisted system configuration. + +--- + +## I5 Agentic Delegation + +Autonomous AI agents acting within governance policies. + +All AI actions MUST operate through the **control plane**. + +--- + +# 11. Canonical Element Types + +*(VSM System 1)* + +Standard element classifications: + +* Capability +* Service +* Application +* Platform Service +* Data Store +* Control Component +* Management Interface +* Policy +* Automation +* Intelligence Component + +--- + +# 12. Canonical Relation Types + +*(VSM System 2)* + +Architecture elements MUST use defined relation types. + +| Relation | Meaning | +| ------------ | -------------------------- | +| realizes | implements capability | +| depends_on | requires another element | +| composes | combines multiple elements | +| exposes | provides interface | +| governs | enforces policy | +| observes | collects telemetry | +| hosted_on | runtime placement | +| isolated_by | tenancy mechanism | +| augmented_by | enhanced by intelligence | + +--- + +# Appendix A — VSM Perspective on Kubernetes + +*(Cybernetic Architecture Interpretation)* + +Kubernetes can be interpreted as a **cybernetic control system**. + +Mapping Kubernetes components to VSM: + +| VSM System | Kubernetes Equivalent | +| ---------- | --------------------------------- | +| System 1 | application pods | +| System 2 | scheduler, networking | +| System 3 | controllers, reconciliation loops | +| System 3* | monitoring and observability | +| System 4 | autoscaling and adaptive systems | +| System 5 | governance and policy frameworks | + +--- + +## Cybernetic Loop + +Kubernetes continuously performs: + +``` +observe → compare → reconcile +``` + +This implements Beer’s cybernetic control loop. + +--- + +## Viability Principle + +The system maintains stability by balancing: + +* operational workloads +* coordination mechanisms +* governance policies +* adaptive intelligence + +--- + +## Recursion + +Each subsystem can itself be a viable system. + +Examples: + +* a microservice architecture +* a Kubernetes cluster +* a developer platform + +Each level can contain its own: + +* operations +* coordination +* governance +* intelligence + +--- + +# Appendix B — Sources and Influences + +Orthogonal Architecture integrates ideas from: + +* Stafford Beer — Viable System Model +* Viable System Model +* Kubernetes architecture documentation +* cloud architecture frameworks +* platform engineering practices +* capability-centric architecture approaches + +Influential work includes: + +* *Platform Strategy* — Gregor Hohpe +* Kubernetes architecture documentation +* cloud architecture frameworks (Google Cloud, AWS) +* Domain-Driven Design + +--- + +# Summary + +The Orthogonal Architecture Standard provides a **formal modeling specification** integrating: + +* platform engineering +* cloud architecture +* capability modeling +* cybernetic governance +* AI integration + +Using VSM tagging ensures that architectures remain **viable, adaptive, and governable systems**. + + +xxx