# Shared Variables Context

Your container is running with the **shared variables filesystem** mounted at `/variables/`.
This is the only way you read a step's inputs and return its outputs to the control
plane — there is no API to call, no credential to hold, no env var to substitute.
You write plain files under your own step folder; the CP picks them up.

Normative source: `spec/workflow-variables.md` (WV-1..6a). This document summarises
the contract; when in doubt, the spec wins.

## What is where

```
/variables/
  workflow/                       # run inputs, frozen at dispatch time (WV-8)
    run-id
    template
    item.uuid
    item.title
    item.label
    item.flow-state
    artifacts.<key>               # per WorkflowInput.required_artifacts
  <step>/                         # this step's OWN folder — write outputs here
  <loop-id>_<n>/<step>/           # loop body node in iteration n (n is 1-based)
  .self                           # path to your own step folder (read-only)
  .done                           # completion marker, written by the entrypoint
```

You only write under your OWN folder. The pack sidecar walks that folder after you
exit and returns its contents to the CP. Earlier loop iterations' results and your
direct `depends_on` dependencies' outputs are also under `/variables/`, pre-filled
when your container started — you only READ those.

## Two env vars are set for you

- `WORKFLOW_VARIABLES_ROOT` — always `/variables`.
- `WORKFLOW_VARIABLES_SELF` — the path to your own step folder
  (e.g. `/variables/judge` for a top-level node named `judge`, or
  `/variables/review-loop_2/judge` for loop iteration 2's `judge` node).

Neither ever contains a value. Both are paths only. Treat both as read-only inputs.

## Key naming (the contract you'll be checked against)

- A variable's key is the joined, lowercased path from `/variables/` to the leaf
  file, with `.` as the separator.
  `/variables/judge/VERDICT` ↔ `judge.verdict`.
  `/variables/review-loop_2/judge/findings/HIGH` ↔ `review-loop_2.judge.findings.high`.
- **Leaf files are UPPERCASE** on disk by convention; folders stay lowercase.
  Lookup via the helpers and the CP API is case-insensitive.
- Each path segment, after lowercasing, must match `^[a-z0-9][a-z0-9_-]{0,63}$`.
  Maximum depth is 8 segments. Dotfiles, symlinks, FIFOs, sockets, and devices are
  skipped with a warning (never read or followed).
- Two leaf files at the same level whose names lowercase to the same key → both
  rejected at pack time as `invalid_output_key`.
- **Reserved names** that cannot be used as step or loop ids (case-insensitive):
  `workflow`, `while`, `for`, `foreach`, `loop`, `until`, `do`, `repeat`, `if`,
  `else`, `elif`, `elseif`, `then`, `switch`, `case`, `default`, `when`, `break`,
  `continue`, `return`, `goto`, `yield`, `try`, `catch`, `except`, `finally`,
  `raise`, `throw`, `and`, `or`, `not`, `xor`, `in`, `is`, `true`, `false`,
  `null`, `none`, `nil`, `yes`, `no`, `on`, `off`. The full list lives in
  `controlplane/typed_workflows/reserved_ids.py` and may grow by spec amendment.
- Step/loop ids are restricted to lowercase letters, digits, `-` and `_`, starting
  with a letter; no trailing `_<digits>` (reserved for loop-iteration suffixes).

## What you can see (visibility)

- `workflow.*` — always. These are the run inputs, frozen for the life of the run
  (later item changes are not reflected here; pass them on through step outputs).
- The outputs of each of your **direct** `depends_on` nodes (the same set the
  manifest DAG wires you to) — not transitive.
- Inside a loop body, **every prior iteration's** outputs for **every** step in
  the loop — not just the immediately preceding one. So iteration 2 sees what
  iterations 1, 2, … of every loop body node wrote. Iteration 1 sees only its
  direct dependencies.
- Nothing else. Your own folder is always created, even if empty.

## Declared outputs

If your node's template declares `outputs: [<key>, ...]`, those are the keys you
are expected to write. Any file actually present under your step folder is
accepted regardless — `outputs:` is for policy and tooling, not an allowlist.
A missing declared output produces a warning by default (configurable per-project
to fail the step with `variables_missing_output`).

## Values

- **Strings only.** JSON is supported as a string value — you parse it yourself;
  the CP never interprets a value's structure.
- Per-value cap is configurable (`max_value_bytes`, default 1 MiB). Per-step cap
  (`max_step_bytes`) and per-step file count (`max_step_files`) also apply.
- Values are data — never substituted into prompts, commands, or environment
  variables by the CP. Don't put values in shell; read them through the helpers
  or the CLI.

## Helpers (use these, not shell)

A Python package is pre-installed in your image at `/opt/agent/variables/` and a
CLI at `/usr/local/bin/wfvar`. Both are stdlib-only.

```python
from variables import load, save, keys

value = load("verdict")                    # load from your own folder
save("verdict", "CLEAN")                   # write into your own folder
keys()                                     # list keys under your own folder
keys(prefix="judge.")                      # narrow by prefix (read-only access)
```

```bash
wfvar get VERDICT                 # print the value, NO trailing newline
wfvar set VERDICT CLEAN           # write into your own folder
wfvar list                        # list your own keys
wfvar path                        # print your own step folder (same as $WORKFLOW_VARIABLES_SELF)
wfvar get judge.findings.high     # read another step's output (visibility permitting)
```

Exit codes: `0` ok, `1` not found (key is valid but absent), `2` invalid key or
usage, `3` value exceeds per-value limit, `4` write attempted outside your own
step. Do not wrap `wfvar get` with extra shell that strips newlines — it prints
exactly the stored bytes.

**Don't write plan-like content with `wfvar set <key> <body>`** — argv breaks on
shell quoting and truncates at ARG_MAX. For multi-line / quoting-sensitive bodies
(e.g. the decompose plan files at `/variables/<node>/items/<local_id>`), use your
file-write tool or a heredoc with a terminator that cannot occur in the body,
writing directly into `/variables/<node>/...`.

## Safety

The pack sidecar reads your step folder with strict traversal protections
(`O_NOFOLLOW`, `S_ISREG` checks, size caps, 4 KiB marker cap). It does not follow
symlinks you might drop in. A symlink at any level is silently skipped with a
warning — never assume it will be read.

## What you must NOT do

- Do not read or write outside your own step folder under `/variables/`.
- Do not call out to the CP API directly — the helpers and the pack sidecar
  handle all variable transport.
- Do not assume `/variables/` exists in an unstamped container — it doesn't.
- Do not write to `/variables/.done` — the entrypoint owns that marker; it is
  written for you after `run_finalize_phase` returns, whether you exited 0, non-zero,
  or via SIGTERM.
- Do not store values in env vars, command lines, or prompts — values are data,
  and data doesn't go there.