@openship/protocol 0.1.0 → 0.1.2

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.2",
   "source": "https://github.com/openshipdev/openship/tree/main/skills/openship",
-  "sourceCommit": "f1338ebcb6a49927383b5b7d55be70a3d966d8d2"
+  "sourceCommit": "11f343e2e3418c0a2bb473d229099e4f9431f801"
 }

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

@@ -38,7 +38,11 @@ Any positive number of layers is supported. Each is an explicit graph, not a gen
 
 ## Nodes, containment and sources
 
-Node kinds are `Root`, `Block`, `Store`, `Host`, `Container`, `Process`, and `Library`. Block describes a capability; Store describes persistent data. The other kinds describe a system boundary, execution environment, grouped runtime, executable component, and reusable dependency respectively.
+Node kinds are `Root`, `Block`, `Store`, `Host`, `Container`, `Process`, `Contract`, and `Library`. Block describes a capability; Store describes persistent data. Root, Host, Container, Process, and Library describe a system boundary, execution environment, grouped runtime, executable component, and reusable dependency respectively.
+
+A **Contract** is a Process running on consensus: its execution and state transitions are governed by the consensus rules of its network. “Smart” is implied. Use `Contract` for consensus-executed components and `Process` for ordinary runtimes, including RPC servers and transaction relayers. Contract follows the same containment, connection, refinement, configuration, and instance-binding rules as Process; database `state` remains exclusive to Store bindings. The network can be described by a parent Host and configuration or metadata.
+
+`Contract` extends the node-kind vocabulary without changing the `openship: "1.0"` or `systemsVersion: "2.0"` envelope. Consumers with the previous closed vocabulary must update before accepting documents containing Contract.
 
 ```json
 {
@@ -65,6 +69,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 +180,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
     },
@@ -118,6 +124,7 @@
             "Host",
             "Container",
             "Process",
+            "Contract",
             "Library",
             "Block",
             "Store"
@@ -577,6 +584,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.2",
   "description": "Canonical OpenShip 1.0 types, validators, consumer helpers, schemas, and skill assets.",
   "type": "module",
   "license": "MIT",

package/src/index.d.ts

@@ -10,7 +10,7 @@ export interface SourcesManifest { openship: "1.0"; capability: "sources"; diges
 export interface SourcesBundle { openship: "1.0"; capability: "sources"; digest: string; files: Record<string, { encoding: OpenShipEncoding; content: string; [key: string]: unknown }>; [key: string]: unknown }
 export interface DiscoveryAgent { summary: string; instructions: string; skill: string; [key: string]: unknown }
 export interface DiscoveryDocument { openship: "1.0"; capability: "discovery"; project: { name: string; description: string; [key: string]: unknown }; agent: DiscoveryAgent; page?: string; capabilities: { sources: { description: string; manifest: string; bundle: string; mcp?: string; [key: string]: unknown }; systems?: { description: string; document: string; [key: string]: unknown }; changes?: { description: string; policy: string; submit: string; status: string; [key: string]: unknown }; [key: string]: unknown }; [key: string]: unknown }
-export type SystemsNodeKind = "Root" | "Block" | "Store" | "Host" | "Container" | "Process" | "Library";
+export type SystemsNodeKind = "Root" | "Block" | "Store" | "Host" | "Container" | "Process" | "Contract" | "Library";
 export type SystemsNodeOwnership = "first_party" | "third_party";
 export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 export interface SystemsConfiguration { name: string; description: string; required: boolean; sensitive?: boolean; value?: JsonValue; secretRef?: { nodeId: string; key: string }; }
@@ -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

@@ -299,7 +299,7 @@ export function validateSystems(value, options = {}) {
       const path = `${at}.nodes[${i}]`, node = object(rawNode, path);
       identifier(node.id, `${path}.id`);
       if (nodeById.has(node.id)) fail(`${path}.id`, "must be globally unique");
-      if (!["Root", "Block", "Store", "Host", "Container", "Process", "Library"].includes(node.kind)) fail(`${path}.kind`, "invalid node kind");
+      if (!["Root", "Block", "Store", "Host", "Container", "Process", "Contract", "Library"].includes(node.kind)) fail(`${path}.kind`, "invalid node kind");
       string(node.name, `${path}.name`);
       const metadata = object(node.metadata, `${path}.metadata`);
       if (!["first_party", "third_party"].includes(metadata.ownership)) fail(`${path}.metadata.ownership`, "must be first_party or third_party");
@@ -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) {