From b5048cb7362017aa427aa1382cd78937253c5033 Mon Sep 17 00:00:00 2001 From: continuist Date: Thu, 21 Aug 2025 17:32:57 -0400 Subject: [PATCH] Upload files to "/" --- nomenclature_glossary.md | 143 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 nomenclature_glossary.md diff --git a/nomenclature_glossary.md b/nomenclature_glossary.md new file mode 100644 index 0000000..1bee9c2 --- /dev/null +++ b/nomenclature_glossary.md @@ -0,0 +1,143 @@ +# 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.