# 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:**
  ```json
  {
    "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.