Module items 

Structs

ItemMeta

Lightweight item metadata available without authentication. Walks .joy/items/, peeks each file: if it is a JOYCRYPT blob, reads the zone name from the header without decrypting; if it is plaintext YAML, parses just enough to extract the id and crypt_zone fields. Used by joy crypt status / joy crypt ls / joy auth to count and locate Crypt content without prompting the user for a passphrase.

LockedItem

Lightweight placeholder for an encrypted item the caller cannot decrypt. ID is read from the filename, zone from the JOYCRYPT magic header; nothing is decrypted. Used by joy ls to render a [Crypted in zone <name>] row instead of failing the whole listing. See JOY-0174-D3.

Functions

delete_item

Delete an item by ID. Returns the deleted item.

detect_cycle

Check if adding a dependency would create a cycle. Returns the cycle path if one exists.

find_item_file

Find the file path for an item by its ID. Accepts both full IDs (JOY-0042-A3) and short-form (JOY-0042). Short-form returns an error if ambiguous (multiple matches).

list_item_metadata

Walk .joy/items/ and return one ItemMeta per item file. Never prompts, never decrypts. Use load_items when you need full Item objects.

load_item

Load a single item by ID.

load_items

Load all items from .joy/items/. Inaccessible-encrypted items are silently skipped (the caller treats them as not present). For surfacing locked-item placeholders, use load_items_with_locked.

load_items_with_locked

Load all items from .joy/items/, separating decryptable ones from encrypted blobs the caller has no zone-key for. Plaintext items and items whose zone key is currently active are returned as Item; items in zones without an active key are returned as LockedItem placeholders. See JOY-0174-D3.

next_id

Generate the next item ID by scanning existing files. Returns “ACRONYM-0001” for the first item, increments the highest found. All items share one number space regardless of type.

remove_references

Remove references to a deleted item from other items’ deps and parent fields. updated_by is recorded on each touched item so the audit trail names the actor who triggered the dereference.

save_item

Save an item to .joy/items/{ID}-{slug}.yaml.

title_hash_suffix

Generate 2 hex digits from the title for collision-safe IDs (ADR-027).

touch_for_attribute_change

Record an attribute-level mutation on an item. Sets updated / updated_by for sort recency AND appends an entry to history for the audit footer. Use this whenever you mutate an item attribute (status, priority, deps, assignee, edit, …). Do NOT use it for comment add / edit / rm; those use touch_for_comment_change instead, because per-comment audit lives on the comment itself.

touch_for_comment_change

Bump an item’s updated / updated_by for sort recency without appending to its attribute history. Use this for comment add / edit / rm: the item is touched but no attribute changed, so the audit trail of comment activity lives on the comment itself (its edits list, plus the item’s comments Vec membership) rather than in the item’s attribute history.

update_item

Update an item in place (overwrites its file).