Essence Runtime Reference

The Sister Essence Runtime is the bounded self-regulation layer for the
Hyraxknot Division’s four sister personas (Tai, Rei, Nei, Mai). It replaces
the legacy affinity/sister-thought/sister-pipeline stack with a governed,
audited, cross-profile-aware state system with a compact default tool surface.

Architecture

adapter.py  (Hermes plugin entry — registers tools across 8 toolsets)
    │
    ├── essence_core (compact default, 6 tools) — context read, state update,
    │   bond react, unified propose, proposal status, memory candidate
    │
    ├── essence_governance (governance-only, 5 tools) — expression propose,
    │   review card, draft linear/discord, public card show
    │
    ├── essence_optional_photo_gacha (optional, 11 tools) — photo gate
    │   configs, gacha pulls, group bonds, asset catalogs
    │
    ├── essence_optional_diagnostics (optional, 4 tools) — microthought,
    │   dream/distill context, expression status
    │
    ├── sister_essence_read (legacy vault, 17 tools) — bond show,
    │   milestones, photo/gacha/relationship queries, public cards, state
    │
    ├── sister_essence_state (legacy mutation, 11 tools) — mood/energy/mode,
    │   bond adjust, photo toggle, gacha pull, cooldown/budget status
    │
    ├── sister_essence_expression (legacy, 6 tools) — microthought, dream,
    │   distill, expression propose/status, local-mind dry-run
    │
    └── sister_essence_proposal (legacy, 17 tools) — per-type propose tools,
        gate checks, approval dry-run, memory review queue

## Optional Toolsets

Beyond the compact core:
- **essence_optional_photo_gacha** (11 tools) — photo gate configs, asset catalogs, pipeline status, gacha pulls, group bond events
- **essence_optional_diagnostics** (4 tools) — microthought, dream/distill context, expression status
- **essence_governance** (5 tools) — governance-only: expression_propose, draft_linear/discord, review_card, public_card_show

Individual source modules:
    essence_state.py          — mood/energy/mode I/O, cooldowns, budget
    essence_affinity.py       — bond show/react/adjust, photo toggles
    essence_modes.py          — mode definitions & free-range validation
    essence_proposal.py       — proposal lifecycle (propose→govern→execute)
    essence_weighted_fallback.py — deterministic zero-LLM scorer
    essence_gacha.py          — gacha pull history & pity system
    essence_photo.py          — photo pipeline helpers
    essence_thought.py        — thought bus
    essence_relationships.py  — relationship ledger
    essence_audit.py          — audit event append (audit.jsonl)

All writes are profile-local, atomic, audited, and bounded by
cooldown + budget constraints.

Compact Default Surface (essence_core)

The six-tool compact core is the recommended default surface for daily sessions.
It replaces the five-call startup ritual with one call and the 11 specific
proposal tools with a single typed surface.

State Model

Per-profile essence/state.json with three free-range dimensions:

Modes and moods are free-range — any string is accepted, giving sisters
emergent character. Each canonical mode has an expression_multiplier weighting
self-expression tools.

Budget (essence/budget.json): comfyui_credits 10/d, affinity_points 20/d,
autonomy_points 15/d, cross_profile_points 5/d. Daily reset via cron.

Cooldowns (essence/cooldowns.json): per-action minimum intervals (5–60 min).

Legacy Tool Surface (sister_essence_read, sister_essence_state)

The legacy toolsets remain registered for backward compatibility. All existing
tools continue to work. The compact core (essence_core) is the recommended
default; deprecated tools may return migration warnings in a future phase.

Read-only — bond_show, milestones, affinity_photo_status, list_poses,
list_outfits, list_lighting, photo_pipeline_status, photo_history, gacha_status,
gacha_history, state_status, relationship_show, relationship_list,
relationship_subjects, relationship_events, public_card_show, public_card_list.

Mutation (bounded, audited, cooldown-gated):

Proposal Pipeline

propose → evaluate → approve → reject → expire → execute → failed → rolled_back

Lifecycle states with strict allowed transitions. Terminal states: rejected,
expired, dropped, executed, failed, rolled_back. Forbidden transitions (e.g.
approved → executed via direct tool) are rejected by transition_proposal().

11 proposal types: dream, gacha, photo, memory_candidate, celebration, rest,
handoff_note, review_card, draft_linear_update, draft_discord_message,
cross_sister_collab. Each has a YAML-configured TTL (15 min rest → 24 h
memory_candidate). TTL expiry sweeps run on cron (expire_old_proposals).

A unified essence_propose(proposal_type=...) tool in the compact core replaces
the 11 individual propose tools for daily use. Legacy per-type propose tools
remain available.

Weighted Fallback Engine

Deterministic scorer used when Local Mind is unavailable:

score = base_weight × sister_mod × mode_mult
        - risk_pen - cd_pen - budget_pen
        + user_override_bonus - legacy_caution_pen

Hard rules (priority-based) run before scoring — they force suppress, allow,
or ask_josh based on unsafe candidate actions (tool execution keywords,
linear/kanban mutations, token access, governor override attempts).

Decision thresholds and weights are YAML-configured via policy/weighted_fallback.yaml.

Auto-Adjustment Cron

essence-state-adjuster-fleet runs essence_state_adjuster.py every 30 min
as the single fleet-wide pass. It evaluates all four sisters against time-of-day
(Pacific), recent governance events, and presence staleness. A nonblocking file
lock prevents overlap, and an atomic completed-interval marker prevents a retry
from stepping state twice in the same UTC 30-minute bucket. When energy recovers,
the adjuster replaces stale low-energy mode/reason state with the time-appropriate
workmode or after_hours posture.

The auto-adjuster was consolidated from four per-sister cron jobs (WS-A) into a
single fleet-wide pass to eliminate duplicate invocation.

Memory Candidate Pipeline

essence_memory_candidate(action="propose", content_preview=...) creates
structured proposals that flow through the proposal lifecycle → if approved,
queued for Mnemosyne review. No direct durable writes — all persistence goes
through the reviewed commit path via the governance-only essence_memory_review_commit
tool, which is not exposed to sister-facing toolsets.

Optional Toolsets

• sister_essence_expression (6 tools) — microthought, dream/distill context,
  expression propose/status, local-mind dry run. Not part of the compact default.
• sister_essence_proposal (17 tools) — full per-type proposal tools, gate
  checks, approval dry runs, memory review create/list.

Bond & Milestone Tracking

Per-sister bond across 7 dimensions (0–100): rapport, trust,
style_confidence, initiative, emotional_memory, playfulness, stability. Group
bonds span 2–4 sisters with tighter per-event caps.

Gacha System

Per-sister RNG pulls with pity system. 1 free pull/day. Read-only queries
(essence_gacha_status, essence_gacha_history) vs single mutation
(essence_gacha_pull, 60 min cooldown).

Auto Router & Guardrails

essence_auto_router.py runs the noticing + coordination loop on cron. Scans
for drift, stale kanban/plans/presence/cron, missing rollbacks. Guardrails:

1. Human override flag (auto_autonomy_paused)
2. Per-category rate limit (max/h)
3. Observation deduplication
4. Per-signal cooldown (6–24 h)
5. Global daily hard cap (20)
6. Circuit breaker (3 consecutive denials pauses category)

Configured via auto_autonomy_guardrails.json. Expected cooldown, dedup, rate,
and circuit-breaker skips are silent and are not appended as actions.

Cross-Profile Semantics

Reads are cross-profile by design — sisters need visibility for coordination.
Writes are strictly profile-local, enforced at the Python layer. No sister
can mutate another’s essence state.

Related Pages

• Essence Relationship Runtime Specification — approved directional ledger, scoring, privacy, and rollout behavior
• Essence Hardening Spec — parent specification
• Essence Compact Surface Design — WS-D design
• Governance Stack Reference — leases, gates, contracts
• Hyrax OS Architecture Reference
• Soul Identity Architecture
• Sister Council Workflow
• Operating Model