WellManifest

AI Cost Tracking

• 🤖 LLM usage: $0.0135 (10 commits)
• 👤 Human dev: ~$145 (1.5h @ $100/h, 30min dedup)

Generated on 2026-08-04 using openrouter/qwen/qwen3-coder-next

WellManifest is an alpha protocol and polyglot runtime for manifests, typed configuration, procedural policy, URI Process orchestration and format negotiation. One server can receive JSON, YAML, HCL-like data, typed WellManifest, policy DSL or proto3 IR and return the representation preferred by the receiving side.

Version 0.1.0 is a functional reference implementation and architecture package. The Python HTTP/WebSocket runtime, JSON/YAML/TOML conversion, the four status syntaxes, JSON Schema validation, URI Process authorization, CQRS/ES event log, situation profiles and JavaScript SDK are executable and tested. Rust/WASM/PyO3/N-API, MQTT and gRPC are supplied as buildable contracts and container targets; they are not yet feature-parity implementations of all dialects. The packaged local evidence is 23 Python tests, 4 Node tests and a multi-client HTTP/Node/RPi/event-log E2E run.

Why

A browser may prefer JSON, an operations service YAML, an existing tool HCL, a strongly typed module WellManifest, a microcontroller a compact protobuf message, and a governance repository a procedural RULE/WHEN/DO/FORBID/ASSERT policy. WellManifest separates those surface formats from a common envelope, IR, diagnostics and capability contract.

JSON / YAML / TOML / HCL / typed@1 / policy-sh@1 / proto3
                         │
                         ▼
              WellManifest Document + IR
                         │
       schema validation │ diagnostics │ authorization
                         ▼
              WellManifest Envelope v1
          HTTP │ WebSocket │ MQTT v5 │ gRPC
                         │
                         ▼
 frontend │ backend │ RPi/IoT │ digital twin │ remote runtime

Fast start

Local reference runtime

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
wellmanifest capabilities
wellmanifest convert examples/dialects/status.yaml --from yaml --to json
wellmanifest validate examples/dialects/status.json --schema schemas/status.schema.json
wellmanifest serve --port 8080

Docker sidecar

docker compose up --build runtime www
curl http://localhost:8080/healthz

Add the runtime to an existing Compose project:

services:
  wellmanifest:
    build:
      context: ./vendor/wellmanifest
    environment:
      WELLMANIFEST_DEFAULT_CONTRACT: contract:dev
    ports:
      - "8080:8080"

Any language can then use HTTP:

curl -fsS http://localhost:8080/v1/convert \
  -H 'content-type: application/json' \
  -d '{
    "source":"status:\n  value: SUCCEEDED\n",
    "source_dialect":"yaml",
    "target_dialect":"json",
    "projection":"data"
  }'

Four supported status forms

All four forms normalize to the same data model. The first and fourth remain HCL-shaped; split and inline typing belong to typed@1.

status {
  operation = "002-cv-pdf2md"
  value = "SUCCEEDED"
  errors = []
}

status {
  operation: FolderOperationId
  operation = "002-cv-pdf2md"
  value: OperationState
  value = "SUCCEEDED"
  errors = []
}

status {
  operation: FolderOperationId = "002-cv-pdf2md"
  value: OperationState = "SUCCEEDED"
  errors: [OperationError] = []
}

status {
  operation = "002-cv-pdf2md" #folder
  value = "SUCCEEDED" #state
  errors = []
}

The comment form is accepted as a legacy hint and emits WARNING WM-TYPE-102; schema or a typed declaration remains the source of truth. Canonical typed output is field: Type = value.

URI Process

import {UrirunProcessClient} from "@wellmanifest/sdk";

const client = new UrirunProcessClient({
  nodeUrl: "http://localhost:8080",
  contractRef: "contract:dev",
});

const result = await client.execute(
  "youtube://channel/video/query/list",
  {channel: "ours"},
  {allowedUriProcesses: ["youtube://*"], runId: "ticket-002:youtube:1"},
);

youtube://* is a permission pattern. It is never an executable URI. The server resolves production authority from a Contract AQL reference, checks the concrete URI and appends requested/completed/failed events.

Package and service matrix

Repository map

src/wellmanifest/       Python reference runtime
packages/js/            browser and Node SDK
crates/                 Rust, CLI, WASM, PyO3 and N-API crates
proto/                  gRPC/protobuf contract
schemas/                JSON Schema 2020-12 contracts
examples/               HCL, typed DSL, policy, SOA, POA, IoT, twins, LLM
www/                    project landing page
Dockerfile              HTTP/WebSocket runtime image
compose.yml             runtime, MQTT, gRPC, site and firmware simulator
docs/                   architecture and operational documentation
tests/                  local and source-compatibility tests

Commands

make test              # Python + Node tests
make serve             # HTTP/WebSocket gateway
make proto             # generate Python gRPC stubs
make e2e               # local multi-client E2E
make package           # source ZIP and tar.gz

Security boundary

WellManifest is not a generic remote shell. The reference service:

• accepts only concrete URI Processes;
• treats wildcards as contract scopes only;
• executes registered adapters, never arbitrary source code;
• supports idempotent run IDs and append-only events;
• keeps digital twins read-only and unable to expand authority;
• plans HTTP and GPIO operations without performing mutations by default;
• returns stable ERROR, WARNING and INFO diagnostics.

See docs/SECURITY.md and docs/URI_PROCESS.md.

Documentation

• Architecture
• Protocol and content negotiation
• Dialects and four syntaxes
• Transport contracts
• Generated HTTP/OpenAPI API
• Plugin and external-language adapter model
• URI Process and Contract AQL
• SOA, POA, CQRS and Event Sourcing
• Digital twins and situation profiles
• Firmware and Raspberry Pi
• LLM integration
• Docker and deployment
• E2E testing
• Compatibility matrix
• Implementation status and limitations
• Roadmap

Provenance of the governance examples

The PyPI distribution name is wellmanifest. The external well package is not a hard dependency: wellmanifest.integrations.well detects it only when a compatible installation is present, without inventing or binding to an undocumented API.

The fixtures under tests/fixtures/governance/ are copies of the supplied wellmanifest/new-project manifest, intent, schemas, diagnostics, stack profiles and CONTRIBUTING.md. Tests prove that the current JSON instances remain valid and the normative DSL blocks can be imported into policy IR.

License

Licensed under Apache-2.0.