vaibify 0.2.1__tar.gz → 0.2.2__tar.gz

vaibify-0.2.2/.claude/skills/add-data-loader/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: add-data-loader
+description: Recipe for adding a new file-format loader to vaibify/gui/dataLoaders.py. Use when the task is to support reading a new data file extension (e.g., netCDF, Zarr, a domain-specific binary format) in quantitative benchmark tests.
+---
+
+# Adding a new data-file loader to vaibify
+
+Use this recipe when the task is to support reading a new data file
+extension in vaibify's quantitative benchmark tests.
+
+`vaibify/gui/dataLoaders.py` is the dispatch table mapping file
+extensions to loader functions. The text between its markers is also
+embedded verbatim, by `fsReadLoaderSource()`, into the self-contained
+quantitative test file vaibify generates
+(`templateManager.fsBuildQuantitativeTestCode`). This embedding is the
+primary constraint on every loader you add. The introspection script
+that proposes benchmarks does NOT embed it: it keeps its own copy of the
+format handling, which you extend separately (step 6).
+
+## Prerequisites
+
+Read these first:
+
+- `AGENTS.md` (repo root) — global rules and traps
+- `vaibify/gui/dataLoaders.py` — the existing loaders, the
+  `# -- begin loader source` marker block, and the module docstring's
+  "Where these loaders run"
+- `vaibify/gui/introspectionScript.py` — the f-string executed inside
+  containers, with its own `_DICT_FORMAT_MAP` and benchmark chain; read
+  its module header first
+- `vaibify/gui/templateManager.py` — `fsBuildQuantitativeTestCode`,
+  which embeds the loader source, and `SET_PRIOR_TEMPLATE_HASHES`, which
+  records the template hashes a change retires
+
+## The critical invariant
+
+The text between the `# -- begin loader source` and
+`# -- end loader source` markers in `dataLoaders.py` is read as a
+string by `fsReadLoaderSource()`, then inlined into a self-contained
+Python test file that runs wherever the project's tests run: **inside
+the container** for a container project, and in the hub's pytest
+subprocess on the researcher's machine for a host project. The
+`vaibify generate-standards` command also imports the loaders on the
+host (`vaibify/testing/standards.py`); the hub process itself only
+embeds the text (`tests/testDataLoadersStayOutOfTheHub.py`). That
+environment has a known Python version and a limited set of packages
+available. This means:
+
+- Loaders must be **pure Python** plus the packages already used in
+  the loader-source block (`json`, `pathlib`, `re`, `numpy`). Do not
+  introduce new top-level imports into the loader-source block
+  without confirming the dependency is always present in the
+  container images vaibify supports.
+- If a format requires an optional package (e.g., `netCDF4`, `zarr`,
+  `pyarrow`), the loader must `import` inside the function body and
+  raise a clear error if the import fails. Do not place the import at
+  module top level inside the loader-source block.
+- Loaders read only the path they are handed: no configuration, no
+  host-only utilities. Build paths with the `pathlib` the block already
+  imports, as `_ffLoadValue` does.
+- Loaders must be deterministic and side-effect-free beyond the file
+  read.
+
+## Steps
+
+### 1. Add the extension to `_DICT_FORMAT_MAP`
+
+In `dataLoaders.py`, inside the loader-source block (between the
+`# -- begin loader source` and `# -- end loader source` markers), add
+the extension(s) to `_DICT_FORMAT_MAP`, mapping to a canonical format
+string you'll use in step 2:
+
+```python
+_DICT_FORMAT_MAP = {
+    ...
+    ".nc": "netcdf",
+    ".nc4": "netcdf",
+    ...
+}
+```
+
+Keys are lowercase: the lookup lower-cases the file's suffix, so a
+mixed-case key can never match
+(`test_every_advertised_extension_actually_resolves`). List the new
+format in the format table of `docs/testing.md`.
+
+### 2. Implement the loader function
+
+Also inside the loader-source block, define
+`_ffLoad<Name>Value(sFullPath, dictAccess)` following the shape of
+the existing loaders. `sFullPath` is the path `_ffLoadValue` has
+already joined onto the step directory; `dictAccess` is the dict
+`_fdictParseAccessPath` parsed from the access path (`key`, `column`,
+`dataset`, `section`, `hdu`, `listIndices`, `sAggregate`). Finish
+through the shared extractors (`_ffExtractArrayValue`,
+`_ffExtractTabularValue`, `_ffExtractDataframeValue`) so index and
+aggregate syntax behave as they do for every other format.
+
+Conventions:
+
+- Function name: `_ffLoad<Name>Value` — `ff` because it returns a
+  float.
+- Optional dependencies: import inside the function body and raise a
+  clear `ImportError` with a helpful message if missing.
+- Errors: when the file cannot be read or the access path does not
+  resolve, raise `ValueError` naming the path and the format, chained
+  from the library's error, as `_ffLoadVtkValue` does
+  (`Failed to load <path> as vtk: ...`).
+- Return type: a Python `float`, not an array; the generated test
+  compares it with `np.allclose`.
+- Every binding carries a cast prefix
+  (`testVariableBindingsCarryCastPrefixes`). Unprefixed names in older
+  loaders (`mesh`, `table`) are seeded debt, not a pattern to copy.
+
+### 3. Register the loader in `_DICT_LOADERS`
+
+Still inside the loader-source block, add the mapping:
+
+```python
+_DICT_LOADERS = {
+    ...
+    "netcdf": _ffLoadNetcdfValue,
+    ...
+}
+```
+
+`DICT_LOADERS`, below the end marker, is the public alias of this dict;
+do not edit it.
+
+### 4. Confirm public symbols are unchanged
+
+The module-level `__all__` should still be
+`["DICT_FORMAT_MAP", "DICT_LOADERS", "ffLoadValue", "fsReadLoaderSource"]`.
+Do not add the new loader function to `__all__` — loaders are
+internal to the dispatch.
+
+### 5. Re-pin the quantitative template hash
+
+Any edit inside the marker block changes the generated quantitative
+test, so `tests/testGuiTemplateManager.py::testTemplateHashesArePinned`
+fails until you add the outgoing hash
+(`DICT_PINNED_TEMPLATE_HASHES["quantitative"]` in that test) to
+`SET_PRIOR_TEMPLATE_HASHES` in `vaibify/gui/templateManager.py`, then
+pin the new hash the failure message prints. Skip the first half and
+every project's untouched quantitative test files read as custom
+scripts.
+
+### 6. Mirror the format in the introspection script
+
+`introspectionScript.py` is an f-string executed inside containers (and
+on the researcher's machine for a host project), with its own copy of
+the format handling, because a container script cannot import from the
+host. No test binds the two copies, so a format added only to
+`dataLoaders.py` loads but is never introspected: no benchmarks are
+proposed for it, and nothing says so. Inside the template that
+`_fsBuildIntrospectionScript` returns:
+
+- add the extension(s) to its `_DICT_FORMAT_MAP`;
+- add an `elif sFormat == "<name>":` branch to `_fnLoadAndBenchmark`;
+- add `_fnBenchmark<Name>(sFullPath, sFileName, dictReport)`, modeled
+  on `_fnBenchmarkTfrecord`: an optional import that fails sets
+  `dictReport["sError"]` and returns rather than raising, and every
+  access path it emits must be one your loader reads back.
+
+Every literal brace in that text is doubled (`{{`, `}}`), because the
+whole script is one f-string: a single brace is interpolated on the
+host, which either breaks the build of the script or changes it
+silently.
+
+### 7. Raise the two module-size caps
+
+`dataLoaders.py` and `introspectionScript.py` are held to their entries
+in `tests/testArchitecturalInvariants.py::DICT_GRANDFATHERED_MODULE_LINES`,
+each the module's size when it was last raised, so a new format crosses
+both. Raise each by exactly the lines the edit adds, with a one-line
+dated reason above it, as the TFRecord fix did:
+
+```python
+    # 1222 -> 1229 (2026-10-01): a TFRecord feature is read from the decoded example.
+```
+
+### 8. Add a test
+
+Create `tests/testDataLoader<FormatName>.py`. At minimum:
+
+- Confirm the extension is in `_DICT_FORMAT_MAP`.
+- Confirm the format string is in `DICT_LOADERS`.
+- Call `ffLoadValue` against a small fixture file and assert the
+  returned scalar matches the expected value.
+- Run the generated introspection script over the fixture, as
+  `tests/testIntrospectionTfrecord.py` does
+  (`_fsBuildIntrospectionScript`, then `subprocess.run` with
+  `sys.executable`), and assert that a benchmark names an access path
+  `ffLoadValue` reads back.
+- If the format requires an optional dependency, add a test that
+  skips cleanly when the dependency is absent (`pytest.importorskip`).
+  CI installs `.[dev]`, not the `formats` extra.
+
+Keep fixture files small and science-agnostic. Do not commit real
+scientific datasets. A test fixture should be a hand-crafted
+minimal file that exercises the format's structure.
+
+### 9. Verify both embedded sources still parse
+
+`fsReadLoaderSource()` returns the text between the markers as a
+string. That string must be valid Python on its own — it becomes the
+body of the generated test file. Run:
+
+```bash
+python -c "from vaibify.gui.dataLoaders import fsReadLoaderSource; exec(fsReadLoaderSource())"
+python -c "import ast; from vaibify.gui.introspectionScript import _fsBuildIntrospectionScript; ast.parse(_fsBuildIntrospectionScript([], 'data'))"
+```
+
+If the first fails, something in your edit broke the embedded loader
+source. Common causes: a top-level statement that uses a name defined
+outside the block; a top-level import of a package that is not
+installed. If the second fails, a brace in step 6 was not doubled.
+
+### 10. Run the test suite
+
+```bash
+python -m pytest tests/testDataLoader<FormatName>.py tests/testDataLoaders.py tests/testGuiTemplateManager.py tests/testStyleInvariants.py -v
+python -m pytest tests/testArchitecturalInvariants.py::testModuleSizeIsBounded -v
+python -m pytest tests/ -q --ignore=tests/testContainerBuildIntegration.py
+```
+
+### 11. Exercise via generated tests if possible
+
+If you have a running container and a workflow that outputs the new
+format, trigger a quantitative test generation and confirm the
+inlined script runs inside the container without errors.
+
+## Common failure modes
+
+- **`exec(fsReadLoaderSource())` fails** — you added a symbol outside
+  the marker block that the inlined code references, or a top-level
+  import not available in the container image.
+- **Container test script fails with ImportError** — your loader
+  top-level-imports a package that isn't in the container. Move the
+  import inside the function and raise a clean error on failure.
+- **The format loads but generation proposes no benchmarks for it** —
+  step 6 was skipped; the introspection script does not know the
+  extension.
+- **Access path parsing is inconsistent with existing loaders** —
+  study the CSV and HDF5 loaders to match conventions (slash-separated
+  paths, colon-separated indexing, etc.).
+- **Science-specific fixture committed** — remove it; use a
+  hand-crafted minimal file.
+
+## Do not
+
+- Do not add a loader that reads configuration or calls host-only
+  utilities: the same text runs in a container and on a host
+  project's machine.
+- Do not change `fsReadLoaderSource()`'s behavior to include code
+  from outside the marker block.
+- Do not add an optional reader's package to vaibify's core
+  `dependencies` in `pyproject.toml`. It belongs in the `formats` extra,
+  beside the readers already there, and in that extra's row of
+  `docs/install.md`. The container image installs the project's
+  declared Python packages and the analysis stack
+  (`T_ANALYSIS_STACK_PACKAGES`), never this extra, so inside a container
+  the reader is present only when the project declares it, and the
+  loader's `ImportError` says so when it is not.
+- Do not commit real scientific data as test fixtures. Vaibify is for
+  the general problem; commit synthetic files only.

vaibify-0.2.2/.claude/skills/add-route-module/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: add-route-module
+description: Recipe for adding a new FastAPI route module to the vaibify backend under vaibify/gui/routes/. Use when the task is to expose a new group of HTTP or WebSocket endpoints.
+---
+
+# Adding a new route module to vaibify
+
+Use this recipe when you need to add a new group of HTTP or WebSocket
+endpoints to the vaibify FastAPI backend. Every route module follows
+the same contract; follow these steps in order.
+
+## Prerequisites
+
+Read these first:
+
+- `AGENTS.md` (repo root) — global rules and traps
+- `vaibify/gui/AGENTS.md` — backend contracts
+- the `container-mutations` skill — for any route whose path carries
+  `{sContainerId}`: what the carrier-mode declaration in step 4 means,
+  and the ledger a container exec changes
+- the `host-mode-and-paths` skill — for any route that composes a path
+- `vaibify/gui/routes/committedFileRoutes.py` — small, current reference
+  for a container-scoped module (agent actions, carrier declarations, a
+  read on the frozen read list); `vaibify/gui/routes/runtimeSetupRoutes.py`
+  is the hub-only, control-plane counterpart. (`figureRoutes.py`, the old
+  reference, is still recorded in the carrier-mode allow-list that may
+  only shrink, so it shows nothing about step 4.)
+
+## Steps
+
+### 1. Create `vaibify/gui/routes/<name>Routes.py`
+
+The filename is camelCase ending in `Routes.py` (e.g., `metricsRoutes.py`,
+`userRoutes.py`). The file must declare `__all__`, provide a module
+docstring, and export a module-level function `fnRegisterAll(app, dictCtx)`
+(a module that confines paths to the workspace takes it as a third
+argument, as `fileRoutes` does: `fnRegisterAll(app, dictCtx, sWorkspaceRoot)`).
+
+Minimal scaffold:
+
+```python
+"""<One-sentence description of what this route group does>."""
+
+__all__ = ["fnRegisterAll"]
+
+from fastapi import HTTPException
+
+from ..routeScope import S_CARRIER_TYPED_READ, ffnDeclareCarrierMode
+
+
+def _fnRegisterExample(app, dictCtx):
+    """Register GET /api/<name>/{sContainerId}/<resource>."""
+
+    @app.get("/api/<name>/{sContainerId}/<resource>")
+    @ffnDeclareCarrierMode(S_CARRIER_TYPED_READ)
+    async def fdictReadExample(sContainerId: str):
+        fnRequire = dictCtx["require"]
+        fnRequire(sContainerId)
+        # ... implementation ...
+        return {"bOk": True}
+
+
+def fnRegisterAll(app, dictCtx):
+    """Register all <name> routes."""
+    _fnRegisterExample(app, dictCtx)
+```
+
+Notes:
+
+- A handler is named for what it returns, like every other function:
+  `fdict…` for a JSON dict (most handlers), `fresponse…` for a
+  `Response`, `fn…` only for one that returns nothing.
+  `tests/testStyleInvariants.py` fails an `fn` function that returns a
+  value, and that budget is zero.
+- Functions are about 20 to 30 lines (a guideline: split for reuse or a
+  genuine conceptual boundary, never to meet a line count). Factor helpers
+  out (`_fn…`, `_fs…`, `_fdict…`) if a handler grows.
+- The module-level `fnRegisterAll` should only call the per-endpoint
+  `_fn…` helpers. Keep it thin so tests can import it without side
+  effects.
+- For container-path joins use `posixpath`, never `os.path`. Never use
+  `WORKSPACE_ROOT` as the jail: resolve the project's root with
+  `projectRoots.fsResolveProjectRoot(sContainerId, WORKSPACE_ROOT)` (the
+  constant is only the container answer the resolver is handed) and
+  confine a caller's path with
+  `fsValidatePathWithinRoot(sAbsPath, sProjectRoot)`. A route that WRITES a caller's path also applies
+  `fnRejectWriteDenylistedPath` and passes `fdictConfinedWriteKeywords`
+  to the write. All three live in `vaibify.gui.pipelineServer`, beside
+  the figure helpers `fsResolveFigurePath` and
+  `fbaFetchFigureWithFallback`; the `host-mode-and-paths` skill explains
+  the resolvers.
+- For shell-quoting container command arguments, use
+  `fsShellQuote` from `vaibify.gui.pipelineRunner`.
+- If the route needs Docker access, call through
+  `dictCtx["docker"]`; do not import Docker utilities directly.
+
+### 2. Register the module in `vaibify/gui/routes/__init__.py`
+
+Add the module name to both the `__all__` list and the
+`from . import (...)` block. Preserve the existing order grouping
+where it makes sense; otherwise append.
+
+### 3. Mount the module
+
+Importing a module registers nothing. Add an explicit call,
+`routes.<name>Routes.fnRegisterAll(app, dictCtx)`, to
+`pipelineServer._fnRegisterAllRoutes`, which both the viewer and the hub
+build. A route that belongs only to the hub's control plane is imported
+and called inside `appFactory._fnRegisterHubLifecycle` instead, as
+`runtimeSetupRoutes` is. No test catches a module that is imported but
+never mounted; its own endpoint tests (step 7) are what fail.
+
+### 4. Declare each route's scope and carrier mode
+
+`fnValidateRouteScopesOrRaise` refuses to build the app while any
+mutating route has no authorization scope, so every test that builds an
+app fails, not one. A path carrying `{sContainerId}` is scoped by
+convention: a mutating route is `container-owner`, a GET or HEAD is
+`container-read`. Anything else is declared by you:
+
+- **A route whose path carries `{sContainerId}`** declares what it does
+  to the container with `@ffnDeclareCarrierMode(...)`, placed BELOW the
+  `@app.<verb>(...)` line. An undeclared one fails
+  `testEveryContainerScopedRouteEitherDeclaresOrIsRecordedAsAwaiting`,
+  and `SET_ROUTES_AWAITING_CARRIER_MODE` may only shrink. The
+  declaration authorizes nothing: the handler still opens a carrier
+  around each mutation. Choose the mode with the `container-mutations`
+  skill; `S_CARRIER_TYPED_READ` only for a handler that reaches no exec
+  and no container write.
+- **A GET whose path carries `{sContainerId}`** is lease-enforced, and
+  must also be added, with a comment saying what it reads, to
+  `routeScope.SET_CONTAINER_READ_ROUTES`
+  (`testContainerReadScopeIsAFrozenRatchetedAllowlist`).
+- **A mutating route with no `{sContainerId}`** is named in
+  `routeScope.DICT_CONTROL_PLANE_SCOPES` with its scope and a comment
+  saying why (`runtimeSetupRoutes` uses `S_SCOPE_BROWSER_HUB`), or
+  stamped with `@ffnRouteScope(...)` below its `@app.<verb>(...)` line.
+
+If a handler execs into or writes to the container,
+`tests/mutationInventory.json` gains a row: regenerate it with
+`python tools/generateMutationInventory.py --write` and classify the row
+as the `container-mutations` skill describes, or
+`tests/testMutationInventory.py` fails.
+
+### 5. Register state-mutating endpoints with `@ffnAgentAction`
+
+If any endpoint on the new module mutates state and a researcher
+could reasonably invoke it from the UI (run, test, verify, commit,
+create, edit, delete, push, publish, upload, write, etc.), it must
+appear in the agent-action catalog so the in-container `vaibify-do`
+CLI can translate researcher intent into the same call. Use POST, PUT
+or DELETE for a mutation: `testAgentActionCatalogShape` refuses a PATCH
+entry, and `testAgentActionRegistered` does not look at PATCH routes.
+
+Two things go together:
+
+1. **Decorate the handler.** Import the decorator and apply it
+   directly above the FastAPI path-op decorator:
+   ```python
+   from ..actionCatalog import ffnAgentAction
+
+   @ffnAgentAction("my-new-action")
+   @app.post("/api/my-thing/{sContainerId}/do-it")
+   @ffnDeclareCarrierMode(S_CARRIER_MODE_A_SYNCHRONOUS)
+   async def fdictRunMyThing(sContainerId: str): ...
+   ```
+
+2. **Add a catalog entry** in
+   `vaibify/gui/actionCatalog.py::LIST_AGENT_ACTIONS`. Copy the shape
+   of existing entries: `sName`, `sCategory`, `sMethod`, `sPath`,
+   `bAgentSafe`, `sDescription`. The `sName` here must match the
+   decorator argument exactly. Add `saQueryFields` naming every handler
+   parameter FastAPI reads from the query string (anything that is not
+   a path placeholder, a body model or the `Request`);
+   `testGeneratedActionsSendFieldsOnTheTransportTheRouteReads` fails
+   otherwise, because `vaibify do` would send that field as a body the
+   route never reads.
+
+Pick `bAgentSafe`:
+
+- **True** — execution, read-side work, test runs, agent authoring
+  (writing files, creating/updating steps the agent is working on),
+  committing canonical state, downloading inputs.
+- **False** — destructive (delete, clean, kill, force), externally
+  visible (push to Overleaf, publish to Zenodo), or requiring
+  researcher judgment (accept plots as standard, set Zenodo metadata,
+  reorder pipeline semantics). `push-to-github` is agent-safe by a
+  recorded decision; read its catalog entry before citing it as
+  precedent.
+
+Every state-mutating route, whether or not the GUI invokes it, must
+also have a CLI equivalent. Register it in exactly one place:
+
+- `LIST_AGENT_ACTIONS` — callable by agents and by `vaibify do`
+  (ships into the container);
+- `LIST_RESEARCHER_ACTIONS` — `vaibify do` on the host only, never
+  shipped into the container (credential-free researcher actions); the
+  route must also be in `SET_INTENTIONALLY_EXCLUDED_PATHS`, and its
+  entry needs `saQueryFields` on the same rule as above;
+- `DICT_ROUTE_TO_HOST_COMMAND` — a hand-written `vaibify` subcommand
+  (credentials, typed confirmations, interactive frames), which must
+  already exist;
+- `SET_GUI_ONLY_ROUTES` — genuine browser plumbing, with a one-line
+  reason.
+
+The last three live in `vaibify/gui/researcherActions.py`.
+`SET_INTENTIONALLY_EXCLUDED_PATHS` (in `actionCatalog.py`, with a
+comment) keeps a route off the agent lane, and is not a CLI home: an
+excluded route still needs exactly one of the three, whether or not the
+GUI calls it. The setup wizard's step route is both excluded and mapped
+to `vaibify setup-docker` in `DICT_ROUTE_TO_HOST_COMMAND`.
+
+Confirm registration:
+
+```bash
+python -m pytest tests/testArchitecturalInvariants.py::testAgentActionRegistered -v
+python -m pytest tests/testArchitecturalInvariants.py::testEveryGuiInvokedMutationHasCliEquivalent -v
+python -m pytest tests/testArchitecturalInvariants.py::testEveryCatalogActionHasCliCommand -v
+python -m pytest tests/testArchitecturalInvariants.py::testGeneratedActionsSendFieldsOnTheTransportTheRouteReads -v
+python -m pytest tests/testHubAppGovernance.py tests/testResearcherActions.py -v
+```
+
+`testAgentActionRegistered` builds only the viewer app;
+`testHubControlPlaneRoutesAreGoverned` applies the same rule to the hub.
+
+### 6. Raise the module-size caps you cross
+
+`testModuleSizeIsBounded` holds every module to `I_MODULE_LINE_CAP`, or
+to its entry in `tests/testArchitecturalInvariants.py::DICT_GRANDFATHERED_MODULE_LINES`,
+which records the module's size when it was last raised. The modules a
+new route registers in (`actionCatalog.py`, `routeScope.py`,
+`appFactory.py`, `pipelineServer.py`) sit at or near their caps, so a
+registration line usually trips one. Raise that entry by exactly what
+the edit needs, with a one-line dated reason above it, as the setup
+wizard did:
+
+```python
+    # 1544 -> 1548 (2026-10-24): the setup wizard's step route is excluded from the agent catalog, with why.
+    "actionCatalog.py": 1548,
+```
+
+A module still at the default cap takes its first entry the same way.
+Never delete blank lines or docstrings to fit under a cap.
+
+### 7. Add tests
+
+Create `tests/test<Name>Routes.py`. At minimum:
+
+- A test that imports the module and confirms `fnRegisterAll` is
+  callable.
+- One test per new endpoint, using the FastAPI `TestClient`. Look at
+  existing `tests/testPipelineRoutes*.py` and `tests/testSyncRoutes*.py`
+  for mocking patterns for the Docker context.
+
+Do not add Docker-dependent tests here — those go under the
+`testContainerBuildIntegration.py`-style exclusions.
+
+### 8. Run the contract tests
+
+```bash
+python -m pytest tests/testArchitecturalInvariants.py -v
+python -m pytest tests/testCarrierModeDeclaration.py tests/testSecurityBoundaryInvariants.py tests/testStyleInvariants.py -v
+```
+
+Expect these to pass without modification:
+
+- `testEveryRouteModuleExportsRegisterAll`
+- `testAllRouteModulesRegisteredInInit`
+- `testAllPackageModulesDefineDunderAll` (if your file lands outside
+  `routes/`, make sure it declares `__all__`)
+- `testModuleSizeIsBounded`, once step 6 is done
+- `testEveryContainerScopedRouteEitherDeclaresOrIsRecordedAsAwaiting`
+  and `testContainerReadScopeIsAFrozenRatchetedAllowlist`
+
+### 9. Run the new route's tests and the full suite
+
+```bash
+python -m pytest tests/test<Name>Routes.py -v
+python -m pytest tests/ -q --ignore=tests/testContainerBuildIntegration.py
+```
+
+### 10. Exercise the endpoint end-to-end if possible
+
+If the route affects the dashboard or reports container state, start a
+real container and confirm the GUI reflects the new data correctly.
+Remember: the dashboard must always reflect the true state of the
+workflow and the container. Do not cache, short-circuit, or hide
+errors.
+
+## Common failure modes
+
+- **`testAllRouteModulesRegisteredInInit` fails.** You forgot to add
+  the module to the `from . import (...)` block in
+  `vaibify/gui/routes/__init__.py`, which is what the test reads. Add
+  it to `__all__` as well; the test does not check that list.
+- **Every app-building test fails with "Mutating routes with no declared
+  authorization scope".** Step 4: a mutating route outside the
+  `{sContainerId}` convention needs a `DICT_CONTROL_PLANE_SCOPES` entry
+  or an `@ffnRouteScope` stamp.
+- **Import error at app startup.** The route module imports a symbol
+  that doesn't exist, or there's a circular import. Route modules can
+  import from `..pipelineServer`, `..pipelineRunner`, and domain
+  modules, but not from other route modules — those are siblings.
+- **A 500 error on the new endpoint when the container is stopped.**
+  Handlers should check container state via `dictCtx["require"]` (called with the container id)
+  early and return a clean 4xx error when the container is not
+  running. Do not mask the error — surface it.
+- **The endpoint answers 404 though every contract test passes.** The
+  module is imported but not mounted: step 3.
+
+## Do not
+
+- Do not bypass `VaibifyApi` on the frontend side if you're also
+  adding a JS caller for this endpoint — route through
+  `scriptApiClient.js`.
+- Do not embed science-specific example names (planet names, system
+  names) in route paths, sample data, or test fixtures.
+- Do not add a new polling loop on the frontend without discussion —
+  see the invariants in `vaibify/gui/static/AGENTS.md`.