theway-contract 0.1.22

theway shared leaf contract β€” raw session persistence interfaces, persisted DAG snapshots, sidecar models, and path layout; no engine, protocol, or runtime dependencies.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# theway-contract

English | [δΈ­ζ–‡](README.zh.md)

`theway-contract` is the workspace leaf for data that must cross runtime, persistence, and protocol implementations without importing any of them. It defines serializable records, storage traits, automation sidecar models, session identifiers, and the `~/.theway` path layout; it contains no agent engine, database backend, or network transport.

## Public modules

| Module | Responsibility |
|---|---|
| [`config`](src/config.rs) | Resolve the base directory and derive stable per-working-directory paths. |
| [`session`](src/session.rs) | Define raw stored session records plus the asynchronous `SessionReader` and `SessionStore` traits. |
| [`session_id`](src/session_id.rs) | Validate and normalize persisted session identifiers. |
| [`dag`](src/dag.rs) | Define persisted DAG run and node snapshots and their state-file path. |
| [`triggers`](src/triggers.rs) | Define session-scoped dynamic-trigger and cron sidecar records. |
| [`extension`](src/extension/mod.rs) | Define the single unversioned runtime-extension ABI: manifests, lifecycle/action envelopes, durable entries, trust records, diagnostics, and client-neutral contributions. |

`theway-core` converts typed runtime session entries to these raw records. `theway-storage` implements the persistence traits, while `theway-transport` reuses or re-exports the client-visible data that belongs at this leaf.

The checked-in TypeScript declarations and JSON Schemas shipped by the workspace plugin development SDK are generated from the Rust extension contracts. Regenerate them with `cargo run -p theway-contract --example generate_extension_artifacts -- sdks/plugin/abi`; the extension contract tests regenerate into a temporary directory and reject drift.

The unversioned ABI keeps lifecycle envelopes, hook classes and actions, branch-local durable entries, diagnostics, trust records, commands, and client contributions engine-neutral. Sensitive values, executable runtime objects, and ABI version selectors have no field in these records.

## Documentation

- [Architecture and invariants](docs/architecture.md)

## Validation

```bash
cargo test -p theway-contract
cargo doc -p theway-contract --no-deps
```