dryv-compiler

dryv-compiler is the Python Author compiler/provider for Dryv.

It captures the typed AuthorState snapshot from the project's dryv.app(...) (in the project's own Python, via execution/bootstrap.py), resolves author handles to canonical JSON Pointers, and lowers the states into dryv.ir/v1alpha1. The engine's contract models and validate_runtime_ir are the final authority; the compiler never accepts IR the engine rejects.

Commands

dryv-py doctor ./dryv.py
dryv-py compile ./dryv.py
dryv-py stdio

stdio uses the canonical Dryv Authoring Protocol.

Request example:

{"type":"compile-request","session_id":"build-1","entrypoint":"./dryv.py","protocol_versions":["dryv.authoring/v1alpha1"],"runtime_ir_versions":["dryv.ir/v1alpha1"],"batch_size":64}

Provider messages use canonical types such as:

provider-hello
begin
batch
diagnostic
end
error
cancelled

How lowering works

dryv.app(...).snapshot()        typed AuthorState (dryv_author.state)
    ↓ mapping/index.py          identities → canonical names and pointers
    ↓ mapping/encode.py         states → canonical JSON; query "*" expansion;
                                projection selections → canonical projection fields
    ↓ mapping/compile.py        DryvIR.model_validate + validate_runtime_ir
    ↓ protocol/records.py       one record per registry entry, with author origins

Author states mirror canonical shapes, so lowering is structural. Registry names are group-qualified (group.Name). The app itself is emitted as the application named by its key.

Parity: tests/test_compiler.py compiles tests/fixtures/faidibiz_app.py (a port of the TypeScript faidibiz example) and, when bun is available, asserts the same semantic digest as the TypeScript compiler.

Canonical naming

The compiler must normalize Dryv-owned wire vocabulary regardless of Python Author implementation details:

Dryv-owned object keys     -> lower_snake_case
Dryv-owned fixed values    -> lower-kebab-case
Authored identifiers       -> preserve exactly
Reserved/external tokens   -> preserve governing spelling

Canonical examples include:

session_id
runtime_ir_version
property-primitive
property-generic
provider-hello
$ref

The compiler must never apply a blind recursive case converter because authored names and standards-owned values are opaque.

See .docs/reference/ir/naming.md and .docs/reference/ir/properties.md.

Responsibility boundary

The compiler may:

• validate Author/compiler compatibility;
• inspect and execute the Python authoring environment;
• validate Python Author state;
• resolve symbolic relationships;
• classify implementation-specific declarations into canonical concepts;
• normalize canonical key/value spelling;
• compile to Runtime-owned IR contracts;
• stream deterministic Authoring Protocol records;
• preserve source/provenance diagnostics.

It must not:

• create a competing semantic model;
• generate application source code;
• select template packs;
• choose output paths;
• write generated project files;
• own persisted Runtime serialization.

Equivalent Python and TypeScript authored meaning must converge on equivalent canonical Runtime IR.

Development

uv sync
uv run ruff format .
uv run ruff check --fix .
uv run mypy
uv run pytest
uv build