j3d1/toolshed
2
1
Fork 0
Code Issues 9 Pull requests 1 Projects Releases Packages Wiki Activity
toolshed/docs/glossary-todo.md
jedi 395a9b156a stash
2026-08-20 05:19:53 +02:00

8.9 KiB
Raw Blame History

Glossary terminology TODO

Working list from a repo-wide audit of where code/docs use a different word for a concept that 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").