Metadata-Version: 2.5
Name: dryv-compiler
Version: 0.0.1
Summary: Runnable Python authoring compiler/provider for Dryv
License: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: dryv-author<0.1,>=0.0.1
Requires-Dist: packaging<26,>=24
Description-Content-Type: text/markdown

# 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

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

`stdio` uses the canonical Dryv Authoring Protocol.

Request example:

```json
{"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:

```text
provider-hello
begin
batch
diagnostic
end
error
cancelled
```

## How lowering works

```text
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:

```text
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:

```text
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

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