daw-contracts

Public, versioned runtime contracts for the DAW ecosystem.

daw-contracts collects the message formats, error conventions, event shapes and discovery protocols that independent Dragons@Work programs agree on to interoperate at runtime -- language- and transport-neutral, implementable in Lua, C, Go, Rust, or anything else.

Status: In development · License: ISC

❤️ Contribute and support our work

What is daw-contracts?

A contract defines what two independent implementations must agree on at runtime -- an error format, an event shape, a discovery protocol. Repository structure, coding conventions, build systems, and project workflows don't belong here -- those live in the respective projects.

Every contract is fully implementable on its own: everything needed to implement e.g. daw_error/v1 or mainjan/v1 lives in that contract's own directory, without relying on external or internal project documentation.

What problem does it solve?

Independent programs -- different languages, different repos, different teams -- need to agree exactly at certain points: what does an error object look like? How is an event passed on? How does one cell find another? Without a central, versioned place for these contracts, either silent coupling to one implementation emerges, or every project invents its own, incompatible format.

Existing contracts

mainjan/v1              -- capability discovery and routing between cells
daw_error/v1            -- structured error object instead of an error string
daw_error_report/v1     -- error report (primary error + following errors)
daw_event/v1            -- event object
daw_event_response/v1   -- response to an event
daw_channel_log/v1      -- routing of log messages
daw_content_syslog/v1   -- structure/meaning of syslog-style content
daw_field_type/v1       -- declarative field type definition (value semantics + acquisition paths)
daw_i18n/v1             -- language-neutral translatable text resources

Status

Contracts move through three stages: draft (structure settled, no implementation depends on it yet), beta (at least one real implementation actively uses it), and stable (proven through use, no further changes within this version). Each contract's current status is in its contract.json.

Structure

<contract-name>/
  v1/
    contract.json      -- machine-readable descriptor
    specification.md   -- normative behavior (authoritative)
    CHANGELOG.md        -- history within this version
    rationale.md        -- optional, non-normative, explains the "why"
    examples/
      valid/
      invalid/
        <case>/
          input.json
          expected.json

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

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

Documentation

• TEMPLATE.md -- authoring guideline for new contracts
• GLOSSARY.md -- shared terms (cell, capability, provider, route, contract, descriptor, binding)

Contributing

Bug reports, tests, feedback, and contributions are welcome.

The primary development repository is on Forgejo: Development repository

The GitHub repository is a public mirror for better discoverability. Please submit issues and contributions to the primary repository.

Open Knowledge Needs People

We develop ideas, share knowledge, and build open source software and tools. Projects like this one don't grow on their own -- they live because people ask questions, experiment, share knowledge, find bugs, and help make things better.

You can contribute in different ways:

• reporting bugs
• reviewing code
• testing on other platforms
• improving documentation
• translating content
• or, if you like, supporting us financially

Every contribution helps us keep developing open knowledge and open source software.

Contribute and support our work →

License

Released under the ISC License as part of the Dragons@Work open source ecosystem.