stash

docs/glossary-todo.md

@@ -0,0 +1,141 @@
+# Glossary terminology TODO
+
+Working list from a repo-wide audit of where code/docs use a different word for a concept that
+[glossary.md](glossary.md) already gives a canonical name. Nothing here has been changed yet, this
+is a collection point before any renaming/edit work starts. Grouped by glossary term; only real
+inconsistencies are listed, not every correct usage that was checked and cleared.
+
+## Backend
+
+- `frontend/src/federation.js` — the whole module (`class ServerSet`, `add(server)`, every
+  request method) talks about "server" throughout where the concept is a **Backend**.
+- `frontend/src/store.js` — `getHomeServers`, `getFriendServers`, `getAllKnownServers`,
+  `setAllFriendsServers`/`all_friends_servers`, `home_servers`, `lookupServer` (~line 313, 325,
+  332, 359, 76-77, 107-108, 334).
+- `frontend/src/views/Friends.vue:16,43` — user-visible table column labeled "Server".
+- `docs/design-in-progress/tags.md` (lines 10, 20, 45, 76-78, 117, 204, 228-229) — "server" used
+  throughout for what the glossary calls Backend (same looseness federation.md already has, but
+  worth normalizing here too since tags.md is in active editing).
+- `issues.md:58` — "federated home servers" / "user identity" conflation.
+- `deploy/dev/docker-compose.yml` (`instance_a`/`instance_b`) and `docs/development.md:106-108` —
+  "instance"/"backend instance" as a near-synonym for Backend.
+- `cli-client/toolshed-client.py:11-70`, `README.md:92` — `--host`/`self.host` for "which backend
+  to talk to".
+
+## Discovery
+
+- `frontend/src/store.js:313` — `lookupServer` action *is* the discovery operation, never named
+  "discovery".
+- `frontend/src/store.js:347` — `could not resolve server for friend` — "resolve" used instead.
+- `docs/design-in-progress/items-labels.md:99`, `docs/development.md:108` — describe the
+  discovery operation via "resolves"/"direct the frontend to the correct backend" without naming
+  it (minor, but candidates for a one-word tightening).
+
+## Handle / User handle
+
+- ~~`backend/authentication/models.py` (`class KnownIdentity`...), `signature_auth.py`
+  (`author_identity`...), `frontend/src/identity.js` (`serializeIdentityRecord`...)~~ — no longer a
+  finding: the glossary now has an explicit **Identity** entry (handle + keypair, held together as
+  the unit a backend trusts), and this is exactly what these already name. No renaming needed here;
+  if anything, these are the parts of the codebase the new Identity entry should point to as
+  reference implementations.
+- `backend/toolshed/serializers.py:49-57` (`FriendSerializer`) — API field is literally named
+  `"username"` but its value is a full handle (`username + '@' + domain`). Already
+  self-acknowledged in a comment at `frontend/src/store.js:404`. **Highest-value single fix** —
+  it's a live API contract, not just an internal name.
+- `frontend/src/store.js` — several action params destructured as `{username}` that actually carry
+  a full handle: `lookupServer` (313), `getFriendServers` (359), `fetchFriendProfile` (401-405),
+  `login` (276-282).
+- `frontend/src/views/Login.vue` (lines 24, 27-28, 82-83, 102-105, 115-117) — form label/variable
+  "Username" for a field that must be a full user handle (`user@domain`, per its own validation
+  message at line 103).
+- `frontend/src/router.js:51` — route param `/inventory/shared/:user/:id` uses `:user` for what's
+  meant to eventually be a full handle; contrast with the sibling route at line 61 which already
+  correctly uses `:handle`. (Already called out by items-labels.md itself, so low-risk to leave
+  as-is, but listed for completeness.)
+
+## Availability policy, Friend/Friendship, Signature/Signing, Strict resolution, Actor, Targeted sharing
+
+No real inconsistencies found — implemented code already uses the glossary's own terms
+consistently (`availability_policy` field name throughout backend+frontend; `friend`/`befriend`
+consistently; `Signature`/`sign`/`verify` consistently; `_HandleNotFound`/`_resolve_handle` in
+`backend/toolshed/offlinedata.py` implement strict resolution faithfully without needing to name
+it; Actor and Targeted sharing are unimplemented with no competing name anywhere).
+
+- Checked and cleared, not a real conflict: `frontend/src/neigbors.js`'s `NeighborsCache`/
+  "neighbor" vocabulary — refers to unreachable backend *domains* during discovery, not to
+  friendship, despite reading like a synonym at a glance.
+
+## Group / Group handle / Membership list
+
+- `backend/backend/settings.py:36` — `django.contrib.auth` ships a built-in `Group` model, shown
+  as "Groups" in the Django admin. Not unregistered anywhere. Will collide by name with the
+  proposed actor-type Group once that's implemented — worth a decision now (unregister the
+  built-in admin Group, or otherwise disambiguate) before the real feature lands.
+- `issues.md` (issue #3, "Group Concept", ~lines 62-156) — a standalone proposal that conflicts
+  with the already-settled `docs/design-in-progress/groups.md` design on three points at once:
+  - `Group.public_key`/`private_key` fields (contradicts "does a group need its own keypair? No").
+  - `GroupMembership` backed by a signed `membership_certificate` rather than a plain membership
+    list (contradicts the glossary's Membership list entry).
+  - Bare `Group.handle` strings with no `#` prefix, e.g. `"makerspace-nord"`, and a
+    `GroupInvitationIncoming.group_handle` field/API surface (`POST /api/groups/` etc., ~lines
+    65-66, 117-121, 150-156) that never uses the `#groupname@domain` shape.
+  This is a design-conflict issue, not a wording tweak — `issues.md` should be reconciled with (or
+  explicitly marked superseded by) `groups.md` before anyone implements from it.
+
+## Keypair / Private key / Public key
+
+- Wire-format drift on the one field that actually crosses the network: `befriender_key` is used
+  for a public key at `frontend/src/store.js:435,449` and `backend/toolshed/api/friend.py:107`,
+  while the model field, serializer field, and UI all call the same value
+  `befriender_public_key`/`public_key` (`backend/authentication/models.py:144`,
+  `backend/toolshed/serializers.py:65`, `backend/toolshed/api/friend.py:118`,
+  `frontend/src/views/Friends.vue:81`).
+- `cli-client/toolshed-client.py` (`--key`, `TOOLSHED_KEY`, `self.signing_key`, ~lines 12, 52, 57)
+  and `README.md:92` — never say "private key," just "key"/"Toolshed key", even though it's
+  specifically the private half.
+
+## Origin
+
+- `backend/configure.py:130` ("Identifier set {} already imported, skipping") and the model
+  `ImportedIdentifierSets` (`backend/hostadmin/models.py:13-19`) — call an imported origin dataset
+  an "identifier set".
+- `issues.md:206-210` — Instance Admin TODO list: "identifier-sets" for **Origin** and bare
+  "identifiers" for **Classification handle**, both alternate terms not matching glossary names.
+
+## Alias
+
+- `backend/shared_data/ee_packages.json:40,64` — two tags already carry an `"alias"` field in real
+  data (e.g. `SOT54` → `alias: "TO-92"`), but shaped as a bare name string, not an
+  `origin#type:name` handle pointer, and with no unit-conversion concept. It's silently dropped on
+  import today (`Tag`/`TagSerializer` have no `alias` field). Not a different-word issue, but the
+  design doc (which calls Alias "Proposed") doesn't acknowledge this pre-existing, inert
+  precedent — worth reconciling either the data or the doc.
+
+## Tag / Property / Category
+
+- `frontend/src/components/workflow/workflows/BulkItemImportWorkflow.vue:495` — CSV
+  column-auto-mapping heuristic treats `"type"` as a synonym for Category:
+  `lowerColumn.includes('category') || lowerColumn.includes('type')`.
+
+## Item Handle
+
+- `frontend/src/views/Search.vue:30,52,110` — a field literally named `handle` is computed here
+  (`e.owner==this.user ? e.id : "shared/"+e.owner+"/"+e.id`), but it's a router-path fragment, not
+  an Item Handle: no domain-qualified `user@domain.tld:id` shape, and `e.owner` is a bare username.
+  Whoever implements the real Item Handle later is likely to collide with this existing variable.
+
+## Item Label
+
+- `frontend/src/components/workflow/workflows/FotoFirstBulkImportWorkflow.vue:567-572,822` and
+  `FotoFirstBulkImportWorkflow2.vue:593-598,847` — checkbox "Generate QR codes for items" /
+  `importOptions.generate_qr_codes` names exactly the Item Label concept but never uses that term
+  (and the option is currently unwired — declared and defaulted `true` but never read elsewhere).
+
+## Item URL / Local id / Domain / Frontend / Definition fingerprint / Fragmentation / Handle collision / Classification handle
+
+No real inconsistencies found — each already uses consistent, glossary-matching vocabulary
+(`id`/`item_id` for Local id; `origin` kept cleanly separate from `domain` everywhere it's used;
+`get_handle()` consistently for Classification handle; no competing names found anywhere for
+Fragmentation, Handle collision, or Definition fingerprint, which also doesn't collide with the
+unrelated `File.hash` content-hash field despite both being called "hash").