[EPIC] Establish single ownership of the Appwrite environment

[Polichinel]

The problem

The platform resolves Appwrite configuration through two mechanisms that both write to the same shared mutable state — the process environment — with no rule about which wins.

views-models/postprocessors/un_fao/run.sh sources .env (15 coordinates + 1 secret at lines 23-27), then exports registry values over the top (line 88). The registry wins because it runs second, not because anything says it should. Reorder those two blocks and the semantics invert silently.

Why this is correctness, not tidiness

Two prior reviews framed this as duplication and discoverability. A third, reading it through Rust's ownership model, found it meets a formal definition. Rust states three conditions for a data race, all of which must hold simultaneously:

Condition	Here
Two or more pointers access the same data	.env and the registry both name APPWRITE_ENDPOINT, *_BUCKET_ID, all 15
At least one is used to write	both write
No mechanism synchronising access	none. Statement order is the only discipline, and it is implicit

All three hold. This is not an analogy — it satisfies the definition.

Two related findings from the same lens:

• A /blob/main/ reference is a dangling pointer. Rust: "a reference to a location that may have been given to someone else." views-datafactory's guides linked to main; §5.7 was struck; the reference silently began resolving to different rules. A pinned tag is a lifetime annotation; main is a raw pointer into mutable storage.
• Clone must be visible. Rust does not forbid duplication — it forbids implicit duplication, because .clone() is "a visual indicator that something different is going on." The secret exists in four places and nothing marks any of them as a copy.

The contract already mandates the fix; the shell layer cannot express it

Seam contract §2:

Every library on this seam receives credentials as constructor parameters from the launching process and must never source, persist, default, or log them.

That is ownership and borrowing stated exactly: the launcher owns, libraries borrow, libraries never persist. views-postprocessing implements it correctly (it asserts rather than loads). Shell cannot comply — it has no parameter passing to child processes, only the global environment. That is why this defect class keeps recurring, and it is not a bug in any one file.

Desired end state

• Exactly one writer per class of value. Registry owns coordinates. Operator owns the secret. A second writer errors rather than losing quietly.
• No importable library loads a .env anywhere on the platform.
• Registry resolution failure exits non-zero. No warn-and-continue.
• A new machine is set up by running one script, which is tested in CI without real credentials.

Already shipped — verified against current HEADs, not assumed

Work	Where	State
find_dotenv() deleted; preflight on every Appwrite path; AppwriteConfig frozen	views-pipeline-core#346	closed
C-231 metadata-delete fix	views-faoapi#322	shipped in v1.4.0
Cache-partition salt	views-faoapi#323	shipped in v1.4.0
Conformance vector	views-appwrite#13	closed

Explicitly NOT this epic

• Extracting shared client code into views-appwrite. That is views-faoapi#337, gated on þing-01 D8, which is views-appwrite#23. Those two are the same decision seen from opposite sides. Cross-linked, not re-scoped here.
• The 131 run.sh files. They do not touch Appwrite — grep -ci appwrite returns 0. CRP: things not reused together should not be forced together. They get one marking line (S7) and nothing else.
• The views-models rename; any secret-store design; views-pipeline-core#339's eviction phases.

Stories

#	Story	Repo	Depends on
S1	Contract states the single-writer rule	views-appwrite	—
S2	Registry resolution fails loud (C-47)	views-models	—
S3	tools/platform_env.sh — one writer (C-48)	views-models	S1, S2
S4	The surviving library dotenv load at model_path.py:371	views-pipeline-core	—
S5	faoapi resolves coordinates from the registry	views-faoapi	S1
S6	Agreement check between the two registry readers (C-50)	views-appwrite	—
S7	Mark the 131 generated run.sh as clones	views-models	—
S8	bootstrap.sh, CI-testable without credentials	views-models	S2, S3
S9	Fill the dead [Internal Tech Guide]() link	views-platform/docs	S8
S10	views-crafdapi adopts the pattern at birth	views-faoapi	S5

Order: S1 · S2 · S4 · S6 · S7 (independent) → S3 → S5 → S8 → S9 · S10

S2 first among implementation items — it is the one most likely to break the machine being set up next.

Epic acceptance criteria

• Exactly one writer per class of value; a second writer errors rather than losing silently
• No importable library loads a .env anywhere on the platform
• Registry resolution failure exits non-zero
• views-faoapi's .env requires one variable
• bootstrap.sh green in CI with no real credentials, and followed end-to-end on a machine that had never run the platform
• The onboarding guide's technical pointer resolves
• views-crafdapi never acquires a second .env habit
• Both registry_to_env.py copies proven to emit identical output

Why this epic is homed here

The registry is homed in this repo and this is seam contract §4 territory. Most of the work lands in views-models and views-faoapi; this epic holds the shape, the ownership rule, and the acceptance criteria.

[Polichinel]

S1 (#27) closed as unnecessary — the rule already exists in §4, ratified since þing-01.

The epic proceeds unchanged otherwise. S3 (views-models#309) and S5 (views-faoapi#349) listed S1 as a dependency; they now depend on §4 directly. The enforcement S1 was reaching for becomes a regression test folded into S3.

No þing is required for any remaining story. Next: S2, views-models#308.

[Polichinel]

Prudence sweep, 2026-08-02 — five errors found in my own issues, all corrected

Run after I broke the coordinate registry platform-wide and did not notice for a day. Every factual claim in every story issue was re-verified against the files.

Issue	Error	Corrected to
S2 views-models#308	run.sh:81	:67
S3 views-models#309	.env sourced at :23	:24
S3 views-models#309	"15 coordinates"	12 — prefix-inferred, which §3 forbids
S6 #28	"two registry readers"	three — crafdapi added one
S10 views-faoapi#350	"no .git, package still views_faoapi"	both wrong — it is a public git repo, already renamed

Verified correct and unchanged: S4 (model_path.py:370-371), S5 (api.py:41-50, 8 vars), S7 (132 runners, 1 with the pattern, 42 lines, 0 appwrite refs), S9 (empty link at line 31).

The break's blast radius was wider than I first reported

Three readers crashed, not one — including views-faoapi/deployment/registry_to_env.py, which provisions the production server, and views-crafdapi/deployment. Fix in #31.

One structural finding from the sweep

The contract rename did not break anything: pipeline-core's two code references are pinned at platform-001-v1.2.0, a tag that still resolves to the old filename. That is the pinning rule doing exactly what it exists for — and it is the reason the rename was safe while the registry edit was not. A pinned reference survives a rename; a live data file does not survive a schema mistake.

[Polichinel]

Status audit, read in every repo's code 2026-08-12 — 7 of 10 stories are done, and this epic has not been blocked for some time

This issue has sat in a "blocked on other repos" bucket, including in summaries written from this seat. That was wrong. The audit below is code, not issue text.

#	Story	Repo	State
S1	Contract states the single-writer rule	views-appwrite	✅ DONE TODAY — §4.2, appwrite-seam-v1.7.0
S2	Registry resolution fails loud (C-47)	views-models	✅ platform_env_require_registry() is FATAL, exits non-zero
S3	One writer (C-48)	views-models	✅ tools/credentials/platform_env.sh
S4	The library dotenv load at model_path.py:371	views-pipeline-core	✅ gone — only a path attribute remains
S5	faoapi resolves coordinates from the registry	views-faoapi	✅ deployment/bootstrap.sh builds .env.faoapi from it, FATAL if absent
S6	Reader-agreement check (C-50)	views-appwrite	✅ shipped as the guards (cross-repo) CI job
S7	Mark the generated run.sh as clones	views-models	❌ 0 of 115 carry a marker
S8	bootstrap.sh, CI-testable without credentials	views-models	✅ .github/workflows/bootstrap.yml — fixture registry, FAKE-CI-SECRET, idempotence tested
S9	Fill the dead [Internal Tech Guide]() link	views-platform/docs	❌ structurally blocked — see below
S10	views-crafdapi adopts the pattern at birth	views-crafdapi	✅ has both deployment/bootstrap.sh and registry_to_env.py

S1 is done — and why it was late is the finding

S1 had no dependencies and lived in this repository. It sat undone for eleven days while seven of the other nine shipped elsewhere. Nobody was blocking us; we had not looked.

appwrite-seam-v1.7.0 adds §4.2 — exactly one writer per class of value: coordinates and [contract.*] facts written by the registry, the secret by the operator, and a second writer must fail loudly rather than take the later of two writes.

It obliges consumers — obliges_consumers_since moves 1.5.2 → 1.7.0, the first raise since that mechanism was built. A rule constraining how every launcher assembles the environment asks something of every launcher, and the honest classification was worth more than the convenient one.

The rule describes what the platform already does, which is the argument for stating it now: views-models' platform_env.sh declares itself the only writer, and both consumer APIs' bootstrap.sh build the environment from the registry and abort rather than falling back. Compliance is currently free.

The desired end state, checked

• ✅ Exactly one writer per class — now stated (§4.2) and implemented in all three launchers
• ❌ No importable library loads a .env anywhere — views_pipeline_core/modules/dataloaders/dataloaders.py:402 still calls load_dotenv. It raises on both missing-file and failed-load, so it is fail-loud rather than silent, but the end state says none
• ✅ Registry resolution failure exits non-zero
• ✅ One script sets up a machine, CI-tested without real credentials

What actually remains

S7 — small, views-models' to do: a marker line on 115 generated files.

S9 is not "not yet done", it is structurally impossible as filed. docs/Onboarding Resources/views_platform_onboarding_guide.md is in no repository — it sits untracked in the workspace root. No pull request in any repo can fix its dead link. This needs an operator decision: which repository owns platform onboarding? Until that is answered, S9 cannot be assigned, and #25 is blocked on the same fact.

The dataloaders.py load — belongs to views-pipeline-core; not currently any story here.

Recommendation

Retitle or re-scope: this epic is ~70% shipped and reads as untouched. The remaining work is one small task in views-models, one operator decision, and one library load in views-pipeline-core.

#29 is this epic's tracking twin — the same relationship #74 had to epic #66, which was closed as stale yesterday. It should get the same treatment whenever this one closes.

[Polichinel]

⚠ Correction to my audit above — S9 is not structurally blocked

My status audit an hour ago said of S9:

"not "not yet done", it is structurally impossible as filed... the guide is in no repository... No pull request in any repo can fix its dead link. This needs an operator decision: which repository owns platform onboarding?"

Wrong. The guide is tracked in views-platform/docs — Onboarding Resources/views_platform_onboarding_guide.md. My search globbed sibling directories matching views-*; the repository is checked out as docs/. A null result from a search that could not have found the thing is evidence about the search, not the world — which is register C-67's rule, applied everywhere on this platform except to my own probe.

The Internal Tech Guide also already exists, in the same folder: Onboarding Resources/internal_technical_guide.md. S9 is a broken relative link to a file sitting beside it. One line.

S9 is not blocked, but it should not be done first

The target mentions Appwrite, the registry, credentials, or .env zero times, and tells a newcomer that run.sh sets everything up. That is no longer true on the delivery path — un_fao/run.sh sources platform_env.sh, which needs a sibling views-appwrite checkout and is FATAL without it.

Filling the link would point people at instructions that fail. So S9 is really two steps: fix the target, then the link. The dead link is currently the less harmful of the two states.

Corrected epic status

#	Story	State
S1–S6, S8, S10		✅ 8 done
S7	Mark the generated run.sh as clones	❌ 0 of 115 — views-models, small
S9	The tech guide + its link	⚠️ not blocked — views-platform/docs, two steps, ordered

So this epic is 8 of 10 shipped, and neither remaining story needs an operator decision. My "which repo owns onboarding?" question was invented by a bad search.

The ownership question was still worth asking, and it has an answer

Discussed with the operator; the agreed split:

• views-platform/docs owns navigation — "what repos exist, where do I start". Thin, cheap, rarely changes.
• The repos own instruction — "what do I run". Anything with a command in it lives next to the thing that executes it.
• Nothing executable is described in prose in a repo with no CI. The setup section becomes a pointer to bootstrap.sh, which is already CI-tested in views-models with a fixture registry and a fake secret — S8 of this epic. A script CI runs cannot go stale silently; the paragraph describing it did.
• Seam-specific onboarding stays here — docs/ADRs/platform/joining_the_seam.md, next to the contract it describes.

The reasoning, which is the same one this epic is built on: distance from the source of truth is maintenance cost, and stale documentation fails the way a guard that cannot fail does — silently, while looking fine.

Filed on views-platform/docs.

[Polichinel]

⚠ Second correction — S1 was already done, and I undid my own "fix"

My audit two comments up listed S1 as ❌ not done and then claimed to have shipped it as contract §4.2 in appwrite-seam-v1.7.0.

Both were wrong. S1's issue — #27 — was closed as unnecessary on 2026-08-02, with PR #30 withdrawn. Its reasoning still holds:

"the clause was redundant where it was right, and wrong where it was new."

• Redundant where right — §4 has said since þing-01 that coordinates are never copied into .env as a source of truth; §6 raises on a wrong coordinate; §7 makes preflight fail loud.
• Wrong where new — the novel part, that a launcher must refuse even when the two writers agree, was rejected then and is rejected now. It makes a correct environment an error.
• The work went to S3 — "a latent hazard with a correct current behaviour is a test, not a clause." views-models#309 shipped it as tools/credentials/platform_env.sh.

§4.2 has been struck in appwrite-seam-v1.7.1, and obliges_consumers_since returned to 1.5.2 — nobody should inherit an obligation from a withdrawn clause. Struck rather than deleted, per §10.

How I did it

I read this epic's story table, grepped the contract for "single writer", found nothing, and concluded S1 was undone — without opening #27. #27's closing note ends: "Before adding a clause, check whether the contract already says it."

The same failure that produced the clause produced it a second time, against a note written to prevent exactly that.

Corrected epic status

#	Story	State
S1	Contract states the single-writer rule	✅ closed as unnecessary 2026-08-02 (#27) — the rule is §4; enforcement is S3
S2, S3, S4, S5, S6, S8, S10		✅ done
S7	Mark the generated run.sh as clones	❌ views-models#310 — 0 of 115 marked
S9	The tech guide + its link	⚠️ views-platform/docs#82 — not blocked, but fix the target before the link

9 of 10. One small task in views-models, one documentation task with an ordering constraint. Nothing needs an operator decision, and my earlier "which repo owns onboarding?" question was invented by a bad search.

Also corrected

I filed views-platform/docs#83 duplicating #82 — which is named in #29's own checklist, the document I was auditing. #83 is closed; its one real finding has been moved to #82.

All three errors share a cause: I read a summary table where the linked issues were the evidence. Register C-73.