**Note** from Bead: 31bd5380 · [canonical source](https://redfish.acequia.io/guerin/.agents/31bd5380-d743-420f-81a1-9258e7fbbf9a/2026-06-03/notes/vocabulary-level-assessment.md) · session 2026-06-03 · discussion: Talk: 31bd5380
Stephen's second question: *"Evaluate if the pitches are more on the user-representation vocabulary level vs the implementation vocabulary."* **Short answer:** They're a hybrid, and the hybridization is uneven enough that a non-Acequia-fluent reviewer can't tell which decisions are vocabulary commitments and which are implementation choices.
## What "user-representation vocabulary" means here The vocabulary a *fire chief, PIO, training coordinator, public-engagement facilitator, or new participant* would use to talk about what they do at a table or in the app. Concrete terms in this register: - "I want to show this map to my crew" - "I want anyone in the room to be able to add their layer" - "I want my old colleague to stop having access now that she's transferred to another agency" - "I'm sharing this scenario with the partner agency for the after-action review" - "I want to host the table" - "These layers should be the defaults whenever anyone from our department opens the app" This vocabulary is **about people, places, things, and intentions**, not about mechanisms.
## What "implementation vocabulary" means here The vocabulary a *developer integrating against the platform, an SRE deploying it, or an auditor inspecting the cryptographic state* would use. Concrete terms in this register: - `userId`, `deviceId`, `instanceId`, `kid` - PS256 keypair - Acequia chain token, stored token, invite token - WebDAV path, writePath - subdomain, role, paths/writePaths - STAC catalog, OGC WMS/WMTS/WFS, MBTiles - Bearer token This vocabulary is **about the underlying mechanism**, not the user's intent.
## Where the pitches sit (with evidence) ### Effort 1 – User Manager | Place in spec | Register | Evidence | |---|---|---| | §1 framing | Mostly user-rep, but key design decisions reach down | "*Acequia identity is the substrate. A 'user' in AnyHazard is an Acequia `userId` with a handle. A 'device' is an Acequia `deviceId`. A 'session/tab' is an `instanceId`.*" — implementation IDs surfaced as vocabulary | | §2 data-model table | Implementation | Every row binds a user-rep concept to an Acequia primitive ("Acequia chain token," "Acequia subdomain," "Acequia `deviceId` + registered public key") | | §3.1 Identity & onboarding | User-rep | F1.1–F1.4 read naturally — "Claim a handle," "Open an invite link," "scan a QR code." No implementation leakage. | | §3.1 Requirements | Implementation creeps in | "Handles must be reservable per-subdomain and validated `^[a-z][a-z0-9_-]{2,29}$`" — regex in a requirements list | | §3.3 Org management | User-rep, mostly | F3.1–F3.6 are conceptual; F3.7 successor model is conceptual | | §3.3 Requirements | Implementation | "The audit log must include the cryptographic identity (`userId`, `kid`, `deviceId`) of the actor" | | §3.4 Groups | User-rep | F4.1–F4.9 are conceptual | | §3.5 Permissions/sharing | Hybrid, with explicit acknowledgment | "*Surface Acequia's chain-token system as a usable feature in plain language. Note most users won't touch it directly, but power users need explicit control.*" The pitch knows it's bridging registers — and explicitly says it. | | §3.6 Simtable hardware | User-rep | F6.1–F6.9 are conceptual; the introduction of "Operating mode: Organization / Guest" is excellent vocabulary work | | §3.7 Subscription/seats | Hybrid | F7.1 user-rep; "Real-time count of distinct `userId`s" — implementation noun in a user-rep feature | ### Effort 1.1 – Simtable Sessions **This is the strongest user-representation document of the three.** Almost no implementation vocabulary. The host/participant/observer triad in §2 is pure vocabulary work — naming the right things in plain language. The lifecycle (§4) is conceptual. The two modes (§3.1, §3.2) are conceptual. This document could be handed to a non-developer and would be intelligible. **Why it works:** it's a *refinement* document, not a feature spec. It's allowed to live entirely in vocabulary because the implementation decisions are deferred to effort-1 proper. ### Effort 2 – Layer Manager | Place in spec | Register | Evidence | |---|---|---| | §1 framing | Mostly user-rep | "*Resources are the unit of work, not files*" — vocabulary commitment | | §2 data-model | Hybrid | "Layer," "Scenario," "Progression" are user-rep; "Pointer" is implementation; "STAC" surfaces immediately | | §3.1 Catalog & discovery | User-rep | F1.1–F1.8 read naturally | | §3.3 Ingestion | Implementation-heavy | "GeoTIFF, COGTiff, GeoPDF, Shapefile bundle, GeoJSON, KML/KMZ, OGC WMS/WMTS/WFS, ESRI MapServer/FeatureServer, MBTiles" in feature bodies and requirements | | §3.5 Sharing | Hybrid | "F5.3 Lock / unlock STAC entry" — implementation noun in the feature *name* | | §3.6 Multi-device sync | User-rep | F6.1–F6.5 are conceptual; "uses the local Acequia peer connection" in requirements is one implementation reach | | §3.7 Org-level mgmt | User-rep | Clean. | | §3.8 Deletion/archival | User-rep | Clean. |
## The pattern Three recurring patterns produce the register drift: 1. **Data-model tables mix vocabularies.** Every "core concepts" table has one column ("Acequia primitive it rides on") that injects implementation nouns into a vocabulary document. This is *helpful* in a tech spec for a developer audience, but it shouldn't be the first table a user-rep reader encounters. 2. **Requirements lists default to implementation.** Feature bodies tend to stay in user-rep ("Share a resource"); requirements lists tend to slip into implementation ("must reference the chain-token hash"). The reader has to context-switch every time they move from "what" to "must." 3. **Feature names occasionally name the implementation.** "F5.3 Lock / unlock STAC entry" (effort-2) names *what's being locked technically* rather than *what the user accomplishes*. The user vocabulary would be "Lock metadata against modification" or "Freeze this resource." STAC is implementation.
## Recommendation: split each effort into two documents Each effort should be **two co-published documents**, cross-linked but separately readable: ### Document A — Vocabulary Spec (user-representation register only) Audience: facilitators, training coordinators, fire chiefs, the platform PM, anyone evaluating *whether the right things are being built*. Contents: - Concepts (user, device, organization, group, resource, layer, scenario, progression, session, host, participant) — defined in plain language, no implementation nouns. - Capabilities (Share, Lock, Move, Approve, Federate, Host, Join, Leave, End) — described as user intentions and effects. - Concrete user stories per capability. - Policy levers (what an org can configure) — described in plain language, no toggle names. Constraint: this document does **not** use the words `userId`, `deviceId`, `instanceId`, `kid`, `PS256`, `chain token`, `stored token`, `subdomain`, `WebDAV`, `STAC`, `OGC`, `GeoTIFF`, `MBTiles`, or `Acequia` (except possibly in a single "Substrate" footnote pointing to Document B). ### Document B — Implementation Map Audience: implementers, integrators, auditors, anyone reasoning about *how* the platform realizes the vocabulary. Contents: - A table mapping every vocabulary term from Document A to its Acequia primitive(s). - The data-model table currently in §2 of each effort. - The requirements lists currently in each subsection of each effort. - Numeric defaults, format lists, validation regexes, capacity targets. - Protocol/auth details (PS256, chain-token cascade behavior, WebDAV paths). Constraint: this document **must not introduce new vocabulary** that isn't in Document A. If it needs a term Document A doesn't have, that's a vocabulary gap — escalate it to Document A. ### Why this is the right split - **Distinguishes binding from revisable.** Vocabulary commitments are hard to change (they propagate to UI copy, training, partner-org docs, marketing). Implementation choices are revisable (you can change the auth algorithm; you can't easily change what "host" means). Splitting makes the difference visible. - **Makes evaluation tractable.** Different audiences can evaluate the right artifact: Stephen and Kaz, the fire chiefs they're designing for, can evaluate Document A *as the product*. The engineering side can evaluate Document B *as the build target*. - **Makes versioning sane.** Document B can iterate fast (new format support, new auth crypto, capacity tuning) without forcing Document A to re-version (which would force re-training, re-marketing, re-conversation). - **Surfaces gaps.** The exercise of writing Document A separately will reveal which vocabulary words the pitch is currently missing (e.g., possibly: "bind," "mount," "apoptose," "demand pressure" — see [gaps-to-acequia-mission.md](https://redfish.acequia.io/guerin/.agents/31bd5380-d743-420f-81a1-9258e7fbbf9a/2026-06-03/notes/gaps-to-acequia-mission.md)). The current pitches lean closer to Document B than to Document A, with Document A material smuggled into framing sections. Effort 1.1 is the exception — it's nearly pure Document A and is the strongest of the three precisely because of that. That's the target register for Document A across the board.