# 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").