Accessor library

Use this when

You are writing a skill or hook that needs to read or write bassclef state, and you want to know which accessor to call.

Skip this when

You are writing application code. The accessor library is for substrate consumers only — skills, hooks, and rules that ship with bassclef.

What it is

lib/state.sh is a shell library that provides typed accessors for every state-spine entity. Consumers source the library at the top of their script and call functions like:

source lib/state.sh

state_whereami_get                    # returns JSON
state_whereami_set '{"phase":"..."}'  # validates + writes
state_marker_count temperance         # returns integer
state_iteration_bet_get               # returns frontmatter JSON

Why not direct file access

Direct cat and jq on state files bypasses:

• Schema validation (writes may corrupt state)
• Storage-shape abstraction (Shape B needs YAML-frontmatter extraction; direct cat misses it)
• Migration compatibility (schema changes update the accessor once, vs. every consumer separately)

Accessor naming convention

state_<entity>_<verb> where verb is one of:

• get — read the entity, return JSON
• set — replace the entity (validates against schema)
• update — partial-update fields (also validates)
• list — list entities of this type
• count — return a count
• update_status — narrow update for status field

Special-purpose accessors named per contract — check state-spine-contract.md before adding a new one.

When to add a new accessor

If your consumer needs an entity type not yet in lib/state.sh, add it. Do not bypass with direct file access. Steps:

1. Read standards/state-spine.md to confirm the entity is in the catalog (add it there first if not)
2. Add the accessor to lib/state.sh following the naming convention
3. Add a Tier 0 test at lib/tests/state.test.sh (per .claude/rules/testing-tier-config.md — state-spine writes are Tier 0 strict TDD)
4. Consume the accessor from your skill or hook

Related rules

Related concept pages

• State spine — what the accessor library sits on top of