Definitions as resources with ACID-compliant runtime validation

Summary

Make the top-level definitions: section syntactic sugar for resources.definitions — a reserved resource whose children are JSON Schemas stored in the CRDT document. After desugaring, $ref: "#/definitions/Task" maps directly to the JSON Pointer /definitions/Task in the resource document.

Definitions become fully mutable at runtime. Agents with appropriate ACL permissions can add, modify, or remove schemas via resources-write. Schema changes trigger eager revalidation of all dependent resources; the write is rejected and atomically reverted if any resource would become invalid.

Design

Definitions as Resources — Design (wiki)

Key decisions

  • Fully mutable definitions at runtime via resources-write
  • Eager revalidation of dependent resources on definition change (reject on failure)
  • Standard ACL rules — agents need explicit /definitions read/write permissions
  • ACID compliance using existing state_frontiers() / revert_to() rollback mechanism
  • Pipeline refactor: parse → validate → expand → desugar → hydrate (splits current expand_compose_file into three phases)
  • SchemaRegistry struct encapsulates resource-to-schema tracking, replacing the raw HashMap

Prerequisites

  • #93 (closed) must be completed first (runtime schema validation for resources-write)

Acceptance criteria

  • definitions: top-level section desugars into resources.definitions entries during the desugar phase
  • definitions is a reserved resource name; validated to not exist in the user's resources section
  • After desugaring, the definitions field on ComposeFile is cleared (single source of truth)
  • Definitions are stored in the CRDT at /definitions/<Name> and accessible via resources-read
  • Loader pipeline is refactored into: parse → validate → expand → desugar → hydrate
  • Serializing the ComposeFile after validate is idempotent with the input
  • SchemaRegistry struct replaces raw resource_metadata HashMap in ResourcesServer
  • Writing to /definitions/* validates new schema against CRDT-safe meta-schema
  • Writing to /definitions/* eagerly revalidates all dependent resources; reverts on failure
  • Deleting a definition that is still referenced by resources is rejected
  • Standard ACL enforcement on /definitions paths (read and write)
  • Error messages identify the definition, affected resource, and specific schema violation
  • Existing tests continue to pass; new tests cover all validation scenarios
  • Example compose file updated to demonstrate definitions accessible as resources
Edited by Jean-Marc Le Roux