daw-contracts

Public, versioned runtime contracts for the DAW ecosystem.

A contract defines what independent implementations must agree on to interoperate at runtime — a message format, an error convention, an event shape, a discovery protocol. Language- and transport-neutral: a contract may be implemented in Lua, C, Go, Rust, or any other language, over any transport.

What belongs here

Contracts that a program actually speaks, sends, receives, or returns at runtime. If two independent implementations must agree on it at runtime to interoperate, it belongs here.

mainjan/v1     -- capability discovery and routing between cells
daw_error/v1   -- structured error return contract
daw_event/v1   -- event contract
daw_log/v1     -- logging contract

What does not belong here

Repository structure, coding conventions, build systems, and project workflows are outside the scope of this repository. Design rationale and implementation notes are intentionally kept separate from the contracts themselves.

This repository is meant to be self-contained: everything needed to implement a contract published here — mainjan/v1, daw_error/v1, daw_event/v1, or any other — should be found within it, without relying on external or internal project documentation.

Structure

<contract-name>/
  v1/
    contract.json      -- language-neutral, machine-readable descriptor
    specification.md   -- normative behavior and semantics (authoritative)
    CHANGELOG.md        -- history within this version
    examples/
      valid/
      invalid/
        <case>/
          input.json
          expected.json

bindings/
  lua/                  -- language-specific mapping, not part of the contract
  ...

A contract's version is fixed in its path. v1 never changes incompatibly; a breaking change becomes v2.

Naming

• <project>/vN — owned and defined by one project (e.g. mainjan/v1, anagild_snapshot/v1).
• daw_<name>/vN — owned by no single project, binding for the whole ecosystem (e.g. daw_error/v1, daw_event/v1).

TEMPLATE.md is not a contract itself — it is the authoring guideline for anyone proposing a new one: directory layout, required files, naming, and versioning rules. See TEMPLATE.md for details.

See GLOSSARY.md for shared terms used across contracts (cell, capability, provider, route, contract, descriptor, binding).

Status

Contracts move through three stages: draft (structure settled, no implementation depends on it yet, changes possible any time), beta (at least one implementation actively uses it, changes still possible but must not happen silently), and stable (proven through use, no further changes within this version -- a breaking change becomes a new version).

License

See LICENSE.