Skip to content

CANON-VS-ADR-018-RECONCILIATION-01 — Close Report

Brief: CANON-VS-ADR-018-RECONCILIATION-01 (v2, Gate 1 substrate-bytes-pressure-tested) Authority: Tier 1 / position #1 in RECON-FOUNDATION-LENS-01 §5 re-sequenced queue Filed: 2026-05-27 (Tim + Claude collaboration) Executed: 2026-05-26 across two work sessions (Gate 1 pressure-test prior, Gate 2 substrate inventory + verification + drafts, Gate 3 review, Gate 4 commit) Commit: 43593e87 (4 files changed, 104 insertions, 123 deletions) Status: Closed cleanly. 8 commits ahead of origin, held for Tim push instruction.

1. What was reconciled

Seven tensions

# Tension Resolution
1 Env suffix vocabulary (-ref vs -staging, both directions) -ref retired from name level (contract preserved as reference-data: yes annotation in cloudflare-resource-inventory.md). -staging adopted per ADR-018 v4. Final closed set: -prod / -dev / -staging.
2 Utility decomposition (three concepts in canon, one in ADR) shared- prefix retired (no RTOpacks cross-product target). -tooling/-state suffix mechanism retired (role expressed via Q3 platform-owned rtopacks- prefix). ADR-018's no-prefix utility category adopted as canonical. Entity-prefix-required vs utility-no-prefix principle-level contradiction resolved in favour of ADR-018 (utility category supersedes mandatory entity prefix).
3 Acronym handling (canon's eight-acronym list vs ADR Q1 high-bar test) General rule (source-acronym describes data origin); canon's eight as worked examples, not exhaustive. Vendor brands (QuickBooks, Stripe) resolve to full words. qb is not a sanctioned form. ADR-018 Q1b discussion sharpened from informal qb-reconcile to canonical quickbooks-reconcile for internal consistency.
4 Per-resource-type rename feasibility Verified per-resource-type against current Cloudflare documentation 2026-05-26. Workers + KV renamable cheaply; D1 + R2 + Queues require create-new-and-migrate. ADR-018 rename-conformance phase sequencing updated to reflect: Phase 1 = Workers + KV; Phase 2 = D1/R2/Queue bundled with migration briefs; Phase 3 = remaining D1/R2/Queue deliberate.
5 Per-resource-type pattern grammars vs universal 5-segment shape Universal 5-segment shape supersedes per-resource-type patterns. KV uppercase-underscore named as explicit substrate-imposed exception. Broadened at Gate 2 to cover env tokens (_PROD / _DEV / _STAGING) per substrate inventory finding — one rule wider than v2 brief stated.
6 ucca- scope prefix + ucca as domain word ucca- retired as scope prefix (no operational target in RTOpacks substrate; UCCA Online on separate CF account). ucca permitted as domain/function word in RTOpacks-owned cross-product bridges (e.g. rtopacks-ucca-export-worker-prod). Principle generalises to any external product RTOpacks integrates with.
7 DB-to-surface 1:1 alignment Preserved as substrate-naming-design guidance in canon. Composes with ADR-018's determination test (surface and DB independently resolve to convention-conformant names; guidance is that they should be lexically aligned when 1:1).

Spine §9 fold-in (recon item C1)

  • Naming convention statement updated from 4-segment shape <scope>-<module-or-domain>-<function>-<artefact-type> to ADR-018 v4's 5-segment shape <scope-prefix>-<domain-or-module>-<function>-<artefact-type>-<environment>.
  • Four stale worked examples replaced with convention-conformant equivalents:
  • client-studio-storage-module → rto-studio-storage-db-prod
  • tga-mirror-ingest-bus → rtopacks-tga-mirror-ingest-bus-prod
  • sms-outbound-wrapper → rtopacks-sms-cellcast-wrapper-prod
  • rto-ops-db → rtopacks-ops-db-prod (per Q3 platform-owned determination)
  • ADR-018-as-authoritative-source note added explicitly.

2. Rename-feasibility verification result

Verified 2026-05-26 against current Cloudflare documentation. Captured in both cloudflare-naming-canon.md (with source URLs) and architecture-decisions.md ADR-018 (rename-cost section).

Resource Renamable? CF doc reference
Workers Yes /changelog/post/2025-09-03-new-workers-api/ (stable UUID across rename)
KV namespaces Yes /kv/reference/kv-commands/ (wrangler kv namespace rename)
D1 databases No /d1/wrangler-commands/ (no rename CLI)
R2 buckets No /r2/buckets/public-buckets/ (bucket name in S3 endpoint URL)
Queues No /queues/get-started/ ("queue name cannot be changed after creation")
Service bindings Yes (via Worker rename) UUID stable; binding name per-Worker config

ADR-018's yesterday-flag ("D1 cannot be renamed; Workers can") was directionally right but partial — verification surfaced KV as also-renamable (expanding Phase 1) and confirmed R2 + Queues as also-not-renamable (expanding Phases 2/3 beyond D1). The table is point-in-time; future briefs reference it but verification may update.

3. Substrate-state intelligence surfaced (path (a) RECON Category A confirmations)

The Gate 2 pre-draft inventory pass surfaced multiple substrate-state observations that resolve recon items the canonical docs couldn't ground on their own. These are confirmed Phase 1/2 targets for WORKER-AND-DB-NAMING-CONFORMANCE-01; not actioned in this brief.

Substrate orphans (Phase 1 rename targets — Workers, cheap)

  • kn-preview worker — no prefix at all; Q1 fails (what is "kn"?). Substrate orphan against both canon and ADR-018.
  • radar-crawl worker — no prefix; Q1 fails on first segment.
  • enrich-sync worker — no prefix; Q1 fails (what is being enriched? what source?).
  • cricos-sync worker, tga-sync worker, stats-cache worker, qb-reconcile worker — currently unprefixed; reconciled convention puts them in rename queue:
  • cricos-sync → rtopacks-cricos-sync-worker-prod (Q3 platform substrate ingestion)
  • tga-sync → rtopacks-tga-sync-worker-prod (Q3 platform substrate ingestion)
  • stats-cache → potentially utility per Q1 + Q1b; deferred to Phase 1 judgment
  • qb-reconcile → rtopacks-quickbooks-reconcile-worker-prod (Q1b fails; Q3 platform; vendor brand to full word)

Substrate orphans (Phase 2 rename targets — D1, requires migration)

  • All 9 prod D1 databases lack environment suffix entirely — rto-ops-db, rto-radar-db, rto-workspace-db, rto-landscape-db, rto-calendar-db, rto-micro-db, rto-licensing-db, rto-abs-db, rto-nrt-db. Each requires -prod suffix per ADR-018 v4. Some may also need scope-prefix re-evaluation under the Q-test (e.g. rto-ops-db likely becomes rtopacks-ops-db-prod per Q3 operator-facing; rto-abs-db becomes rtopacks-abs-db-prod per Q3 platform substrate).

Confirmations (path (a) working as designed)

  • Zero -ref resources, zero -staging resources at name level for non-Worker D1 prod, zero shared- resources, zero ucca- resources, zero -tooling/-state suffix resources — all retired-suffix/retired-prefix recommendations are substrate-aligned. The reconciliation work is rule-shaping, not rename-driving for these categories.
  • -staging adopted per ADR-018 v4 is substrate-confirmed — 4 staging Workers and 8 staging D1s already use the suffix. ADR-018 matches operational reality.
  • KV uppercase-underscore is load-bearing and substrate-confirmed — all 12 KV namespaces use the convention. Exception language in canon is operationally grounded.

4. KV exception broadening — v2-brief refinement landed at Gate 2

The v2 brief's Tension 5 stated the KV uppercase-underscore exception in terms of character set and separator. The Gate 2 substrate inventory pass surfaced that the exception also extends to the env-suffix shape: staging KV namespaces use _STAGING (underscore-prefixed, uppercase), not -staging. Examples: ANON_THREAT_KV_STAGING, LEADS_STAGING, SESSION_KV_STAGING, MCP_API_KEYS_STAGING.

This is one rule wider than the v2 brief stated and was raised to Tim at Gate 2 substrate-state flags. Tim's response at Gate 3 confirmed the broader exception as the operationally consistent shape. The reconciled canon captures this explicitly:

KV naming shape: <SCOPE_PREFIX>_<DOMAIN_OR_MODULE>_<FUNCTION>_<ARTEFACT_TYPE>_<ENVIRONMENT> ... Environment markers as _PROD / _DEV / _STAGING (underscore-prefixed, uppercase).

The discipline: Gate 1's substrate-bytes pressure-test surfaced three additional tensions over v1; Gate 2's substrate inventory pass surfaced this further refinement. Substrate-state evidence consistently sharpens rules through use, per the candidate standing rule [[feedback_schema_inspection_as_recognition_trigger]].

5. New forward-referenced briefs / observations

No new briefs filed (per brief drip rule). Recon-§4 Category A observations recorded above resolve into the existing WORKER-AND-DB-NAMING-CONFORMANCE-01 brief's three phases:

  • Phase 1 (Workers + KV renames immediate): the substrate orphans listed in §3
  • Phase 2 (D1/R2/Queue bundled with migration briefs): the 9 prod D1s lacking env suffix
  • Phase 3 (deliberate): remaining items lacking migration vehicle

6. Canonical doc state at close

  • docs/docs/infrastructure/cloudflare-naming-canon.md — substantially rewritten. 179 lines → ~140 lines. Universal convention delegated to ADR-018; canon retained for substrate-specific facts.
  • docs/docs/infrastructure/cloudflare-resource-inventory.md — cross-reference updated to reflect ADR-018 as universal authority + canon as substrate addendum (2-line change).
  • docs/docs/ops/architecture-decisions.md — header pinned (18 → 19 ADRs); ADR-018 Q1b worked-examples sharpened (qb-reconcile → quickbooks-reconcile, vendor-brand resolution rule); ADR-018 rename-feasibility section expanded with verified per-resource-type table (25 line change).
  • docs/docs/ops/client-spine.md — §9 naming convention statement updated to 5-segment shape with conformant worked examples and ADR-018-authoritative-source note; closing-line ADR count pinned (18 → 19) (4 line change).
  • Commit 43593e87 — single coherent commit per METADATA-RECONCILIATION-AT-COMMIT discipline. 8 commits ahead of origin, held until Tim push instruction.

Per RECON-FOUNDATION-LENS-01 §5 re-sequenced queue, Tier 1 #2 is the next pull direction. Candidates from the recon Tier 1 set:

  1. IDENTITY-MODEL-RATIONALISATION-01 — Step 0 prerequisite for ANY ops-db split work. Resolves 4 identity conventions in rto-ops-db (email/UUID/prefix/randomblob user_id) into one canonical model. Blocks all DB-split execution. Strong sequencing case: identity work clears a known blocker on multiple downstream briefs.
  2. Standing-rules updates — three candidate rules earned through use are awaiting promotion to formal rules: METADATA-RECONCILIATION-AT-COMMIT (applied cleanly at this commit; one more application earns promotion); RECON-PASS-ON-FOUNDATION-SHIFT (recon §C8); recon-docs-at-position-4b (recon §C10). Small, fast brief that codifies the discipline.
  3. WORKER-AND-DB-NAMING-CONFORMANCE-01 Phase 1 — Workers + KV renames are now unblocked by this brief. Cheap, fast, high architectural-visibility value.

Tim's call on which to drip next. The METADATA-RECONCILIATION-AT-COMMIT discipline working as candidate rule at this commit suggests a small standing-rules update brief could land quickly and codify the disciplines for the next iteration; IDENTITY-MODEL-RATIONALISATION-01 is the heavier prerequisite that needs to land before DB-split work resumes.

8. Process notes

Gate 1 substrate-bytes pressure-test pattern held

The same "engineering-reality flags raised against the canonical proposal" discipline that produced the four ADR-018 refinement rounds on 2026-05-26 produced this brief's v2 sharpening (4 → 7 tensions, plus per-tension resolution sharpening). The pattern continues to earn its place: canonical articulation tested against substrate bytes consistently sharpens rather than retracts.

Gate 2 substrate inventory as second pressure-test layer

The pre-draft substrate inventory at Gate 2 surfaced a further refinement (KV exception broadening to env tokens) over and above Gate 1's bytes-pressure-test. Two layers of substrate-state pressure-testing produced a substantially sharper canon than the v1 brief shape would have. The pattern: bytes-pressure-test at Gate 1 (against canonical doc state) + inventory-pressure-test at Gate 2 (against live substrate state) catches different classes of drift.

METADATA-RECONCILIATION-AT-COMMIT discipline

Header pins on architecture-decisions.md and client-spine.md applied in the same commit as the substantive changes, per the candidate standing rule. Two header pins + one cross-reference update + two substantive doc changes = five-file coherent commit. The discipline scales naturally to small adjacent fixes; this is the second observable instance of the rule applying (first: SPINE-AND-ADR-05b header pin caught one commit late).

End of close report. Brief drip moves to next brief on Tim's instruction.