sic/docs/design-nested.md

# sic — nested (multi-hop) design & chain-resolution decision

Status: **Accepted** — 2026-07-23. This records a decision and its rejected alternatives
*for the audit trail* — a future reader should see that a shared-store router was considered
and killed for cause, not overlooked.

## Goal

Make `sic host/hop1/hop2 … argv` real: run a command inside a container reached through a
chain of hops (`incus exec`, `docker exec`, `pct exec`, …) without a shell re-parsing argv at
any layer. The v2 wire-protocol **daemon** (`cmd/sicd`, `gateway/sicd`) already implements
one-layer-per-hop peeling; this covers the **client** and the rollout.

## Model (confirmed)

The **client builds the whole onion up front**: wrap the innermost command in a frame for hop
N, wrap that for hop N-1, … outermost for hop 1, and ship the nested blob to hop 1. **Each
`sicd` peels exactly one layer** (its own), runs its runtime verb with **`sicd` itself** as the
command (`incus exec <c> -- sicd`), and that inner `sicd` reads the next frame from stdin and
repeats. There is **no separate `sic-run` binary** — see Decision 3. Construction is recursive
and up-front; unrolling is iterative and distributed.

One frame = preamble (`MAGIC 0x00`, then 4-byte big-endian `len32`) + a djb netstring whose
content is `netstring(argc)` + argc argv netstrings + `payload`; the payload of a non-terminal
frame is itself a full frame for the next hop.

## Decision 1 — chain resolution: **static per-client config**

`/etc/sic/hosts.toml` declares, per host, the ordered runtime verbs for its hops
(`nest = ["incus", "docker"]`, etc.). The client reads it to turn `host/hop1/hop2` into the
concrete verb + address at each layer. **Fail loud on any mismatch** (unknown host, more hops
than the config declares) — never guess.

### Rejected: a shared memory store as the chain router

Resolving chains by querying a shared, mutable fleet-memory store was proposed and **rejected**.
Even with the bootstrap circularity removed (the store's own address is a flat local setting, so
a lookup is one direct call, not a nested one), it loses on four counts:

- **Trust (dispositive).** Such a store is *mutable and shared*. Any writer poisons one chain
  entry and every subsequent `sic` call through that chain execs the attacker's verb on the
  target host — a supply-chain RCE vector. Static config is immutable-after-deploy and auditable
  once.
- **Staleness fails the wrong way.** A moved/renamed container makes the stored chain lie, and
  the client *silently* execs into the wrong container. Static config fails loud (connection
  refused); a mutable store turns a hard error into quiet wrong-target execution.
- **Availability.** The store may live on a host that sleeps; resolution would die with it, and a
  local cache to cover that is just a slower, staler config file.
- **No net benefit.** The client needs a local store *address* regardless, so the store only adds
  a fragile network hop + cache to do what a flat file read already does.

A shared memory store may still be useful for *memory* — this decision is narrowly about
*routing*, nothing else.

## Decision 2 — migration: **daemon dual-read, daemon-first**

The v2 daemon hard-requires the `0x00` magic; the deployed v1 client sends a digit first, so a
naive v2 deploy breaks every existing call on the many live hosts already running v1. Instead the
daemon **sniffs the first byte** — `0x00` → v2 parser, digit → v1-legacy parser — a
once-per-connection branch, ~20 lines, zero perf cost. Ship the v2 daemon everywhere first; roll
clients independently, no flag day.

## Decision 3 — the chain link is `sicd` itself (no `sic-run` binary)

An earlier draft proposed a separate `sic-run` helper as the per-hop peeler. It is **not built**:
`sicd` is already a pure v2 frame-peeler, so the inner-hop command is just `sicd`
(`incus exec <c> -- sicd`), and one binary deploys instead of two (a deployment-simplicity
decision). **Verified empirically, not assumed** — `sicd` invoking `sicd` was run against a
two-layer nested frame (`build sicd; frame("sicd", frame("cat", payload)) | sicd`): the payload
reached the inner hop, exit status propagated, stderr clean. sicd calling sicd peels correctly,
so nothing about a nested hop needs behaviour sicd lacks. The only prerequisite is that **sicd is
present in every container a chain traverses** (a packaging/rollout item, not new code).

## Backward compat & the two original bugs

- A **bare `--`** must survive into the innermost argv untouched (the payload is opaque bytes;
  no hop interprets it) — closes the double-dash bug (#1).
- **stdin must be forwarded** into/through the frame — closes the silent zero-byte-file bug.
- A **bare host** with no `/` stays a single v1-style hop (backward compatible).

## Escape hatch (documented, not built)

If redeploying clients on chain changes ever costs more than the trust of a live store,
distribute **signed manifests out-of-band** — deterministic like static config, updatable like a
live store, without the mutable-store poison vector. Future work; explicitly not today's problem.

## Consequences

- Chain changes require redeploying clients (accepted: moves are infrequent, rollouts controlled).
- No network dependency and no mutable store in the routing path — routing is deterministic and
  auditable.
- Next: implement `cmd/sic` (config read + recursive frame build + `--`/stdin fixes) and the
  daemon dual-read; ensure sicd is deployed into target containers (no `sic-run` binary); both
  are Go.