stash

docs/design-in-progress/items-labels.md

@@ -1,8 +1,11 @@
 # Item Handles & Physical Labels (Design in Progress)
 
-Status: not implemented. This document collects the problem, goals, and open design questions for
-giving inventory items stable identifiers and physical (scannable) labels. Nothing here is
-settled.
+Status: partially implemented. This document collects the problem, goals, and open design
+questions for giving inventory items stable identifiers and physical (scannable) labels. The core
+handle/URL shape question below is settled, generalized to cover any owned kind, not just items —
+see [User-Qualified ID](../handles-and-shortids.md#user-qualified-id) and
+[Item URL](../glossary.md#item-url). The remaining open questions (unguessability, label retirement
+on deletion, route reconciliation, lending/borrowing) are not.
 
 ## Problem
 
@@ -59,11 +62,16 @@ unguessability question below).
 Two distinct formats are needed, because "an item handle" is used in two different situations:
 
 - *A compact handle, for use where context already makes clear it's a Toolshed item.* Inside the
-  app, in exports, in logs, anywhere the reader already knows they're looking at Toolshed data,
-  the handle doesn't need to spell that out or be openable on its own. This can be as short as
-  `user@domain.tld:id`, the item's owner handle with `:id` appended, mirroring how a tag/category
-  handle already appends `:name` after its origin (see federation.md's Unique Handles section).
-  No new delimiter concept, just the same pattern applied to items.
+  app, in exports, in logs, anywhere the reader already knows they're looking at Toolshed data, the
+  handle doesn't need to spell that out or be openable on its own. An item's compact handle is the
+  item-kind instance of the general [User-Qualified
+  ID](../handles-and-shortids.md#user-qualified-id) scheme: the item's owner handle, the `i` kind
+  letter, and the local id, e.g. `alice@example.com:i42`. The same scheme covers any owned kind (a
+  storage location, for instance); item handles are just the motivating case. An alternative in the
+  same compact-handle family pairs the owner's domain with a [short
+  id](../handles-and-shortids.md#short-ids) instead, e.g. `domain.tld:~DyU` (see
+  [Domain-Qualified Short ID](../handles-and-shortids.md#domain-qualified-short-id)) — shorter, at
+  the cost of needing the app's short id decoder to make sense of it at all.
 
 - *A self-contained URL, for use with no context at all.* A physical label, a link shared outside
   the app, has to work without the reader already knowing what it is or which server it belongs