Aura/fieldtests/milestone-project-environment/FINDINGS.md

# Fieldtest — milestone "Project environment — the project-as-crate authoring loop" (#180) — 2026-07-02

**Status:** Draft — awaiting orchestrator triage
**Author:** fieldtester (dispatched as the milestone-close gate)

## Scope

The milestone-close gate for the **project-as-crate authoring loop**: `aura new`
scaffolds a buildable cdylib project; inside it the `aura` host discovers
`Aura.toml`, cargo-builds + loads the project cdylib, merges the project
vocabulary with `aura-std`, and runs blueprints with project provenance in the
manifest; `aura graph introspect --vocabulary | --content-id | --identity-id`
introspects the merged surface and topology ids.

Run entirely from the **public interface** — `README.md`,
`docs/project-layout.md`, `docs/glossary.md`, `docs/design/INDEX.md`
(C13/C16/C17/C24), `aura … --help`, and the fieldtests corpus *shape*. No
`crates/*/src` and no `crates/*/tests` were read; no rustdoc was consulted. The
only node-authoring template available was the scaffolded `Identity` node.
Artefact under test: `target/debug/aura`, rebuilt from HEAD via
`cargo build -p aura-cli` before the run; the project cdylib rebuilt with
`cargo build` in the project between edits.

## Tasks

All fixtures under `fieldtests/milestone-project-environment/`. The scaffolded
project is `momentum-lab/`.

### Task 1 — scaffold -> build -> run -> run-again -> provenance  — WORKS
Commands (verbatim):

    aura new momentum-lab                       # -> "created project `momentum-lab` (namespace `momentum_lab`)"
    cd momentum-lab && cargo build              # clean
    aura run blueprints/signal.json             # -> s1_starter_run.json
    aura run blueprints/signal.json  (x2, diff) # byte-IDENTICAL (determinism)

- The emitted crate is buildable as-is: `crate-type=["cdylib"]`, an empty
  `[workspace]` table (so it builds under the engine tree), path-dep on
  `aura-core`, a `CLAUDE.md`, `.gitignore`, an `Aura.toml` (`[paths] runs`), a
  `src/lib.rs` with a worked `Identity` node registered via `aura_project!`, and
  a starter `blueprints/signal.json` that already wires the project's own
  `momentum_lab::Identity` node at the graph tail — so the very first run
  exercises the merged vocabulary, not just std.
- The run report's manifest carries the milestone's headline provenance:
  `"project":{"namespace":"momentum_lab","dylib_sha256":"ceda123f…"}`. Two runs
  are byte-identical (C1). Evidence: `s1_starter_run.json`.

### Task 2 — author your own node (the real authoring loop)  — WORKS
Edited `momentum-lab/src/lib.rs` to add a `Negate` (f64 sign-flip) node
following the scaffolded `Identity` template, registered it in
`vocabulary()`/`type_ids()`, then:

    cargo build                                                  # clean
    aura graph introspect --vocabulary                           # now lists momentum_lab::Negate
    aura graph build < s2_negate.ops.json > s2_negate.bp.json    # resolves the project node
    aura run s2_negate.bp.json                                   # -> s2_negate_run.json

- The op-list (`s2_negate.ops.json`, canonical authoring form per README) wires
  `price -> SMA/SMA -> Sub -> Bias -> momentum_lab::Negate`. `graph build`
  resolved the project node and emitted a runnable blueprint (`s2_negate.bp.json`).
- The new node visibly changed behaviour: `total_pips` went `+0.34185 -> -0.34185`
  (exact sign flip), the R block changed accordingly, and the manifest's
  `dylib_sha256` updated (`ceda123f… -> 70263c83…`) — proof the host loaded the
  fresh build per invocation. Deterministic on re-run. Evidence:
  `s2_negate_run.json`.

### Task 3 — introspection: --vocabulary / --content-id / --identity-id  — WORKS

    aura graph introspect --vocabulary                    # 2 project + 22 std = 24 lines
    aura graph introspect --node momentum_lab::Negate     # in value:F64 / out value:F64
    aura graph introspect --content-id  < s2_negate.ops.json         (A)
    aura graph introspect --content-id  < s3_negate_renamed.ops.json (B)
    aura graph introspect --identity-id < {A,B}
    aura graph introspect --content-id --identity-id < A            # both, content first

- `--vocabulary` lists project types first, then std alphabetically; `--node`
  resolves a project node's ports. Renamed-twin test (A vs B = same topology,
  different node names): content-ids differ (`bd6c70…` vs `9dc729…`),
  identity-ids are equal (`b02fbb…`), and the combined flag prints content-id
  first — exactly as README / the `identity id` glossary entry document.
  Cross-check: `content-id(A)` equals the `topology_hash` stamped in
  `s2_negate_run.json`'s manifest. Evidence: `s3_id_comparison.out`.

### Task 4 — misuse paths a newcomer hits  — WORKS (one friction)
- Charter violation (registered a non-`momentum_lab::`-prefixed type id,
  rebuilt): refused at load, exit 1,
  `aura: project vocabulary rejected: type id ` + "`NoNamespace`" + ` lacks the
  project prefix ` + "`momentum_lab::`" + ` — names both sides, house-style prose.
  Reverted after capture. Evidence: `s4_charter_violation.err`.
- `--release` with only a debug build: exit 1, names the exact missing path + the
  fix (`run cargo build in the project first`). Evidence: `s4_release_missing.err`.
- Outside any project: `--vocabulary` -> std-only (22); a project blueprint is
  refused (see Finding F5). Walk-up discovery from a nested subdir
  (`momentum-lab/blueprints/`) correctly finds `Aura.toml` (24 entries).

## Findings

### [friction] F1 — `aura new` leaves a nested `.git` that snags the enclosing tree
- Task 1. `aura new` runs `git init`; the scaffold contains `momentum-lab/.git`.
- Correct for a real standalone project (C16: "its own git history"). But
  `docs/project-layout.md` explicitly supports scaffolding under the engine tree
  "before it moves to its own repo" — the exact reason the empty `[workspace]`
  table is emitted. That handles cargo's walk-up; nothing handles git's walk-up:
  the nested repo becomes an embedded gitlink in the enclosing repo, so
  `git add fieldtests/…/momentum-lab` would add a submodule pointer, not the
  files. I had to `rm -rf momentum-lab/.git` for the corpus to be committable.
- Recommended: skip `git init` when an enclosing `.git` is detected, or document
  the scaffold-under-a-repo wrinkle beside the `[workspace]` note.

### [doc-gap] F2 — no worked example of a node that reads a bound param
- Task 2. The only authoring template is the scaffolded `Identity` (param-less;
  build closure `|_| Box::new(..)`). No public doc (README, project-layout,
  ledger, --help) shows how a `PrimitiveBuilder` build closure consumes a bound
  param — the natural next step (a tunable, sweepable node). I could author a
  param-less node from the surface alone, but a first parametric node cannot be
  written from the public docs without reading engine source/rustdoc.
- Recommended: have `aura new` emit one param-bearing node in the template (or
  document the build-closure param-read in project-layout.md). Highest-value gap.

### [doc-gap] F3 — the manifest `project` provenance block is undocumented
- Task 1. The manifest's new `"project":{namespace,dylib_sha256}` block is the
  milestone's headline provenance, but the glossary `manifest` entry still
  defines a manifest as "(node-commit + params + data-window + seed + broker
  profile)" — no `project`. A consumer inspecting the JSON meets an undocumented
  field.
- Recommended: add `project` (namespace + dylib hash) to the glossary manifest
  definition.

### [friction] F4 — `run` leaks a raw Rust `Debug` enum for an unknown node type
- Task 4. Same logical error, two phrasings: `graph build` (stdin) ->
  `op 5 (add): unknown node type "momentum_lab::Negate"` (exit 1, prose);
  `run` (argv file) ->
  `aura: s2_negate.bp.json: UnknownNodeType("momentum_lab::Negate")`
  (exit 2, raw Debug-formatted enum variant). The exit-code split is correct and
  documented (C14: argv-file content = exit 2, stdin data = exit 1), but the
  `run` path's `UnknownNodeType("…")` breaks the lowercase house style every other
  diagnostic uses. Evidence: `s4_outside_run.err`, `s4_outside_build.err`.
- Recommended: render the loader error on the `run` path in house-style prose
  (e.g. `unknown node type "momentum_lab::Negate"`).

### [doc-gap] F5 — "outside a project" is not distinctly diagnosed
- Task 4. Running a project blueprint with no `Aura.toml` up-tree surfaces the
  downstream symptom (`UnknownNodeType`), not the likely cause ("not inside a
  project / no Aura.toml found"). A newcomer who cd'd out of their project reads
  "unknown node type" rather than "you are not in a project".
- Recommended: when a blueprint names a `namespace::Type` and no project was
  discovered, hint that no `Aura.toml` was found up-tree.

### [doc-gap] F6 — scaffolded `Aura.toml` omits the documented data-archive-root path
- Task 1. Glossary/`project-layout.md` say `Aura.toml` carries "the data archive
  root and the runs dir"; the emitted file has only `[paths] runs = "runs"`. No
  concrete key name for the data archive root is documented or scaffolded, so a
  newcomer wanting `aura run --real <symbol>` has no scaffolded slot to point at
  their recorded data. Low severity for a synthetic-default v1.
- Recommended: scaffold the data-archive-root key (commented) or drop it from the
  Aura.toml prose until a consumer reads it.

### [working] W1 — the merged-vocabulary authoring loop is real and clean
- Tasks 1-3. Edit lib.rs -> `cargo build` -> the next `aura` invocation loads the
  fresh dylib (manifest `dylib_sha256` tracks the rebuild), merges 2 project + 22
  std types, resolves the project node in `graph build`, `run`, and every
  `introspect` mode, and produces deterministic runs. Walk-up `Aura.toml`
  discovery works from nested subdirs. The whole authoring loop the milestone
  promises works end-to-end from the public docs.

### [working] W2 — id semantics and diagnostics are precise
- Tasks 3-4. `--content-id`/`--identity-id` behave exactly as documented
  (name-blind identity id equal across renamed twins; byte-exact content id
  differs; combinable, content-first; content-id == manifest `topology_hash`).
  The charter refusal and the `--release`-missing message are both clear,
  exit-code-correct, and actionable. One micro-nit inside W2's otherwise-great
  `--release` message: it says "or pass --release …" even when `--release` was
  already passed (the generic hint doesn't adapt to the current mode).

## Milestone verdict: GREEN

A downstream consumer can run the entire project-as-crate authoring loop —
`aura new` -> `cargo build` -> run (deterministic, with project provenance) ->
author a real node -> rebuild -> introspect the merged vocabulary -> topology ids
— from the public docs alone, with zero behavioural bugs. All six findings are
friction/doc-gap polish, not loop blockers:

| Finding | Class | Recommended action |
|---|---|---|
| F1 nested `.git` snags enclosing tree | friction | plan (skip git-init under a repo, or document) |
| F2 no param-node authoring example | doc-gap | plan (scaffold a param node) — highest-value gap |
| F3 manifest `project` block undocumented | doc-gap | tighten glossary |
| F4 `run` leaks Debug enum on unknown type | friction | plan (house-style the loader error) |
| F5 "outside a project" not distinctly diagnosed | doc-gap | plan (hint on missing Aura.toml) |
| F6 Aura.toml data-archive-root un-scaffolded/undocumented | doc-gap | tighten docs |
| W1/W2 loop + id semantics correct | working | carry-on |