@openship/protocol 0.1.0 → 0.1.1

package/README.md

@@ -15,3 +15,5 @@ if (imported.snapshot.kind === "systems") validateSystems(imported.snapshot.docu
 The package contains the exact canonical `skills/openship` schemas, examples, and references. See the repository root README for the generated-skill workflow.
 
 Version 0.1.0 replaces legacy Systems with `systemsVersion: "2.0"`: `system.layers`, `system.refinements`, and optional `system.instances`. Sources and Changes retain their 1.0 formats. Consumers must migrate; `validateSystems` explicitly rejects the legacy graph. Each layer is independently renderable, while node IDs and shared context span the entire system.
+
+Version 0.1.1 adds optional `system.domains` entries (`id`, `name`, `nodeIds`, optional `description`). Membership may overlap and span layers. Documents without domains remain valid; `openship: "1.0"` and `systemsVersion: "2.0"` do not change.

package/dist/package-meta.json

@@ -1,7 +1,7 @@
 {
   "openship": "1.0",
   "package": "@openship/protocol",
-  "packageVersion": "0.1.0",
+  "packageVersion": "0.1.1",
   "source": "https://github.com/openshipdev/openship/tree/main/skills/openship",
-  "sourceCommit": "f1338ebcb6a49927383b5b7d55be70a3d966d8d2"
+  "sourceCommit": "fad5993fea4e1a21d95ec76d5ec89621364822b8"
 }

package/dist/skill/references/examples/valid/systems-layered.json

@@ -326,6 +326,27 @@
           }
         ]
       }
+    ],
+    "domains": [
+      {
+        "id": "web",
+        "name": "Web app",
+        "nodeIds": [
+          "logical.web",
+          "p.web",
+          "provider.web"
+        ]
+      },
+      {
+        "id": "state",
+        "name": "State",
+        "nodeIds": [
+          "logical.data",
+          "technical.data",
+          "provider.data",
+          "p.web"
+        ]
+      }
     ]
   },
   "systemsVersion": "2.0"

package/dist/skill/references/openship-systems.md

@@ -65,6 +65,23 @@ Layer-local edges have `id`, `type`, `fromNodeId`, `toNodeId`, and optional meta
 
 Refinements have `id`, `fromNodeId`, and `toNodeId`. IDs MUST be unique within `system.refinements`. The source MUST belong to a later layer than the target. Thus the concrete source implements the more abstract target. Many-to-many mappings, skipped layers, and root mappings are allowed. Refinements neither imply containment nor copy configuration, documents, or runtime edges.
 
+## Domains (optional)
+
+`system.domains` MAY declare an ordered list of domains. A domain groups blocks independently of layers, containment, and refinement. Each requires a unique `id`, a nonempty `name`, and `nodeIds`; an optional nonempty `description` explains its scope. Domain IDs use the standard ID grammar. Member IDs MUST be unique within the domain and MUST reference existing nodes anywhere in the system.
+
+```json
+"domains": [
+  { "id": "web", "name": "Web app", "nodeIds": ["logical.web", "technical.web"] },
+  { "id": "state", "name": "State", "nodeIds": ["technical.web", "technical.database"] }
+]
+```
+
+A node MAY belong to zero, one, or multiple domains. Empty domains and an empty domain list are valid. Membership is explicit and is not inherited through parents or refinements. Omitting domains preserves the existing Systems behavior.
+
+Viewers SHOULD select all domains initially. When filtering, a node matches if it has no domain or belongs to any selected domain. Keep the layer root and ancestors needed to render matching nodes as structural boundaries; this does not make other children visible. Hide connections whose endpoints do not match. Domain filters are presentation controls, not access controls. Keep domain selections across layer changes.
+
+Domains are an additive capability in package 0.1.1. The envelope remains `openship: "1.0"` and `systemsVersion: "2.0"`.
+
 ## Configuration
 
 Nodes and instance bindings MAY contain a `configuration` array. Each entry requires a unique `name`, a nonempty `description`, and a boolean `required` flag. Optional `value` contains JSON data; its absence means unresolved, whereas an explicit null is a supplied value.
@@ -159,7 +176,7 @@ Artifact IDs are unique within the system.
 1. Envelope, Systems version, and embedded Sources integrity.
 2. Layer IDs, global node IDs, roots, containment, configuration and source selectors.
 3. Layer-local edges and cycle checks.
-4. Refinement endpoints and order.
+4. Domain declarations and member references; refinement endpoints and order.
 5. Instance membership, bindings, configuration, state and secret scopes.
 6. Shared document hashes, concerns, matrix/artifact references, prompts and supersession chains.
 

package/dist/skill/references/schemas/systems.schema.json

@@ -77,7 +77,13 @@
         },
         "nodes": false,
         "edges": false,
-        "rootNodeId": false
+        "rootNodeId": false,
+        "domains": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/domain"
+          }
+        }
       },
       "additionalProperties": true
     },
@@ -577,6 +583,35 @@
         }
       },
       "additionalProperties": true
+    },
+    "domain": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "nodeIds"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "nodeIds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/id"
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": true
     }
   },
   "additionalProperties": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openship/protocol",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Canonical OpenShip 1.0 types, validators, consumer helpers, schemas, and skill assets.",
   "type": "module",
   "license": "MIT",

package/src/index.d.ts

@@ -21,7 +21,8 @@ export interface SystemsLayer { id: string; name: string; role: "logical" | "tec
 export interface SystemsRefinement { id: string; fromNodeId: string; toNodeId: string; [key: string]: unknown }
 export interface SystemsBinding { nodeId: string; resourceId?: string; configuration?: SystemsConfiguration[]; state?: { appliedMigration?: string; snapshot?: { ref: string; capturedAt: string; digest?: string } }; [key: string]: unknown }
 export interface SystemsInstance { id: string; name: string; environment: string; layerId: string; bindings: SystemsBinding[]; [key: string]: unknown }
-export interface SystemsGraph { id: string; name: string; layers: SystemsLayer[]; refinements: SystemsRefinement[]; instances?: SystemsInstance[]; metadata?: Record<string, unknown>; context?: Record<string, unknown>; [key: string]: unknown }
+export interface SystemsDomain { id: string; name: string; description?: string; nodeIds: string[]; [key: string]: unknown }
+export interface SystemsGraph { id: string; name: string; layers: SystemsLayer[]; refinements: SystemsRefinement[]; domains?: SystemsDomain[]; instances?: SystemsInstance[]; metadata?: Record<string, unknown>; context?: Record<string, unknown>; [key: string]: unknown }
 export interface SystemsDocument { openship: "1.0"; capability: "systems"; systemsVersion: "2.0"; source: { manifest: SourcesManifest; bundle: SourcesBundle; [key: string]: unknown }; system: SystemsGraph; [key: string]: unknown }
 export interface VerifiedSourceFile { metadata: SourceFileMetadata; bytes: Uint8Array }
 export interface VerifiedSources { manifest: SourcesManifest; bundle: SourcesBundle; files: VerifiedSourceFile[]; decodedBytes: number }

package/src/index.js

@@ -326,6 +326,16 @@ export function validateSystems(value, options = {}) {
     }
     for (const type of ["Dataflow", "Dependency"]) assertAcyclic([...local.keys()], edges.filter((edge) => edge.type === type).map((edge) => [edge.fromNodeId, edge.toNodeId]), `${at}.edges[${type}]`);
   }
+  const domains = array(system.domains === undefined ? [] : system.domains, "$.system.domains");
+  unique(domains.map((domain) => identifier(object(domain, "$.system.domains").id, "$.system.domains.id")), "$.system.domains");
+  for (const domain of domains) {
+    const at = `$.system.domains.${domain.id}`;
+    string(domain.name, `${at}.name`);
+    if (domain.description !== undefined) string(domain.description, `${at}.description`);
+    const members = array(domain.nodeIds, `${at}.nodeIds`);
+    unique(members, `${at}.nodeIds`);
+    for (const nodeId of members) if (!nodeById.has(nodeId)) fail(`${at}.nodeIds`, "must reference existing system nodes");
+  }
   const refinements = array(system.refinements, "$.system.refinements");
   unique(refinements.map((ref) => identifier(object(ref, "$.system.refinements").id, "$.system.refinements.id")), "$.system.refinements");
   for (const ref of refinements) {