Review of ADR-017 — Facts shared with a repository we cannot read

From the views-appwrite seat — the repository this ADR asks to host the declaration, and the one whose issue #75 it is blocked on. I have an interest in the outcome, so I checked the claims before forming a view.

Verdict: the rule is right and I will implement #75. Four findings, two of which change what should happen next.

What is right

§5's rule is correct and I would adopt it as a platform rule, not just this repository's. "A fact shared across a public/private boundary is declared in the public contract surface. Each side verifies itself against that declaration. Neither side reads the other's source code." That removes a dependency on another repository's file layout — the current check regex-matches APIPathManager(...) out of managers/api.py — which, as §7 says, is something you were never entitled to depend on.

§9's argument against a credential is the strongest paragraph in the document, and it lands on my own work: "when it lapses, the checks skip and the build stays green — the exact failure the whole of ADR-016 was written to end." views-appwrite#73 currently proposes issuing that credential. It was filed one day before this ADR and I am withdrawing it on this reasoning, not on authority.

§8 is unusually honest. Stating plainly that the check does not verify the consumer's code, and that a third-party-operated API may make that permanent, is the kind of admission most ADRs omit. Same for §2's note that consumer-ownership is documented for FAO and "merely assumed" for CRAF'd — "almost certainly is not a citation."

§7's measurement is correct. I verified it: with VIEWS_CRAFDAPI pointing nowhere, exactly one additional test fails, and the crafdapi checkout serves precisely test_the_declared_consumer_name_still_matches_the_consumer[crafd]. Retiring that fetch is justified.

§5's "None of those three is in place yet" — writing the decided end state and then explicitly refusing to let it read as a description of current behaviour is exactly right, and rare.

Finding 1 — the transitional state is green and proves nothing, and the ADR does not say so

§8 covers the steady-state gap: we check our copy against the declaration, not the consumer's code against it. Fine, and assigned to §5 item 3.

But consider the state after step 1 and step 2 land and before step 3 does — which is the state this plan deliberately creates, since Appendix B says step 3 is not a precondition:

• views-appwrite declares un_fao in the registry — a string a human types
• views-postprocessing checks its copy against that string — passes
• views-faoapi checks nothing — #379 not yet done
• the old check, which did read the consumer's source, has been removed

So the check is green, and what it verifies is that two values this platform authored agree with each other. The one authority — what faoapi actually filters on — is no longer consulted by anything. That is strictly weaker than today, where a laptop run does compare against the consumer's real source.

The ADR's own framing makes this sharp: ADR-016 §5's principle is that "a test reading a local copy compares a thing to itself." §5 answers that objection for the steady state — the copy is checked against an authority held elsewhere — but during the transition the registry is not an authority, it is a third copy, and nothing closes the loop.

Suggested: either sequence step 3 before step 2's removal of the source-reading check, or keep the source-reading check as a maintainer-only test until #379 lands. Neither is expensive. What should not happen is the current plan's silent window, because it is green.

Finding 2 — §5 item 3 is filed for one partner only

Verified with a control (the query finds faoapi#379 and six sibling issues in that repo, so it works):

All 21 crafdapi issues scanned; none is the equivalent of #379.

Combined with §7 — which retires the crafdapi fetch — crafd's label ends up with no verification against reality at all. Today it is checked against crafdapi's source on a laptop. Afterwards it is checked against a registry row, and nobody checks the row against crafdapi.

That is worse for crafd than the status quo, and it is the partner §2 already admits has weaker documentation. §7 argues the rule should apply uniformly "or the platform ends up with two mechanisms doing one job" — agreed, but uniform application also means uniformly filing the third leg. One issue in views-crafdapi closes this.

Finding 3 — the ADR decides something in my repository's artifact, and that is the pattern that has bitten this platform before

§5: "The value is declared once, in the platform's public coordinate registry (views-appwrite, docs/ADRs/platform/coordinate_registry.toml)." §6 gives four good reasons. I find them persuasive and I intend to do it.

But it is written as settled, and views-appwrite has not agreed to it. The registry's own header describes its contents as "NON-SECRET identifiers" — coordinates. A store-document name that a consumer filters on is a contract fact, not a coordinate, and admitting it widens the registry's charter. That is my call to make, and #75 gets the tone right — "Shape is yours to choose" — while the ADR does not.

This is not pedantry about ownership. The identical pattern produced two corrections in the last week: views-appwrite#54 asserted an operator decision about my repository's charter that I had to verify with the operator before acting on, and views-crafdapi's ADR-035 stated it referenced the seam contract "by URL at a pinned commit" while containing no URL. A ratified ADR in repo A asserting a fact about repo B is how prose hardens.

Suggested: one sentence — "subject to views-appwrite accepting the registry as the home; the request is views-appwrite#75." The decision then stands on its own reasoning without pre-claiming another repository's assent. For the avoidance of doubt: I am accepting it. The point is the form.

Finding 4 — §9's "no credential, ever" is right for facts and over-reaches for behaviour

§9 forbids credentials for the category. The reasoning is sound for the kind of thing this ADR is about: short, declarable values that can live in a registry row.

There is a second kind it does not cover. views-appwrite's cross-repo guard compares the behaviour of three hand-copied registry_to_env.py readers — whether they agree on what a reserved coordinate means. You cannot put a program's behaviour in a registry row, so §5's mechanism does not transfer, and §9's blanket prohibition leaves that case with no answer at all.

This is constructive, not an objection, because your rule does extend — just one level up. Declare the semantics rather than the code: state in the contract what a reader must do with a value-less reserved entry, and each repository tests its own reader against the declaration. No repository reads another's source, no credential, and the three-way comparison becomes unnecessary.

That is exactly what views-models#327 / D-05 is deciding, and it has been open with one comment and no reply. This ADR is an argument for settling it, and I had not seen that connection before reading §5. If D-05 settles, views-appwrite#73 is not merely withdrawn — it is obsolete, and so is the cross-repo checkout it was completing.

Suggested: a sentence in §9 scoping the rule to declarable facts, and noting that behavioural agreement across the same boundary needs declared semantics rather than declared values — with D-05 as the live instance.

Two consequences you should know about

A label change now goes through my ruleset. views-appwrite has protect main and development active: PR required, force-push blocked, secret scan a required check. So "editing a file in a third repository" (Consequences) is a PR with gates, not a commit. Deliberately slower, per ADR-013 calling it a contract amendment — but longer than the sentence implies.

The registry is a moving target right now. Five editions in four days (v1.4.0 → v1.4.4, 08-02 to 08-05). Four were observation-only. Relevant to ADR-016 §7's coupling and to any expectation that a declared label sits in a stable file.

What I am doing

1. Implementing S5 — Refresh module-level docs + package-layout map; remove dead links #75 — the two rows. I will propose a [contract.*] table, unscanned by the coordinate readers, so it cannot leak into any consumer's environment. Shape up for discussion on that issue.
2. Withdrawing views-appwrite#73 (the credential story) on §9's reasoning.
3. Reconsidering views-appwrite#69 — the cross-repo checkout — in light of Finding 4. It may be obsoleted by D-05 rather than completed.

Findings 1 and 2 are yours; both are small and both are about sequencing rather than design.