# scout — v8 substrate feedback

> Running log of friction hit while building **inside** the v8 conventions.
> **This is feedback about the substrate, not about this project** — it gets
> compiled into `/srv/.logs/planning/server-evolution-2026.md` or the ops queue
> (`/srv/.logs/ideas.md`) once the build settles.
>
> Scope discipline: only entries where the *server framework, standards library,
> or gateway* caused the friction. Bugs in this project's own code belong in
> `handoff.md`, not here.
>
> Each entry: what happened, what it cost, and a candidate fix.
> (Pattern proven 2026-07-30; it is what turns one project's
> pain into a standards fix for every later project. Delete this file if the
> project never hits substrate friction.)

## 2026-08-12 — dev-dependencies have no home on the React/FastAPI stack

**What happened:** the M1 pytest suite must run in-container against real
Postgres (the upserts are PG-dialect). `react.md` prescribes pytest+httpx but
the stack's Dockerfile pattern has no dev-dependency layer, so the suite needs
`pip install pytest httpx` via `docker exec` — and every `srv-gw deploy`
recreates the container and silently wipes it. **Cost:** two mid-session
"ModuleNotFoundError: httpx" failures and a re-install after every deploy;
tests also aren't in the image, so they ride in via `docker cp`.
**Candidate fix:** react.md documents a standard `requirements-dev.txt` +
optional build stage (or a sanctioned "tests run like this" recipe) so
in-container testing is a first-class path instead of ad-hoc.

## 2026-08-12 — openapi-typescript makes defaulted fields required

**What happened:** adding an optional-with-default field
(`client_website: str = ""`) to a Create model broke the image build — the
generated TS client marks defaulted fields *required* (`defaultNonNullable`
default), so an existing frontend caller no longer compiled. The failure is
GOOD (the seam-check working) but it surprises: a "backwards-compatible"
backend addition is not backwards-compatible at the generated-client layer.
**Cost:** one failed deploy cycle (~3 min).
**Candidate fix:** one line in react.md's generated-client section naming this
behavior, so the next builder budgets the frontend edit into any Pydantic
model addition instead of discovering it from a red build.

## 2026-08-12 — concurrent subagents + setgid dirs don't mix cleanly

**What happened:** two parallel agents `mkdir -p`-raced the same new source
directory; the loser's `chmod 775` (session not in the project group) silently
stripped setgid, briefly leaving wrong group ownership. Both self-healed via
`sg`/`srv-gw fix-permissions`, and agents.md already documents the kernel
behavior — but the rule "create new subdirectories under `sg <project>-dev`"
lives per-project. **Cost:** ~2 min of agent self-correction, no residue.
**Candidate fix:** promote the `sg`-for-new-dirs rule from per-project
agents.md into `coding.md`'s file-permissions section (it applies to every
served project on the box).