j3d1/toolshed
2
1
Fork 0
Code Issues 9 Pull requests 1 Projects Releases Packages Wiki Activity

stash

Browse source
This commit is contained in:
j3d1 2026-08-27 01:39:03 +02:00
parent d56784eb8d
commit 6ee5ae38b1
8 changed files with 246 additions and 153 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/glossary.md
View file

@ -47,7 +47,8 @@ and talks to it directly, regardless of where the frontend itself was loaded fro
A name that's unique within its own scope and carries, as part of itself, enough information to say
where it's authoritative, without needing a central registry to look it up. The general term
covering [user handles](#user-handle), [group handles](#group-handle) (proposed),
[classification handles](#classification-handle), and [item handles](#item-handle) (proposed).
[classification handles](#classification-handle), [User-Qualified IDs](#user-qualified-id), and
[Domain-Qualified Short IDs](#domain-qualified-short-id).
*See: [federation.md](federation.md#unique-handles)*
**Strict resolution** (Implemented)
@ -109,7 +110,8 @@ The asymmetric keypair backing exactly one [user handle](#user-handle); together
keypair backing it are what's called an [identity](#identity). The private key signs requests made
as that user and never leaves their control; the public key is handed out to establish trust in the
handle (at registration, or via a [friend](#friend-friendship) exchange) and is used to verify
signatures. Only user handles carry a keypair, not groups, classification handles, or item handles.
signatures. Only user handles carry a keypair, not groups, classification handles, or
User-Qualified IDs.
*See: [federation.md](federation.md#cryptography)*
**Membership list** (Proposed)
@ -157,8 +159,8 @@ a property alias specifically, also states a unit conversion (even if it's "iden
**Classification handle** (Implemented)
Umbrella term for a [tag](#tag-property-category), [property](#tag-property-category), or
[category](#tag-property-category) handle, of the form `origin#type:name`, e.g.
`git:base#property:length`. Distinct from a [user handle](#user-handle) or [item
handle](#item-handle): it names a reusable classification concept, not an actor or an owned thing.
`git:base#property:length`. Distinct from a [user handle](#user-handle) or [User-Qualified
ID](#user-qualified-id): it names a reusable classification concept, not an actor or an owned thing.
*See: [federation.md](federation.md#tags-properties-and-categories)*
**Definition fingerprint** (Partially implemented)
@ -201,29 +203,47 @@ strings today.
## Items & Physical Labels
**Item Handle** (Proposed)
The compact identifier for a specific item that's meaningful outside its owner's own account:
`user@domain.tld:id`, the owner's [user handle](#user-handle) plus a [local id](#local-id). Used
where it's already clear from context that it's a Toolshed item, e.g. inside the app, in exports,
in logs, so it doesn't need to spell that out or be openable on its own. Contrast with [Item
URL](#item-url), the self-contained form for when no such context can be assumed.
*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
**Domain-Qualified Short ID** (Implemented)
A [domain](#domain) paired with a [short id](handles-and-shortids.md#short-ids) token, e.g.
`toolsheddomain.tld:~DyU`. A bare short id token is opaque and scoped to whichever backend minted
it, nothing in the token itself says which backend's id numbering to read it against, so it only
means something inside the app instance that's currently talking to that backend. Prefixing it with
its domain supplies the missing piece, the same way any other handle's domain half does, so the
pair keeps resolving correctly even after being copied out of the instance it was minted on. Unlike
a [User-Qualified ID](#user-qualified-id) or [Item URL](#item-url), it isn't limited to owned kinds
(any kind in the short id registry can be domain-qualified) and isn't meant to be openable with zero
context, no scheme, no path, opaque bit-packed payload, it belongs inside the app or between things
that already speak its short-id format, not on a physical label.
*See: [handles-and-shortids.md](handles-and-shortids.md#domain-qualified-short-id)*
**Item Label** (Proposed)
**Item Label** (Implemented)
A physical, scannable encoding (QR code, barcode, or similar) of an item's [Item URL](#item-url),
meant to be printed and stuck on the physical object it refers to.
*See: [items-labels.md](design-in-progress/items-labels.md#goals)*
**Item URL** (Proposed)
The self-contained URL form of an [Item Handle](#item-handle), for use with no context at all, e.g.
an [Item Label](#item-label): `https://<any frontend>/i/user@domain.tld/id`. Has to open directly
to the right frontend and land on the right item on its own, since the reader can't be assumed to
already know what it is or which server it belongs to. Any frontend can serve this URL, the host
named in it isn't part of the item's identity, only the handle in its path is.
**Item URL** (Implemented)
The self-contained URL form of an item's [User-Qualified ID](#user-qualified-id), for use with no
context at all, e.g. an [Item Label](#item-label): `https://<any frontend>/i/user@domain.tld/id`.
Has to open directly to the right frontend and land on the right item on its own, since the reader
can't be assumed to already know what it is or which server it belongs to. Any frontend can serve
this URL, the host named in it isn't part of the item's identity, only the handle in its path is.
*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
**Local id** (Implemented)
An item's identifier as it exists today: unique only within its owner's own inventory, not
meaningful outside that owner's account. The starting point both the [Item
Handle](#item-handle) and [Item URL](#item-url) build on.
meaningful outside that owner's account. The starting point both a [User-Qualified
ID](#user-qualified-id) and [Item URL](#item-url) build on.
*See: [federation.md](federation.md#items), [items-labels.md](design-in-progress/items-labels.md#problem)*
**User-Qualified ID** (Implemented)
The compact identifier for a specific owned thing (an item, a storage location, ...) that's
meaningful outside its owner's own account: `<owner-handle>:<kind><local-id>`, e.g.
`alice@example.com:i42`, the owner's [user handle](#user-handle) (or [group
handle](#group-handle) for a group-owned thing) plus a one-letter kind tag (`i` for item, `s` for
storage location) and a [local id](#local-id). Used where it's already clear from context that it's
Toolshed data, e.g. inside the app, in exports, in logs, so it doesn't need to spell that out or be
openable on its own. Generalizes what used to be a bespoke, item-only "Item Handle" concept: the
kind letter is what an item-specific `user@domain.tld:id` shape was missing, nothing in that string
said it was specifically an item. Contrast with [Item URL](#item-url), the self-contained form for
when no such context can be assumed.
*See: [handles-and-shortids.md](handles-and-shortids.md#user-qualified-id)*