# asolaria

A command-line tool for the Asolaria Aether stack. It lets you generate Ed25519 keys, sign and
verify files, run the tighten-only gate verdict from `gate/verdict` over an envelope file, and
(`observe`) compute the gate scores from observed graph events with the trained L0 EdgeLevelGNN,
without writing Rust. Results are pipe-delimited HBP rows ending in `json=0`.

## Install from source

Requires Rust 1.81 or newer. Clone the repository, then from its root:

```
cargo install --locked --path cli
```

`--locked` builds with the reviewed `Cargo.lock`. Without it, `cargo install` re-resolves
dependencies to their newest versions, some of which no longer build on Rust 1.81. The binary is
installed to `~/.cargo/bin`, which must be on your `PATH`.

## Walk-through

The seed file is a secret, so keep it outside the checkout (here, in your home directory):

```
asolaria keygen --out ~/asolaria-me.seed          # KEYGEN|public=<hex>|seed_file=...|json=0
asolaria sign --key ~/asolaria-me.seed cli/examples/envelope.hbp   # SIGN|sig=<hex>|public=<hex>|bytes=<n>|json=0
asolaria verify --pub <public> --sig <sig> cli/examples/envelope.hbp   # VERIFY|ok=1|json=0
asolaria gate cli/examples/envelope.hbp           # GATE|verdict=PROCEED|...|signature=unchecked|...
asolaria gate cli/examples/envelope.hbp --pub <public> --sig <sig>     # ...|signature=verified|...
asolaria pubkey --key ~/asolaria-me.seed          # PUBKEY|public=<hex>|json=0
asolaria observe --events model/l0-edge/tests/fixtures/events.hbp cli/examples/observe-envelope.hbp
```

The last line prints one `GATE` row; see [`observe`](#observe) below.

To capture fields from a row in a shell script, split on `|`:

```
ROW=$(asolaria sign --key ~/asolaria-me.seed cli/examples/envelope.hbp)
SIG=$(echo "$ROW" | cut -d'|' -f2 | cut -d= -f2); PUB=$(echo "$ROW" | cut -d'|' -f3 | cut -d= -f2)
```

`-` in place of a file reads stdin. Signatures cover the exact bytes of the file, so any edit,
including whitespace or a comment line, invalidates them. Options also accept `--opt=value`, and
`--` ends option parsing. `asolaria <command> --help` (or `help <command>`) prints that command's
usage; no arguments, `help`, `-h` or `--help` print the overview (exit 0); `-V` and `version`
are aliases for `--version`.

`-h` or `--help` anywhere before `--` prints help with exit 0 and no `GATE` row, including where a
file path goes. A wrapper that runs `gate` or `observe` therefore passes `--` before file paths
(`asolaria observe --events "$E" -- "$F"`) and requires the `GATE` row, not only exit 0.

## Commands

| Command | Output |
|---|---|
| `keygen --out <seed-file>` | 32 bytes of OS randomness written as 64 lowercase hex characters and a newline. Refuses to overwrite an existing file; on Unix the file is created with mode 0600. Prints the public key only, never the seed. |
| `pubkey --key <seed-file>` | The public key of a seed file (exactly 64 hex characters, optional trailing newline). |
| `sign --key <seed-file> <file\|->` | Ed25519 signature (128 hex) over the exact input bytes. |
| `verify --pub <64 hex> --sig <128 hex> <file\|->` | `VERIFY\|ok=1` or `VERIFY\|ok=0\|reason=signature_invalid` / `reason=key_malformed`. |
| `gate <envelope\|-> [--pub <hex> --sig <hex>]` | `GATE\|verdict=…\|hookwall=…\|spawn_gate=…\|tier_gate=…\|fischer=…\|input_guard=…\|signature=…\|reason=…\|json=0` |
| `observe --events <events\|-> <envelope\|-> [--pub <hex> --sig <hex>]` | The `GATE\|…` row of `gate` with `score`, `l0_real`, `mark` and `reverse_risk` after the verdict (see [`observe`](#observe)) |
| `help`, `--version` | Usage summary; `VERSION\|name=asolaria\|version=…\|json=0`. |

`gate` with `--pub`/`--sig` first verifies the signature over the exact envelope bytes. A signature
that does not verify, or a public key that is not a curve point, makes the verdict BLOCK
(`signature=invalid`, exit 4) for any envelope that parses. It can only tighten the result, never
loosen it. If the signature is invalid *and* the envelope does not parse, the row is still BLOCK
(exit 4) with every gate reported as `UNEVALUATED`. A valid or absent signature over an envelope
that does not parse is a usage error (exit 2, no GATE row). Without `--pub`/`--sig` the row says
`signature=unchecked`, and the verdict is only as trustworthy as wherever the envelope came from.

`signature=verified` means only that the exact bytes were signed by the private key matching the
`--pub` you passed. Take `--pub` from a trusted, pinned source, never from the same channel as the
envelope: anyone can sign an envelope (with any `caller_tier`) using their own key.

In `reason` and `seed_file`, `%`, `|` and control characters are percent-encoded (`%25`, `%7C`,
`%0A`, …), so a row is always one line with a fixed set of fields. Errors go to stderr as
`ERROR|kind=<usage|io>|reason=<escaped>|json=0`.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success; `gate` or `observe` verdict PROCEED |
| 1 | `verify` failed, an I/O error, or the result row could not be written (closed pipe, full disk) |
| 2 | Usage error: bad arguments, malformed hex or seed file, `keygen` target already exists, envelope or events parse error, envelope over 1 MiB, or an `observe` envelope with a score key or without `payload` |
| 3 | `gate` or `observe` verdict HOLD |
| 4 | `gate` or `observe` verdict BLOCK |

Only exit 0 means PROCEED. Treat every other exit code (including 1, 2 and any crash) as
do-not-proceed. If the GATE row cannot be written, a HOLD or BLOCK keeps exit 3 or 4 and a PROCEED
becomes exit 1. If the KEYGEN row cannot be written, the new seed file is removed.

## Envelope format

One `key=value` per line, at most 1 MiB in total. Lines that are blank or whose first non-space
character is `#` are ignored. The key must match exactly (no surrounding spaces); the value is
everything after the first `=`, taken verbatim (a trailing `\r` is dropped). Unknown keys,
duplicate keys, a missing required key, a line without `=`, non-UTF-8 input and malformed values
are all usage errors (exit 2): nothing is guessed. Control characters (tab, CR inside a line, ESC,
NUL, …), Unicode bidi controls and a leading byte order mark are rejected on every line,
comments included, so an envelope cannot display differently from how it parses; save files as
UTF-8 without a BOM. Integers are plain decimal digits; flags are `0`, `1`, `false` or
`true`. Defaults are the strict values, not `FischerEnvelope::default()` (which pre-fills proof
paths). See [`examples/envelope.hbp`](examples/envelope.hbp) for a clean envelope that composes to
PROCEED.

| Key | Field | Type | Default |
|---|---|---|---|
| `slot` | `VerifiedEnvelope::slot` | integer 0..=255 (64 and above makes hookwall BLOCK) | required |
| `syscall_no` | `syscall_no` | integer 0..=255 | required |
| `caller_pid` | `caller_pid` | integer, u64 | required |
| `hook_tier` | `hook_tier` | `micro`, `cosign`, `firmware` | required |
| `caller_tier` | `caller_tier` | `public`, `restricted`, `stealth`, `hidden`, `shadow`, `secret`, `sovereignty` | required |
| `target_tier` | `target_tier` | same as `caller_tier` | required |
| `event_tags` | `event_tags` | comma-separated, no empty items | empty list |
| `forward_score_q` | `forward_score_q` | integer 0..=1000 | required |
| `reverse_risk_q` | `reverse_risk_q` | integer 0..=1000 | required |
| `pid` | `fischer_envelope.pid` | text | unset (Fischer BLOCKs `missing_pid`) |
| `actor` | `fischer_envelope.actor` | text | empty |
| `verb` | `fischer_envelope.verb` | text | empty (Fischer BLOCKs `missing_verb`) |
| `target` | `fischer_envelope.target` | text | empty |
| `payload` | `fischer_envelope.payload` | text | empty |
| `payload_json_true` | `fischer_envelope.payload_json_true` | flag | `0` |
| `hbp_path` | `fischer_envelope.hbp_path` | text | unset |
| `sidecar_plan` | `fischer_envelope.sidecar_plan` | text | unset |
| `ledger_path` | `fischer_envelope.ledger_path` | text | unset |
| `tuple` | `fischer_envelope.tuple` | text | unset |
| `cube_47d` | `fischer_envelope.cube_47d` | text | unset |
| `cosign` | `fischer_envelope.cosign` | text | unset |
| `halt_path` | `fischer_envelope.halt_path` | text | unset |
| `authority_jump` | `fischer_envelope.authority_jump` | flag | `0` |
| `recursive_consent` | `fischer_envelope.recursive_consent` | flag | `0` |
| `operator_witness_required` | `fischer_envelope.operator_witness_required` | flag | `0` |
| `operator_witness` | `fischer_envelope.operator_witness` | flag | `0` |
| `composite` | `fischer_score.composite` | text; accepted for completeness, ignored by every gate and not shown in output | `0` |
| `l0_real` | `fischer_score.l0_real` | flag | `0` |
| `shannon_q` | `fischer_score.shannon_q` | integer 0..=1000 (per-mille) | `0` |
| `shannon_above` | `fischer_score.shannon_above` | flag | `0` |
| `g4_state` | `fischer_score.g4_state` | `UNKNOWN`, `EDGE_MINED`, `PATH_FOUND`, `CONVERGED`, `MISTAKE_FLAGGED` (anything else parses, then the input guard BLOCKs it) | `UNKNOWN` |
| `fischer_strict` | `VerifiedEnvelope::fischer_strict` | flag | `0` |

An optional text key that is present with an empty value (`cosign=`) is set to the empty string,
which every gate treats like unset. What each gate checks is described in
[`../gate/verdict/README.md`](../gate/verdict/README.md).

## observe

`asolaria observe --events <events> <envelope> [--pub <hex> --sig <hex>]` computes every
GNN-derived gate input itself, from a file of observed graph events and the request in the
envelope, and then runs the same five gates as `gate`. It takes no other options. It runs in
process in Rust (`gate/observed` over `model/l0-edge`): no Python, torch, Node, JSON or network.

The **envelope** uses the format above with every key except the seven scores:
`forward_score_q`, `reverse_risk_q`, `composite`, `l0_real`, `shannon_q`, `shannon_above` and
`g4_state`. Any of them is a usage error (exit 2) naming the key and its line. The required keys
are `slot`, `syscall_no`, `caller_pid`, `hook_tier`, `caller_tier`, `target_tier` and `payload`.
asolaria-hookwall.mjs:70 scores `envelope.payload` when it is a string and
`JSON.stringify(envelope.payload ?? envelope.verb ?? '')` otherwise; `observe` scores the string
form only, so an envelope without `payload` is a usage error (exit 2). An empty `payload=` is
scored as the empty string, as upstream scores an empty string payload. In the request,
`actor -> target` is the edge the L0 model scores (graph node ids), and `pid` and `payload` are
what asolaria-score scores (`score(pid, content)`). See
[`examples/observe-envelope.hbp`](examples/observe-envelope.hbp).

The **events** file holds one row per graph-runtime event,
`EVENT|actor=<id>|actor_type=<t>|target=<id>|target_type=<t>|risk=<integer>|status=<s>`, with
`#` comments and blank lines ignored. Every key is optional, and values are percent-escaped
(`%25`, `%7C`, `%3D` and every control byte). The full format and the parser's refusals are in
[`../model/l0-edge/README.md`](../model/l0-edge/README.md). `-` reads either file from stdin
(not both). The whole events file is read into memory; the parser accepts at most 1,000,000
events.

What it computes, in order:

1. Node features for every id in the events (`extractNodeFeatures`, gnnDataExport.js:25-64),
   scaled as `train_baseline.py` scales them.
2. The L0 EdgeLevelGNN forward that the running server (`inference_server.py`, port 4792) runs,
   on the request asolaria-score sends: nodes `[actor, target]`, edge `[[0, 1]]`. When the actor
   or the target never appears in the events there is no L0 reading, as when :4792 does not
   answer (`l0_real=false`). At a `toFixed(4)` rounding midpoint the L0 value can be one e4 unit
   from what torch's float32 output gives (measured in
   [`../model/l0-edge/README.md`](../model/l0-edge/README.md#the-forward)).
3. The asolaria-score signals: `l0` (when present), Shannon of the payload and the sha baseline
   of `pid|payload`. L4, G1, G2 and G3 have no service in this stack and are absent.
4. The composite (asolaria-score.mjs:154-163) and `reverseGain` (lines 104-108).
5. The gate envelope: `forward_score_q = composite_e4 / 10` (rounded down) and
   `reverse_risk_q = reverse_risk_e4 / 10` (rounded up) for the spawn gate, where `_e4` values
   are the four decimals of `toFixed(4)` as integers (units of 1/10000), and the Fischer
   score (`composite`, `l0_real`, `shannon_q`, `shannon_above`, `g4_state=UNKNOWN`). Every other
   field comes from the envelope.

`observe` prints the `GATE` row of `gate` with four keys after the verdict, rendered as the
hookwall observation row renders them (asolaria-hookwall.mjs:48-51): `score` is JavaScript
`String` of the composite (`sc.composite`), `l0_real` is `true` or `false`, `mark` is
`FORWARD_GNN_MARK_GENIUS` when `reverseGain` promotes and `REVERSE_GAIN_MARK_MISTAKE` otherwise
(asolaria-score.mjs:107), and `reverse_risk` is `+(1 - composite).toFixed(4)`. A failed signature
over an envelope or events file that does not parse gives the BLOCK row of `gate`, every gate
`UNEVALUATED`, without these keys. The L0 reading and the separate signals are not printed;
`gate/observed` returns them to Rust callers. With the
SYNTHETIC events fixture (`model/l0-edge/tests/fixtures/events.hbp`), from the repository root:

```
$ asolaria observe --events model/l0-edge/tests/fixtures/events.hbp cli/examples/observe-envelope.hbp
GATE|verdict=HOLD|score=0.2139|l0_real=true|mark=REVERSE_GAIN_MARK_MISTAKE|reverse_risk=0.7861|hookwall=PROCEED|spawn_gate=HOLD|tier_gate=PROCEED|fischer=PROCEED|input_guard=PROCEED|signature=unchecked|reason=HOLD by spawn_gate; hookwall=Proceed spawn_gate=Hold tier_gate=Allow fischer=PROCEED cpl=0 flags=[proof_gain_q,gnn_observable,reproducible] input_guard=[]|json=0
```

The exit code is 3 (HOLD). The other request pairs listed in the fixture's header give, with the
same envelope otherwise:

| `actor -> target` | `score` | `l0_real` | `mark` | verdict (exit) |
|---|---|---|---|---|
| `agent:benign -> svc:ledger` | 0.2139 | true | `REVERSE_GAIN_MARK_MISTAKE` | HOLD (3) |
| `agent:rogue -> svc:vault` | 0.7593 | true | `FORWARD_GNN_MARK_GENIUS` | PROCEED (0) |
| `agent:ghost -> svc:ledger` | 0.4705 | false | `REVERSE_GAIN_MARK_MISTAKE` | HOLD (3) |

The model was trained with `BCELoss` on the `gnnDataExport.js` edge label (train_baseline.py:83-105),
which is 1 for risk >= 6, status blocked or denied, or an action containing blocked or denied
(gnnDataExport.js:74-77). asolaria-score adds L0 to the composite with weight 0.30
(asolaria-score.mjs:156-159). These are the upstream definitions; `observe` reproduces them.

`--pub`/`--sig` work as for `gate` and cover the exact envelope bytes only. The events file is
not signed, so `signature=verified` says nothing about it. The events file decides the L0 term:
with `examples/observe-envelope.hbp`, the single row
`EVENT|actor=agent:benign|target=svc:ledger|risk=9` gives `score=0.7375` and PROCEED (exit 0),
where the fixture gives `score=0.2139` and HOLD (exit 3).

## Scope

- Ed25519 is real: `ed25519-dalek` via `asolaria-hookwall`, verified with `verify_strict` (which
  also rejects small-order keys and non-canonical signatures). Keys come from the operating
  system's random source (`getrandom`).
- The gates are deterministic software policy over values you supply. For `gate`, scores,
  `g4_state`, `l0_real` and the tiers are inputs, not measurements. For `observe`, the scores
  are computed from the events file you supply (`g4_state` is `UNKNOWN`: this stack has no G4
  service); the events and the tiers are still inputs. The tool enforces nothing by itself; the
  caller must act on the verdict and exit code.
- `signature=verified` means the exact bytes were signed by the private key matching `--pub`,
  nothing more. There is no key registry or pinning, and envelopes carry no expiry or nonce, so a
  signed envelope can be replayed.
- Nothing persists. No ledger, log or chain row is written; `keygen` writes only the seed file.
- There is no physical attestation. The `sovereignty` tier is a policy label; nothing detects
  hardware or operator presence.
- A seed file is a secret. Keep it mode 0600, outside any repository, and never commit it. The seed is held in hookwall's
  `PrivateKey` (zeroized on drop) and the hex buffers are wiped, but this is ordinary userspace
  memory, not a hardware key store. On Windows the file gets the directory's default ACL.

- `sign` and `verify` read their whole input into memory; `gate` and `observe` cap envelopes at
  1 MiB; `observe` reads the whole events file into memory.

## Development

From the `cli/` directory:

```
cd cli
cargo +1.81.0 test --locked
cargo +1.81.0 clippy --locked --all-targets -- -D warnings
```

`Cargo.lock` pins every crate shared with `gate/hookwall/Cargo.lock` to the same version.
`observe` adds only path dependencies (`gate/observed`, `model/l0-edge`); no new crates.io crate.

## License

MIT. See [`../LICENSE`](../LICENSE).