Skip to content

Architecture: freeze the minimal normative semantic model and conformance contract #2

Description

@sfloess

Migrated from FlossWare/loom-ai#1001 following Grok review.

The architectural direction is established. The remaining work is to make the protocol precise enough for independent implementations.

Required definitions

  • Contract: exact identity, operations, compatibility, and required semantics
  • Implementation: what it means to claim satisfaction of a Contract
  • Capability and Requirement: matching rules, cardinality, versioning, and compatibility
  • lifecycle states and transitions
  • Plan definition versus Execution state
  • Discovery as a normative protocol surface
  • Provider/Builder acquisition semantics
  • language-neutral Results and Evidence
  • protocol-level failures

Representation

Keep the normative model independent of serialization. Evaluate OpenAPI, JSON Schema, Protobuf, messaging standards, and related mechanisms as realization layers rather than defining Loom with one markup language.

Conformance

Make machine-checkable conformance a first-class acceptance criterion covering contract satisfaction, discovery, builder acquisition, dependency resolution, plan execution, lifecycle, results, and evidence.

Architectural tests

  • loom-ai and a future loom-java can implement the same semantics.
  • HTTP/REST and JMS can expose the same contract semantics.
  • A BPEL-oriented workflow engine can use Loom for service discovery/invocation while retaining BPEL semantics above Loom.
  • A concrete platform can consume Loom and domain-specific Loom implementations without defining Loom itself.

Concrete platforms are examples of Loom consumers, not part of the Loom protocol or its architecture.

Activity

  1. sfloess commented on Sep 18, 2026

    @sfloess
    MemberAuthor

    Implemented the first contract-representation layer on branch architecture/contract-representation: normative representation guidance, JSON Schema as the initial structural format, OpenAPI explicitly treated as an HTTP binding rather than the contract, behavioral conformance as a separate layer, and ADR-0007. Initial contract schema added. Next review should validate the semantic model and schema boundaries before we expand the schema set or build loom-python.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions