Nomenclature System for Cards, Real Things, and Consumables

This document captures the agreed naming scheme so we never confuse digital records with real-world things in everyday speech. Use it in product copy, docs, and APIs.

1) Core Rules (Simple & Consistent)

Card = the digital record. Always say “X card” when you mean the record.
Example: “Open the drill card.”
Real things = just say the plain noun (“the drill”, “100 yards of duct tape”).
Only add a qualifier when ambiguity matters (e.g., “the drill card vs the drill”).
Avoid the word unit in ordinary speech. If a distinction is essential in technical text, use piece (durable) or lot (consumable batch).
Consumables use supply terms: stock, lot, and move (receipt/issue/transfer).
Keep schema versioning explicit (e.g., offer.device@v1) and separate from a card’s content version and ACL revision.

2) Glossary (Final Terms)

Concept	Name (singular / plural)	Everyday speech	Digital record (card type)	Notes
Digital record describing anything	Card / Cards	“open the drill card”	`type:*@vN`	Signed, encrypted, schema-versioned
Schema/format	Type	“type `offer.device@v1`”	—	Major version for breaking changes
Durable real thing (tool, room, bike)	(just the noun) / piece(s)	“borrow the drill”	`asset.device@v1` (example)	Use piece only if needed to disambiguate multiples
Consumables (aggregate)	Stock	“we have duct tape in stock”	`stock.supply@v1`	Represents managed pool of a consumable
Consumable batch	Lot / Lots	“a lot of 100 yards”	`stock.lot@v1`	Tracks quantity, source, expiry
Stock movement	Move / Moves	“issue 10 yards”	`stock.move@v1`	One of: receipt (add), issue (remove), transfer (between stores)
Request for something	Need / Needs	“post a need for tape”	`need.*@v1`	Searchable projection only
Availability / ability	Offer / Capacity	“publish an offer”	`offer.*@v1`	What can be allocated
Time-bounded right to use	Permit / Permits	“you have a permit for the drill”	`permit.usage@v1`	Non-transferable, revocable
Result after use	Outcome / Outcomes	“log the outcome”	`outcome.*@v1`	For learning & audit
Minimal searchable subset	Index View	“peer index view”	(derived JSON)	Audience-scoped projection
Access authority pointer	Authority Handle	“ask the authority in the handle”	(tiny signed JSON)	`{did, endpoint, acl_rev}`
Permission linkage	Relation / Relations	“add a relation for viewer”	(Zanzibar tuples)	Stored server-side, not in cards
Encrypted payload + header	Cipherpack	“download the cipherpack”	(blob)	Holds ciphertext + key-bag header
Short-lived decryption packet	Key Grant	“request a key grant”	(sealed bytes)	Per card/version; expires in minutes

Rule-of-thumb in conversation: If you don’t say “card,” you are talking about the real thing.

3) Consumables: Fields & Phrasing

Everyday speech: “100 yards of duct tape”, “issue 10 yards”, “we received 5 rolls.”

Standard fields for consumables:

{
  "quantity": 100,
  "measure": "yard",
  "packaging": "roll",      // optional
  "lots": [
    {"lot_id": "lot_01ABC...", "quantity": 60, "receivedAt": "2025-08-01", "expiresAt": null},
    {"lot_id": "lot_01DEF...", "quantity": 40, "receivedAt": "2025-08-10", "expiresAt": null}
  ]
}

Moves (stock.move@v1) specify one of:
- receipt: add to stock
- issue: remove from stock (e.g., to a task/permitted user)
- transfer: move between stores/collections
Avoid the word unit for “unit of measure.” Use measure instead.

Example sentence:

“Issue 10 yards from the duct tape stock (lot L-482) to Alice’s task, and the card will show the new balance.”

4) Durables: Modeling & Speech

Everyday speech: “the drill”, “room A”, “the cargo bike”.
Digital card: asset.device@v1 for tools, asset.space@v1 for rooms/spaces, etc.
For many identical physical items, either:
- Track as one card with an instances list, or
- Create separate piece cards: asset.device.piece@v1 (only when disambiguation is necessary).
Permit grants time-bound access: “permit 2 weeks for coursework.”

5) Style Rules for Writing

Prefer plain nouns for real things; append card to refer to records.
Keep IDs internal: card_01HZ…, lot_01HX…. Use friendly titles in UI.
Use Title Case in UI (“Garden Shed Drill”), snake_case in APIs.
In UI copy, buttons read: Open card, Create card, Issue stock, Receive stock, Transfer stock, Grant permit, Close permit.

6) Schema Naming Patterns

Durables: asset.device@v1, asset.space@v1, asset.vehicle@v1
Consumables: stock.supply@v1, stock.lot@v1, stock.move@v1
Coordination: need.*@v1, offer.*@v1, permit.usage@v1, outcome.*@v1

Versioning rules:

@vMAJOR in the type = breaking change to the schema/format.
card.version = content edit number for a specific card.
card.acl_rev = authorization state revision.

7) API/DB Mapping (Concise)

Tables: cards, relations, needs, offers, permits, outcomes, stock_supply, stock_lot, stock_move.
Key columns:
- cards.type_id (e.g., offer.device@v1)
- cards.version (content version int)
- cards.acl_rev (auth revision int)
- cards.authority_handle (JSON: {did, endpoint, acl_rev})
Endpoints:
- POST /cards (create/update Card)
- POST /permits (issue Permit)
- POST /key-grant (get Key Grant)
- POST /stock/move (receipt/issue/transfer)
- GET /search (returns Index Views only)

8) Examples in Natural Sentences

“Post a Need card for 100 yards of duct tape; when approved, we’ll issue from the duct tape stock and record a Move.”
“Borrow the drill; your Permit begins Monday and unlocks the shed code (via Key Grant) on the drill card.”
“Our node mirrors the Index View for garden tools from the co‑op and uses the Authority Handle to request access when you open a card.”

9) Quick Glossary (tooltips you can reuse)

Card: Digital record; signed, encrypted, and shareable.
Type: The schema/format a card follows (something@v1).
Stock: Consumables we track (quantities & measures).
Lot: A specific batch of stock with its own quantity/expiry.
Move: A stock adjustment (receipt, issue, or transfer).
Permit: Time-bounded right to use something; non-transferable.
Relation: Permission link (who can do what).
Index View: Minimal, searchable summary of a card for a given audience.
Authority Handle: How to contact the node that decides access.
Key Grant: Short-lived decryption key for a specific card version.

One‑Sentence Summary

Cards are the digital source of truth; plain nouns refer to real things. Use stock/lot/move for consumables, permit for time-bounded access, and keep schema versions (@vN) separate from card versions and ACL revisions.

7.4 KiB Raw Blame History Unescape Escape