143 lines
7.4 KiB
Markdown
143 lines
7.4 KiB
Markdown
# 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.
|