Architecture: define contract representation layers

README.md

@@ -42,7 +42,7 @@ The repository naming and layering rule is defined by FlossWare engineering stan
       +-- Plans
       +-- Results / Evidence
 
-The core model is intentionally recursive. A Worker, Plan, service, builder, or other implementation is governed by the same protocol rules. A Plan may therefore compose other implementations without becoming a privileged primitive.
+The core model is intentionally recursive. Implementations are governed by the same protocol rules regardless of their internal form. A Plan may therefore compose other implementations without becoming a privileged primitive.
 
 ## Repository boundary
 
@@ -61,6 +61,17 @@ AI-specific semantics belong in loom-ai. Language implementations belong in the
 7. **Evidence is first-class.** Results and evidence are language-neutral artifacts that support verification, evaluation, and audit.
 8. **Conformance matters.** Interoperability is demonstrated by machine-checkable protocol conformance, not by matching one reference implementation's classes.
 
+## Contract representation
+
+A Loom contract is expressed through complementary layers:
+
+1. **Normative semantics** define meaning, obligations, compatibility, and observable behavior.
+2. **Machine-readable schemas** define the structure of contract artifacts. JSON Schema is the initial structural representation.
+3. **Executable conformance** verifies behavioral obligations that schemas cannot express.
+4. **Protocol bindings** define how the same contract is exposed through a transport. OpenAPI is an HTTP binding, not the definition of Loom.
+
+No single serialization or transport format defines Loom.
+
 ## What Loom does not define
 
 Loom does not require:
@@ -78,6 +89,6 @@ Loom does not require:
 
 ## Specification status
 
-The repository is intentionally specification-first. The initial work establishes the semantic vocabulary and boundaries before implementation is added.
+The repository is intentionally specification-first. The initial work establishes the semantic vocabulary, contract representation layers, and boundaries before implementation is added.
 
-See docs/specification.md for the current normative model and docs/adr/0001-language-neutral-protocol.md for the architectural decision establishing this repository as the home of Loom itself.
+See docs/specification.md for the current normative model, docs/contract-representation.md for the representation layers, and docs/adr/0001-language-neutral-protocol.md for the architectural decision establishing this repository as the home of Loom itself.

docs/adr/0007-contract-representation-layers.md

@@ -0,0 +1,28 @@
+# ADR-0007: Contract Representation Layers
+
+Status: Proposed
+
+## Context
+
+Loom must support independent implementations without making a programming language, serialization format, or transport the definition of the protocol. A contract therefore needs both precise semantics and machine-checkable representations.
+
+## Decision
+
+Loom contracts are expressed through four complementary layers:
+
+1. Normative semantic specification.
+2. Machine-readable JSON Schemas for structural artifacts.
+3. Executable conformance tests and fixtures for behavioral obligations.
+4. Protocol bindings such as OpenAPI for HTTP exposure.
+
+The semantic contract is authoritative for meaning. JSON Schema is authoritative for the structure of serialized artifacts. Conformance is authoritative for executable behavioral verification. A protocol binding is authoritative only for its transport realization.
+
+OpenAPI is therefore a binding, not the definition of Loom.
+
+The same layering applies to domain repositories such as loom-ai. Domain contracts may add domain semantics while preserving foundational Loom semantics.
+
+## Consequences
+
+Implementations can be written in Python, Java, Erlang, or another language without inheriting a language-specific contract. HTTP, messaging, and in-process implementations can expose the same semantics. Schema validation can catch structural incompatibilities, while conformance tests catch behavioral incompatibilities.
+
+The contract repository must not define semantics solely through an implementation API or OpenAPI document.

docs/contract-representation.md

@@ -0,0 +1,42 @@
+# Loom Contract Representation
+
+A Loom contract is defined at the semantic level first. Serialization and transport mechanisms are realizations of that contract, not the contract itself.
+
+Loom uses four complementary layers:
+
+1. Normative semantic specification: meaning, obligations, compatibility, and observable behavior.
+2. Machine-readable schemas: structural representation of contract artifacts.
+3. Executable conformance: verification of semantic obligations.
+4. Protocol bindings: transport-specific realization such as HTTP.
+
+No single representation is authoritative for all four layers.
+
+## Authority
+
+The contract repository is authoritative for contract identity and version semantics, operation meaning, capability and requirement semantics, compatibility and matching rules, lifecycle behavior, plan and execution semantics, result and evidence semantics, protocol-level failures, and conformance requirements.
+
+Schemas define structure, but do not replace behavioral semantics.
+
+## Machine-readable representation
+
+JSON Schema is the initial structural representation for Loom artifacts because it is language-neutral, broadly implementable, and independent of transport. Schemas live under schemas/.
+
+## HTTP and OpenAPI
+
+OpenAPI is a binding specification for HTTP exposure of Loom contracts. It is not the normative definition of Loom. An HTTP binding must preserve the semantics defined by the Loom contract.
+
+## Other bindings
+
+The same semantic contract may be realized through messaging systems, in-process APIs, or other protocols. A binding is conformant when it preserves observable contract semantics.
+
+## Behavioral conformance
+
+Conformance tests must cover behavior that schemas cannot express, including capability/requirement matching, discovery, implementation satisfaction, lifecycle transitions, builder acquisition, dependency resolution, plan resolution, execution, result semantics, evidence semantics, and protocol-level failure behavior.
+
+## AI-domain contracts
+
+loom-ai follows the same model. It defines AI-domain semantics above Loom and may provide JSON Schemas and conformance fixtures. loom-ai-python realizes those contracts in Python.
+
+## Design rule
+
+If an artifact answers what Loom means, it belongs in the contract repository. If it answers how a particular language or transport realizes Loom, it belongs in the corresponding implementation or binding.

schemas/README.md

@@ -0,0 +1,14 @@
+# Loom Schemas
+
+JSON Schemas define the machine-readable structural representation of Loom contract artifacts. They complement, but do not replace, the normative semantic specification and executable conformance suite.
+
+Initial schema set:
+
+- contract.schema.json
+- capability.schema.json
+- requirement.schema.json
+- implementation.schema.json
+- result.schema.json
+- evidence.schema.json
+
+Schemas define structure. The normative specification defines meaning. Conformance tests verify behavior. OpenAPI or another protocol description may reference these schemas when exposing Loom over a transport.

schemas/contract.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flossware.org/loom/schemas/contract.schema.json",
+  "title": "Loom Contract",
+  "type": "object",
+  "required": [
+    "id",
+    "version",
+    "operations"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}