# Chapter: Compositions
---
title: "Compositions"
plain_name: "Apps built on LychD"
original: https://hexanomicon.dev/compositions/
guide: https://lychd.snayu.ai/docs/compositions/
---
# Compositions (Apps built on LychD)
## Plain-English summary (Snayu)
**What it is:** Index of Apps (Compositions): reusable applications that keep their own records, judge their own results and control which side effects they may request. Lists the app Areas, the reference portfolio and candidate studies.
**Why it matters:** Start here to see which apps exist, how they are grouped, and how finished work passes from one app to another.
- An App owns durable records, a finish judgment and recovery; Areas only group apps for browsing.
- Apps exchange settled, exact results directly; coordinating several apps' live jobs needs an App Bundle (Suite).
- Candidate studies (Reach, Thorn, Accounting Office, Workshop, Transmuter) are proposals, not accepted apps.
## Original text (Hexanomicon)
A publication needs sources, editorial judgment, and a release decision. A musical work needs its own acceptance, credits, and production records. Combining them should preserve what each contribution means and who answers for it.
A **Composition** gives each application a durable home. For the publication, Broadcast keeps
the source words and evidence alongside editorial decisions and candidate revisions. Riffmaw
keeps the musical work's production history and acceptance. When the editor uses that music,
Broadcast judges its place in the final cut without taking over Riffmaw's judgment of the music.
Putting the accepted cut before an external audience still needs a separate release decision.
More generally, a Composition keeps the application's records, judges its results, and governs
the effects it may request. Its policies, projections, and catalogue of Patterns belong to the
same reusable application across customers, Products, and deployments. Browse by the outcome
you want to leave behind.
For a software question, [Creation investigation](creation/index.md) retains the source, candidate
and separate verdict under one bounded application contract.
## The Portfolio
These **Native Reference Compositions** are accepted first-party application contracts and worked examples. [State of Work](../state-of-the-work.md#composition-portfolio-delivery) collects their implementation evidence.
### Areas
An **Area** groups Compositions by the kind of work you want to find. Each Area has an index
leading to its applications and their outcomes.
| Area | Enter through |
| --- | --- |
| [Creative Works](creative-works/index.md) | visual work, music, language editions, playable builds, and publication |
| [Stewardship & Acquisition](stewardship-and-acquisition/index.md) | personal health and wellbeing, places, animal care, cultivation, and acquisition |
| [Presence & Embodiment](presence-and-embodiment/index.md) | social presence, presentation, virtual worlds, physical bodies, and mobile sessions |
| [Professional Operations](professional-operations/index.md) | attributable client casework and professional handoffs |
Areas may overlap because a reader can approach the same work from different concerns. Each
Composition nevertheless keeps one canonical route and owns its records and judgment; the Area
only helps the reader find it. A [Suite](products-and-suites.md#compositions-relate-without-nesting)
coordinates live work within one Area or across several. The [Area contract](../adr/28-workflow.md#areas-for-discovery)
keeps that navigation separate from application ownership, while Guides and Candidate studies
provide separate views of explanations and proposals.
## Follow a shared work
[Canvas](canvas/index.md) keeps visual boards, original ink and reviewed transformations.
[Atelier](atelier/index.md) produces accepted visuals, [Riffmaw](riffmaw/index.md) music, and
[Language Edition](language-edition/index.md) aligned dialogue and captions.
[Broadcast](broadcast/edit.md) admits their exact settled bundles into its timeline and judges
the resulting editorial work. Its [release](broadcast/release.md) is a separate external act.
The direction can change without erasing earlier work. A locked Broadcast master and script can
enter Language Edition; the returned language bundle enters a new Broadcast Invocation for a
new edition. Each owner preserves its records, acceptance, and recovery.
Settled artifacts connect these applications directly. A result that must coordinate several
owners' live Invocations—commissioning work, awaiting revisions, or recovering their execution—
needs a **Suite**.
The [worked handoffs](products-and-suites.md#compositions-relate-without-nesting) extend this
relationship to household care, embodied presence, and professional casework. A **Product** gives
the resulting application or Suite a named operator promise.
## Candidate studies
These studies develop application boundaries beyond the accepted Portfolio.
[Reach connected work](reach/connected-work/index.md) proposes a successor to the public Discord
contract for bounded Gmail, Discord and GitHub correspondence, optional WhatsApp, account onboarding,
autonomous delivery policy and recovery. It does not broaden the existing Reach revision or deployment profiles.
[Thorn](thorn/index.md) studies whitehat security casework: authorized assessment, bounded response
during an attack, cooperative investigation, and supported reports and corrections. Monitoring
supplies evidence; general system maintenance keeps its own owners.
[Accounting Office](accounting-office/index.md) studies business documents, bank reconciliation,
entity-owned books, asset and subscription obligations, and period close. Provider adapters and
jurisdiction profiles vary under one proposed accounting lifecycle.
[Workshop](workshop/index.md) tests technical-service casework. Mechanic is its proposed first Product under the passenger-vehicle service profile.
[Transmuter](transmuter/index.md) studies the passage from imported digital material to
attributed knowledge and proposals for memory and identity. Extractor and Synthesizer are its
internal stages; naming, labeling, and classification belong to Extractor.
## The Composition test
For a new idea, ask what should remain when the conversation ends and who can judge it finished.
Then try the difficult endings: work refused, partly completed, stopped, or interrupted with an
effect still unknown. Who keeps that account and decides how to recover? [Choosing a Home](choosing-a-home.md)
tests whether those responsibilities need a Composition or already belong to a Product, profile,
Pattern, projection, mechanism, reference, or Suite.
The companion guides follow the choices involved in shaping and combining applications:
| Question | Continue with |
| --- | --- |
| What operator promise does a Product offer? | [Products and Suites](products-and-suites.md) follows a named operator promise into one configured Deployment. |
| Does this result need coordination between live Invocations? | [The worked handoffs](products-and-suites.md#compositions-relate-without-nesting) distinguish a settled foreign result from separate owners' live work coordinated by a Suite. |
| Which machinery can applications share? | [Shared machinery, separate judgments](choosing-a-home.md#shared-machinery-separate-judgments) keeps shared engines distinct from application records and authority. |
| Who accepts each part of a compound result? | [The media comparison](choosing-a-home.md#media-owners-do-not-follow-file-extensions) locates visual work, music, language editions, picture sound, and interactive world sound by acceptance rather than codec. |
**How a leaf should read:** [authoring criteria](choosing-a-home.md#how-a-leaf-should-read) keep each application rooted in a representative journey and falsifiable result. [Lexicon](../lexicon/index.md) owns terms; [Workflow](../adr/28-workflow.md#compositions-products-suites-and-schedules) owns their architectural law.
Follow the [Map](../map.md#the-application-road) to carry an application's work through the body,
and [Transmutation](../divination/transmutation/index.md) to follow creation through trial,
judgment, and return.
---
title: "Choosing a Home"
plain_name: "Guide: where an idea belongs"
section: "Compositions > Guides"
original: https://hexanomicon.dev/compositions/choosing-a-home/
guide: https://lychd.snayu.ai/docs/compositions/choosing-a-home/
---
# Choosing a Home (Guide: where an idea belongs)
## Plain-English summary (Snayu)
**What it is:** A routing guide for deciding whether a new idea needs a new App or fits as a Packaged Offer (Product), profile, Workflow, view, integration, typed reference or App Bundle (Suite).
**Why it matters:** Read before proposing a new app or feature, so you put it in the smallest correct home instead of creating an oversized app.
- A routing table maps each kind of change (new customer, job, vertical, UI, engine) to its proper home.
- Shared machinery like the Web Fetcher, Voice or Vision does work, but the consuming app keeps the judgment.
- Media ownership follows who accepts the result (visual, music, language, picture sound), not the file format.
## Original text (Hexanomicon)
“Help a garage diagnose cars and find parts” is an operator promise before it is an architecture. Follow the durable work: a technical service case needs an owner, a parts request may use another owner's result, and a promise to coordinate both live processes needs its own coordination contract.
[Workflow](../adr/28-workflow.md#compositions-products-suites-and-schedules) owns the law. This page tests where the idea belongs.
## One idea end to end
**Mechanic** is the proposed Product a garage would recognize. “Choose the next diagnostic test” is one use case. [Workshop](workshop/index.md), still a candidate, would own the durable service case under its passenger-vehicle profile. One configured garage installation would be a **Deployment**.
An already-settled part requirement may pass to Scavenger as exact sourcing input. Only a result that must actively coordinate diagnostic and acquisition Invocations needs a **Suite**. None of those packaging or transport choices can supply a missing application owner.
## The shortest routing test
| What actually changed? | Give it this home |
| --- | --- |
| a thematic route for finding related applications | an **[Area](index.md#areas)**, with links to the existing Composition owners |
| another customer, host, credential set, or local configuration | a **Deployment** from an exact Product revision or Composition-owned reference deployment-profile revision |
| another concrete job the operator needs to finish | a **use case** supported by a Product |
| another profession, market promise, default set, or support envelope | a **Product** identity or immutable revision, according to whether the stable operator promise changed |
| another repeatable score under the same application owner | a **Pattern** and immutable Scroll revisions |
| another vertical, region, provider, or form factor under the same records, authority, recovery, and finish judgment | an exact owner-qualified **profile** |
| another UI, report, device view, or public explanation | a **projection**, with its own presentation owner |
| another engine, API, transport, capture surface, or implementation mechanism | an exact Provider, Animator/Connector, adapter, or client integration, plus a typed package **Contribution** through its explicit **Core** or **Extension Domain** owner when registration is required |
| an already-settled result from another owner | an exact typed record, artifact, observation, or receipt reference |
| one live result must coordinate the lifecycle and settlement of several application owners | a **Suite** |
| genuinely new durable records, judgment, effects, outcomes, and recovery reused beyond one Product, client, or deployment | a candidate **Composition** |
Name the owner and kind of every profile: Workshop service profile, Reach deployment profile, Animator capability profile. `Profile` is no global LychD entity. Pin its exact revision and retain the owning records, authority, recovery, and honest finish.
“Translate this” usually names a versioned Translation Spell or owner-declared transformation. [Language Edition](language-edition/index.md) earns application ownership through durable source/segment alignment, casting, spoken performance, captions, conform, acceptance, and recovery. Interface localization remains a Frontend catalogue; common language machinery does not merge them.
## A curated Portfolio, not a closed universe
The Portfolio should grow more slowly than Products, profiles, use cases, and Deployments. A numerical cap would instead reward god-Compositions that accumulate incompatible records and safety law.
Before acceptance, follow a case beyond the conversation. Identify the record that must survive,
the judgments and policies that govern it, and the endings it must distinguish: finished,
refused, partial, or unknown. Explain how stopped work restarts or recovers.
Then test the proposed ownership. Find an existing owner, if one fits, and show why a Pattern,
profile, Product, projection, Extension Domain, package Contribution, Provider, or typed reference
cannot carry the work. Name the smallest fixture that could disprove the design and the consumers
who need it for independent reasons. Two Products or use cases can corroborate reuse; they are
neither quota nor proof. Decorative wrappers count for little.
## Reuse without making a god
A profile can vary vocabulary and rules while preserving one lifecycle, authority, recovery,
and finish. Workshop can admit a new trade only while the service case still fits. A vague
universal casework schema cannot absorb Broker, legal, accounting, or municipal judgment without
evidence of a shared root lifecycle.
Follow a serviced heater into a shared enclosure. Homestead keeps the place and its provision,
even when a professional visits. The repair establishes neither a colony's seasonal state nor
a crop's suitability: [Keeper](keeper/index.md) and [Cultivator](cultivator/index.md) retain
those histories and care judgments. Pets and livestock can use Keeper profiles; indoor plants
and cultivated fungi can use Cultivator profiles. They need no universal biological state list.
A physical body poses the same test at another boundary. Familiar can reuse its contract while
capability, safety, stop, and settlement law stay coherent. A different emergency or recovery
boundary may require another owner.
## Shared machinery, separate judgments
Start with the work that can be shared without moving its judgment. Scout can search/fetch/render/crawl while an application decides source policy, interpretation, rank, and consequence. Mail/platform delivery carries a message; the application still decides recipient purpose, disclosure, review, reply meaning, and follow-up. Echo/Prism similarly supply admitted media effects while their consumers judge interpretation and acceptance.
The same boundary applies to transport and physical work. Tether/Veil provide roads without creating identity or grants. Legion can carry a bounded task while the body retains fresh local refusal. A model or tool provider therefore never owns application decision policy.
Applications connect through exact requests, observations, artifacts, and receipts. They do not exchange ambient databases, credentials, Sigils, sessions, or judgment. In household work, Wellbeing supplies personal food needs and confirmed consumption; Keeper and Cultivator supply care needs, material-use evidence, and collected yields. Homestead retains inventory/provision and commissioned site effects.
Calling that equipment IoT identifies an integration mechanism. Calling the subjects fauna and flora groups them within the [Stewardship & Acquisition Area](stewardship-and-acquisition/index.md). Neither label establishes an application owner. The [stewardship handoff](products-and-suites.md#homestead-keeper-and-cultivator) explains when shared equipment becomes live coordination. Scavenger separately keeps irregular listings, sellers, major commitments, parcels, and property diligence. Across presentation targets, Avatar follows the same principle: it groups presentation while Reach, Blockworld, Spectre, and Familiar retain their local work.
### Media owners do not follow file extensions
A single engine or compound container can produce several roles. The role's acceptance determines its owner:
| Office | Owns | Does not inherit |
| --- | --- | --- |
| **[Prism](../sepulcher/extensions/prism/index.md) · Extension Domain** | visual/spatial effect contracts, technical result settlement, provenance, and derivative facts | a visual commission or creative acceptance |
| **[Echo](../sepulcher/extensions/echo.md) · Extension Domain** | speech capture, STT/TTS, speech chronology, delivery, and playback facts | translation, casting, music, or application purpose |
| **[Atelier](atelier/index.md) · Composition** | visual commission, direction, image, VFX, motion, and accepted visual package | music, timed-language editions, editorial cut, or publication |
| **[Riffmaw](riffmaw/index.md) · Composition** | musical composition, instrumental and vocal performance, arrangement, mix/master, and musical cue map | ordinary speech, dubbing, standalone foley, or picture sound |
| **[Language Edition](language-edition/index.md) · Composition** | source-aligned language versions, translation/adaptation judgment, spoken performance, captions, dialogue conform, and restricted language-version packaging | Persona identity, music, editorial recut, or publication |
| **[Avatar](avatar/index.md) · Composition** | Persona-linked presentation eligibility, Morphe selection, and projection bindings, including exact eligible voice references | Persona lineage, raw media, speech engines, or target-world authority |
| **[Foundry](foundry/index.md) · Composition** | interactive world sound bound to exact game events, states, places, listeners, and runtime behavior | music, ordinary speech, picture-bound post-production, or a reusable universal sound library |
| **[Broadcast](broadcast/index.md) · Composition** | canonical source words and claims, picture-bound sound, final editorial timeline/render/mux, release, and correction | upstream visual, musical, voice, or provider truth |
A Translation Spell has an authority-qualified publisher; Spellweaver validates placement without taking linguistic or application truth. Compound model returns likewise keep one technical parent and independent visual/music/dialogue/picture/world-sound semantic admission. No generic reusable-sound Composition is accepted; a future owner must prove its own lifecycle rather than hide in an existing craft.
## An unresolved ownership need stops at study
If an external system already owns the needed truth, define an exact typed integration. If the state is bounded client UI or device-local presentation, leave it there. If LychD needs distinct durable application records, judgment, effects, finish, and recovery, prepare a candidate study.
Until an exact external authority or accepted Composition revision resolves the need, affected use cases remain candidate or unsupported. A Product cannot temporarily own the missing truth or admit that path as supported.
## How a leaf should read
Give the reader one representative journey, then the exact identity, Pattern catalogue, inputs, outcomes, records, handoffs, and stopping line needed to understand it. Classify foreign relations as settled reference, unmanaged external precondition, or live Suite seam. Keep local authority/privacy/effect/recovery and the smallest falsifying fixture; link shared architecture and delivery instead of repeating them.
Native records, policies, and finish judgment enter `src/lychd/compositions//**`; `clients//**` can project them without acquiring their authority. A stable key and separate Composition revision, such as `example.application` revision `1`, differs from Pattern `example.perform_work@1`. [Workflow](../adr/28-workflow.md#composition-identity-revision-and-retirement) owns frozen revision, successor, and retirement law. [State](../state-of-the-work.md#composition-portfolio-delivery) owns registration and execution evidence.
## From study to matter
```text
Product/use-case study exposes a need
→ candidate Composition tests the owner and defeat conditions
→ Portfolio acceptance establishes design truth
→ source enters only with an executable first-party contract
→ State of Work records what is actually delivered
```
A placeholder package cannot advance this sequence. There is no Crypt `compositions/` loader or Markdown discovery. [State](../state-of-the-work.md#composition-portfolio-delivery) records Composition registration, selection, scheduling, and execution evidence; its [Loom entry](../state-of-the-work.md#loom-workflow-views) retains the bounded source-registry projection.
Continue with [Products and Suites](products-and-suites.md), or return to the [Portfolio](index.md).
---
title: "Products and Suites"
plain_name: "Guide: Products and Suites"
section: "Compositions > Guides"
original: https://hexanomicon.dev/compositions/products-and-suites/
guide: https://lychd.snayu.ai/docs/compositions/products-and-suites/
---
# Products and Suites (Guide: Products and Suites)
## Plain-English summary (Snayu)
**What it is:** Explains Packaged Offers (Products, a named promise to an operator), App Bundles (Suites, which coordinate live jobs across several apps), Installations (Deployments) and the different kinds of views onto an app.
**Why it matters:** Read when packaging apps for customers or when one result seems to need several apps working together.
- A Product packages a promise; it never takes over an app's records, judgment or effects.
- Passing a finished result needs no Suite; starting, awaiting, cancelling or recovering several apps' jobs does.
- Worked handoffs cover Homestead/Keeper/Cultivator, Workshop/Scavenger and Atelier/Riffmaw/Language Edition/Broadcast.
## Original text (Hexanomicon)
An editor can assemble a film from visual, music, and language bundles that already exist. A different promise—commission changes in all three and deliver one jointly settled result—must coordinate their live work. The distinction is whether the application receives finished contributions or must coordinate work still in progress.
A **Product** is the promise an operator chooses. It names the profession or market it serves,
the supported jobs, defaults, and support envelope. Its exact revision pins the eligible
Compositions or Suites, their owner-qualified profiles, and the projections through which the
operator meets them.
A **Suite** takes responsibility for the live coordination that a joint result needs. It has its
own authority-qualified identity, revision, and exact coordination Pattern/Scroll. Casting that
score opens a parent Invocation/Run; each participating Composition keeps a separate Invocation
and Run. A direct Intent can cast the Suite without a Product, and several Products may pin the
same eligible Suite.
## From promise to one execution
| Term | Meaning |
| --- | --- |
| Product-supported use case | a class of operator job |
| Deployment | one configured Product or Composition-reference-profile context for an operator |
| Composition Pattern, or Suite-owned coordination Pattern across several | reusable technical realization |
| Invocation | one admitted Circle for requested work |
| Run | the durable execution and ledger identity representing that Invocation |
The coordination contract must say which members and Patterns take part, what typed
ArtifactRef/Intent handoffs they exchange, how their work is correlated, and which aggregate
ceilings and partial-completion rules govern the result. Each member keeps its records, judgment,
policy, consent, secrets, Sigils, credentials, provider grants, and effects. The Product packages
the promise; it acquires neither an executor's nor a scheduler's office.
## Compositions relate without nesting
[Areas](index.md#areas) group Compositions for discovery. A Suite may coordinate members within
one Area or across several; neither shared membership nor crossing a thematic boundary implies
live coordination. For example, a cultivation plan and a physical task could involve Cultivator
from Stewardship & Acquisition and Familiar from Presence & Embodiment. A promise to initiate,
await, and settle both Invocations needs a Suite; passing a settled plan alone does not. Each
member retains its own judgment and effect authority.
Replace a broad `depends_on: composition` edge with the actual relation:
| Relation | Consequence |
| --- | --- |
| Co-packaging | Several capabilities share a Product; no Suite follows. |
| Settled typed reference | Exact record, artifact, observation, receipt, or binding enters as input; no Suite follows. |
| External precondition/reference | A foreign binding, capability, or policy is required but its lifecycle remains outside consumer control; no Suite follows. |
| Live coordination | One result must initiate/admit, await, retry, cancel, recover, correlate, or settle several owners' Invocations; a Suite is required. |
References supply no installation, availability, upgrade, lifecycle, credential, admission, ambient database, or effect authority.
### Avatar and Spectre
Spectre can admit a generic VR Habitat/Encounter without Avatar. Meeting the Lich may require an exact already admitted `ProjectionBinding@2` as an external precondition. Its binding may still be live, but Spectre cannot create, revise, close, await, cancel, or recover it. Attributed results can later cross without a circular dependency.
A promise to admit a new projection, open the Encounter, await their attributed results, cancel both when required, and report partial completion needs a Suite. A Product may package that promise, not create its authority.
### Companion and Familiar
Companion requires an exact Familiar-backed device, while Familiar retains capability, safety, and stop law. Opening the mobile session needs no Suite. Coordinating its conversation with a Familiar mission or real-world effect does.
### Workshop and Scavenger
Proposed Mechanic packages Workshop's passenger-vehicle service profile. A settled part requirement can enter Scavenger without moving diagnosis or seller authority. Joint diagnostic/acquisition cancellation, ceilings, recovery, and partial settlement require a Suite that a later Product may pin.
### Homestead, Keeper, and Cultivator
[Keeper](keeper/index.md) can record a colony in a manually tended test tube, and [Cultivator](cultivator/index.md) can follow a plant without a connected sensor. [Homestead](homestead/index.md) owns physical site assets, resources, stores, provision, and commissioned controls when used. Each care owner retains the subject, placement, life history, needs, and biological interpretation. A shared enclosure can have both Keeper and Cultivator placements referencing one Homestead asset; owning the heater does not decide either occupant's needs.
An exact `KeeperSupplyNeed@1` or `CultivatorSupplyNeed@1` can enter Homestead provision; an attributed yield can later enter stores. An admitted environment requirement can receive a `HomesteadEnvironmentResult@1` in separate work. These settled references need no Suite, and technical success does not settle biological care. A common household Product or dashboard also needs no Suite merely to show the three owners together.
“Prepare care during my absence” needs a Suite when it promises to start care-planning Invocations, await household supply and environment work, and recover or cancel them as one result. Before casting that path, publish its own revision with exact member Patterns, handoffs, deadlines, aggregate ceilings, conflict policy, cancellation, and partial settlement. This example accepts no Suite identity or executable absence workflow.
The joint result must preserve what each member actually did. A refused water allocation leaves the dependent tending plan blocked; a completed purchase remains committed when another member fails. The parent cannot cancel local life-support protection or erase a member's unknown physical effect to declare the household ready.
### Atelier, Riffmaw, Language Edition, and Broadcast
A broader **Atelier studio** is proposed as one workspace for music, visuals, and their shared
timeline. This operator experience is distinct from the accepted visual Composition
`atelier.studio` revision `5`; this example publishes no studio Product or Suite revision.
Riffmaw remains independently usable for musical work and live jam.
A transient audition can present the parts together without accepting their final relation.
Authoritative editorial cuts, timing, selected asset revisions, and audiovisual acceptance belong
to [Broadcast](broadcast/edit.md), even when its finished candidate stays local. Atelier retains
visual judgment, Riffmaw musical judgment, and Language Edition its aligned language contribution.
The shared controls project those records and their declared timebase relations.
A joint audio/video generator performs one technical attempt with shared provenance and
attributable cost. Declared role owners admit their facets without requiring duplicate generation
or separate screens. Separable accepted facets may remain usable within their admitted limits;
refusal of a required inseparable facet blocks the compound use. A missing effect acknowledgement
remains unknown and must be reconciled before another attempt.
Changing a drop's position within the musical work creates successor music and cue revisions.
Moving unchanged music on Broadcast's timeline instead revises the editorial arrangement without
changing Riffmaw's master. Timing changes stale dependent synchronization approvals; changes to
source revisions, consent, or use boundaries still follow each owner's invalidation rules. The
earlier pairing remains attributable history, with no guarantee that its approval is still valid.
A Suite coordinates changes, dependencies, cancellation, and partial completion when the result
coordinates multiple owners' live Invocations. A shared timeline or compound model alone requires
no Suite.
Language Edition can use a settled Broadcast script/locked master, Atelier visual reference, and
Riffmaw music master without live coordination. Broadcast can later admit the settled language
bundle in another Invocation. The diagram follows those contributions into their target work.
```mermaid
flowchart TD
B["Creative brief"] --> V["Atelier · visual/VFX"]
B --> R["Riffmaw · music"]
BS["Broadcast script + locked master"] --> D["Language Edition · language edition"]
R --> S["MusicAssetBundle@1"]
R --> C["MusicCueMap@1"]
C --> V
V --> A["VisualAssetBundle@1"]
D --> L["TimedLanguageAssetBundle@2"]
A --> G["Foundry"]
S --> G
A --> P["Broadcast"]
S --> P
L --> P
P --> PS["Picture sound + editorial timeline"]
G --> GB["Playable build"]
PS --> PC["Publication candidate"]
```
Each arrow can remain a settled reference. A compound video model does not create a Suite; independent semantic owners must admit its facets. [Workflow](../adr/28-workflow.md#compositions-products-suites-and-schedules) owns the Suite execution contract; [State](../state-of-the-work.md#composition-portfolio-delivery) records delivery.
Generating material during play still needs [Foundry's target-use admission](foundry/assets.md).
Live hotload requires a future activation and recovery contract. A persistent artistic project
whose identity, shared direction, selections, and undo span music, film, and games also needs an
explicit ownership decision. Product packaging and Suite coordination supply neither lifecycle.
## Deployment and projection are different axes
A deployment profile is an immutable eligible topology/configuration template. A **Deployment**
instantiates an exact Product revision or Composition-owned reference profile for an operator,
with actual hosts, bindings, credentials, and policy. A Productless reference creates no market
promise, supported-use-case catalogue, or support envelope. A separately configured installation
for another host or customer ordinarily creates another Deployment; enrolling another User or
changing their credentials does not by itself create one.
[IAM](../adr/38-iam.md#people-accounts-and-instances) keeps people, accounts, and instances distinct.
Personal, family, and organizational use may share the same application contracts. For example, a
parent may administer a household instance used by relatives through clients, while also using a
personal instance and an employer's instance. A company may use one shared instance or several
separately governed instances. These examples impose neither a mandatory organization hierarchy
nor automatic cross-instance trust.
Three kinds of projection answer different questions. The **domain projection** is the owner's
read model: what the application makes available to inspect. The **client projection** presents
it on a platform and keeps bounded local state. A **public projection** explains or depicts it
through a website, screenshot, report, or other account. Client and public presentations do not
acquire application authority, and a new interface supplies no delivery evidence.
Different Users may receive different client projections of the same application and even the
same work. A worker might see a fault-report form, a maintainer a diagnostic view, and an approver
a bounded decision screen. An assigned working profile may bundle those presentation choices with
access assignments, but Ward decides actual permission and the application retains its records,
judgment, and effects. A distinct screen neither creates a new Composition nor rewrites its
workflow. These are [profile and interface requirements](../adr/38-iam.md#profiles-and-working-interfaces),
not a shipped industrial application or profile selector.
## Commercial catalogues and open-source Products
Commercial catalogues may live outside LychD and reference exact public revisions. Their websites own presentation; private Product truth stays outside technical docs. LychD may link rather than copy it.
To establish an open-source Product reference, pin the exact Product/use-case and Composition/Suite/profile revisions. Account for code licence/notices and the separate model, data, fixture, font, screenshot, mark, and redistribution rights. The reference also needs reproducible installation/acceptance, State evidence, and an honest account of externally supplied dependencies; source alone is insufficient.
If necessary weights, corpora, providers, or assets cannot be redistributed, describe “open-source Product code with externally supplied dependencies,” not an unqualified FOSS Product. State must record the evidence before it becomes a technical reference. This page creates no catalogue or selector.
[Choosing a Home](choosing-a-home.md) · [Workflow](../adr/28-workflow.md#compositions-products-suites-and-schedules) · [State of Work](../state-of-the-work.md#composition-portfolio-delivery)
---
title: "Creative Works"
plain_name: "Area: Creative Works"
section: "Compositions"
original: https://hexanomicon.dev/compositions/creative-works/
guide: https://lychd.snayu.ai/docs/compositions/creative-works/
---
# Creative Works (Area: Creative Works)
## Plain-English summary (Snayu)
**What it is:** Index of the creative apps: visual work (Atelier, Canvas), music (Riffmaw), dubbing and captions (Language Edition), game builds (Foundry) and publications (Broadcast), each listed with the outcome it produces.
**Why it matters:** Use it to find which creative app owns a given kind of output before reading that app's pages.
- Each app is routed by intended outcome and role, even when several apps use the same file format.
- Finished bundles pass directly between these apps.
- Jointly commissioning and awaiting changes across apps requires a Suite.
## Original text (Hexanomicon)
Make and adapt visual work, music, language editions, games, and publications. This Area routes
each contribution by its intended outcome and semantic role, including when several Compositions
use the same file format.
| Composition | Outcome |
| --- | --- |
| [Atelier](../atelier/index.md) | A still image, moving sequence, or visual/VFX package ready for its next use. |
| [Canvas](../canvas/index.md) | A revisable visual board with original ink, reviewed transformations and a portable document. |
| [Riffmaw](../riffmaw/index.md) | A composed or performed musical work, a production package, and cues when needed. |
| [Language Edition](../language-edition/index.md) | Replacement dialogue, narration, translation, or captions aligned to a locked source. |
| [Foundry](../foundry/index.md) | A playtested local game build that another person can reproduce. |
| [Broadcast](../broadcast/index.md) | An article or audiovisual publication candidate whose claims lead back to their sources. |
When the needed contributions already exist, pass their settled bundles between these
Compositions. If the result instead promises to commission and await changes jointly, it requires
a [Suite](../products-and-suites.md#compositions-relate-without-nesting).
[Composition Areas](../index.md#areas)
---
title: "Canvas"
plain_name: "App: Canvas (drawing board)"
section: "Compositions > Creative Works"
status: "Partial"
original: https://hexanomicon.dev/compositions/canvas/
guide: https://lychd.snayu.ai/docs/compositions/canvas/
---
# Canvas (App: Canvas (drawing board))
## Plain-English summary (Snayu)
**What it is:** Canvas is a visual whiteboard at /canvas: draw freehand, add nodes and arrows, select part of the board, export it for a model, and review a proposed change before applying it, with undo and local save.
**Why it matters:** Read before working on the Canvas web view or anything that sends board selections to a model and applies its proposals.
- Lasso or rectangle selection limits what a proposal may change; original ink is always preserved.
- Proposals made against an older board revision are refused as stale; accepted changes apply once and can be undone.
- Boards are saved as local files only; no server storage, live model call or microphone input yet.
**Status:** Partial. Local board authoring works; no live model, server storage or registered workflow.
## Original text (Hexanomicon)
Draw an explanation while speaking to the people who need to understand it. Keep the rough
marks, select the part worth improving, and judge a proposed change before it replaces anything.
**Canvas** owns that visual board and its revision history. Its accepted Composition identity is
**`canvas.board`, revision `1`**.
The first profile is a **portable board authoring demo** at `/canvas`. A browser draft can be
saved as a local document and opened again. It is not a server-retained Project, a published
workflow, or evidence that the illustrated architecture is running. [State of Work](../../state-of-the-work.md#canvas-board-authoring)
owns the delivered evidence and its limits.
The Vite development preview opens Canvas in the Altar's offline workbench profile, so drawing
needs no sign-in and starts no protected status or Bridge request. The shell and dock controls
remain visible with the backend unavailable until explicitly connected. The compiled application
keeps the normal authenticated shell and API boundaries.
## Sketch, select, and judge
Begin with a blank board or the explicitly illustrative example. Draw actual freehand strokes,
add named nodes, and connect them. **Lasso** circles actual ink and selects whole intersecting
objects; the contour itself never becomes a source stroke. **Select** keeps rectangular selection,
and the Objects list supplies its keyboard alternative. Neither gesture cuts strokes. The
highlighted objects are the permitted edit scope.
Unselected objects supply context and keep their identities.
Capture the selection with an instruction. The portable packet contains the original selected
strokes and objects, the bounded scene, world bounds, exact scene revision, and a PNG crop of
that same paused revision when capture succeeds. Inspect the packet before taking it to a model.
Creating or downloading it performs no model transmission. Instruction and label text remain
data, never executable commands.
An imported model proposal names that packet's scene, revision and selected identities. Review
its new objects, labels, archived source strokes and positions before applying it. Existing
objects outside the selection cannot be changed. A changed scene makes the proposal stale;
capture a fresh packet. Acceptance applies the complete change once, preserves original ink,
and can be undone. A rejected or invalid proposal leaves the board intact.
The local **Tidy** helper regularizes geometry. It does not interpret an arbitrary spoken or
written request. A proposal authored by Codex and manually imported is attributed as manual
model transport; it does not establish a live LychD vision-provider integration.
## Keep the explanation steady
Nodes have editable text, optional symbolic artwork, stable identity and explicit connections.
Text is rendered separately from image pixels, including short overlays such as “DB”. Local PNG
artwork keeps its declared provenance; attaching it does not claim generated-media custody or
creative acceptance. World-fixed ink stays where drawn. This profile does not infer attachment
of handwriting to a nearby node.
An explicit arrangement settles movable nodes using their dimensions, existing positions,
connections and pinned obstacles. Drawing, selecting and dragging hold the scene steady.
Arrangement is one undoable change; simulation steps do not become revision history. Motion
respects reduced-motion preferences. The semantic object list offers selection and editing
without requiring a pointer or pan/zoom gesture.
## The board and its neighbors
| Canvas owns | Related owner |
| --- | --- |
| Board documents, source ink, visual objects, selection packets, proposal review and reversible edits | [Atlas](../../divination/altar/atlas.md) retains undertaking purpose, concerns and judgments. A board is not an Atlas decision. |
| Visual workflow sketches and possible future exports | [Loom](../../divination/altar/loom.md) retains exact workflow meaning and admission. A drawn arrow is not an executable permission. |
| Illustrations of execution | [Orb](../../divination/altar/orb.md) projects recorded Run evidence. Diagram motion supplies no execution observation. |
| Placement of local symbolic artwork | [Atelier](../atelier/index.md) owns visual commissions and creative acceptance; [Prism Image](../../sepulcher/extensions/prism/image.md) owns designed technical image jobs. |
| Requests for optional generated assets | [ComfyUI](../../sepulcher/animator/soulstone/engines/comfyui.md) is a possible inference engine. Its graph does not become the board or a Loom Scroll. |
No relationship is inferred from proximity or a shared label. Future exact references may open
their owning instrument without transferring its records, permissions or execution authority.
## Save, stop, and return
Download the local document to retain the current scene and its bounded undo/redo snapshots
outside the browser; closing an unsaved draft can lose it. Save the current draft before opening
another document. Before an import replaces that draft, it validates format, byte and collection
bounds, finite geometry, unique identities, source-stroke references, image envelopes and edge
endpoints. Untrusted imports cannot contain remote images, SVG or executable code.
The portable size budget reserves the same fixed space for numeric values in the browser and
Python. This prevents differences in number formatting from changing acceptance, although the
conservative budget may be larger than the compact downloaded file.
Undo and redo preserve object identities and create fresh scene revisions so an old model response
cannot become current again accidentally. The board has no live external effect to reconcile in
this profile. A future server-retained, concurrent or provider-backed profile must define its own
admission, custody, conflict and interrupted-effect recovery before becoming supported.
The executable file and proposal contracts belong to
[`src/lychd/compositions/canvas/`](https://github.com/hexanomicon/lychd/tree/main/src/lychd/compositions/canvas).
The first profile does not register an executable Pattern or Invocation. Live microphone capture,
automatic model interpretation and image generation require separately proved integrations.
The [manual Codex example](https://github.com/hexanomicon/lychd/tree/main/examples/canvas)
provides a selection packet, a proposal bound to the untouched sample, and a reproducible
draw/select/review/save journey. It runs without a GPU or model service.
## Smallest falsifying journey
Draw two rough boxes and an arrow, select them beside an unrelated object, and capture the real
marks and crop. Import a proposal that makes editable nodes, preview it, apply it, rename and
move a node, then undo and redo. The unrelated object and original source ink survive. Change
the scene after capture and verify that the old proposal is refused. Save and reopen the local
document and repeat through the keyboard object list. Any lost geometry, silent out-of-scope
edit, partial acceptance or successful stale application defeats this profile.
---
title: "Atelier"
plain_name: "App: Atelier (visual art)"
section: "Compositions > Creative Works"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/
guide: https://lychd.snayu.ai/docs/compositions/atelier/
---
# Atelier (App: Atelier (visual art))
## Plain-English summary (Snayu)
**What it is:** Atelier takes a visual commission, such as a still image, animation or visual effects package, from brief to an accepted, traceable result, keeping direction, sources, candidates and approved revisions on record.
**Why it matters:** Read when working on image or video generation features, or deciding what visual work Atelier owns versus music, editing or game import.
- The commission declares its finish: an accepted still, accepted motion, or a sealed VisualAssetBundle.
- You, the Operator, remain visual director; generators and editors are replaceable tools.
- Stops before sound, engine import, final editing and publication, which other apps own.
**Status:** Designed. Accepted design; no registered workflow or delivered implementation.
## Original text (Hexanomicon)
The Magus asks for a still image that can stand on its own. Once accepted, that image may later become the first frame of a moving sequence. Atelier carries either commission to its declared finish, keeping visual direction, source influence, candidates, and accepted revisions attributable.
The craft can combine generators, editors, renderers, procedural work, capture, and authored material. The Magus remains visual director. Here **VFX means visual effects**.
## The work
Start with [Brief](brief.md): what should exist when the commission is done, and how will you
judge it? [Direction](direction.md) turns those intentions into a visual language.
[Assets](assets.md) makes and reviews images, models, textures, and other visual roles.
Enter [Motion](motion.md) when the requested work changes through time. Once a result is
approved, [Package](package.md) seals the exact revisions another craft can admit.
## The requested finish
Choose the requested finish when admitting the commission: an accepted still, accepted motion, or an approved immutable `VisualAssetBundle@1`. The principal Pattern `atelier.build_visual_package@3`, published by `atelier.studio` revision `5`, works from that commission, frozen references, target profile, and acceptance criteria. If it cannot reach the requested boundary, it must return exact partial or non-completion under the pinned score.
Reaching a requested still boundary completes the Run; later motion begins a forward Invocation over the retained artifact. [Motion](motion.md#progressive-visual-depth) follows both motion within the pinned score and separately admitted continuation.
Atelier owns the commission, visual judgment, candidates, accepted revisions, provenance, and package. It stops before sound production, engine import, final audiovisual assembly, publication, or rights certification. [Riffmaw](../riffmaw/) owns music; [Language Edition](../language-edition/) owns timed-language editions; [Foundry](../foundry/) owns engine integration; [Broadcast](../broadcast/) owns picture sound, the final editorial relation, and publication.
These craft boundaries can meet in one proposed Atelier studio, with shared controls and a
timeline. [The studio example](../products-and-suites.md#atelier-riffmaw-language-edition-and-broadcast)
distinguishes that broader operator experience from this visual contract and follows joint
generation, music revisions, and game-directed work.
## Revision continuity
??? info "Earlier designs and their exact successors"
Revision `5` supersedes revision `4`, advancing `atelier.build_visual_package` and `atelier.forge_visual_sequence` to `@3` with exact `ImageJob@2`/`VideoJob@2` Prism placements and pre-execution compound-facet authority. Revision `4` replaced `SyncCueMap@1` with `MusicCueMap@1`, routed returned sound by role, and advanced the former `@1` Patterns to `@2`. No Portfolio registry or Run used revisions `3` or `4`; no executable migration exists, and historical references keep their meanings.
[Workflow](../../adr/28-workflow.md) · [Vision](../../adr/36-vision.md) · [Composition Portfolio](../index.md)
---
title: "Brief"
plain_name: "Atelier: the visual brief"
section: "Compositions > Creative Works > Atelier"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/brief/
guide: https://lychd.snayu.ai/docs/compositions/atelier/brief/
---
# Brief (Atelier: the visual brief)
## Plain-English summary (Snayu)
**What it is:** How Atelier fixes a commission before generation starts: purpose, audience, target format, budget, roles, acceptance criteria and a frozen set of reference images with their rights and consent.
**Why it matters:** Read when designing how visual requests are admitted, especially reference handling, likeness consent and cost limits.
- References are frozen by snapshot and digest; a URL alone cannot freeze them or grant use.
- Changing purpose, references or likeness use creates a new brief revision.
- Missing consent or source authority leads to a question, reduced scope or refusal before work starts.
**Status:** Designed
## Original text (Hexanomicon)
Before a generator opens, the director must be able to say what the image is for and what would make it fit. The brief freezes that starting point, so an appealing candidate cannot quietly redefine the commission.
## Admit the commission
Start with purpose and audience, then name the target profile, budget, requested visual roles, and acceptance criteria. Each image, model, texture, animation, or sequence needs concrete spatial, temporal, and format constraints. Where the director has not decided, leave a question for review rather than accepting a provider default.
The references need an equally clear boundary. Admit a finite set by snapshot and digest, retaining classification, permitted purpose, retention, and known provenance. A URL helps locate the material but cannot freeze it; possessing a copy cannot grant its use. Before dependent production, resolve the likeness, consent, disclosure, and use boundaries for recognizable people, protected marks, confidential material, and disputed origin.
Those choices continue to matter after generation. Attach prompts, control images, masks, adapters, fine-tunes, and selected examples to each candidate so the influence remains inspectable. “AI-generated” names a production method; it cannot erase lineage or certify a use.
## Freeze the starting line
The admitted revision becomes the common reference for production and review. It pins the commission and target profile, exact snapshots and open questions, roles and output limits, review criteria, cost/provider/Portal/retention ceilings, and effects needing separate approval.
Changing the purpose, adding a reference, requesting a new likeness use, or selecting a materially different target creates a successor brief. If essential source authority or consent is missing, answer with a question, reduced safe scope, or refusal before dependent work begins.
[Direction](direction.md) and [Assets](assets.md) receive the accepted revision and digest. Provider sessions, Sigils, secrets, and downstream permission stay outside that handoff.
---
title: "Direction"
plain_name: "Atelier: visual style rules"
section: "Compositions > Creative Works > Atelier"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/direction/
guide: https://lychd.snayu.ai/docs/compositions/atelier/direction/
---
# Direction (Atelier: visual style rules)
## Plain-English summary (Snayu)
**What it is:** How Atelier turns your taste into a reviewable style guide covering palette, composition, light, camera and exclusions, and uses it to judge and correct candidates.
**Why it matters:** Read when building style guidance or review and correction loops for generated visuals.
- The style guide separates intent, observations about references, your decisions, and concrete tests.
- It must not instruct copying protected work or imitating a named living artist.
- A failed candidate is traced to a rule, then either the rule or its execution is corrected.
**Status:** Designed
## Original text (Hexanomicon)
A palette alone will not tell an illustrator where an exception belongs. Direction makes the Magus's taste usable across several assets: what the work should feel like, which visual rules support that intention, and how a candidate will be judged.
## A reviewable visual system
`atelier.establish_style_bible@1` records the chosen composition, shape, proportion, palette, material, light, camera, typography, motion, and exclusions where they apply. Observations about references can inform these choices. They do not instruct the maker to copy protected expression or imitate a named living artist.
Make the reasoning visible in four layers. Begin with the **intent** and the response it seeks. Keep attributable **observations** about references separate from the Magus's **decisions**, including controlled exceptions. Then state concrete **tests** that will show whether a candidate follows those decisions.
Provider prompts, seeds, controls, and exploratory images can help discover this visual system. The accepted direction remains their governing reference, and each accepted asset records the exact direction revision used in its review.
## Review and correction
When a candidate fails, identify the relevant rule and decide whether the rule or its execution needs repair. `atelier.revise_from_correction@1` admits a bounded forward correction to that layer. Conflicting rules, an impossible target, or exhausted correction return exact non-completion.
A display can also change the judgment. `atelier.presenter_calibration@1` may compare how a viewer or presentation changes perception. Use that evidence to inform a direction revision; it cannot edit an accepted asset or certify every display.
The resulting visual language guides [Assets](assets.md) and [Motion](motion.md). Acting on it still requires separate admission for generation, spending, egress, publication, or a changed brief.
---
title: "Assets"
plain_name: "Atelier: making visual assets"
section: "Compositions > Creative Works > Atelier"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/assets/
guide: https://lychd.snayu.ai/docs/compositions/atelier/assets/
---
# Assets (Atelier: making visual assets)
## Plain-English summary (Snayu)
**What it is:** How Atelier produces and reviews images, sprites, textures and 3D models as candidates, with full lineage of sources, tools, transforms and review findings.
**Why it matters:** Read when implementing asset generation, normalization or review, or the record-keeping behind them.
- Every transform records parent, operation, parameters, tool and output digest so a reviewer can trace changes.
- Results are probed against target format, size, geometry and other limits before acceptance.
- A paid generation with a lost acknowledgement stays unknown until reconciled, to avoid paying twice.
**Status:** Designed
## Original text (Hexanomicon)
A sprite, texture, illustration, or model begins as a candidate. Its attractive surface is only one part of the decision: Atelier must also retain what influenced it, which transformations made it, and whether it meets the declared role.
## Candidate lineage
`atelier.forge_concept_set@1`, `atelier.forge_sprite_set@1`, `atelier.forge_texture_set@1`, and `atelier.forge_model_asset@1` combine admitted generation, procedural work, deterministic transforms, manual editing, capture, or authored sources.
Keep the candidate's source references, classifications, permitted influence, and retention together. Its production record names the tool/provider revision, prompts or controls, seed when available, cost, and result.
The production history must let a reviewer follow each candidate back through its changes. Each transform therefore binds its parent digest, operation, parameters, implementation, output digest, and loss. Review adds the asset revision, role, format/profile facts, findings, approval, and derivatives. Both generation and normalization create artifacts with parents.
Spatial candidates additionally declare geometry, appearance, structure, deformation, assembly and procedural facets; units, axes, origin, scale, bounds and transforms; material channels, parts, skeleton and camera facts; and representation conversions. A glTF/GLB can contain mesh, PBR appearance, skeleton, skinning and animation together. Point clouds, Gaussian and radiance forms, neutral voxels, game block grids, and portable assemblies remain distinct forms. [Prism Form](../../sepulcher/extensions/prism/form.md) owns their technical production; Atelier owns visual acceptance.
## Produce, normalize, review
Make the candidate against the exact brief and direction. Before decoding its media, apply the hostile-media limits in [Vision](../../adr/36-vision.md). Then establish whether the result can meet the target: probe format, dimensions, frames, color, geometry, topology, materials, units, axes, bounds, size, and any other target limits. Retopology, baking, rigging, voxelization, and other normalization preserve lineage and declared loss. They may repair technical fit; an ambiguous likeness or failed source still needs its own resolution.
Review selects, rejects, or returns attributed findings. The smallest supported repair creates a new candidate; accepted material is replaced only by a successor revision. Unresolved influence, consent, likeness, Portal egress, or target fit produces quarantine, reduced scope, or refusal.
Paid generation binds idempotency identity and exact request digest. A lost acknowledgement leaves it **unknown** until provider records reconcile it; another attempt could buy the same work twice.
Accepted revisions enter [Package](package.md); temporal work continues through [Motion](motion.md). Neither result carries engine, editorial, or publication authority.
---
title: "Motion"
plain_name: "Atelier: animation and video"
section: "Compositions > Creative Works > Atelier"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/motion/
guide: https://lychd.snayu.ai/docs/compositions/atelier/motion/
---
# Motion (Atelier: animation and video)
## Plain-English summary (Snayu)
**What it is:** How Atelier handles moving visuals: animation, transitions, camera moves and generated video, typically from an accepted first frame through video generation to a reviewed sequence.
**Why it matters:** Read when working on image-to-video pipelines, music-synced visuals, or video models that also return sound.
- A finished still can end the job; later animation starts a new job using the kept image.
- Sound returned by a video model needs its own owner declared beforehand; undeclared sound is quarantined.
- Review covers the whole duration: seams, flicker, continuity and timing, not single frames.
**Status:** Designed
## Original text (Hexanomicon)
The first frame has been chosen. Motion asks what should change, over which timebase, and how the director will recognize a finished sequence. Its material includes animation, transitions, camera movement, loops, and generated or authored visual sequences.
Prism's [Video](../../sepulcher/extensions/prism/video.md) supplies pixel effects; [Kinesis](../../sepulcher/extensions/prism/kinesis.md) supplies structured motion recovery, generation, retargeting, cleanup, synchronization, and conversion. Atelier keeps choreography, visual direction, review, and acceptance across those replaceable tools. Music, sound design, final audiovisual editing, and public rendering retain separate owners.
## Progressive visual depth
The commission declares an accepted still, accepted motion, or sealed package as the requested finish. `atelier.build_visual_package@3` may contain exact image, review, motion, probe, and package placements branching on that typed policy. Alternatively, a completed image becomes immutable input to a new `atelier.forge_visual_sequence@3` Invocation.
A path through motion to a sealed package is:
```text
brief + target profiles + language policy
→ ImageJob@2 generate or edit
→ review and select exact first frame
→ optional second boundary image
→ VideoJob@2 i2v or first_last
→ temporal probe and visual review
→ VisualAssetBundle@1
```
At a requested still boundary, success is terminal. A declared review Gate or hardware transition may enter Stasis while something remains outstanding; future animation alone is no reason to keep the completed Run open.
The Scroll names Image and Video Spell contracts. Its exact Resolution Lock may bind Qwen Image and an LTX-2.5 Comfy preset, other local profiles, or separately admitted Portal implementations. This is an illustrative binding, not a delivery claim. Prism's prompt-translation record preserves original/model-facing texts, translator revision, and loss; an imported Comfy graph is no portable Scroll or global Translation service.
## Clips and cues
`atelier.forge_animation_set@1` binds clips to exact assets and Form rigs, plus Kinesis motion revisions when used. `atelier.forge_visual_sequence@3` binds frame rate, duration, aspect, continuity, and transitions. Exports retain source revisions, tools, transforms, timeline, probes, and checksum.
A [Riffmaw](../riffmaw/sync.md) `MusicCueMap@1` offers musical events, windows, intensity, and transitions. The director chooses their visual answer without editing the musical map. Audio conditioning likewise requires an exact admitted reference.
A video attempt may also produce sound, so its owners must be known before execution. Before a `VideoJob@2`, `MediaFacetAuthoritySet@1` must declare the visual role, `atelier.studio` revision `5`, and exact commission request digest. Any sound role needs separate authority.
After production, Atelier issues its own `SemanticFacetAdmissionReceipt@1` for the visual facet, keeping the compound Prism parent attached. Riffmaw, Language Edition, Broadcast, or Foundry separately admits declared music, timed-language, picture-sound, or world-sound facets. Undeclared sound is quarantined/deleted. When streams are inseparable, refusal by any required owner prevents use of the compound.
Those judgments may concern one joint model attempt with a shared timebase. They require neither
duplicate generation nor a separate screen for each role; [Vision](../../adr/36-vision.md#compound-media-and-application-acceptance)
keeps the single technical parent and each facet's admission explicit.
## Review the movement
Check the sequence duration against the target, then review across that full duration: seams, ordering, camera continuity, clipping, flicker/accessibility hazards, and export stability can fail between otherwise acceptable frames. A bounded correction makes a successor revision. A wrong timebase, stale assets, unsupported profile, or ambiguous synchronization returns findings or refusal.
[Package](package.md) receives accepted motion as visual material. Broadcast owns its final placement, trim, retime, transitions, captions, sound relation, and claims. Foundry owns engine import/runtime behavior. A pinned FFmpeg or other deterministic renderer may serve either office without deciding the creative sequence or final cut.
---
title: "Package"
plain_name: "Atelier: sealed visual package"
section: "Compositions > Creative Works > Atelier"
status: "Designed"
original: https://hexanomicon.dev/compositions/atelier/package/
guide: https://lychd.snayu.ai/docs/compositions/atelier/package/
---
# Package (Atelier: sealed visual package)
## Plain-English summary (Snayu)
**What it is:** How Atelier seals accepted visuals into a VisualAssetBundle that other apps can inspect, plus how it handles effects, failures, restarts and deletion.
**Why it matters:** Read when building the handoff from Atelier to Foundry or Broadcast, or its recovery behaviour.
- The manifest records revisions, lineage, tools, findings, approvals and known use limits.
- The package carries no credentials or permission for other uses; consumers may refuse it.
- A bad reference or revoked consent marks dependent revisions stale without erasing history.
**Status:** Designed
## Original text (Hexanomicon)
A consumer needs to know exactly which images it received and which uses their acceptance covered. `atelier.export_visual_package@1` seals that answer in `VisualAssetBundle@1`; `atelier.review_visual_package@1` returns findings without changing approved material.
## What crosses the boundary
The package manifest lets another craft inspect the accepted work before using it. It binds the revision/digest, target profile, assets, visual constraints, source and derivative lineage, tools/provider receipts, validators, findings, approvals, and known use or likeness boundaries.
[Foundry](../foundry/) uses that account to decide whether exact revisions can enter an engine and support playability. [Broadcast](../broadcast/) judges their use in claims, storyboards, timeline, render, accessibility, and publication. Either consumer may refuse. The visual director's approval answers the original commission; exported files cannot extend that judgment to an entirely different one.
The handoff therefore carries no Sigil, secret, provider session, approval for another use, or downstream effect authority.
## Effects, failure, and return
Paid generation and external handoff each need their own effect record, binding an idempotency key and exact payload digest. If an acknowledgement is missing, keep the result **unknown**. Reconcile that same effect with its provider or consumer before deciding whether another attempt is permitted.
A bad reference, revoked consent, or later finding makes every dependent revision stale. Preserve the accepted history so it remains possible to explain what was used and why. A correction must address those dependencies rather than overwrite the accepted package.
Restart first recovers the pinned Pattern, schema, sources, providers, tools, receipts, and artifacts. If parked work is incompatible with them, it must drain, migrate explicitly, or end non-complete. Deletion follows the same chain of custody: inventory derivatives and handoffs, request authorized downstream removal, and record any material still held externally.
## Proving package
Begin with a local, style-led 2D commission using licensed references. Freeze the [brief](brief.md), version the [direction](direction.md), make concept plus sprite/texture assets, probe and normalize them, and complete a bounded repair before accepting `VisualAssetBundle@1`. This first proof includes no sound, engine import, channel render, Portal, paid generation, or public release.
Then try separate landscape and portrait hero profiles. Keep the accepted stills and animate one or two exact boundary frames through an admitted Video implementation. Probe loop and export behavior before sealing the successor package. The declared still or motion boundary can each be an honest finish.
Model-returned sound may cross into the package only with pre-execution role authority, its independent `SemanticFacetAdmissionReceipt@1`, and the shared compound parent. Retain all three with the admitted material. [Motion](motion.md#clips-and-cues) follows each role's admission. Broadcast alone accepts the final editorial audiovisual relation.
Return to [Atelier](index.md), or follow the declared finish in [Motion](motion.md#progressive-visual-depth).
---
title: "Riffmaw"
plain_name: "App: Riffmaw (music making)"
section: "Compositions > Creative Works"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/
---
# Riffmaw (App: Riffmaw (music making))
## Plain-English summary (Snayu)
**What it is:** Riffmaw is the planned music app: describe an idea, bring a reference or performance, hear alternatives and shape the music with AI help, through four roads: Forge, Perform, Jam and Produce.
**Why it matters:** Read first before working on music generation, recording, jam sessions or mixing features.
- You choose what to keep; the assistant proposes material and edits within scope.
- Each road ends its own job; results pass forward as exact artifacts, never silently resumed.
- Owns music only: speech, dubbing, picture sound, visuals and publishing belong to other apps.
**Status:** Designed. Native app not built; only offline engineering probes exist (see Workbench).
## Original text (Hexanomicon)
Riffmaw is the music-making application being developed for LychD. Its intended experience is
to describe an idea, bring a reference or performance, hear alternatives, and shape the music
with AI assistance and approachable controls. The interface should offer detailed production
controls when needed, while keeping small changes accessible without DAW expertise.
An assistant can help develop a brief, propose material or edits, and compare candidates within
the requested scope. The Magus chooses what to keep. A remembered drop, a guitar take, a sung
line, or an empty session can all begin the craft; their contributions remain attributable.
## Start with a musical idea
The intended interaction begins with a musical request, for example:
- “Make a short psytrance sketch, with a quieter opening and a stronger bass entrance.”
- “Turn this part down; let me compare it with the previous version.”
- “Use this reference moment to explore a similar texture with different notes.”
[Workbench](workbench.md#approachable-interaction) develops that edit-and-listen experience.
Its [development operations](workbench.md#development-operations) describe the finite engineering
tools available to exercise today; they do not yet supply the native application or an AI
listening assistant. [State of Work](../../state-of-the-work.md#music-comfy-engineering-probes)
keeps that implementation boundary.
## Ways of making
| Road | Pattern | What can finish here |
| --- | --- | --- |
| **Forge** | `riffmaw.forge_track@2` | Offline composition/generation from a brief, references, lyrics, or empty session: `MusicCandidateSet@1` or `MusicFindingSet@1`. |
| **Perform** | `riffmaw.capture_take@2` | Explicitly armed audio/MIDI from played, sung, rapped, musical-spoken-word, or programmed performance: `PerformanceTake@1` and observations/findings. |
| **Jam** | `riffmaw.open_jam@2` | Performers and admitted machine players answering against mapped clocks: recoverable `MusicalPerformanceSession@1` or findings. |
| **Produce** | `riffmaw.forge_music_bundle@2` | Bounded arrangement, mix, master, probes and listening review: `MusicAssetBundle@1`, candidates, findings, or refusal. |
Each road ends by settling its own Invocation. Carry exact artifacts into later forward work without nesting or silently resuming another Pattern. A future Scroll may combine separately named capture/generation/render/review placements, but must do so under its own revision, Resolution Lock, and authority ceiling.
The passage between roads preserves their separate decisions: file access does not arm an input, a take does not admit training, a candidate mix is not master approval, and export does not publish.
## The work
Find the material in [Sources](sources.md), down to the exact musical moment. When people or
machines perform, [Sessions](sessions.md) preserves their takes and shared time;
[Hardware](hardware.md) admits the capture routes they use. [Music](music.md) develops that
material into an arrangement and master candidate.
Choose machinery through [Studio](studio.md), which keeps tool roles and dated candidates
separate from the craft. For uncertain roles, [Voice](voice.md) distinguishes musical performance
from speech, and [Sound](sound.md) follows what belongs to music. [Sync](sync.md) offers cues for
another work; [Package](package.md) seals the musical handoff.
## Reference contract
`riffmaw.music` revision `2` accepts a music brief plus explicitly admitted references, lyrics, takes, MIDI, scores, samples, or live inputs. Alongside the road-specific returns, it can issue `MusicCueMap@1`. It stops before ordinary dialogue, spoken replacement/localization, picture sound, visuals, final audiovisual assembly, impersonation, and publication. Language Edition, Broadcast, Atelier, and their technical providers retain those offices.
Prompt, lyric, requested sung language, and interface locale remain separate. Exact model profiles must prove their musical/language behavior; a local ComfyUI or other Soulstone binding and a Portal API are independently evidenced implementations. [Music](music.md#language-belongs-to-the-musical-request) owns the request; [Studio](studio.md#current-candidate-map) records candidates.
## Revision continuity
??? info "Earlier designs and their exact successors"
`riffmaw.audio` revision `1`, its `Sonic*` family, and former `riffmaw.forge_track@1`, `riffmaw.capture_take@1`, `riffmaw.open_jam@1`, `riffmaw.index_sources@1`, and `riffmaw.mark_moment@1` are retired without reinterpretation. New identity `riffmaw.music` revision `1` used the five Pattern names at `@2`. Revision `2` advances principal `riffmaw.forge_music_bundle` to `@2` for model-native pre-execution music authority and semantic admission. `MusicAssetBundle@1` already accommodates those exact provenance receipts; other music Patterns remain unchanged. No registry, Run, or stored application record used the retired designs, so no executable migration exists.
[Audio](../../adr/37-audio.md) · [Workflow](../../adr/28-workflow.md) · [Composition Portfolio](../index.md)
---
title: "Sources"
plain_name: "Riffmaw: reference material"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/sources/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/sources/
---
# Sources (Riffmaw: reference material)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw admits specific audio files as references and marks an exact musical moment (for example a drop at 01:32) without turning the whole media library into influence.
**Why it matters:** Read when building source indexing or reference-moment search for music.
- Only named files enter, with limits on size, duration and recursion; no ambient home folder.
- A chosen moment is recorded with source, timebase, region, uncertainty and rights.
- Similarity can locate a clue but cannot prove authorship or safe reuse.
**Status:** Designed
## Original text (Hexanomicon)
The idea arrives as a timestamp and a sound made with the mouth:
> “At `01:32` it drops: _tz, tz, u-do_. Keep the pressure and spacing, change the musical matter.”
Sources helps find that moment without turning the whole media library into admitted influence.
## Admit, index, mark
`riffmaw.index_sources@2` accepts named files, recordings, or attributable artifacts, bounding recursion, symlinks, bytes, duration, decoding, metadata, and retention before indexing. Neither an ambient home directory nor a searchable provider catalogue enters by default.
Once a source is admitted, use `riffmaw.mark_moment@2` to locate the idea. A timestamp, beat range, tapped rhythm, phrase, or other bounded clue ranks spans under a pinned feature set, and the Magus selects the useful one. Record that choice in `ReferenceMoment@1` with its source, digest, timebase, exact region, observations, uncertainty, attribution, rights, and admission decision.
Similarity can locate a clue; it cannot prove authorship or safe reuse. Translate a style request into reviewable pocket, density, accents, space, motion, instrumental relation, and energy. A lifted melody, disputed source, missing permission, or hidden influence leads to quarantine, replacement, or refusal.
[Music](music.md) receives the exact reference without permission to copy, generate, spend, arm capture, clone a performer, or publish. Ordinary dialogue and picture sound retain their owners despite sharing an audio format.
---
title: "Sessions"
plain_name: "Riffmaw: recording and jamming"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/sessions/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/sessions/
---
# Sessions (Riffmaw: recording and jamming)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw records performances (takes) and runs live jam sessions with human and machine players on shared, mapped clocks, preserving raw audio and MIDI before any editing.
**Why it matters:** Read before working on audio capture, comping, MIDI, remote jamming or live machine accompaniment.
- Recording requires explicitly arming an exact route; raw audio and MIDI are kept immutable.
- Machine players have levels: observe, accompany, transform, conduct; escalation needs fresh consent.
- Late machine entrances are dropped safely; human monitoring keeps working without a model.
**Status:** Designed
## Original text (Hexanomicon)
Keep what was actually played before editing makes it seem inevitable. A take preserves one armed performance; a jam adds participants, mapped clocks, and the conditions under which their responses could be heard.
## Arm and capture
Arm the exact performance route before `riffmaw.capture_take@2` begins. Admission pins its device, clocks, sample rate, latency, monitoring, channels, plug-in state, session revision, and consent. Preserve immutable raw audio/MIDI first, so later transcription, timing correction, comping, cleanup, or transformation can always identify the performance it changed.
`PerformanceTake@1` separates performance from attributed tempo, pitch, timing, score/lyric transcription, and other observations. Their source regions and uncertainty remain visible. [Audio](../../adr/37-audio.md) governs visible, bounded, revocable capture, custody, and hostile input. A later `MusicalPerformanceSession@1` may reference settled takes; shared file formats do not create a jam.
## Choose without erasing
When choosing the best passages, record each source take and selected region in the comp. Acceptance does not rewrite rejected takes or their retention rules. Changes to device, clock, plug-in, or session likewise create explicit revisions.
If a failure leaves capture uncertain, first stop the device. Reconcile the artifacts and session state before retrying; silence cannot prove that nothing was recorded.
[Music](music.md) receives artifacts and observations without an open DAW, microphone authority, or credentials. Ordinary spoken replacement/localization remains Language Edition work.
## Jam in shared time
`riffmaw.open_jam@2` brings participants into one bounded musical session. Spellweaver admits its Invocation/Scroll; the Pattern cannot admit its own Circle or nested production.
Microphones, instruments, MIDI/controllers, clips, remote performers, and machine players each declare monitor, recording, retention, analysis, transformation, remote transmission, and response scope. Required preservation without admitted recording/retention refuses the route or jam. Network presence does not grant recording consent; one performer cannot change another's participation or monitor scope.
“follow behind my attack,” “answer only at phrase endings,” and “that distortion is energy, not a key change” can create successor `FeelProfile@1` revisions. They correct interpretation without rewriting performance or earlier observations. This is the long road toward performance-native direction through timing, touch, phrasing, dynamics, repetition, and contrast. Persistent personalization/training still requires separate corpus admission and model promotion.
`MusicalPerformanceSession@1` binds revision, participants/roles, assistance policy, model/tool allowlist, and these exact records:
| Record | Binds |
| --- | --- |
| `ClockDomainMap@1` | Audio sample frames, monotonic time, beat and bar position, clock epoch, external, leader or distributed mode, peer mappings, clock-rate divergence, resampling, and uncertainty. A remote peer never implies sample lock. |
| `LiveAudioGraphProfile@1` | Driver, sample rate, quantum and periods, ports and links, channel map, declared direct-monitor route, measured capture, playback and round-trip latency, xruns, hot-plug events, and graph revisions. |
| `MidiEventStream@1` | Device and port, MIDI 1 or UMP profile, channel and sample offset, notes, CC and sustain, bend, pressure or MPE, transport events, event loss, and admitted SysEx policy. |
| `CaptureManifest@1` | Immutable pre-fader sources, optional processed prints, MIDI, hardware returns, local and remote stems, exact frame boundaries, discontinuities, and checksums. A guitar DI remains separate from its amp or cabinet monitor path. |
| `RemoteJamLeg@1` | Peer identity, topology, codec, channels, encryption, jitter buffer, loss concealment, latency estimate, clock-rate divergence, resampling, reconnect epoch, local-monitor policy, and recording consent. |
Together, these records keep the mix, individual sources, MIDI/control events, responses, and route/clock changes attributable. Graph checkpoints refer to that work through typed references, bounded sequence state, and receipts. The PCM/MIDI streams, device handles, and plug-in state remain outside those checkpoints.
A route's participation is **observe** (correctable observations, no audible reply), **accompany** (bounded musical answer), **transform** (process the selected live route while preserving dry source), or **conduct** (propose structural/tempo/cue changes). Escalation needs new visible admission by every affected Principal; proposals cannot silently become changes to a human performance.
## Performance as a correctable language
`MusicalGestureObservation@1` may interpret notes/chords, key/tuning, beat/pocket, accents, articulation, dynamics, timbre, phrases, repetition, tension/release, and player relations. Preserve source regions, feature/model revisions, latency, confidence, and competing readings. It grants no access to emotion or unspoken intent.
A musical answer must also explain when it was prepared and when it actually entered. `JamResponse@1` binds source-time cutoff and lookahead, jam/route epochs, turn sequence, answered observation/cue, controls, ready-by deadline, scheduled window, planned/actual first audible sample, measured latency, output acknowledgement, omission reason, and audio/MIDI artifact. This preserves the difference between an intended entrance and its observed result.
## The realtime stopping line
[Audio](../../adr/37-audio.md#application-owned-live-audio) owns callback, clock-epoch, output-fence, monitoring, reconnect, and uncertain-playback law. Riffmaw adds musical beat/bar mapping and deadline windows. A late machine entrance may be safely omitted; the human monitor remains available without a model. Partial sessions retain acknowledged takes/events. Continuation is a newly armed Invocation with new musical clock and route epoch.
## Proving the jam
Use armed dry guitar DI, keyboard MIDI, two local performer roles, and a synthetic remote leg with controlled jitter, loss, and clock-rate divergence. Capture every named clock/graph/MIDI/manifest record and a scheduled response. Exercise xrun, removal, epoch loss, plug-in crash/latency change, late output, and uncertain remote acknowledgement. Prove continued direct monitoring, stale-output fencing, raw audio/MIDI reconciliation, and newly admitted continuation. Export session, sources, stems, MIDI, tempo, and marker maps. This fixture proves state and recovery; measured device latency and musical usefulness need a separate hardware bake.
---
title: "Music Hardware Boundary"
plain_name: "Riffmaw: audio hardware routes"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/hardware/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/hardware/
---
# Music Hardware Boundary (Riffmaw: audio hardware routes)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw admits an exact audio input route (interface, channel, clock, latency, monitoring) for a take, keeping the dry instrument signal separate from the processed sound you hear.
**Why it matters:** Read when dealing with Linux audio devices, PipeWire routes or instrument and vocal capture.
- Opening a DAW or plugging in an instrument does not arm recording; explicit arming does.
- Speech on the same interface goes to Voice or Language Edition, not Riffmaw.
- No device gets a compatibility presumption; each route must pass its own test.
**Status:** Designed
## Original text (Hexanomicon)
The guitar's dry signal and the amp sound heard in the headphones are related, but they are not the same recording. Riffmaw admits the musical reason to arm an exact route and preserves those separate sources for later production.
[Audio Hardware and Host Routes](../../sepulcher/animator/audio-routes.md) owns replaceable Linux/device candidates and setup evidence. [Audio](../../adr/37-audio.md) owns capture, custody, transport, interruption, and uncertain playback. ALSA, PipeWire, interfaces, drivers, and workstation hardware do not become Riffmaw records.
## Admit a musical route
`riffmaw.capture_take@2` begins after visible operator arming. Pin device/channel, driver/graph revisions, sample format/rate, clock epoch, latency/monitor path, dry/processed split, performer authority, retention, stop/cancel behavior, and byte/duration ceilings. Opening a DAW, attaching an instrument, or pairing a transmitter does not supply that admission.
Channels sharing an interface can retain different owners. Speech intended for dialogue/transcription enters Echo and, for timed editions, Language Edition. Instrumental, sung, rapped, or musical-spoken-word material may enter Riffmaw. Simultaneous PCM capture merges none of their consent, custody, session, or acceptance.
## Instrument and vocal tracking
Build the admitted profile from exact device instructions and host measurements. For each microphone/instrument channel, identify its electrical input mode, power requirements, gain/clip behavior, and monitoring route. Connector shape and vendor claims cannot prove Linux compatibility.
Explicitly map direct monitoring and any processed Guitarix or other effect path so dry/processed doubles are intentional. Retain dry DI separately from the amp/cabinet print; the monitored sound must not obscure which signal was recorded.
Bluetooth/TWS, passive-instrument inputs, and anonymous microphone kits receive no special compatibility presumption. Every route must pass the exact format, latency, stability, reconnect, and failure bake. Device settings belong to the qualified host route rather than universal instructions inferred from a musical role.
## Records and proof
`PerformanceTake@1` retains immutable audio/MIDI with device, clock, channel, consent, discontinuities, and transforms. Several routes/takes may later join `MusicalPerformanceSession@1`; a single take cannot silently become a jam.
The hardware proof records dry guitar/bass and musical vocals through a real desktop PipeWire session with networking disabled. Exercise channel swap, clipping, xrun, removal, clock change, processed-monitor failure, cancellation, crash reconciliation, and deterministic export. The receipt proves only that exact musical host route, not generic speech, timed editions, live Jam, cloning, or other hardware.
---
title: "Music"
plain_name: "Riffmaw: composing and mixing"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/music/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/music/
---
# Music (Riffmaw: composing and mixing)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw develops material into an arrangement, mix and master: composing with models or humans, lyrics and sung language, live answer latency classes, autonomy levels, and mixing and mastering.
**Why it matters:** Read when building music generation, arrangement, mixing or mastering logic, or deciding how autonomous production may be.
- Finish levels: assets only, assisted session, or autonomous master candidate; your acceptance is always separate.
- Live accompaniment declares a latency class: inline DSP, streaming, scheduled (near-live) or offline.
- Lyrics, prompt language, sung language and interface language are separate inputs.
**Status:** Designed
## Original text (Hexanomicon)
A guitar phrase can become the center of an arrangement, a reference for an accompaniment, or material the producer decides to leave alone. Music keeps that choice editable through generation, performance, composition, sampling, signal processing, and DAW work.
## Compose and arrange
`riffmaw.forge_track@2` pins brief, sources, `FeelProfile@1`, target form, budget, and acceptance. A model may propose motifs, harmony, rhythm, timbre, sections, or complete sketches; a human performance or another method can answer or replace them. Each artifact retains tool/provider revision, controls, seed where available, source influence, input/output digests, and cost.
Describe how the music should move and how its parts should answer one another in `FeelProfile@1`. It can begin as direction or derive from correctable take/[jam](sessions.md#jam-in-shared-time) observations about pocket, density, attack, space, motion, instrumental relation, tension/release, and when the machine should listen. Corrections create linked immutable revisions; they cannot establish the performer's unspoken intent.
The Magus uses that direction to select structure, tempo map, meter, key/tuning, roles, transitions, repetition, and variation. A generated sketch remains a candidate for those choices.
## Language belongs to the musical request
Brief language, structured-description language, lyrics, requested sung language, and phonetic/transliteration aids are separate typed inputs. Preserve original words. An exact Translation Spell can propose a lexical derivative; Riffmaw owns lyric adaptation and musical fit, keeping author, implementation, rhyme, metre, pronunciation, and meaning-loss findings. A generator's favored prompt language cannot replace approved lyrics.
Each exact music profile separately proves description understanding, lyric rendering, pronunciation, structure tags, mixed-language behavior, and instrumental mode. Neither Altar locale nor Persona language selects these fields. Optimized lyrics are another authored candidate.
Singing, rap, and musical spoken word remain here. [Language Edition](../language-edition/) owns dialogue, narration, spoken replacement, and captions within a source-aligned timed-language edition. A translated song keeps Riffmaw's lyric/performance revisions while the edition keeps source alignment, captions, fit, and packaging; exact words, timing, performance, and findings cross the seam.
## Answer and develop
An admitted jam may request accompaniment, counterpoint, percussion, harmony, texture, effects, or transitions from a recent performance window, submix, MIDI, cue, or FeelProfile. Preserve both scheduled and actual entrances. The request chooses an honest latency class:
| Class | Contract |
| --- | --- |
| **Inline DSP** | Bounded processing inside a proved realtime-safe host; no model or control-plane wait enters the audio callback. |
| **Streaming player** | A model emits playable increments under a measured buffering and deadline contract. |
| **Scheduled player** | Riffmaw prepares a phrase, bar, or section ahead and fences its future entrance against the mapped musical clock. |
| **Offline producer** | No live deadline; generation and revision occur only after the captured session is frozen. |
Phrase- or bar-ahead scheduling is **near-live**. Symbolic MIDI into a deterministic synth is the first proposed Linux road before any claim of sample-continuous generated audio. After capture closes, frozen artifacts may enter slower comping, tempo-map editing, bounded repair, extension, supporting layers, arrangement, or mix. Returning to performance requires a newly armed jam.
## Production autonomy
The request pins its permitted finish:
| Finish policy | Riffmaw may do | Required return |
| --- | --- | --- |
| **`assets_only`** | Generate, capture, separate, clean, align, label, and package reusable musical material. | Dry and processed assets, stems where available, observations, and lineage; no implied mix approval. |
| **`assisted_session`** | Also arrange, route, automate, process, and render one or more proposed mixes. | Editable production plan and session state, stems, candidate mixes, findings, and unresolved choices. |
| **`autonomous_master_candidate`** | Also select bounded candidates, repair failed regions, mix, master, run deterministic gates, and repeat within budget. | A master candidate satisfying its automated gates, stems and receipts, or the exact criteria and budget that prevented completion; Magus acceptance remains separate. |
Before the loop, declare candidate count, wall time, compute, paid cost, similarity risk, loudness, repair attempts, and stopping policy. A planner can direct admitted generators, analyzers, editors, renderers, effects, and mastering tools, using deterministic probes and bounded listening judgments for the next revision. Budget exhaustion returns permitted attributable candidates/findings, never a relabeled master.
These policies cannot arm capture, authorize payment/Portal egress, admit a plug-in, export, accept, or publish. A failed binding settles before an exact predeclared branch or new Invocation tries another road; the Resolution Lock never changes mid-casting.
## Edit, mix, master
Comping, timing, tuning, cleanup, resampling, and destructive processing retain parent revisions. The mix records routing, gain, pan, automation, effects, spatial relation, and balance among instrumental, vocal, sampled, and processed elements. Stems export those relationships rather than become independent masters.
Mastering works toward declared loudness, peak, dynamics, sample rate, format, and sequencing targets. Keep score/MIDI where present, edits/session lineage, stems, mix, and master attributable so the reviewer can trace the result. Probes establish measurable fit; listening review decides musical fit.
Record each operation that produced the result separately. Generation, DAW export, and plug-in renders are separate effects. If an acknowledgement is lost, retain **unknown** until the provider, session, or destination reconciles it. Failed profiles, similarity uncertainty, stale inputs, or exhausted repair return findings/refusal.
Music returned with video still needs Riffmaw's judgment. Before the `VideoJob@2` began, its `MediaFacetAuthoritySet@1` must have declared `music`, `riffmaw.music` revision `2`, and the exact request digest. After Prism settles the technical attempt, Riffmaw issues `SemanticFacetAdmissionReceipt@1` over music/compound digests, use, rights, evidence, findings, and disposition. Labels, demux, and undeclared sound cannot supply that musical acceptance.
[Package](package.md) seals accepted work. [Sync](sync.md) exposes exact musical events to another craft.
---
title: "Studio"
plain_name: "Riffmaw: production tools"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/studio/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/studio/
---
# Studio (Riffmaw: production tools)
## Plain-English summary (Snayu)
**What it is:** The production loop and the replaceable tool roles (planner, generator, analyzer, renderer, live host, mastering and so on), plus a dated map of candidate tools like MiniMax Music 3, DawDreamer and PipeWire.
**Why it matters:** Read when choosing or integrating music tools, models or audio libraries for Riffmaw.
- A neutral production plan drives tools; it is never executable code or a DAW session.
- The candidate map (reviewed 2026-08-26) lists selection inputs, not delivered integrations.
- First proofs: offline render with one music model, then a separate live-graph proof.
**Status:** Designed. Tool roles and candidates are planned; no production integration delivered.
## Original text (Hexanomicon)
A production plan might call for a new bass layer, a dry guitar print, a changed transition, and a candidate master. Each need belongs to a different tool role. Studio keeps those roles replaceable while Riffmaw retains the music, its acceptance, and its recoverable history.
## Closed-loop production
```text
brief + admitted sources + takes or jam
→ MusicProductionPlan@1
→ generate, capture, or separate candidates
→ analyze musical and measurable facts
→ arrange and render a multitrack revision
→ mix and master under declared targets
→ listen, measure, accept, repair, or stop
→ assets, editable session handoff, or MusicAssetBundle@1
```
For each iteration, name the parent material and charge one bounded attempt. Accepted sources and takes remain unchanged, so a proposed repair can be compared with the work it seeks to improve. Keep model ranking, measured facts, and Magus acceptance distinguishable throughout. [Music](music.md#production-autonomy) explains which finishes and repairs the request permits.
[Sessions](sessions.md#the-realtime-stopping-line) follows live deadlines and epoch recovery against `ClockDomainMap@1`. The Scroll owns execution and termination; the plan owns musical direction. Once Jam closes, its accepted captured material can enter a slower offline Invocation.
## Production roles
| Role | Owes Riffmaw | Does not own |
| --- | --- | --- |
| **Planner** | A versioned `MusicProductionPlan@1` containing creative form, track roles, desired source placements, prompts, edits, and acceptance criteria. | Executable topology, implementation choice, budgets, grants, checkpoints, retry, cancellation, or stopping law; the exact Scroll and Resolution Lock own those. |
| **Generative processor** | Music, continuation, variation, cover, repaint, conversion, production-effect, or separated-source artifacts from an exact engine and model profile with controls and receipts. | Arrangement acceptance, authorship judgment, native-stem claims, or the production session. Speech synthesis enters through Echo's admitted `tts` contract; dialogue within a source-aligned timed-language edition remains [Language Edition](../language-edition/) work. |
| **Analysis worker** | Attributed tempo, beat, onset, pitch, chord, section, similarity, loudness, clipping, and quality observations with uncertainty. | Creative approval or permission to transform its source. |
| **Offline studio renderer** | A pinned timeline and processing graph with tracks, clips, MIDI, routing, automation, processors, intermediate renders, node captures, and master buses. | Capture, live monitoring, creative mix decisions, the brief, source rights, performer consent, or publication. |
| **Live graph and monitor host** | A realtime-safe audio graph, device and route lifecycle, direct monitoring, latency and xrun evidence, output fence, and emergency bypass. | Model planning, recording permission, or a promise that remote peers are sample-locked. |
| **Timebase coordinator** | Explicit mappings among sample frame, monotonic time, musical beat and bar, MIDI or network tempo, epochs, clock-rate divergence, and uncertainty. | Authority to retime an accepted performance or treat tempo phase as audio transport. |
| **MIDI connector and machine-player scheduler** | Attributed MIDI/UMP events and deadline-fenced future audio or MIDI entrances against one clock epoch. | Permission to read arbitrary devices, admit SysEx, or emit stale responses. |
| **Capture writer** | Immutable pre-fader audio, MIDI and discontinuity manifests without blocking the realtime callback. | Analysis, transformation, retention beyond the admitted policy, or the canonical session record. |
| **Remote-jam transport** | Authenticated audio/MIDI carriage, codec and jitter state, latency, loss, clock-rate divergence, reconnect epochs, acknowledgements, and local-monitor policy. | Recording consent, a shared sample clock, or Composition authority. |
| **DSP and instrument host** | Allowlisted processor binaries, instruments, presets, ports, automation, latency compensation, tails, crash isolation, safe bypass, state, and rendered output. | Ambient plug-in discovery or silent substitution of a missing processor. |
| **Mastering worker** | A target-bound final processing revision and measurable loudness, peak, dynamics, stereo, sample-rate, and format facts. | Musical acceptance merely because numerical targets passed. |
| **Media utility** | Bounded decode, encode, resample, trim, join, metadata, waveform, and conformance operations. | Semantic interpretation or application finish. |
| **Human DAW projection** | Portable assets, tempo and marker maps, automation or mix notes, and enough lineage to continue manually. | The canonical Riffmaw record or authority to mutate it behind the handoff. |
These tool roles act on `MusicProductionPlan@1` as a neutral creative record. At each pinned placement, the exact Spell implementation compiles only the admitted creative fields into its tool dialect. The plan itself does not become executable Python, a Scroll, a DAW session, or a provider request.
If an implementation fails, settle that attempt first. Another declared exact branch or a forward Invocation may then try different craft. This preserves the current Resolution Lock instead of silently changing the tools underneath the same casting.
A human handoff must name what can be continued: portable assets, MIDI, maps, processing receipts, and notes. It must not promise lossless plug-in/automation round trips merely because two programs can open a project format.
## Current candidate map
The following ledger retains the study reviewed **2026-08-26**. Its dated observations are selection inputs, not delivery or promotion receipts. Before a trial, each candidate still needs licence admission, exact engine/model profile where applicable, pinned Rune, hardware/latency measurements, hostile-input bounds, fixtures, restart behavior, and a bake against the role above. Fast-changing availability and APIs must be checked again at selection time.
| Candidate | Candidate office | Present reading |
| --- | --- | --- |
| [audio.cpp](https://github.com/0xShug0/audio.cpp), evaluated at `0.5` | Inference engine for music-generation and separation profiles | Local route for explicitly supported ACE-Step, Stable Audio, Demucs and RoFormer families. A Riffmaw profile admits only proved musical operations; server API and pipelines remain experimental, loaded sessions live until process exit, and Apache-2.0 runtime terms do not admit a model's weights. Keep exact families in isolated, lifecycle-reclaimable workers. |
| [MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) | Offline generative-processor model profile | Direct long-form song candidate conditioned on lyrics plus a detailed music description. The upstream card exposes SGLang-Omni and Diffusers routes; the [Comfy-Org pack](https://huggingface.co/Comfy-Org/MiniMax-Music-3) supplies a ComfyUI-shaped route. Each pack, component, structured-caption transform, language, duration, precision, offload plan, cancellation behavior, and licence closure needs an exact bake; no route becomes Riffmaw truth or speech TTS. |
| [MiniMax hosted Music Generation](https://platform.minimax.io/docs/api-reference/music-generation) | Portal generative-processor candidate | A separate provider API currently names `music-3.0` and accepts prompt plus lyrics. It is not presumed byte-, model-, output-, or policy-equivalent to the open-weight Music 3 profile. The provider's August 2026 notice restricted paid Music/Lyrics API access to existing paying users from August 20 and announced discontinuation of the free music APIs. Recheck eligibility and terms before every trial; no local failure may replay here automatically. |
| [DawDreamer](https://github.com/DBraun/DawDreamer) | Isolated offline renderer and DSP/instrument host | First candidate for processor DAGs, audio and MIDI, timing, automation, VST and FAUST, and simultaneous graph-node captures. It is GPLv3 and Alpha, has no capture or live-jam contract, and emits no persistent human-editable DAW session; its “stems” are selected graph outputs. |
| [FFmpeg](https://ffmpeg.org/) | Media utility and conformance probe | Conversion, resampling, channel, packaging, and two-pass loudness-normalization route when the exact binary, build flags and sample format are pinned. Target compliance is not mastering judgment. |
| [librosa](https://github.com/librosa/librosa) | Initial analysis library | ISC-licensed first route for a bounded tempo and onset proving fixture. It is an analysis implementation, not a realtime clock or production decision-maker. |
| [PortAudio](https://www.portaudio.com/) with [python-sounddevice](https://github.com/spatialaudio/python-sounddevice) | First bounded capture worker | Small first route for one explicitly armed audio take. It does not supply the multiclient graph, musical clock, remote jam, or full studio session. |
| [PipeWire](https://pipewire.org/) with [JACK](https://jackaudio.org/) compatibility | Live graph, MIDI and monitor host candidate | Linux route for low-latency ports, links, MIDI, transport, latency and xrun evidence. It is host infrastructure rather than another inference engine and still needs a Riffmaw capture, epoch and output-fence adapter. |
| [Ableton Link](https://github.com/Ableton/link) | Optional LAN tempo and phase bridge | Provides musical tempo, beat and phase agreement. It is not audio transport, recording consent, or sample-clock authority. |
| [JackTrip](https://jacktrip.github.io/jacktrip/) | Remote-jam transport candidate | First research-bake candidate for low-latency network audio. Authentication, encryption, jitter, recording consent, clock-rate divergence, failure and local monitoring remain Riffmaw admissions rather than consequences of connection. |
| [DAWproject](https://github.com/bitwig/dawproject) | Neutral human-handoff candidate | MIT interchange schema for project structure and device state where a target DAW supports it. Canonical handoff remains raw and rendered assets, MIDI, tempo and markers because not every workstation round-trips the format. |
| [Essentia](https://github.com/MTG/essentia) | Optional broad analysis worker | Broad MIR coverage, but the open path is AGPLv3, commercial alternatives exist, and upstream learned-model terms can be non-commercial or no-derivatives. Do not make it the default first dependency. |
| [Matchering](https://github.com/sergree/matchering) | Watched reference-guided final processor | GPLv3 optional reference treatment whose latest packaged release is old. It matches one target's measurable spectrum, level, peak and stereo properties to a reference; it neither mixes stems nor proves musical mastering quality. |
| [Ardour](https://ardour.org/) | Human DAW and watched mature renderer | FOSS workstation for capture, sessions and stem export. Lua, OSC and `libardour` utilities deserve a later bake, but headless/API parity with complex GUI editing is not promised and arbitrary plug-ins are not sandboxed. |
| [Diff-MST](https://github.com/sai-soum/Diff-MST) | Ineligible research reference for automatic mixing | Predicts interpretable reference-conditioned gain, pan, EQ and compression, but has no stable package or API and its code is CC-BY-NC-SA. It cannot enter the FOSS Core path under the present policy. |
| [ACE-Step DAW](https://github.com/ace-step/ACE-Step-DAW) | Design reference | Its sequential “LEGO” generation and scriptable browser state resemble Riffmaw's desired loop, but it is an AGPL WIP browser/Tone.js application with IndexedDB state, no releases, and no versioned remote agent contract. |
## Minimum first proofs
[Workbench](workbench.md) records the agent/human edit-render-listen requirements and finite
engineering-worker plan. That trial supplies technical recipes and receipts; native application
admission, Comfy Soulstone management, musical acceptance and Jam keep their separate proofs.
Start the proposed offline proof by choosing one baked music profile. The dated study selects MiniMax Music 3 through an immutable allowlisted ComfyUI preset as the first long-form candidate, with `audio.cpp` as the alternative family road.
The rest of the proof must cover the other production roles: a separated-source profile, isolated DawDreamer with allowlisted processors, pinned FFmpeg, librosa tempo/onset probes, and a LychD sample-accurate compiler that turns creative plan placements into the exact render graph.
That proof may establish `assets_only` and bounded `assisted_session`. Its human return is stems, MIDI, tempo/markers, processor receipts, and mix notes—not a native DawDreamer project. Add PortAudio only for the separate armed-take proof.
The live proof starts again from its own contract: PipeWire/JACK graph and clock evidence, MIDI scheduling, capture writer, output-deadline fence, then a machine player. Scheduled symbolic MIDI precedes any realtime ACE-Step audio claim. Remote Jam and automatic mix control remain later bakes. New tools enter only when they close a missing musical role.
---
title: "Workbench"
plain_name: "Riffmaw: build plan and probes"
section: "Compositions > Creative Works > Riffmaw"
status: "Partial"
original: https://hexanomicon.dev/compositions/riffmaw/workbench/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/workbench/
---
# Workbench (Riffmaw: build plan and probes)
## Plain-English summary (Snayu)
**What it is:** The construction plan for an edit-and-listen music loop, plus a working offline engineering tool: render bounded recipes through DawDreamer, audition them, make guarded edits, and probe a local ComfyUI server.
**Why it matters:** Read before contributing to Riffmaw code; it explains what you can run today and the next native steps.
- A development runner (scripts/music_probe.py) validates, renders, auditions and edits recipes outside the server.
- A ComfyUI probe pins workflows, keeps unknown submissions unknown and never blindly retries.
- Still missing: native app, database records, registered workflow, studio UI and live input.
**Status:** Partial. Offline render and Comfy probes work; native music app not built.
## Original text (Hexanomicon)
An agent and a musician should be able to make a short arrangement, hear it, change notes or
instrument parameters, compare versions, and recover the selected work. This construction plan
starts with a finite offline worker and a local ComfyUI probe. It creates no new Composition.
## Ownership and requirements
Riffmaw owns musical plans, arrangement revisions, instruments, candidate mixes, listening judgment
and musical acceptance. Atelier retains visual commissions, candidates, accepted revisions and
bundles. A future shared view may audition exact settled visual references alongside music.
Broadcast retains final audiovisual placement and acceptance. Coordinating several owners' live
Invocations requires a separately admitted Suite. The unresolved cross-craft project lifecycle
remains explicit in [Products and Suites](../products-and-suites.md#atelier-riffmaw-language-edition-and-broadcast).
| Requirement | Observable acceptance |
| --- | --- |
| One musical meaning | Preview identifies its exact recipe; export uses the same recipe and backend. |
| Shared authoring | Agent and human eventually use identical typed operations; stale expected revisions refuse and earlier state remains recoverable. |
| Editable material | Notes, clips, gain, pan and admitted instrument controls survive save/reload. Generated stereo audio remains a source, not invented synth tracks or native stems. |
| Attributed output | Recipe, source, implementation, engine, processor and output digests accompany each candidate. |
| Correct cache | Every relevant input enters the key; incomplete or corrupt output never counts as a hit. |
| Bounded generation | One operator-reviewed immutable Comfy API workflow pins nodes, models, mutable inputs, output nodes and formats. |
| Honest interruption | Lost submit acknowledgement remains indeterminate; reconciliation queries the same identity without blindly repeating generation. |
| Separate judgment | Technical success and numerical checks never imply musical, visual, editorial or publication approval. |
| Preserved custody | Private sources, working files and generated media stay outside the checkout; bounded descriptors and verified digests determine consumed bytes. |
## Approachable interaction
Riffmaw should let a musician make small changes without DAW expertise, using simple controls or
ordinary-language requests such as “add a little reverb” or “turn this part down.” The longer-term
direction is an assistant that can listen to admitted takes or mixes when helping shape the music,
and eventually hear and respond during live playing. Live interaction follows the separate
[capture and Jam contracts](sessions.md#the-realtime-stopping-line).
The interaction follows a small loop: name the part and desired change, prepare a candidate,
hear it against the selected version, then keep, revise or discard it. A request such as
“turn the bass down” and the corresponding track control use the same typed edit and revision
rules. The response identifies the changed part and the version available to hear. Earlier work
remains available for comparison.
AI assistance may interpret a brief, propose a bounded edit or compare candidates. An unclear
target needs clarification; an unavailable effect returns a finding rather than a claim that
it was applied. Listening observations retain their source and uncertainty. A rendered WAV or a
loudness measurement alone does not establish that an assistant listened to the music.
## Next bounded increments
Keep the first native increment focused on one short edit-and-listen task:
1. Connect the existing finite worker to a native musical revision and candidate. A human and
agent must see the same revision, apply one guarded change, hear the exact result, and recover
the candidate after restart. The authoring, admission and custody requirements in
[Native implementation stages](#native-implementation-stages) still apply.
2. Add one ordinary-language edit over those same typed operations. Show the affected track or
region and the proposed change; preserve comparison and the musician's selection.
3. Qualify one generation or separated-source profile for a concrete musical task, then connect
its verified output to the same revision-and-listening loop. Keep the exact tool and model
proof with [Studio](studio.md#minimum-first-proofs).
Choose a Rust component only when a measured DSP, timing or device requirement needs it. The
first feedback loop can use the existing Python adapters and offline renderer. Capture and live
Jam retain their separate proofs; they are not prerequisites for this offline increment.
## Construction decision
Python owns validation, compilation, adapters and technical receipts. The first offline trial
uses DawDreamer with finite source-owned FAUST instruments, following the dated
[Studio map](studio.md#current-candidate-map). Optional development dependencies stay separate
from Vessel dependencies. A bounded subprocess isolates the native library from the trusted
Vessel; imported plug-ins, arbitrary DSP programs and ambient discovery are excluded.
SuperCollider remains a candidate for a later measured live/offline proof, not an automatic
fallback or second interpretation of the recipe. Rust may supply a demonstrated missing DSP or
timing component. Neither choice establishes compatibility or realtime delivery by itself.
## Finite engineering worker
Give the worker an immutable, schema-versioned technical recipe describing bounded notes, PCM
sources, clip frames, gain, pan and admitted synth controls. It returns aligned stems, a candidate
mix, format/peak observations and digest receipts. This recipe JSON describes the finite trial;
it is not executable Python, a Scroll, `MusicProductionPlan@1`, or a canonical native project.
Admission bounds tracks, events, frames, bytes and process time. It permits at most 32 concurrent
events and uses a conservative graph-buffer estimate, though native RSS has no cgroup limit.
Unsupported formats or missing processors refuse rather than silently substitute. The source-owned
trial instruments make no production-quality claim.
An operator development runner can exercise this mechanism without the Vessel, a background
service, a new public Pulse command, or invented Run/Invocation identities. External workspaces
hold immutable probe inputs and technical receipts. These are not a shadow Phylactery and claim
no native musical state, acceptance, scheduling or Composition recovery.
Comfy is a separate finite external-engine attempt. Its profile pins a literal local endpoint,
classic-server dialect, workflow digest, reviewed node-class declarations, declared model digests,
mutable input openings and expected outputs. Those declarations do not attest runtime closure or
verify the server's loaded model files. Persist exact probe/request identity before submit and
the acknowledged provider identity before retrieval. Music and visual outputs name their
separate intended receiving owners; the
adapter supplies technical results and cannot commission or accept another owner's work.
Client-supplied UUIDs establish correlation, not proven atomic submission replay. Targeted
cancellation is deployment-dependent; the probe must not globally interrupt a shared service.
Empty history never proves no submission occurred. Verify the exact
[classic routes](https://docs.comfy.org/development/comfyui-server/comms_routes) and runtime before
a real model trial. HTTP acknowledgement alone does not establish containment or useful output.
Once fetched, bytes become immutable for that occurrence. Repeating retrieval verifies and reuses
the retained files; if a later file fails, preserve the earlier files and their technical receipts.
To publish a file, first retain deterministic staging and pin its digest, then install the final
file. An interruption after the pin can be repaired from that exact local stage. Normal load
still refuses a missing final file. Unpinned staging, lost or damaged bytes, and conflicting final
files refuse and require manual reconciliation. Repair cannot replace bytes from the server or repeat
generation. Even a matching extension and digest cannot establish that the bytes are a valid
image, video or audio format.
## Development operations
Install the optional profile using
[Contributing](https://github.com/hexanomicon/lychd/blob/main/CONTRIBUTING.md). Choose an absolute,
operator-owned workspace outside the checkout, then use the source development runner:
```bash
uv run --locked --group music-probe python scripts/music_probe.py schema recipe
uv run --locked --group music-probe python scripts/music_probe.py demo --output /absolute/work/recipe.json
uv run --locked --group music-probe python scripts/music_probe.py validate /absolute/work/recipe.json
uv run --locked --group music-probe python scripts/music_probe.py render /absolute/work/recipe.json --workspace /absolute/work
uv run --locked --group music-probe python scripts/music_probe.py audition /absolute/work/recipe.json --workspace /absolute/work --output /absolute/work/audition.html
uv run --locked --group music-probe python scripts/music_probe.py edit /absolute/work/recipe.json --expected-digest DIGEST --track bass --cutoff 900 --output /absolute/work/variant.json
```
`edit` requires the digest returned by `validate`, preserves the earlier recipe and refuses to
overwrite the destination. `render` uses only finite sine, saw and kick programs, gain/pan/lowpass,
and non-stretched PCM clips. Import exact mono/stereo 16/24/32-bit integer WAV at the recipe rate
as `assets/SHA256.wav`; no resampling or arbitrary plug-in loading occurs. Its receipt points to
`renders/CACHE_KEY/`, containing the mix and aligned stereo 16-bit WAV stems. Independently
quantized stems and mix can differ by integer rounding when summed. Peaks above full scale refuse.
`audition` renders or verifies the same exact recipe and writes a standalone read-only timeline
with mix/stem selection and playback. It embeds verified PCM bytes, with a separate 20 MiB media
ceiling, and makes no network requests. Seeking is a browser listening aid, not a realtime clock
proof or musical edit. Controls remain typed recipe edits through the runner; this preview is not
the native studio editor.
A cache hit must identify the same computation. The key binds exact recipe, processor,
renderer/model source, installed DawDreamer/NumPy executable artifacts, their versions and runtime
platform. Repeats on that pinned runtime are verified; cross-platform bit identity is not promised.
Publication uses exclusive hard links, fsync and a receipt committed last. Interrupted or incomplete
entries refuse, under the assumption that directories are stable and operator-owned rather than
hostile mutable mounts.
Execution has its own stopping checks. A 30-second child deadline bounds native execution, followed
by a separate one-second cleanup budget to kill the owned process group and observe its stopped
state through Linux `/proc`. Unavailable or unresolved observation refuses completion. Descendants
that escape into a new session are outside that check, so the worker establishes process separation
rather than Coffin containment.
`schema comfy-profile` and `schema comfy-request` expose the actual Comfy inputs. Supply reviewed
profile and request files, then run `comfy prepare --profile PROFILE --request REQUEST --workspace
WORKSPACE`. `comfy attempt submit UUID --profile PROFILE --workspace WORKSPACE` crosses the submit
fence once; later `reconcile` queries the same occurrence and `fetch` retains its reviewed outputs.
The workspace must already exist. After interrupted file installation, `comfy attempt repair UUID
--profile PROFILE --workspace WORKSPACE` verifies pinned staging and installs only matching bytes.
It makes no HTTP requests, leaves receipt identity unchanged, and can be repeated. A pre-pin stage
blocks further fetching until manually reconciled; old receipts whose bytes were lost cannot be
repaired by this command. No live profile, model, server launch or MiniMax generation is supplied
by these commands. Unknown submission stays unknown; cancellation refuses.
## Native implementation stages
The complete native application still needs these boundaries after the worker proof:
1. Riffmaw musical authoring and immutable edits in PostgreSQL, including concurrent-edit,
request replay, retention and restart rules.
2. Owner-qualified Composition/Pattern publication, typed RunEngine admission, exact tool or
capability binding, durable attempts and admitted media custody.
3. One local Comfy music profile proved against the operator's blueprint, exact model/workflow,
formats, cancellation and restart behavior.
4. A static Svelte view over the same APIs: tracks, timeline, note/clip editing, knobs, waveforms,
audible revision, candidate comparison, job status and explicit musical selection. Litestar
retains authorization, mutation and persistence.
5. Exact settled visual-reference audition and owner-qualified handoffs. Live cross-owner
production, final audiovisual editing and cross-craft undo retain their own owners.
Keyboard/MIDI input, guitar capture, direct monitoring and Jam require separate arming,
clock/route epochs, measured latency, dry takes, xrun evidence and stale-output fences. Offline
playback proves none of those. Paid fallback, arbitrary workflows/plug-ins, autonomous acceptance
and publication are outside this worker trial.
## Acceptance evidence
Retain audible synthesis/import proofs, source trims, aligned stems/mix, deterministic repeats on
the pinned runtime, changed-control and corrupt-cache negative controls, bounded malformed
inputs, cleanup and subprocess interruption. Comfy protocol tests must cover unknown submission,
changed workflow/input rejection, output bounds, empty history and cancellation refusal. Such
tests do not prove real generation or musical quality. A four-bar 145 BPM recipe has rendered
211,862 frames at 32 kHz through DawDreamer 0.9.0 on the development host, with kick/bass/lead stems
and a mix. The changed bass-control recipe and repeat cache are separate technical proofs.
A model receipt follows only after the
blueprint and exact profile are available. [State](../../state-of-the-work.md#composition-portfolio-delivery)
keeps worker, native application and live evidence separate; the
[engineering probe record](../../state-of-the-work.md#music-comfy-engineering-probes) owns this subset.
---
title: "Voice boundary"
plain_name: "Riffmaw: vocal boundary"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/voice/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/voice/
---
# Voice boundary (Riffmaw: vocal boundary)
## Plain-English summary (Snayu)
**What it is:** Explains which vocals Riffmaw owns (singing, rap, musical spoken word, harmonies) and which belong elsewhere, and how performer consent and lyrics are bound to takes.
**Why it matters:** Read when a feature involves voices, to decide whether Riffmaw, Language Edition or Voice (Echo) owns it.
- Consent for one take does not authorize cloning or new words.
- Dialogue, narration and captions belong to Language Edition; speech operations to Voice (Echo).
- A transcript can observe a performance but cannot certify lyrics or musical fit.
**Status:** Designed
## Original text (Hexanomicon)
A sung phrase belongs to its arrangement; a later spoken line needs a different admission. Riffmaw owns singing, rap, musical spoken word, harmonies, and other vocal parts judged as music, without becoming a generic voice-pack or spoken-media owner.
Admit the take under approved lyrics, language/pronunciation assumptions, direction, musical role, timing, and acceptance criteria; `riffmaw.capture_take@2` returns `PerformanceTake@1` under those conditions. Through raw takes, comping, tuning, cleanup, generation, and tone changes, preserve parents, performer/model identity, controls, influence, cost when applicable, and digests. Review that history with the performance before accepted work enters `MusicAssetBundle@1`. A transcript can observe the performance but cannot certify its lyrics, pronunciation, or musical fit.
One take's consent authorizes neither cloning nor later words. Performer authority binds identity, lyrics, purpose, audience, territory, duration, transformations, disclosure, and revocation. Impersonation, concealed synthesis, unapproved words, or ambiguous authority returns review, replacement, or refusal.
[Language Edition](../language-edition/) owns dialogue, narration, spoken replacement, and captions within a source-aligned timed-language edition. [Echo](../../sepulcher/extensions/echo.md) retains speech capture/transcription/synthesis/cloning/delivery/playback facts. [Avatar](../avatar/index.md) may select an exact eligible vocal or acoustic-voice reference for a presentation without gaining new-word synthesis or publication permission.
[Sessions](sessions.md) follows the armed take; [Package](package.md) seals accepted music. Return to [Riffmaw](index.md).
---
title: "Sound boundary"
plain_name: "Riffmaw: sound-effects boundary"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/sound/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/sound/
---
# Sound boundary (Riffmaw: sound-effects boundary)
## Plain-English summary (Snayu)
**What it is:** Explains that sound belongs to whichever app judges its intended role: musical textures and effects to Riffmaw, picture-bound effects to Broadcast, game sound to Foundry.
**Why it matters:** Read when deciding where a sound effect or texture feature should live.
- Riffmaw accepts sound used inside composition, arrangement or mix.
- Shared codecs, plug-ins or generators do not transfer ownership.
- No app currently owns standalone reusable sound packs; Riffmaw publishes none.
**Status:** Designed
## Original text (Hexanomicon)
The same noise can be a musical texture in one work and room tone under a film scene in another. The intended role determines who judges it.
Riffmaw accepts instrument/vocal processing, designed timbres, samples, transitions, textures, and effects inside composition, arrangement, or mix. Sources, tools, transforms, rights, parameters, and digests stay attached. A technically clean waveform can still fail the musical purpose.
[Broadcast](../broadcast/sound.md) owns picture-bound effects, foley, room tone, environmental beds, and ambience judged against exact picture, timebase, event, place, material, distance, perspective, and continuity. Other application sound stays with its consuming Composition. A common codec, plug-in, generator, or DAW does not transfer that judgment.
A reusable standalone sound pack needs a judgment beyond one musical or picture-bound use. No accepted Portfolio owner currently supplies it. A future Composition must prove its independent records, acceptance, recovery, and consumers. Until then, Riffmaw publishes no standalone sound-pack Pattern, and unexplained library material or provider-returned sound must remain attributed candidates.
Continue with [Music](music.md) for a musical use, or return to [Riffmaw](index.md).
---
title: "Sync"
plain_name: "Riffmaw: music cue maps"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/sync/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/sync/
---
# Sync (Riffmaw: music cue maps)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw publishes a MusicCueMap: exact musical events (drops, sections, entrances) on a declared timebase that visual or editing apps can respond to without editing the music.
**Why it matters:** Read when syncing visuals or edits to music, or handling retimes that make cues stale.
- Each cue points to an exact music bundle revision and source region.
- Consumers request a new map instead of editing Riffmaw's map.
- A retime or changed master makes the map stale; a new revision is created.
**Status:** Designed
## Original text (Hexanomicon)
The drop at one exact point in a master can invite a visual answer. Sync makes that musical event available without choosing the camera, image, animation, cut, or editorial claim that answers it.
`riffmaw.prepare_music_cue_map@1` creates `MusicCueMap@1` under a declared timebase. Events, ranges, intensity, continuity, entrances/exits, accents, transitions, and uncertainty each point to an exact `MusicAssetBundle@1` revision and source region. Beat grids, sections, vocal/instrumental entrances, and synchronization anchors remain musical evidence.
[Atelier](../atelier/motion.md) judges visual response; [Broadcast](../broadcast/edit.md) places it in the final timeline. Dialogue replacement belongs to [Language Edition](../language-edition/); picture effects and ambience have Broadcast cues. Consumers request a successor instead of editing Riffmaw's map.
[Kinesis](../../sepulcher/extensions/prism/kinesis.md) may use the exact map in admitted `synchronize` or constrained-generation work. Its new motion derivative keeps music digest, clock relation, anchors, and uncertainty without rewriting the map or deciding creative acceptance.
A retime, frame-rate conversion, shorter master, or changed mix may make the map stale. Reject a mismatched digest/timebase and create a new map revision while preserving the earlier relation as history. Timing-only changes stale dependent synchronization approvals; changed source revisions, consent, or use boundaries must still follow each owner's invalidation rules.
Consumers then judge successors against the new exact references. A shared studio control may propose these related changes together, but each owner retains its accepted records and judgment of the successor.
An audiovisual Suite may coordinate exact music, visuals, and cues. It owns the coordination's aggregate ceilings, correlation, and partial settlement under [Workflow](../../adr/28-workflow.md). Members retain their files, provider sessions, creative approvals, domain budget judgment, Sigils, and publication authority.
---
title: "Package"
plain_name: "Riffmaw: sealed music bundle"
section: "Compositions > Creative Works > Riffmaw"
status: "Designed"
original: https://hexanomicon.dev/compositions/riffmaw/package/
guide: https://lychd.snayu.ai/docs/compositions/riffmaw/package/
---
# Package (Riffmaw: sealed music bundle)
## Plain-English summary (Snayu)
**What it is:** How Riffmaw seals accepted music, stems, mixes and masters into a MusicAssetBundle for other apps, and how it handles effects, recovery, revocation and deletion.
**Why it matters:** Read when building the music handoff to Broadcast or Foundry, or its restart and deletion behaviour.
- The bundle carries checksums, sources and target profiles, but no credentials or publishing permission.
- A lost write acknowledgement stays unknown and is reconciled before retrying.
- Separated-source stems are labelled as estimates, distinct from native or rendered stems.
**Status:** Designed
## Original text (Hexanomicon)
A master arrives with stems, credits, findings, and enough lineage to understand how it was made. `riffmaw.forge_music_bundle@2` seals accepted composition, instrumental/vocal performances, production effects, stems, mix relationships, and masters into `MusicAssetBundle@1` with target profiles, checksums, and exact source revisions.
A compound model-native layer also retains its compound digest and Riffmaw-issued `SemanticFacetAdmissionReceipt@1`. A visual, timed-language, picture-sound, or world-sound receipt cannot substitute for musical judgment.
## Handoff and authority
Broadcast or Foundry independently admits the exact digest, role, format, timing, rights, findings, and approval for its purpose. The bundle carries no Sigil, secret, provider/DAW session, capture permission, performer consent for another use, dialogue/picture-sound authority, editorial placement, or publication permission.
Capture, paid generation, DAW export, and handoff remain separate effects with exact request digests/receipts. A destination may have written bytes before acknowledgement disappeared. Keep that outcome **unknown** and reconcile the write before another attempt.
To resume interrupted work, resolve the exact source, feature, Pattern, model, plug-in, session, edit, mix, and export revisions. Recovery needs that chain to distinguish completed output from a new attempt. Takes, rejects, indexes, works, stems, masters, and handoffs keep independent retention.
Revocation or an invalid source makes dependent work stale while preserving its history. Deletion begins by stopping capture/indexing, then removes permitted derivatives, inventories exports, and leaves required content-free receipts. It records what happened to local material without promising that a consumer forgot an exported work.
## Proving the bundle
Begin with two local synthetic two-minute references, a frozen thirty-second guitar take, short MIDI, an approved sung fixture, and the `01:32` marker. Use pinned onset/tempo observations and an editable `FeelProfile@1` to develop an original four-section arrangement. Produce one generated candidate with a complete receipt, retain the human selection/edit, and add a vocal layer or production-effect print.
Carry that work through intermediate stems, a candidate mix, and a target-conformant technical master. The final bundle must retain three sync markers, restart-safe indexing, and complete lineage so another reader can reconstruct the passage from sources to accepted music.
Label separated estimates separately from native or rendered stems. No ambient folder/microphone, copyrighted catalogue, Portal, visuals, paid effect, or platform call enters the proof. [Sessions](sessions.md#proving-the-jam) owns the independent live-jam fixture.
---
title: "Language Edition"
plain_name: "App: Language Edition (dubbing, captions)"
section: "Compositions > Creative Works"
status: "Designed"
original: https://hexanomicon.dev/compositions/language-edition/
guide: https://lychd.snayu.ai/docs/compositions/language-edition/
---
# Language Edition (App: Language Edition (dubbing, captions))
## Plain-English summary (Snayu)
**What it is:** Language Edition produces replacement dialogue, narration, translation and captions aligned to a locked video source, from verified transcript to performance, captions and an optional track replacement.
**Why it matters:** Read when working on dubbing, subtitles, translation or voice replacement for video.
- A human reviewer must attest the source transcript before aligned wording becomes canonical.
- Translation is a versioned step; the edition's reviewer still judges fit in the scene.
- The optional mux may replace only language tracks; picture, music and other streams are preserved.
**Status:** Designed. Accepted design; first proof is still a target.
## Original text (Hexanomicon)
Two speakers share a short scene. One edition replaces a line in its original language; another
gives the scene translated dialogue and captions. Both must return to the same locked source.
Someone must answer for the words, casting, performance, timing, disclosure, and accepted result.
**Language Edition** keeps that work together.
A language edition need not translate. Same-language replacement, narration, repair, and
accessibility belong to the same durable project. Its passage ends in an attributable set of
timed-language assets, with a constrained track replacement when requested.
## Contract
The Composition is `language_edition.timed_media` revision `2`; its principal Pattern is
`language_edition.build_language_version@2`. A `LanguageVersionRequest@2` states:
- **Source:** an immutable media reference and timebase, or an exact locator with source-eligibility
criteria and requested custody posture.
- **Meaning:** source and target languages, localization brief, glossary, and intended audience.
- **Performance:** exact eligible performer, voice, and capability references, with rights and
disclosure requirements.
- **Finish:** timing, captions, format, accessibility, and acceptance conditions.
The request gives every later revision a common task. Generic translation, speech engines,
network acquisition, byte custody, Persona identity, music, visuals, editorial recutting, and
publication retain their own owners. Crossing into their work requires separate admission.
??? info "Revision 2 and the earlier design"
Revision `2` supersedes revision `1` of the Composition and its `@1` Pattern,
request, and result family. It admits source locators without acquiring Scout or custody
authority and requires source-dialogue attestation before source-aligned wording becomes
canonical. No registry or Run used revision `1`, so there is no executable migration. The
earlier meanings remain part of the design history.
## One bounded language-edition road
**Establish the source.** Language Edition judges whether the source fits the request. A locator
may require a separately granted Scout Fetch or Download. Scout owns Search, Fetch, Download,
destination and contact policy, quarantine arrival, and acquisition receipts. After bounded
quarantine, separately granted, custody-owned Artifact Admission validates retained bytes and
establishes the immutable source master. A URL cannot stand in for that master; an acquisition
receipt cannot settle custody.
**Establish what was spoken.** Bounded demux and probe precede Echo Ear's transcript, diarization,
and timing observations. The proposed `DialogueTranscriptRevision@2` remains observation;
an authorized source-language reviewer must judge it. That reviewer creates `SourceDialogueAttestation@1`, binding the exact
source and timebase, stable segment identities, speakers, words, timing, uncertainty and
corrections, and the reviewer's Principal and evidence. Ambiguity stays unresolved. Only then may
source-aligned wording become canonical. When Broadcast's `ScriptRevision@1` supplies canonical
words, the attestation binds them to spoken segments without revising or taking ownership of
that script.
**Prepare and review the edition.** The attested source enters an optional attributed Translation
Spell and mandatory review, producing `LanguageEditionScriptRevision@2`. A same-language edition
can proceed without translation. Language Edition judges the wording in its scene; the
[translation contract](#translation-is-a-spell-localization-is-the-judgment) keeps the
transformation inspectable.
**Perform and conform.** Eligible casting selects human takes or Echo Voice synthesis for
`DialoguePerformanceRevision@2`. Preserve performer and voice eligibility: selecting them creates
no grant and copies no Persona authority. Dialogue editing, captions, and `DialogueConformMap@2`
align the performance to the source. Review linguistic fit, intelligibility, timing, rights, and
disclosure before acceptance.
**Hand over the assets.** `TimedLanguageAssetBundle@2` binds exact source, attestation, and script
revisions; performance and dialogue artifacts; captions and conform map; rights, disclosure,
findings, lineage, and admission criteria. A consumer can admit this bundle on its own. It is
neither a final picture container nor an editorial recut.
**End where the evidence ends.** If requested, restricted track mux and probes with back-check
may produce `LanguageVersionCandidate@2` under the [locked-picture contract](#preserve-the-locked-picture).
`LanguageEditionFindingSet@2` carries the findings. Each edition retains its attested source,
its own language and performance revisions, and every artifact actually produced. Partial,
incomplete, and unknown outcomes remain exact; an optional mux does not become canonical merely
because it exists.
## Translation is a Spell, localization is the judgment
The authority-qualified publisher of a versioned Translation Spell owns its transformation semantics;
[Spellweaver](../../sepulcher/extensions/weaver/index.md) validates its placement. The request pins
attested text, languages, glossary and protected spans, implementation, detection and fallback,
review, and declared loss. Retain original and derivative so the edition's reviewer can judge
speaker, scene, audience, duration, and fit.
Language detection grants no translation permission. Provider failure grants no substitute
language, voice, model, execution road, or paid service. Another Composition can reuse the exact
Spell while retaining its own judgment.
Language Edition owns captions, subtitles, scripts, and on-screen-language cue sheets as parts
of a timed edition. Content owners retain untimed writing; Frontend retains web and Altar chrome
catalogues. English-only Altar reference chrome requires neither English media nor translated
canonical identities.
## Voices belong to no shortcut
[Echo](../../sepulcher/extensions/echo.md) owns capture, STT, TTS, voice-profile facts, delivery,
and playback chronology. The Animator profile identifies the exact engine, model and acoustic
voice, supported languages and formats, licence, and measured limits. Performer consent and
source rights must independently cover the exact inputs.
Language Edition casts and directs pronunciation and performance, then accepts timing and
disclosure. [Avatar](../avatar/index.md) may supply exact eligibility for a Lich voice while
retaining Persona-linked presentation and Morphe. Resemblance establishes neither identity nor
rights; approval of one line does not authorize arbitrary later words. Riffmaw retains sung
performance and music. Across every road, generated sound proves neither playback nor hearing.
## Preserve the locked picture
The optional mux may add or replace only declared dialogue, narration, caption, subtitle, or
language-metadata tracks. Preserve every non-language stream. Record the preserved and replaced
digests, timebases, codecs, channels, and offsets, the loudness and intelligibility probes, and
the result digest. These records let a reviewer check what survived and exactly what changed.
Changed cuts, scene order, claims, picture sound, or music return to
[Broadcast](../broadcast/index.md). A constrained language replacement cannot quietly become a
new edit. The asset bundle remains a valid handoff without the optional mux; each receiving
owner judges the exact result for its own use.
### Model-native timed-language facet
A `VideoJob@2` may emit synchronized language only when its pre-execution
`MediaFacetAuthoritySet@1` declares `timed_language`, `language_edition.timed_media` revision `2`,
and the exact `LanguageVersionRequest@2` digest. Before execution, resolve the exact Echo speech
interface and profile, performer and acoustic voice, language support, consent, rights,
disclosure, and retention. Native video audio has the same obligations.
Technical settlement by Prism is followed by independent Language Edition admission. Its
`SemanticFacetAdmissionReceipt@1` binds child and compound digests, source attestation and script,
speaker and language role, use, rights, timing, findings, decision maker, and disposition. Retain
that receipt and parent in both the bundle and any optional mux.
Quarantine or delete undeclared speech or text. Demux, labels, or another owner's receipt cannot
admit this facet, and an inseparable compound requires every necessary owner's acceptance of
the exact digest and use.
## Neighbours keep their truth
The source and the result pass through distinct kinds of judgment:
| Neighbour | Contribution it continues to own |
| --- | --- |
| Prism | Attributed OCR, regions, frames, motion, lip-alignment observations, and technical derivatives. |
| Atelier | Accepted visuals. |
| Riffmaw | Music masters, stems, and cues. |
| Avatar | Eligible presentation. |
| Broadcast | Locked editorial source and requests; canonical claims and words; picture sound, recut, final edit, release, and correction. |
Settled exact references need no Suite. A promised result that actively admits, awaits, cancels,
retries, recovers, or jointly settles new work across those owners requires one. A Product may
package a language edition without taking its records; the technical Composition name does not
thereby become the market name.
## Failure, restart, and the first proof
Use stable segment identities to keep every stage tied to the exact source and timebase.
Transcript, attestation, translation, performance, alignment, dialogue-mix, mux, and review attempts
must retain independent revisions and dispositions. This preserves where work stopped when a
language is unsupported, a speaker is ambiguous, rights are missing, timing is lost, intelligibility
fails, the source becomes stale, the budget is exhausted, or provider/write effects are
indeterminate. Return the appropriate findings, refusal, partial result, or `unknown` outcome.
Restart must use reconciled immutable artifacts and settled attempts, without silent substitution.
The first falsifying proof remains a target: run a network-disabled synthetic two-speaker video
with separate picture, dialogue, music-effects, and caption streams on a known timebase. Fake
Ear, Translation, and Voice should build both a same-language and a translated edition. Check
preserved picture and non-language digests, lineage, attestation after human correction, glossary
protection, timing pressure, caption alignment, partial speaker refusal, crash recovery,
deterministic mux, export, and deletion. This would prove the contract's passage. It would not
prove translation quality, real-voice performance, rights, publication, or delivered operation.
[Workflow](../../adr/28-workflow.md) owns the score and its admissions;
[Audio](../../adr/37-audio.md) and [Vision](../../adr/36-vision.md) own the media boundaries.
Return to the [Composition Portfolio](../index.md) for the applications that may receive the
edition.
---
title: "Foundry"
plain_name: "App: Foundry (game builds)"
section: "Compositions > Creative Works"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/
guide: https://lychd.snayu.ai/docs/compositions/foundry/
---
# Foundry (App: Foundry (game builds))
## Plain-English summary (Snayu)
**What it is:** Foundry turns a game idea into a playtested local build another person can reproduce, keeping design, source, imported assets, worlds, game sound, playtests and build receipts.
**Why it matters:** Read before working on game-building, engine integration or game-sound features.
- Two workflows: build a playable slice, and design world sound bound to game events.
- Imports visual, music and dialogue bundles from other apps without rewriting them.
- Does not cover fun judgment, signing, upload, store release or public multiplayer.
**Status:** Designed
## Original text (Hexanomicon)
A game idea becomes useful evidence when another person can load the build and try the intended interaction. Foundry keeps the design, source, imported assets, worlds, scenarios, controller observations, and build receipts needed to repeat that experience.
## Enter the workshop
Start with the bounded change in [Project](project.md). What interaction should someone be
able to try? [Assets](assets.md) admits the exact visual, musical, and dialogue work needed to
make it, preserving each producer's contribution.
[World](world.md) assembles the scene, physics, navigation, controllers, and gameplay.
[World Sound](sound.md) binds sound to events and listeners within that world.
[Playtest](playtest.md) tries an exact scenario; [Build](build.md) seals the local candidate so
that the experience can be repeated.
## Contract
`game.foundry` revision `4` publishes `game.build_playable_slice@3` and the independent `game.design_world_sound@1`. The build starts from an admitted design/source/engine contract and may return `PlayableBuildBundle@1`. Sound starts from `WorldSoundBrief@1` plus exact project/world revisions and may return `WorldSoundBundle@1`. Either can end with exact non-completion.
The Patterns place the following proposed semantic Spells. These contracts are neither Dispatcher capabilities nor delivered implementations.
For a playable slice, the principal build Pattern takes the project through these Spells toward `PlayableBuildBundle@1`:
| Spell | Work it places |
| --- | --- |
| `game.bootstrap_project@1` | Establish project custody and the pinned engine environment. |
| `game.import_asset_bundle@3` | Admit exact producer bundles and create engine imports. |
| `game.assemble_world@1`, `game.bake_world@1`, `game.validate_world@1` | Assemble, compile, and validate the world candidate. |
| `game.playtest_candidate@1` | Try one declared scenario against the exact candidate. |
| `game.balance_from_evidence@1` | Propose a bounded successor from attributed observations. |
| `game.build_candidate@1`, `game.prepare_release@1` | Build and freeze the local candidate and its handoff. |
For interactive sound, the independent Pattern takes its admitted layers through these Spells toward `WorldSoundBundle@1`:
| Spell | Work it places |
| --- | --- |
| `game.import_world_sound@1` | Create sound-specific engine imports. |
| `game.bind_world_sound@1` | Bind admitted sound to exact world events, states, zones, listeners, and runtime behavior. |
| `game.validate_world_sound@1` | Check those sound bindings through their own observations and findings. |
Foundry retains the project source/design, scenes/worlds, interactive sound, resources/imports, tests, recipes, playtests, balance evidence, and local candidates/receipts needed to assess the build. Each producer retains the lineage of its visual, music, or timed-language contribution, while engines and store accounts remain external.
The local finish does not establish fun or authorize autonomous project direction, universal sound libraries, public multiplayer, signing, upload, or store release. To use an XR candidate as a lived place, obtain [Spectre](../spectre/index.md) Habitat and Encounter admission separately.
## Revision continuity
??? info "Earlier designs and their exact successors"
Revision `3` replaced revision `2` with role-qualified music/language inputs and `@2` successors to `game.build_playable_slice@1` and `game.import_asset_bundle@1`. Revision `4` adds the independent world-sound Pattern/record family and advances build/import to `@3` for `TimedLanguageAssetBundle@2`, preserving the frozen `@2` meanings. No Portfolio registry or Run used revisions `2` or `3`; there is no executable migration.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Project"
plain_name: "Foundry: project setup"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/project/
guide: https://lychd.snayu.ai/docs/compositions/foundry/project/
---
# Project (Foundry: project setup)
## Plain-English summary (Snayu)
**What it is:** How Foundry binds a requested feature to an exact repository revision and pinned engine environment before any code or editor changes the work.
**Why it matters:** Read when implementing project bootstrap, engine pinning or the security posture for running game code.
- The engine profile pins engine, templates, platform, physics, plug-ins, random streams and resources.
- Generated code, plug-ins and scripts get no network, secret or install access; untrusted code needs a Sandbox.
- On restart, the exact pinned versions are resolved; the latest is never silently chosen.
**Status:** Designed
## Original text (Hexanomicon)
The request names one feature. Project binds that request to a repository revision and an engine environment before generated source or an editor can change the work around it.
Begin with `game.bootstrap_project@1` to establish custody of the design, repository, `EngineProfile@1`, adapters, dependencies, environment, build recipe, declared scenarios, and acceptance checks. Within that environment, the profile pins engine/export templates, platform/renderer, physics/navigation, importers/plug-ins, locale/random streams, network/containment, and measured resources. These are the conditions under which the feature will be built and assessed.
`game.build_playable_slice@3` coordinates only the admitted feature and retains the source diff created by its Spells. Scenes, resources, settings, tests, and design decisions are project truth; imports and rebuildable caches retain separate records. An attractive screenshot or generated tree must still load, pass checks, build, and survive the declared scenario.
The project can execute code. Generated source, foreign scenes, editor scripts, native extensions, plug-ins, shaders, resources, and import hooks receive no ambient network, device, secret, filesystem-execution, or installation permission. The first proof uses a trusted fixture. General execution requires its engine contract's Tomb profile; headless mode supplies no containment.
Check licence acceptance and destructive source changes through their separate gates. After a restart, resolve the pinned Pattern, source, engine, adapters, environment, and schema before resuming. If they are incompatible, drain the work, migrate it through an explicit adapter, or end with the incompatibility recorded; silently selecting the latest version would change the work under review.
Continue with [Assets](assets.md), [World](world.md), [Playtest](playtest.md), or [Build](build.md).
---
title: "Assets"
plain_name: "Foundry: importing assets"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/assets/
guide: https://lychd.snayu.ai/docs/compositions/foundry/assets/
---
# Assets (Foundry: importing assets)
## Plain-English summary (Snayu)
**What it is:** How Foundry imports visual, music and dialogue bundles into a game engine, recording how each source became an engine asset and returning problems to the producing app as findings.
**Why it matters:** Read when building engine import pipelines, glTF handling or animation import.
- Import receipts record units, axes, scale, materials, skeletons and checks.
- Import failures go back as findings; the producer's lineage and approval stay unchanged.
- Generating assets live during play would need a future hotload contract.
**Status:** Designed
## Original text (Hexanomicon)
A visual asset can be approved by its director and still fail an engine import. Foundry judges the target use and preserves the producer's exact material so a technical failure can return as evidence rather than become a silent source repair.
`game.import_asset_bundle@3` admits `VisualAssetBundle@1`, `MusicAssetBundle@1`, and optional `TimedLanguageAssetBundle@2` against project roles, target, formats, rights, and spatial/temporal limits. Source manifests remain with Atelier, Riffmaw, Language Edition, or their exact producer. Foundry owns the engine-native imports and caches.
## Source to engine derivative
An import must explain how the producer's material became an engine derivative. `AssetImportReceipt@1` binds that source to the importer, target, transformations, outputs, and checks. For spatial material, admission records source units/axes/origin/scale, coordinate transforms, materials/textures, skeleton/animation mappings, generated collision/LOD/engine derivatives, importer/engine revisions, warnings, validation, and performance.
If those checks expose a problem, return it as `AssetFindingSet@1`. The producer receives attributable correction evidence while its lineage and creative approval remain unchanged.
A glTF/GLB can combine mesh, PBR appearance, skeleton, skinning, and animation. Point clouds, Gaussian/radiance forms, neutral voxels, game block grids, and portable assemblies require their own supported import forms. Unsupported forms fail or return findings. [Prism Form](../../sepulcher/extensions/prism/form.md#one-form-job-explicit-operation) owns admitted source-form conversion and declared loss; an engine importer cannot quietly mesh, rig, voxelize, or bake the source.
One asset's collider, LOD, skeleton/material/animation map belongs to its import. World-wide collision layers/masks, navigation joins, spawn, streaming, interaction roles, actor bindings, and controller use belong to the [World](world.md) bake. Reusing a derivative changes neither receipt's ownership.
For motion, begin with the exact accepted animation. Admission pins its target Form rig digest when rig-bound and the Kinesis `MotionAssetSet@1`/retarget receipt when used. [Kinesis](../../sepulcher/extensions/prism/kinesis.md) retains the portable curves, mapping, root/contact semantics, and technical validation. Foundry then owns the choices that make it run in the game: clip compression, engine controllers/state machines, blending, gameplay root motion, and playtest. Passing the import checks cannot certify the source rig or creative choice.
## Distinct sound and world boundaries
[World Sound](sound.md) uses `game.import_world_sound@1` and `WorldSoundImportReceipt@1`; it does not widen the spatial meaning of `AssetImportReceipt@1`. A separately owned reusable pack retains producer lineage, while project-specific event/space/runtime sound stays Foundry truth.
A `.schem` or block grid can enter a project/map asset. Live placement still requires a [Blockworld mission](../blockworld/mission.md), its epoch, lease, inventory, Sentinel, and receipts. A Suite can correlate handoffs and Runs but cannot merge member databases, Sigils, secrets, sessions, approvals, budget judgment, or release authority.
An [Atelier studio](../products-and-suites.md#atelier-riffmaw-language-edition-and-broadcast)
could propose generated material during play. Its creative acceptance and engine import do not
prove live activation. A future hotload contract must bind the exact target-runtime state, reject
stale outputs, distinguish acknowledged, partial, unknown, and reverted application, and preserve
the prior usable revision for bounded recovery. A lost acknowledgement requires reconciliation
before retry. The present import/build contract does not establish that live route.
[Project](project.md) keeps custody; [Build](build.md) seals the candidate using these derivatives.
---
title: "World Sound"
plain_name: "Foundry: in-game sound"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/sound/
guide: https://lychd.snayu.ai/docs/compositions/foundry/sound/
---
# World Sound (Foundry: in-game sound)
## Plain-English summary (Snayu)
**What it is:** How Foundry designs world sound tied to exact game events, states, zones and listener positions (door variants, machine loops, ambience zones) and proves it works in the engine.
**Why it matters:** Read when working on interactive game audio or sound returned by video models for games.
- A cue map says how sound responds; it still has to be bound and tested in the engine.
- Import success proves only import; event, loop and listener behaviour need separate evidence.
- Changes to world, events or engine make dependent sound work stale.
**Status:** Designed
## Original text (Hexanomicon)
A machine starts, loops while running, and stops when its game state changes. An ambience zone answers the listener's position. Foundry owns these **world sound** relations because their acceptance depends on exact interactive events, states, places, listeners, and runtime behavior.
## One bounded Pattern
`game.design_world_sound@1` begins with `WorldSoundBrief@1`, exact project source, `WorldAssemblyPlan@1`, event schema, `EngineProfile@1`, source/rights references, channel/spatial profile, resources, and acceptance. It returns `WorldSoundBundle@1`, `WorldSoundFindingSet@1`, or exact refusal, preserving the project derivative and bindings it made. A later build pins that source revision in a new Invocation; the Patterns never nest or silently resume one another.
Recording, synthesis, procedures, licensed samples, processing, and models can propose layers. Each retains source/derivative digests, author/performer, tool/provider, transforms, rights/consent, role, and loss. Codec or waveform resemblance cannot establish role.
## From cue to audible behavior
The cue map describes how the world should respond. A door can choose admitted variants; a machine has start/loop/stop; a zone crossfades by listener position. These relations still need to be installed and tried in the engine; the map itself is no rendered soundtrack.
`game.import_world_sound@1`, `game.bind_world_sound@1`, and `game.validate_world_sound@1` keep sound-specific records of import, binding, and observation. They do not widen generic asset, bake, or playtest schemas. Import success answers only the import question. Event, zone, loop, listener, priority, and failure behavior require their own evidence.
| Record | Required meaning |
| --- | --- |
| `WorldSoundBrief@1` | exact project/world/event frame, requested roles, listener and spatial policy, target engine/profile, source constraints, rights, budget, and acceptance line |
| `WorldSoundRevision@1` | immutable selected layers and edits with source lineage, variants, loop and transition facts, loudness and channel facts, and approval |
| `WorldSoundCueMap@1` | event and state ids, world regions, listener perspective, conditions, priorities, concurrency, randomization, start/stop/loop/crossfade, attenuation, occlusion, reverb-send, and timing relations |
| `WorldSoundBindingPlan@1` | exact world-plan digest plus proposed event, state, zone, listener, bus, and runtime mappings; inert data rather than engine code or mutation authority |
| `WorldSoundBundle@1` | accepted revisions, cue map, manifests, probes, findings, admission receipts, and exact target constraints |
| `WorldSoundImportReceipt@1` | source-to-engine asset conversion, importer/profile revision, bus and resource facts, outputs, checks, warnings, and declared loss |
| `WorldSoundBindingReceipt@1` | exact event, state, zone, listener, mixer-bus, and runtime binding installed into one world derivative |
| `WorldSoundObservationSet@1` | exact scenario tick/time, emitted cue and engine-event ids, listener zone, mixer state, gaps, and assertions |
| `WorldSoundFindingSet@1` | attributable unsupported role, stale source, rights, timing, spatial, import, binding, resource, or playtest evidence |
## Model-native sound fails closed
Pre-execution `MediaFacetAuthoritySet@1` must declare `world_sound`, `game.foundry` revision `4`, and exact `WorldSoundBrief@1` digest. After [Prism technical settlement](../../sepulcher/extensions/prism/video.md#admit-every-compound-facet), Foundry issues its independent `SemanticFacetAdmissionReceipt@1` over child/compound digests, use, rights, findings, and disposition. Other owners, demux, and provider labels cannot do this for it. Undeclared sound is quarantined/deleted, with no guessed event or library admission. Inseparable compounds need every required owner to accept the exact digest/use.
## Neighboring offices
[Riffmaw](../riffmaw/) owns music even when a game plays it. [Language Edition](../language-edition/) owns timed dialogue/narration/captions and Echo supplies speech operations. [Broadcast](../broadcast/sound.md) owns picture-bound sound; [Atelier](../atelier/) visual direction. Foundry binds admitted material to its game without rewriting it. External packs retain producer lineage; exporting a folder cannot create a universal sound-library Composition.
## Recovery and proof
A sound result depends on the world it was judged against. Changes to project source, world plan, event schema, listener/coordinates, target engine, timebase, rights, or brief make dependent cues/imports/bindings/builds/playtests stale. Preserve those dependencies so review can identify which work must return.
If a recorder, generator, importer, or engine loses an acknowledgement, keep the result `unknown` until the exact job, derivative, destination, and digest reconcile. A fallback requires a declared branch or forward Invocation. Cancellation alone cannot prove that capture, output, or mutation stopped; partial/mismatched material stays quarantined. On deletion, inventory derivatives/imports/bindings/builds/exports and retain an honest account of other custodians' copies.
The first network-disabled synthetic world has deterministic interaction sound, a start/loop/stop machine, ambience zone, listener transition, and bounded failure. Prove cue/event order, loop/crossfade bounds, buses/resources, rebuild/restart, `WorldSoundBindingReceipt@1`, and `WorldSoundObservationSet@1`. This is no proof of universal sound libraries, photoreal acoustics, public release, or another engine profile.
---
title: "World"
plain_name: "Foundry: building game worlds"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/world/
guide: https://lychd.snayu.ai/docs/compositions/foundry/world/
---
# World (Foundry: building game worlds)
## Plain-English summary (Snayu)
**What it is:** How Foundry compiles an inert world plan (space, placements, spawns, physics, navigation, gameplay) into an engine-native world, with Godot as the first engine candidate.
**Why it matters:** Read when working on world assembly, procedural generation, Godot integration or AI-proposed levels.
- The world plan is data, never code or live mutation authority.
- Godot is the first proposed engine; headless mode does not prove containment.
- Models may propose plans or patches but cannot claim playability or execute code.
**Status:** Designed. Engine study dated 2026-08-08; no delivered Godot adapter.
## Original text (Hexanomicon)
A room needs more than visible walls to become a playable place. The player must spawn somewhere, collide with the right surfaces, navigate a route, trigger an interaction, and leave evidence that those relations work. World compiles those meanings into an engine-native candidate from admitted design, source, assets, and motion.
The engine-profile study was reviewed **2026-08-08**. Foundry is an accepted application design; this candidate tool path proves no delivered Pattern, Godot adapter, Tomb, project store, or permission to execute hostile projects.
## One inert assembly plan
```text
design and admitted catalogue
→ inert WorldAssemblyPlan@1 or closed procedural recipe
→ schema, reference, bounds, cardinality, and target validation
→ contained engine compiler
→ collision, navigation, presentation, and controller bake
→ static probes and declared gameplay scenario
→ candidate world revision
```
`WorldAssemblyPlan@1` describes one bounded 2D/3D world or slice. It may be authored, compiled from a closed recipe, or proposed by a Mind. It is inert data, never GDScript, Python, an engine scene, shell, or live-world mutation authority.
| Facet | Required facts |
| --- | --- |
| **source frame** | exact design, project, asset-catalogue, Form assembly, Kinesis motion, and parent-world revisions |
| **space** | 2D or 3D coordinates, units, axes, origin, bounds, zones, layers, chunks, and streaming roles |
| **placements** | stable node or entity ids, exact artifact facets, transforms, variants, parentage, and instance bounds |
| **anchors** | player and actor spawns, cameras, entrances, exits, interactions, checkpoints, targets, and authored landmarks |
| **collision and physics** | body role, shapes, materials, layers, masks, joints, gravity zones, backend profile, and declared tolerances |
| **navigation** | agent profiles, walkable regions, links, avoidance policy, bake parameters, unreachable policy, and expected routes |
| **presentation** | lights, probes, audio zones, occlusion, ambience, level of detail, visibility, and performance budgets |
| **motion use** | exact clips, target rigs, controller states, transitions, blending, root-motion policy, and event bindings |
| **gameplay** | actors, components, interactions, triggers, state, win or stop predicates, and separately referenced source behavior |
| **procedure** | seed, closed generator revision, opened parameters, maximum counts, spatial envelope, and termination rule |
| **target** | `EngineProfile@1`, platform, quality profile, scenario set, and build acceptance criteria |
The principal Pattern uses `game.assemble_world@1`, `game.bake_world@1`, and `game.validate_world@1` as semantic Spells to turn the plan into an inspectable candidate. The compiler checks identities, references, bounds/cardinality, units/axes, placements, physics/navigation, resource ceilings, and target support. It returns unsupported facets in `WorldFindingSet@1` instead of silently dropping them.
When baking succeeds, `WorldBakeReceipt@1` preserves source/result digests, compiler/profile, transforms, generated collision/navigation/lighting/LOD, warnings, validation, and loss. That receipt explains the relationship between the plan and the resulting world.
Engine `.tscn`/`.scn` files and resources emitted by the world compiler, along with import caches, navmeshes, lightmaps, and shader caches, remain derivatives. They do not replace the plan, [project source](project.md), source assets, Form assembly, or Kinesis clips.
## Godot is the first engine profile
The dated first candidate is [Godot](https://github.com/godotengine/godot): an MIT engine with command-line import, headless execution, export, and scene/navigation/animation facilities for the proposed 2D/3D slices. `EngineToolJob@1` bounds each finite inspect, import, assemble, bake, validate, test, or export by exact root, operation, inputs, profile, limits, outputs, findings, cancellation, and receipt. [Playtest](playtest.md) separately owns the live `PlaytestSession@1`.
A [Worker](../../adr/14-workers.md#service-job-attempts) delivers the job to a trusted executor or Tomb through a pinned ToolProfile. Independent residency, queue, lifecycle, or remote work may justify an Animator `JobGrant`; direct Godot is no Soulstone. Editor ports, debug consoles, generic RPC, arbitrary CLI arguments, and project scripts cannot be the stable contract.
To make an engine result assessable, `EngineProfile@1` pins the engine binary/build digest, export-template digest, platform/renderer, and GPU/display/audio mode. It also fixes physics backend/tick/substeps/threading, navigation settings per agent, importers/plug-ins/revisions/licences, and locale/timezone/random streams. Network policy, CPU/GPU/RAM/disk/time ceilings, and trusted-fixture versus Tomb posture bound how that environment may run.
Running headless does not prove containment, deterministic rendering, or audio behavior. Treat project scripts, native extensions, plug-ins, shaders, resource references, archives, and generated code as hostile. General execution must wait for [Tomb](../../adr/09-security.md#6-tomb-execution-contract) evidence covering filesystem, process, device, network, secret, resource, cancellation, and residue boundaries.
Reproducibility is similarly specific: physics/navigation results hold only within the exact profile and asserted tolerances. A changed backend, hardware, driver, threading configuration, or engine needs new evidence.
## Portable sources and engine derivatives
The first portable 3D asset/assembly projection is [glTF/GLB](https://www.khronos.org/gltf/), validated by the [Khronos validator](https://github.com/KhronosGroup/glTF-Validator) before import. OpenUSD/UsdSkel remains a later studio-interchange profile; FBX is optional lossy compatibility and not required for the FOSS road. [Blender](https://www.blender.org/) may prepare contained Form/Kinesis/assets and previews. Opening its scene does not prove engine physics, navigation, gameplay, or playability.
The [asset import](assets.md#source-to-engine-derivative) keeps its transformations in `AssetImportReceipt@1`. `WorldBakeReceipt@1` owns world collision matrices, navigation joins, spawn, streaming, behavior, and controller binding. Reuse preserves their source lineage.
## Procedural and model-assisted worlds
A Mind can propose a plan or reviewed project patch. It cannot invent rights, open an unbounded catalogue, install plug-ins, execute generated source, or claim playability from prose. GDScript, C#, native code, shaders, and build configuration pass ordinary diff review, containment, tests, and playtest; they cannot hide in the closed recipe grammar. Video world models return Prism pixels; spatial models return Form candidates. Both still need normal admission and engine proof.
Begin actors with project-owned deterministic state machines, behavior trees, navigation policies, and fixture controllers. If a later `ActorPolicyProfile@1` admits bounded model observations/actions, the build must already specify what happens when results are unavailable, late, malformed, or unsafe. Admitting that policy grants no console, filesystem, scene mutation, network, or world authority.
## Playable evidence handoff
[Playtest](playtest.md) owns `GameplayScenario@1`, `PlaytestSession@1`, and `EngineObservationSet@1`; [Build](build.md) owns the complete fixtures and candidate. World supplies exact plan, bake receipt, engine profile, and findings.
[Spectre](../spectre/index.md) may receive a world/build/profile and playtest evidence for `VRHabitat@1` admission. It separately checks runtime, spatial, comfort, accessibility, retention, and exit requirements; a successful game scenario does not admit a Habitat.
## The neighboring worlds
[Shadow](../../sepulcher/extensions/shadow/) owns counterfactual branch lineage and prepares Promotion Requests. [Blockworld](../blockworld/) owns persistent-server missions/effects. Foundry owns the local project candidate: offline `.schem` or grid import grants no live placement. Signing, upload, rollout/rollback, public players, and remote-copy receipts require a future distribution owner.
---
title: "Playtest"
plain_name: "Foundry: automated playtests"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/playtest/
guide: https://lychd.snayu.ai/docs/compositions/foundry/playtest/
---
# Playtest (Foundry: automated playtests)
## Plain-English summary (Snayu)
**What it is:** How Foundry runs a declared gameplay scenario against an exact build with a restricted controller and records structured engine observations as evidence.
**Why it matters:** Read when building automated playtesting or balance suggestions.
- A scenario pins build, start state, inputs, assertions and time limits.
- Screenshots support but never replace structured observations.
- Evidence can show loading or regressions, never fun or release readiness.
**Status:** Designed
## Original text (Hexanomicon)
The candidate loads. Now make the player perform the declared interaction and inspect what the engine reports. `game.playtest_candidate@1` runs that bounded scenario against the exact build; screenshots support, but never replace, structured observations.
`PlaytestSession@1` owns the bounded live process. A trusted/Tomb driver may implement it directly; an independently resident, queued, or remote harness may expose `SessionGrant`. [World](world.md#godot-is-the-first-engine-profile) keeps finite `EngineToolJob@1`. The scenario's `ControllerAdapter` exposes only admitted inputs, without shell, editor, debug console, arbitrary RPC, anti-cheat bypass, public-server access, or deceptive player authority.
## Pin the attempt
Define what the attempt will do and what would count as a result in `GameplayScenario@1`. It binds build/world epoch, initial state, spawn/reset, random streams, ordered steps, inputs, structured observations, tick/clock policy, time/action budgets, assertions, tolerances, and terminal outcomes.
A fresh session normally starts a new epoch. Reusing one requires proof of process, world, cursor, and clock continuity. The epoch and cursor keep late observations from being mistaken for evidence about a different attempt.
During the attempt, `EngineObservationSet@1` retains exact tick/time, entity identities, transforms/velocities, collisions/triggers, navigation, controller/animation state, selected gameplay state, logs, performance, gaps, and assertions. Those observations also support recovery. If an input acknowledgement disappears, reconcile the same epoch, cursor, and resulting state before considering another input. Settle recovered, failed, cancelled, or indeterminate/contained. Do not repeat an unproved effect: repetition cannot establish what happened.
## What the evidence can judge
Scenario author, controller, evaluator, and human player remain separate roles. Their evidence may establish loading, completed interaction, frame-time bounds, or regression. It cannot decide fun or release. `game.balance_from_evidence@1` proposes a bounded successor through ordinary project/build/playtest gates without revising old evidence.
A [Spectre](../spectre/index.md) Encounter is separately admitted participant, comfort, interruption, and exit work in a VR Habitat. It cannot substitute for candidate-build judgment.
Continue to [Build](build.md) when the scenario and checks support review.
---
title: "Build"
plain_name: "Foundry: local build candidate"
section: "Compositions > Creative Works > Foundry"
status: "Designed"
original: https://hexanomicon.dev/compositions/foundry/build/
guide: https://lychd.snayu.ai/docs/compositions/foundry/build/
---
# Build (Foundry: local build candidate)
## Plain-English summary (Snayu)
**What it is:** How Foundry tests, builds and freezes a reproducible local game candidate for human review, and why release and distribution stay outside it.
**Why it matters:** Read when working on game build output or anything resembling release.
- The build returns content-addressed bytes with source, command, environment and checksum.
- Human review accepts the PlayableBuildBundle or asks for a repair.
- No signing, upload, store accounts, telemetry or public release.
**Status:** Designed
## Original text (Hexanomicon)
The local candidate is ready when someone else can identify its source, reproduce the admitted checks, and inspect its playtest evidence. `game.build_candidate@1` runs static/engine tests, performs reproducible imports where the exact profile proves them, and returns content-addressed bytes with source, command, environment, probes, and checksum.
Human review assesses the candidate as `PlayableBuildBundle@1`, either accepting it or requesting a forward repair. Once accepted, `game.prepare_release@1` freezes the candidate, compatibility statement, evidence, and handoff. Sending it onward still requires a future release/distribution owner: neither local step signs, uploads, opens public multiplayer, controls store accounts, exports telemetry, rolls out, corrects, takes down, or reconciles remote copies.
Deletion inventories local candidates, imports, caches, and derivatives. An exported handoff is recorded, without a promise that the consumer's copy was recalled.
## Proving the build
A network-disabled synthetic 2D project should bootstrap a repository, admit small visual/music bundles, import through test adapters, build a scene, and run one controller scenario. Emit exactly one `PlayableBuildBundle@1` with source, build, test, playtest, and checksum receipts. Signing, upload, store accounts, telemetry, public players, and release remain outside it.
A separate 3D fixture adds validated GLB, collision, baked navigation, an accepted Kinesis clip and a [Foundry controller](assets.md#source-to-engine-derivative), an interaction, headless logic checks, and a real renderer/hardware playtest receipt. It proves no hostile-project execution, open-world streaming, model-driven actor, networking, or other engine profile.
---
title: "Broadcast"
plain_name: "App: Broadcast (publishing)"
section: "Compositions > Creative Works"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/
---
# Broadcast (App: Broadcast (publishing))
## Plain-English summary (Snayu)
**What it is:** Broadcast turns sourced claims into an article or video: evidence ledger, canonical script, picture sound, timeline edit and render, ending in a local publication candidate. Releasing it is a separate step.
**Why it matters:** Read before working on article or video production, fact-tracking, editing or publishing features.
- Every claim stays linked to its frozen sources.
- A local candidate can be a complete result; publishing needs a separate, approved release.
- Visuals, music and dialogue stay owned by Atelier, Riffmaw and Language Edition.
**Status:** Designed
## Original text (Hexanomicon)
A polished video can make a weak claim feel certain. Broadcast keeps the source words and evidence visible while an editor turns them into an article, narration, captions, picture sound, and a final cut. The useful finish is a publication candidate that can be approved, corrected, or refused before it leaves the machine.
## The work
Begin with the sentence you want an audience to believe. [Sources](sources.md) binds its claims
to frozen spans; [Script](script.md) establishes the canonical words, preserving uncertainty and
attribution as the story takes shape.
In [Edit](edit.md), independently owned assets meet in an explicit timeline.
[Picture-Bound Sound](sound.md) gives the exact locked picture and timebase its effects, foley,
room tone, and ambience. The cut decides how these contributions meet; their source owners
remain visible within it.
[Render](render.md) makes reproducible, accessible bytes. That local candidate can be a complete
result. When an editor chooses to put it before an external audience, [Release](release.md)
handles the separate consequence and any later correction.
## The local candidate
`broadcast.studio` revision `4` publishes `broadcast.build_local_package@3`. Frozen sources, editorial brief, target profile, and admitted visual, music, timed-language, and picture-sound assets can become `EditorialPackage@2` and `PublicationCandidate@2`. A publication receipt exists only after a separate release effect.
Broadcast owns source words/claims, picture sound, editorial judgment, and destination receipts. [Atelier](../atelier/) retains visual/VFX lineage; [Riffmaw](../riffmaw/) music; [Language Edition](../language-edition/) timed-language editions. A delivery adapter cannot inherit editorial judgment. Unattended publication, engagement farming, borrowed asset authority, and unreviewed egress remain outside this application.
## Revision continuity
??? info "Earlier designs and their exact successors"
Revision `4` supersedes revision `3`, advancing the principal Pattern to `broadcast.build_local_package@3` and picture sound to `broadcast.design_picture_sound@2`. It returns `EditorialPackage@2`/`PublicationCandidate@2`, reviews and repairs through `broadcast.review_package@2`/`broadcast.revise_from_correction@2`, and uses only `@2` publication/correction/takedown effects. Revision `3` had introduced timed-language and picture-sound handoffs via `broadcast.build_local_package@2`; revision `4` adds the exact `@2` record family and requires picture-sound authority before model execution, followed by Broadcast's own semantic admission receipt. Retired designs were never registered or run; their meanings remain historical without executable migration.
Follow [Workflow](../../adr/28-workflow.md) for casting and application ownership,
[Vision](../../adr/36-vision.md) and [Audio](../../adr/37-audio.md) for the media contracts beneath
the work, or return to the [Composition Portfolio](../index.md) to choose another craft.
---
title: "Sources"
plain_name: "Broadcast: sources and claims"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/sources/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/sources/
---
# Sources (Broadcast: sources and claims)
## Plain-English summary (Snayu)
**What it is:** How Broadcast freezes evidence as snapshots and builds a claim ledger linking each factual claim to supporting spans, confidence and dependent content.
**Why it matters:** Read when building fact-checking, citation or correction tracking.
- A URL locates a source; a named snapshot freezes it.
- Each claim records its supporting spans, kind of reasoning, confidence and contradictions.
- Corrections mark dependent work stale without rewriting the earlier claim.
**Status:** Designed
## Original text (Hexanomicon)
One sentence in the eventual script may depend on a quotation, a calculation, and a disputed observation. Sources keeps each support visible before voice and imagery make the sentence persuasive.
## Freeze the evidence
A live URL helps locate a source. Freeze the evidence as a named snapshot before a claim depends
on it, keeping three things together:
- **What was read:** source identity, revision/digest, relevant span, and known author
or publisher. Another reader must be able to find the material that supported the claim.
- **How it may be used:** classification, rights posture, audience, purpose, disclosures, and
retention. Custody of a snapshot does not settle every future use.
- **What this work asks of it:** an editorial brief fixing the question, audience, target, scope,
tone, exclusions, review standard, and freshness.
A changed question or changed source creates a forward revision. Keep each script tied to the
revision it relied on under the declared retention policy.
## Build the claim ledger
For each factual claim, identify the spans that support it and whether the work is quotation, extraction, calculation, synthesis, or interpretation. Keep confidence, assumptions, contradictory evidence, and reviewer state alongside that binding. Also record every dependent article, script, caption, or timeline object, so a finding can reach all work that relied on the claim.
A stale or disputed claim can be narrowed, attributed, removed, returned for research, or refused. Fluent wording cannot raise its evidence grade. A correction appends corrected/withdrawn state and stales dependants without rewriting what the earlier claim said.
Check rights, privacy, likeness, and Portal egress when evidence enters and again whenever its intended use changes. Once those checks are satisfied, the evidence and claim revisions can enter [Script](script.md). Voice synthesis, another owner's asset revision, rendering, and publication still require their own authority.
---
title: "Script"
plain_name: "Broadcast: canonical script"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/script/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/script/
---
# Script (Broadcast: canonical script)
## Plain-English summary (Snayu)
**What it is:** How Broadcast owns the canonical article, narration, titles and caption words built from claim revisions, and how they feed language editions.
**Why it matters:** Read when building script authoring, review, or the script handoff to Language Edition.
- Every sentence keeps links to the claims it depends on.
- Language editions cannot replace canonical words; adaptations stay visible.
- Correcting the script marks dependent narration, captions, cuts and renders stale.
**Status:** Designed
## Original text (Hexanomicon)
The canonical sentence must remain readable before it is spoken over an image. Script owns the article, narration, dialogue, title, description, and formatted variants from which spoken delivery and captions derive.
Choose exact claim revisions from the [ledger](sources.md), preserving attribution, uncertainty, and disclosure. A sentence joining several claims keeps every dependency. A shorter channel version may alter structure or length while retaining source meaning, audience, and claim scope.
Approve narration and caption words before assembly. For a timed language version, `LanguageVersionRequest@2` can send [Language Edition](../language-edition/index.md) the exact `ScriptRevision@1`, locked media digest, target language/timebase, pronunciation/performance direction, authority, and request digest. The returned `TimedLanguageAssetBundle@2` cannot replace the canonical words and must keep any adaptation visible. If the source script is corrected, its dependent editions become stale.
Review the words for factual support, quotation, attribution, privacy, likeness, disclosures, accessible language, and audience. Tie each finding to the exact claim or text revision so a bounded forward repair can answer it. Where support or authority remains unresolved, keep the result as a draft, correction request, or refusal.
[Edit](edit.md) receives the accepted script by digest. Later correction stales dependent narration, captions, cuts, renders, and publications, preserving the original words and review history.
---
title: "Picture-Bound Sound"
plain_name: "Broadcast: picture-bound sound"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/sound/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/sound/
---
# Picture-Bound Sound (Broadcast: picture-bound sound)
## Plain-English summary (Snayu)
**What it is:** How Broadcast designs sound tied to exact picture: effects, foley, room tone and ambience judged against a locked cut, including sound returned by video models.
**Why it matters:** Read when working on film sound design or audio from compound video models.
- Each layer records event, place, distance, timing and rights.
- Model-returned sound needs Broadcast declared before execution and its own admission afterwards.
- A changed picture, cut or claim makes affected sound stale.
**Status:** Designed
## Original text (Hexanomicon)
A door closes in a small room. Its impact, distance, reverberant tail, and the silence around it belong to the meaning of that exact shot. Broadcast calls this **picture-bound sound design**: effects, foley, room tone, environmental beds, and ambience judged against picture, scene, cut, claim, or editorial timeline.
`broadcast.design_picture_sound@2` starts with `PictureSoundBrief@1`, locked picture digest/timebase, event/space roles, source/rights references, target channel/loudness profile, and acceptance criteria. Recording, synthesis, licensed layers, processing, or a compound video-model result can propose candidates. Each layer retains source, implementation, transforms, rights, time relation, and digest.
## Hear the scene, then admit the result
Describe how each candidate belongs to the scene in `PictureSoundRevision@1` and optional `PictureSoundCueMap@1`: bind its event, place, material, distance, perspective, duration, continuity, cut relation, and uncertainty. Probes then measure boundaries, clipping, channels, loudness, and format. Editorial review uses that evidence to decide whether the sound communicates the visible event. Seal accepted selections as `PictureSoundBundle@1` for [Edit](edit.md).
Riffmaw owns music; Language Edition owns spoken performance/captions against a locked source; Echo owns speech lifecycle; Foundry may own game-event sound. A reusable standalone library would need its own proved Composition records, judgment, finish, and recovery. Broadcast's scene does not create that owner.
## When the video model also returns sound
A video model may return sound in the same compound result as its picture. Before execution, `MediaFacetAuthoritySet@1` must declare `picture_sound`, `broadcast.studio` revision `4`, and the exact `PictureSoundBrief@1` digest. Core retains the technical attempt, and Prism preserves the compound/child digests, timebase, and provenance.
After technical settlement, Broadcast independently issues `SemanticFacetAdmissionReceipt@1`. Successful demux, another owner's judgment, or `generate_sound` cannot substitute for that admission. Quarantine/delete unexpected sound; when media is inseparable, every necessary owner must accept the exact compound use.
A changed picture, cut, source claim, timebase, or brief stales affected sound. Recorder, generator, renderer, or destination acknowledgement loss remains `unknown` until reconciled. Corrections create successors; sound acceptance itself supplies no final mux or publication authority.
Continue through [Edit](edit.md) and [Render](render.md).
---
title: "Edit"
plain_name: "Broadcast: timeline editing"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/edit/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/edit/
---
# Edit (Broadcast: timeline editing)
## Plain-English summary (Snayu)
**What it is:** How Broadcast admits visual, music, language and sound bundles by exact digest and arranges them in one revisioned timeline, with review and bounded repairs.
**Why it matters:** Read when building the editing timeline or asset admission into it.
- Requests to other apps carry no credentials or effect authority.
- Retimes, replacements or changed words create a new timeline revision.
- Tools like FFmpeg execute the edit; they do not decide it.
**Status:** Designed
## Original text (Hexanomicon)
An accepted image, music master, spoken edition, and room tone still need an editor to decide how they meet. Edit makes that audiovisual relation explicit in one revisioned timeline.
## Admit the assets
Begin by establishing exactly what each contribution is allowed to do in this edit. Admit `VisualAssetBundle@1`, `MusicAssetBundle@1`, `TimedLanguageAssetBundle@2`, and `PictureSoundBundle@1` by exact digest, semantic role, limits, provenance, use boundary, validators, findings, and approval.
Keep each role owner's `SemanticFacetAdmissionReceipt@1`, including the compound digest when facets share a Prism parent. Broadcast then records its own editorial acceptance of their use together. It owns picture-bound sound; visual, music, and timed-language judgment and lineage remain with Atelier, Riffmaw, and Language Edition respectively.
`VisualAssetRequest@1` asks Atelier for role, target, timing, constraints, source/likeness requirements, and request digest. `MusicAssetRequest@1` asks Riffmaw for musical role/timing. `LanguageVersionRequest@2` asks Language Edition for source-aligned words and performance; `PictureSoundBrief@1` opens Broadcast's own sound work. These requests carry no credentials, Sigils, sessions, approvals, or downstream effect authority.
## Own the timeline
Bind script spans, narration, captions, storyboard, all asset revisions, and transitions to an explicit timebase. `MusicCueMap@1` and `PictureSoundCueMap@1` expose producer events; Broadcast chooses placement and cut. Retime, replacement, and changed words create a successor timeline and stale affected approvals.
`broadcast.review_package@2` returns findings against pacing, claim/image relation, continuity, captions, legibility, loudness balance, and target fit. `broadcast.revise_from_correction@2` permits a bounded forward repair. Wrong digests, timebases, claims, or use limits produce findings/refusal instead of an approximate edit.
The timeline also determines which changes need new creative judgment. Generative video editing requests new upstream visual work and cannot be treated as a deterministic trim. Pinned FFmpeg or equivalent tools may probe, trim, concatenate, retime, overlay, mix, mux, and encode under the timeline. The tools execute those operations; they neither decide the edit nor admit stochastic media facets.
[Render](render.md) receives the accepted timeline without permission to publish.
---
title: "Render"
plain_name: "Broadcast: reproducible render"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/render/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/render/
---
# Render (Broadcast: reproducible render)
## Plain-English summary (Snayu)
**What it is:** How Broadcast renders a reproducible, accessible local candidate by pinning every input and setting, then probing the output.
**Why it matters:** Read when working on rendering, encoding or accessibility checks.
- Fonts, codecs, filters, colour, loudness and caption formats are all pinned.
- Captions keep script and timing lineage; accessibility review is part of the candidate.
- A lost write acknowledgement stays unknown until destination and checksum reconcile.
**Status:** Designed
## Original text (Hexanomicon)
A missing font or changed codec can alter what the audience receives even when the timeline is untouched. Render freezes the dependencies that make one local candidate reproducible and inspectable.
Before rendering, pin every input digest and the settings that can change the result: renderer, font, codec, filter, colour setting, channel layout, loudness target, caption format, command/project revision, and target profile. After rendering, probes retain duration, dimensions, frame rate, codec, color/audio facts, caption presence, checksum, and tolerances so the candidate can be checked against that target.
Accessibility travels with the candidate. Captions retain script and timing lineage. Review contrast, legibility, flashing/motion hazards, intelligibility, language, and channel alternatives for the declared audience. Automated measurements support that judgment without certifying lived accessibility.
A completed write may precede a lost acknowledgement. Keep it **unknown** until destination and checksum reconcile; blind repetition can create competing outputs or conceal a partial write. Stale inputs, missing fonts, nondeterministic dependencies, unsupported targets, failed probes, and accessibility findings return failed render or correction requests.
Once accepted, the rendered bytes join the script, timeline, claims, sources, and asset manifests in `EditorialPackage@2` and `PublicationCandidate@2`. Muxing must preserve each independent semantic-facet receipt and compound-parent relation. This completes the local candidate; [Release](release.md) separately handles the effect at a destination.
---
title: "Release"
plain_name: "Broadcast: publishing and corrections"
section: "Compositions > Creative Works > Broadcast"
status: "Designed"
original: https://hexanomicon.dev/compositions/broadcast/release/
guide: https://lychd.snayu.ai/docs/compositions/broadcast/release/
---
# Release (Broadcast: publishing and corrections)
## Plain-English summary (Snayu)
**What it is:** How Broadcast publishes a candidate to an external destination as a separate approved effect, and later issues corrections or takedowns.
**Why it matters:** Read before building any publish, correction or takedown integration.
- Draft and public publishing are distinct effects with idempotency keys and receipts.
- A lost acknowledgement leaves remote state unknown; browser automation cannot retry it.
- Corrections and takedowns keep the original publication history.
**Status:** Designed
## Original text (Hexanomicon)
The candidate can remain local forever and still be finished. Release begins when the editor chooses to put those exact bytes before an external audience, with a destination and an attributable approval.
## Review before effect
Source support, claims, voice/likeness authority, privacy/Portal use, accessibility, asset admission, and render checks supply their own receipts. Publication additionally binds candidate digest, destination, audience, visibility, schedule, disclosures, cost, and approving Principal.
`broadcast.publish_draft@2` and `broadcast.publish_public@2` are distinct effects over `PublicationCandidate@2`. Each pins idempotency key, payload/request digests, destination identity, reconciliation lookup, and `PublicationReceipt@1`. A lost acknowledgement leaves **unknown** remote state until inspection resolves it. Browser automation supplies no authority for an untyped retry.
After release, a correction or removal must still be attributable to the publication it changes. `broadcast.correct_publication@2` creates a forward correction. `broadcast.takedown@2` requests removal while preserving the publication and receipt history. If a platform refuses, authority expires, the candidate changes, remote state remains uncertain, or a gate fails, return that exact blocker.
Recovery begins by resolving the pinned Pattern, source, handoff, script, timeline, renderer, adapter, and receipt revisions. Their retention needs differ: snapshots, rejected renders, candidates, destination receipts, and analytics retain separate policies. Deletion therefore inventories derivatives, requests authorized remote removal, and preserves a content-free receipt. Feeds and caches may still retain copies.
## Proving package
Before testing an external release, prove its local candidate. Build a three-to-five-minute piece from frozen sources: linked claims, article/script, local narration with back-transcript, admitted visual/music/language/picture-sound bundles, captions, explicit timeline, deterministic render, bounded repair, `EditorialPackage@2`, and `PublicationCandidate@2`. The fixture makes no platform call.
Return to [Broadcast](index.md), or inspect the local candidate in [Render](render.md).
---
title: "Stewardship & Acquisition"
plain_name: "Area: Stewardship & Acquisition"
section: "Compositions"
original: https://hexanomicon.dev/compositions/stewardship-and-acquisition/
guide: https://lychd.snayu.ai/docs/compositions/stewardship-and-acquisition/
---
# Stewardship & Acquisition (Area: Stewardship & Acquisition)
## Plain-English summary (Snayu)
**What it is:** Index of apps that care for people, animals, plants, places and supplies: Health, Wellbeing, Homestead, Keeper, Cultivator and Scavenger, each with its outcome.
**Why it matters:** Use it to find which household or care app owns a given task.
- Health covers clinical records; Wellbeing covers ordinary eating and movement.
- Keeper covers animals, Cultivator plants and fungi, Homestead stores and resources.
- Manual records work without connected devices.
## Original text (Hexanomicon)
Find the work that keeps people, living subjects, places, and supplies cared for. Health owns
reviewed personal clinical records and decision support; Wellbeing owns ordinary eating and
movement. Keeper owns animal care, Cultivator owns plants and cultivated fungi, and Homestead owns
physical assets, stores, and resources. Manual records work without connected devices.
| Composition | Outcome |
| --- | --- |
| [Health](../health/index.md) | A reviewed clinical history, one bounded health question, and proposals for human review or qualified handoff. |
| [Wellbeing](../wellbeing/index.md) | Food and ordinary movement that fit one adult’s life, including an honest “this plan cannot fit.” |
| [Homestead](../homestead/index.md) | An account of the household’s stores, supplies, resources, and maintenance, including work safely refused. |
| [Keeper](../keeper/index.md) | An animal or colony’s history through housing, feeding, changing needs, and recorded care. |
| [Cultivator](../cultivator/index.md) | A plant or cultivated fungus’s history through placement, tending, growth, and harvest. |
| [Scavenger](../scavenger/index.md) | A researched shortlist, seller negotiation, approved acquisition, or account of what arrived. |
When care needs involve supplies or shared equipment, follow the
[household handoff](../products-and-suites.md#homestead-keeper-and-cultivator). It explains how the
work passes between owners while each retains its own judgment.
[Composition Areas](../index.md#areas)
---
title: "Health"
plain_name: "App: Health (medical records)"
section: "Compositions > Stewardship & Acquisition"
status: "Designed"
original: https://hexanomicon.dev/compositions/health/
guide: https://lychd.snayu.ai/docs/compositions/health/
---
# Health (App: Health (medical records))
## Plain-English summary (Snayu)
**What it is:** Health helps one consenting adult turn medical documents into a reviewed, correctable clinical history, discuss one health question, and carry diagnostic or treatment proposals to a qualified human.
**Why it matters:** Read before working on anything touching health data, OCR of medical records or clinical decision support.
- Models may summarize and propose but never diagnose, prescribe or order tests.
- A red flag stops consultation and returns an emergency handoff; Health does not call emergency services.
- Clinical data stays local and purpose-limited; it never follows shopping or fitness requests.
**Status:** Designed. Accepted design; no delivered implementation.
## Original text (Hexanomicon)
A folder of photographed reports, remembered symptoms, prescriptions, and laboratory results is
not yet a clinical history. Health helps one consenting adult turn that material into an
attributable, corrigible profile, discuss one bounded health question, and carry a proposed
diagnostic or treatment plan to the right human decision. Unreadable evidence can remain unreadable;
uncertainty is a result, not a gap for a model to fill.
This Native Reference Composition has the stable identity `health.clinical`, revision `1`.
Its records and proposals support the bounded human decisions described below.
## Enter through the case
| Reader journey | Pinned Pattern | Primary records |
| --- | --- | --- |
| [Assimilate records into a reviewed profile](assimilation.md) | `health.assimilate_record@1` | `ClinicalSource@1`, `ExtractedClinicalClaim@1`, `HealthProfile@1` |
| [Consult the evidence and plan diagnostic work](consultation.md) | `health.review_case@1` | `HealthCase@1`, `DiagnosticProposal@1` |
| [Review treatment options and follow up](care.md) | `health.plan_care@1`, `health.follow_up@1` | `CareProposal@1`, `HealthFollowUp@1` |
Each Pattern is independently invocable. An Invocation ends with a committed record or reviewed
proposal, an emergency or qualified-professional handoff, an exact blocker, refusal, partial
result, cancellation, interruption, or explicitly unresolved evidence or external effect. A
longitudinal profile does not turn consultation into an endless Run.
## Contract
Health owns admitted clinical sources and their revisions; extracted claims and corrections;
profile revisions; case questions; patient-reported symptoms; clinician-authored assertions;
measurements and test results; competing explanations; diagnostic and care proposals; consent,
review, sharing, export, deletion, and follow-up receipts. It keeps source observation separate
from extraction, model interpretation, human confirmation, and externally established clinical
fact.
A Mind may summarize evidence, expose contradictions, ask discriminating questions, and propose
diagnostic or treatment options. It may not convert OCR into truth, silently reconcile conflicting
records, declare a diagnosis final, prescribe, order a test, administer treatment, or present
absence of a warning as proof of safety. Deterministic policy checks units, identity, source
coverage, duplicate intake, interactions represented in the admitted knowledge set, approval
bindings, and typed handoffs; passing those checks does not establish medical correctness.
Revision one supports personal clinical decision support for a consenting adult. Emergency care,
autonomous triage, pediatric care, pregnancy and perinatal care, psychiatric crisis response,
controlled substances, surgery, and unsupervised medication changes are outside its supported
treatment path. A red flag stops ordinary consultation and returns an emergency handoff; Health
does not monitor the person or contact emergency services.
## Authority and privacy
The patient, caregiver, clinician, prescriber, laboratory, and record custodian are distinct
principals. Consent to store a photograph is not consent to infer from it, disclose it, accept an
extracted claim, approve a plan, or perform a clinical effect. Human approval cannot create
competence, licensure, a prescription, or provider acceptance. [HitL](../../adr/25-hitl.md) binds
one exact eligible proposal; the applicable clinical and effect owner still rechecks authority at
execution time.
Clinical material is local and purpose-limited by default. Imports, remote inference, lookup,
retained media, sharing, research, export, and deletion have separate revocable permissions and
retention rules. The minimum necessary typed result may cross a boundary. A complete record,
credential, identifier, image, diagnosis, medication list, or genetic result never follows a
shopping, fitness, or household request merely because it might be useful.
[Wellbeing](../wellbeing/index.md) keeps ordinary eating, movement, and reflective check-ins. It may
receive an explicitly approved constraint such as a prohibited ingredient or movement limit,
without receiving its diagnosis or record history. Health may admit an exact patient-reported
observation from Wellbeing only with purpose-specific consent; neither owner rewrites the other.
Settled external clinician, laboratory, pharmacy, or health-record results enter as attributed
references. Live coordination with them would require a separately accepted Suite or integration
contract, not ambient access from this Composition.
## Recovery and falsification
Retain profile, case, source, policy, and Pattern revisions with every accepted fact and proposal.
Corrections must preserve earlier claims and invalidate dependent pending proposals; these
references identify the affected work. On restart, resume only exact compatible work without duplicating an import or approval.
A request or missing acknowledgement cannot establish that a test was ordered, medicine dispensed,
a dose taken, or treatment completed. Settle pending external effects through receipts,
reconciliation, or qualified handoff.
The smallest falsifying fixture uses a wholly synthetic adult and fabricated photographs: a
two-page discharge note, a duplicated laboratory report, one illegible medication line, and a
typed new symptom. It must preserve page regions and extraction gaps, refuse a conflicting patient
identity, keep OCR separate from accepted facts, surface contradictory dates and units, stop on a
red flag, and produce a diagnostic proposal without declaring a diagnosis. A care proposal must
park for an exact authorized verdict, become stale after a relevant profile correction, survive
restart without duplicate approval, and support bounded export and deletion without erasing a
retention blocker. No real patient, provider, live health account, prescription, emergency call,
test order, purchase, or treatment enters the proof.
---
[Composition portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Health record assimilation"
plain_name: "Health: importing medical records"
section: "Compositions > Stewardship & Acquisition > Health"
status: "Designed"
original: https://hexanomicon.dev/compositions/health/assimilation/
guide: https://lychd.snayu.ai/docs/compositions/health/assimilation/
---
# Health record assimilation (Health: importing medical records)
## Plain-English summary (Snayu)
**What it is:** How Health turns photographed or typed medical records into source-linked claims and, after review, a new profile revision, keeping originals, OCR and extracted claims separate.
**Why it matters:** Read when building medical document intake, OCR or the health profile.
- Each claim points to its exact source region and says who asserted it and how.
- Illegible values, conflicting dates and mixed identities stay explicit, never guessed.
- Deletion returns a content-free receipt; legal retention obligations remain named blockers.
**Status:** Designed
## Original text (Hexanomicon)
The Magus can photograph a finite medical record, attach an existing document, or describe a
health event in their own words. `health.assimilate_record@1` turns that bounded intake into
reviewable claims and, only after admission, a new `HealthProfile@1` revision.
## Keep the source and the claim apart
First retain the source in `ClinicalSource@1`: the person it claims to describe, source kind and
custodian, capture and clinical dates, page order, digest, purpose, consent, privacy and retention
policy, and permitted processing. Subsequent crops, rotations, contrast changes, transcriptions,
OCR passes, translations, or structured extractions create traceable derivatives of that source.
At every stage, imported content remains data and cannot instruct the system or grant wider access.
OCR records text, page and image regions, confidence, extractor and configuration revisions,
coverage, unsupported regions, and transformations. It does not replace the image. A model may
propose document type, field meaning, units, code expansion, chronology, and likely duplicates,
but each `ExtractedClinicalClaim@1` points to the exact source region and says whether it is:
- patient reported, document extracted, clinician authored, laboratory reported, model proposed,
deterministically derived, or human confirmed;
- verbatim, normalized, translated, or inferred;
- accepted, rejected, disputed, superseded, or unresolved.
Illegible text, cropped values, missing pages, uncertain decimals, mixed identities, conflicting
dates, and incompatible units remain explicit. The pipeline cannot complete a medication name,
dose, allergy, diagnosis, or test result from plausibility. Duplicate detection links acquisition
paths without deleting distinct originals or silently merging people.
## Build a corrigible profile
The reviewed profile can organize demographics needed for care, allergies and intolerances,
medications, conditions, procedures, immunizations, family and social history, measurements,
laboratory results, clinician instructions, patient testimony, attachments, and unresolved
questions. These are typed views over attributed claims, not one flattened biography. Sensitive
categories such as genetics, reproductive health, mental health, substance use, and identity
documents require explicit category and purpose admission.
An operator accepts, corrects, or rejects proposed claims in a bounded review. Corrections append
new attributed revisions and identify dependent cases and proposals that became stale. A newer
report can supersede a value without rewriting what an earlier report said. Silence confirms
nothing.
## Partial completion and departure
Intake can finish even when parts of the source remain unresolved. Return the accepted claims
alongside an exact list of unread, unsupported, disputed, or unreviewed regions. Cancellation
stops new processing and keeps only material allowed by intake policy. On restart, use source
digest, acquisition identity, processing revision, and completed-region receipts to avoid duplicate
work. A changed source must still enter as new evidence.
Export names the exact profile and source revisions included. Deletion stops new processing and
sharing, removes permitted originals and derivatives, and returns a content-free receipt; legal or
clinical retention obligations remain named blockers rather than being bypassed. Restored backups
must reapply deletion tombstones before reopening material.
---
[Health](index.md) · [Consultation](consultation.md)
---
title: "Health consultation"
plain_name: "Health: one health question"
section: "Compositions > Stewardship & Acquisition > Health"
status: "Designed"
original: https://hexanomicon.dev/compositions/health/consultation/
guide: https://lychd.snayu.ai/docs/compositions/health/consultation/
---
# Health consultation (Health: one health question)
## Plain-English summary (Snayu)
**What it is:** How Health reviews one bounded health question against the reviewed profile and proposes next diagnostic steps without declaring a diagnosis.
**Why it matters:** Read when building symptom review, red-flag checks or diagnostic proposals.
- Emergency rules are checked first; no match is not a safety guarantee.
- Proposals list explanations, contradictions, gaps and the professional role required.
- Test results return through record import and open a new case revision.
**Status:** Designed
## Original text (Hexanomicon)
`health.review_case@1` answers one bounded health question against exact profile and source
revisions. The useful result may be a clearer history, a set of plausible explanations, the next
discriminating observation or test to discuss with a clinician, or an honest stop.
## Open one case
`HealthCase@1` binds the person's reviewed profile revision, question, symptom onset and course,
patient testimony, available measurements and records, unavailable evidence, purpose, urgency,
decision role, jurisdiction or provider context when relevant, and time and privacy bounds. It
does not absorb the whole profile by default. The patient reviews the case summary before it is
used or disclosed.
The consultation first checks declared emergency and escalation rules. A matched red flag returns
an emergency handoff with the triggering evidence and uncertainty. No match means only that the
finite check did not match; it is not clearance, monitoring, or a guarantee that waiting is safe.
## Propose diagnostic work without manufacturing a diagnosis
The review keeps observations, assertions, hypotheses, and established external diagnoses
separate. It can summarize supporting and contradicting evidence, ask focused questions, and rank
candidate explanations only under a pinned knowledge and policy revision. Missing evidence and
limits accompany every rank. Popularity, model confidence, and a clean-looking OCR result do not
establish a diagnosis.
Record the proposed next step in `DiagnosticProposal@1`, tied to the case and profile revisions.
Include candidate explanations, rationale, contradictions and information gaps, then describe the
proposed examination or test, prerequisites, burdens and risks, alternatives, expected
discriminating value, urgency, stop conditions, required professional role, and expiry.
The resulting proposal may call for self-observation, routine clinician discussion, urgent
handoff, or an honest stop as an exact blocker, refusal, or unresolved case. It cannot itself
order a test, certify necessity, interpret an unseen result, or promise access.
An accepted external test order remains the external clinician's act. A returned result enters
through [assimilation](assimilation.md) with its author and source intact, then opens a new case
revision; it never silently settles an earlier hypothesis. Consultation can finish while the
external diagnostic path remains pending.
## Stopping and recovery
Conflicting identity, an unreviewed high-impact field, inadequate evidence, exhausted budget,
unsupported population, unavailable qualified authority, or an emergency boundary can stop the
case. A proposed next step requires its own exact approval when it would disclose data, spend
money, create an appointment, order a test, or cause another effect.
Restart recovers the last committed case and proposal. A changed symptom, medication, allergy,
source, profile, policy, or knowledge revision invalidates the affected pending proposal instead
of borrowing its prior approval. Missing provider acknowledgement leaves the external action
unknown and blocks blind retry.
---
[Health](index.md) · [Care planning](care.md)
---
title: "Health care planning"
plain_name: "Health: treatment options and follow-up"
section: "Compositions > Stewardship & Acquisition > Health"
status: "Designed"
original: https://hexanomicon.dev/compositions/health/care/
guide: https://lychd.snayu.ai/docs/compositions/health/care/
---
# Health care planning (Health: treatment options and follow-up)
## Plain-English summary (Snayu)
**What it is:** How Health compares treatment options for human review, binds an exact approval, and records follow-up of what actually happened.
**Why it matters:** Read when building care proposals, approval screens or adherence tracking for health.
- A proposal is not a prescription; approval is not administration.
- Approving one option covers no alternatives, refills or purchases.
- Follow-up records confirmed events only; reminders or silence prove nothing.
**Status:** Designed
## Original text (Hexanomicon)
A reviewed case can lead to several treatment options, each resting on facts and assumptions
that the person and qualified professional need to see. `health.plan_care@1` develops those
options from externally established facts or explicitly declared diagnostic assumptions.
`health.follow_up@1` later records what the person or qualified professional says happened.
Keep each step distinct: a proposal is not a prescription, a verdict is not administration, and
a plan is not evidence of adherence or benefit.
## Compare care options
`CareProposal@1` binds the person, profile and case revisions, clinical basis and unresolved
assumptions, goal, option, evidence scope, expected benefit, material risks, contraindications and
interactions checked, unknown interactions, alternatives including no action, required clinician
or prescriber, monitoring, escalation and stop conditions, duration, review date, and expiry.
Unsupported dose conversion, incomplete medication or allergy review, or missing authority blocks
the affected option.
The Composition may explain externally issued instructions and prepare questions for a clinician.
It cannot issue or renew a prescription, alter a dose, recommend stopping prescribed medication,
claim an interaction check is complete beyond its admitted sources, or convert patient consent
into professional authorization. Low-risk self-care, clinician-supervised treatment, medication,
procedure, rehabilitation, and watchful waiting remain distinct effect classes with distinct
policy.
## One exact human verdict
When an option is eligible for HitL, its call binds the exact person and case; profile and evidence
revisions; diagnostic basis; intervention, medicine or device identity; dose, route, frequency,
duration and timing where applicable; prerequisites, monitoring and stop conditions; actor and
required qualification; disclosures and destination; cost ceiling; policy revision; and expiry.
Any clinically relevant change creates a new call. Approval of one option does not approve its
alternatives, refills, substitutions, later cycles, purchases, sharing, or administration.
The person making this verdict needs to see the choice and its consequences together. The Altar
should show evidence for and against the option, unresolved fields, likely and severe risks,
alternatives, reversibility, the required professional role, and what approval can and cannot
cause. Denial closes that proposal without effect; revision returns to planning. Approval
authorizes only an eligible next effect, which its owner must recheck. It does not attest safety
or outcome.
Prescription, test ordering, dispensing, booking, payment, device control, and treatment delivery
remain external effects until separately governed owners are accepted and integrated. A
human-entered confirmation or attributable external receipt may record one of them. Missing
acknowledgement remains unknown and must be reconciled before retry.
## Follow up without inventing success
`HealthFollowUp@1` can record a confirmed start, dose or session, skip, deviation, symptom change,
measurement, adverse event, patient reflection, clinician assessment, stop, or unknown outcome,
each with source, time, uncertainty, and linked proposal. A reminder, purchase, dispensation,
schedule, silence, or model inference proves none of these.
Adverse events and red flags stop ordinary progression and return the applicable professional or
emergency handoff. Follow-up may propose a review; it cannot automatically escalate a dose,
continue an expired plan, punish non-adherence, or suppress contradictory testimony. Restart
recovers exact receipts and pending unknown effects without duplicating a treatment event or
reusing an obsolete verdict.
---
[Health](index.md) · [Consultation](consultation.md)
---
title: "Wellbeing"
plain_name: "App: Wellbeing (food and movement)"
section: "Compositions > Stewardship & Acquisition"
status: "Designed"
original: https://hexanomicon.dev/compositions/wellbeing/
guide: https://lychd.snayu.ai/docs/compositions/wellbeing/
---
# Wellbeing (App: Wellbeing (food and movement))
## Plain-English summary (Snayu)
**What it is:** Wellbeing helps one adult plan meals and ordinary exercise that fit their restrictions, time and kitchen, edit the plan, and record what actually happened.
**Why it matters:** Read before working on meal planning, fitness plans or daily check-ins.
- An impossible plan ends honestly as infeasible.
- Only a minimal food need goes to Homestead; private health data never crosses.
- No diagnosis, clinical advice or safety claims about food or exercise.
**Status:** Designed
## Original text (Hexanomicon)
A plan must fit the person who will live it. Wellbeing helps one consenting adult choose food and ordinary movement, revise those choices, and record what actually happened. An impossible plan can end as honest infeasibility. A skipped activity can remain a skip without becoming a verdict about the person.
Imagine planning the next three days with limited time, a small kitchen, and food already in the house. [Profile](profile.md) establishes the reviewed restrictions and preferences. [Eating](eating.md) checks meals and preparation; [Fitness](fitness.md) fits movement into the same person's limits. [Journal](journal.md) receives confirmed events and the Magus's own words after the day is lived.
## Contract
`wellbeing` revision `1` publishes principal Pattern `wellbeing.plan_cycle@1`. Planning begins with a consented adult profile, enabled modes, hard restrictions, soft preferences, time, equipment, and an attributable `InventorySnapshot@1` when availability matters. It can return an editable food-and-movement plan, infeasibility, or a purpose-limited `FoodNeed@1`.
The Composition also keeps confirmed check-ins and reflection through the separate Patterns described in [Journal](journal.md). Confirmation of eating or movement comes through an explicit `wellbeing.check_in@1`; planning cannot supply it.
Wellbeing retains the profile and plan revisions, restrictions, preferences, journals, check-ins, schedules, exports, and deletion records that make the cycle reviewable. The Magus approves each profile, plan, share, external use, export, and deletion. A Mind can propose choices and explain them, while deterministic tools check units, ingredient closure, hard constraints, typed handoffs, and deletion.
## One person's cycle
An approved meal may reveal missing ingredients. Only the minimal food need crosses to [Homestead](../homestead/index.md), which owns stock, recurring provision, and confirmed preparation transformations. Wellbeing chooses what fits the person; it neither sources products nor changes household stock, carts, checkout, or payment. Taste remains corrigible testimony.
This application makes no diagnosis, treatment, clinical or supplement recommendation, or claim
that food or movement is safe. [Health](../health/index.md) separately owns admitted clinical
records and bounded diagnostic and care proposals; its authority does not flow back into a
Wellbeing plan. Children, pregnancy and postpartum, eating-disorder support, rehabilitation,
clinical conditions, biomarkers, medication interactions, and emergencies remain outside this
office. Private health material never follows a shopping request.
## Proving the cycle
A network-disabled synthetic adult fixture should produce a three-day plan from a reviewed food catalogue and inventory snapshot. It must expose ingredient and activity conflicts, unresolved units and infeasibility; permit edit and approval; pass only minimal `FoodNeed@1`; and preserve confirmed and skipped check-ins through restart, export, and deletion without duplicates. No real person, merchant, account, receipt, address, payment, health record, or external lookup enters that proof.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Profile"
plain_name: "Wellbeing: personal profile"
section: "Compositions > Stewardship & Acquisition > Wellbeing"
status: "Designed"
original: https://hexanomicon.dev/compositions/wellbeing/profile/
guide: https://lychd.snayu.ai/docs/compositions/wellbeing/profile/
---
# Profile (Wellbeing: personal profile)
## Plain-English summary (Snayu)
**What it is:** How Wellbeing stores a person's restrictions, preferences, equipment and consent as immutable revisions with provenance, plus export and deletion.
**Why it matters:** Read when building the Wellbeing profile, consent or deletion flows.
- Each fact records its source: user-entered, imported, model-proposed, derived or confirmed.
- Hard restrictions relax only through a confirmed new revision.
- Deletion closes admission, removes data, verifies and leaves a content-free receipt.
**Status:** Designed
## Original text (Hexanomicon)
A preference can change. A hard restriction needs an explicit, confirmed successor before planning may relax it. Profile keeps that difference visible instead of turning yesterday's input into a permanent claim about the person.
`wellbeing.profile@1` seals an immutable revision of restrictions, preferences, time, equipment, enabled modes, consent, and privacy choices. Every fact retains its provenance: `user_entered`, `source_imported`, `model_proposed`, `deterministically_derived`, or `user_confirmed`. A proposed interpretation cannot pass as a confirmed human constraint.
Storage and inference are local by default. Remote providers, lookup, reminders, retained media, calorie or weight features, imports, sharing, export, and research each require revocable consent for their purpose. Journals, measurements, symptoms, diagnoses, medication, clinical records, movement history, and genetics stay out of Homestead, shop queries, catalogues, carts, providers, and merchant messages.
The same custody boundary governs departure. Use `wellbeing.export@1` for the approved export. For deletion, `wellbeing.delete@1` first closes admission, disables schedules, and drains atomic work. It then removes permitted records and derivatives, verifies their absence, and leaves a content-free receipt. Before a restored backup reopens data, it must reapply the deletion tombstones.
Return to [Wellbeing](index.md), or use the reviewed profile in [Eating](eating.md) and [Fitness](fitness.md).
---
title: "Eating"
plain_name: "Wellbeing: meal planning"
section: "Compositions > Stewardship & Acquisition > Wellbeing"
status: "Designed"
original: https://hexanomicon.dev/compositions/wellbeing/eating/
guide: https://lychd.snayu.ai/docs/compositions/wellbeing/eating/
---
# Eating (Wellbeing: meal planning)
## Plain-English summary (Snayu)
**What it is:** How Wellbeing plans meals from restrictions, available food, time and equipment, with strict hard-constraint checks and minimal handoffs to Homestead.
**Why it matters:** Read when building meal planning, ingredient checks or the food handoff to household stores.
- Candidates are blocked, unresolved or eligible; never labelled safe.
- Unknown quantities stay unknown; units convert only with sourced data.
- Only an explicit check-in confirms what was eaten.
**Status:** Designed
## Original text (Hexanomicon)
A cupboard can contain ingredients without containing a feasible meal. Eating turns reviewed restrictions, available food, time, and equipment into choices the Magus can edit, approve, or reject. It also provides preparation guidance; a suggestion records neither cooking nor consumption.
## Plan under hard constraints
The food mode of `wellbeing.plan_cycle@1` pins profile, consent, policy, Pattern, reviewed food catalogue, tools, provider, and any `InventorySnapshot@1`. Deterministic checks traverse ingredients to a finite depth and classify each candidate as `blocked`, `unresolved`, or `eligible`. The interface never translates eligible into “safe.”
An unknown package quantity stays unknown. Decimal arithmetic preserves dimensions; volume becomes mass only through sourced ingredient-specific density. Serving, 100 g, and whole-package bases remain distinct. Neither a model nor a convenient recipe may invent identity or quantity to make the arithmetic close.
Exclusions, equipment, time windows, and operator maxima are hard gates. Variety, convenience, and cost influence the remaining choices. When no choice passes, the result is no feasible plan. Eating does not certify kitchen cross-contact or medical safety.
## Minimal Homestead handoff
[Stores](../homestead/stores.md) supplies only the food identity, quantity interval, location class, freshness or expiry evidence, storage-condition uncertainty, and provenance in `InventorySnapshot@1`. Whole receipts, credentials, payment, addresses, and unrelated stock remain at home with their owner.
If an approved plan lacks ingredients, send only what [Provision](../homestead/provision.md) needs in `FoodNeed@1`: quantities, declared exclusions, useful product traits, expiry, privacy class, and unresolved flags. Keep diagnosis, journal, measurement, medication, genetics, movement history, and merchant instructions out of it. When `ProvisionResult@1` returns, Eating uses its availability evidence to decide whether the plan still fits.
After the meal, only an explicit `wellbeing.check_in@1` can confirm eating or substitution and send a minimal consumption event for stock reconciliation. A purchase, recipe, prepared household lot, plan, or silence cannot establish what the person ate. Eating itself never sources products, mutates stores, builds carts, or pays.
Return to [Wellbeing](index.md).
---
title: "Fitness"
plain_name: "Wellbeing: movement plans"
section: "Compositions > Stewardship & Acquisition > Wellbeing"
status: "Designed"
original: https://hexanomicon.dev/compositions/wellbeing/fitness/
guide: https://lychd.snayu.ai/docs/compositions/wellbeing/fitness/
---
# Fitness (Wellbeing: movement plans)
## Plain-English summary (Snayu)
**What it is:** How Wellbeing fits ordinary exercise within the person's time, equipment and limits, and records only confirmed outcomes.
**Why it matters:** Read when building fitness planning or exercise check-ins.
- Hard limits are checked before preferences; otherwise the plan is infeasible.
- Pain reports halt automated progression without diagnosing anything.
- No calorie inference, gait analysis or penalties for missed activity.
**Status:** Designed
## Original text (Hexanomicon)
The plan called for movement; the day may call for a change. Fitness gives one consenting adult editable choices inside the reviewed profile's time, equipment, enabled mode, hard restrictions, and operator maxima.
In movement mode, `wellbeing.plan_cycle@1` checks those limits before considering softer preferences. If they cannot be met, return infeasibility for the Magus to consider when editing, approving, or rejecting the plan. What happened later is recorded separately: `wellbeing.check_in@1` records only confirmed completion, skip, substitution, duration, or reflection. Silence cannot fill in a missing result.
“My knee hurt” remains the operator's testimony and halts automated progression. It does not
establish an injury, cause, adherence judgment, or treatment. Fitness does not infer calorie
expenditure, analyze gait or form, contact clinicians, share automatically, or punish missed
activity. With purpose-specific consent, the exact testimony may enter a [Health](../health/index.md)
case as patient-reported evidence. Diagnosis, treatment, rehabilitation, clinical conditions,
biomarkers, medication interactions, and emergencies remain outside this office.
Return to [Wellbeing](index.md), or record the day in [Journal](journal.md).
---
title: "Journal"
plain_name: "Wellbeing: check-ins and journal"
section: "Compositions > Stewardship & Acquisition > Wellbeing"
status: "Designed"
original: https://hexanomicon.dev/compositions/wellbeing/journal/
guide: https://lychd.snayu.ai/docs/compositions/wellbeing/journal/
---
# Journal (Wellbeing: check-ins and journal)
## Plain-English summary (Snayu)
**What it is:** How Wellbeing records confirmed check-ins, skips, substitutions and the person's own reflections, separate from what was planned.
**Why it matters:** Read when building check-ins, reminders or cycle reviews.
- A plan is not evidence it happened; only check-ins confirm.
- Reviews give neutral counts and may suggest the next request.
- Reminders are opt-in and pausable, and never fill gaps in history.
**Status:** Designed
## Original text (Hexanomicon)
The meal was planned. Whether it was eaten is another fact, supplied by the person who lived the day. Journal preserves that distinction for check-ins, missed activities, substitutions, and reflection.
`wellbeing.check_in@1` records confirmed eating, completion, skip, substitution, duration, or reflection. `wellbeing.journal@1` preserves the Magus's words. A later `wellbeing.review_cycle@1` may return neutral counts and propose the next manual Intent. It cannot revise a plan or restriction, order goods, diagnose a pattern, or disclose history on that person's behalf.
Keep profiles, sources, plans, decisions, check-ins, journals, derived summaries, schedules, exports, deletion fences, and receipts separately attributable, so a summary cannot obscure where an account came from. Reminders may invite a check-in but cannot fill a blank in lived history. Their schedules are opt-in, timezone-aware, bounded, pausable, and revocable; missed reminders expire and reviews coalesce.
Restart resumes only compatible pinned work and creates no duplicate check-in, export, or deletion effect. [Profile](profile.md) owns the consent, export, and deletion journey. Return to [Wellbeing](index.md).
---
title: "Homestead"
plain_name: "App: Homestead (household stores)"
section: "Compositions > Stewardship & Acquisition"
status: "Designed"
original: https://hexanomicon.dev/compositions/homestead/
guide: https://lychd.snayu.ai/docs/compositions/homestead/
---
# Homestead (App: Homestead (household stores))
## Plain-English summary (Snayu)
**What it is:** Homestead tracks a household's equipment, energy and water, stores, ordinary shopping and maintenance, working from manual records or commissioned devices.
**Why it matters:** Read before working on inventory, shopping, home energy or water, or maintenance features.
- Five workflows: map site, reconcile stores, plan provision, apply environment, maintain site.
- Animal and plant care belong to Keeper and Cultivator; Homestead supplies resources.
- No unsafe energization, interlock bypass, hazardous repair or general robot authority.
**Status:** Designed. Revision 2 accepted design; no delivered implementation.
## Original text (Hexanomicon)
A shop receipt and a confirmed harvest arrive by different roads, but both change what the household may have in its stores. Homestead keeps the place and its material custody legible across a city flat or cottage: equipment, resources, ordinary provision, maintenance, and the observations behind them. It works with manual records as well as commissioned devices.
The Magus can enter through a practical question:
- [Stores](stores.md): what is present, and which receipt, harvest, transfer, or correction changed the estimate?
- [Provision](provision.md): what ordinary supplies are missing, and what happened to the cart or order?
- [Utilities](utilities.md): which resources are available, uncertain, or reserved, and which commissioned controls may be requested?
- [Maintenance](maintenance.md): which fault remains open, and what evidence would close it?
[Keeper](../keeper/index.md) owns animal and colony care; [Cultivator](../cultivator/index.md) owns growing cultures and their tending. Their needs and confirmed yields can enter Homestead without transferring biological judgment.
## Contract
`homestead.steward` revision `2` publishes five independently invocable Patterns:
| Pattern | Bounded result |
| --- | --- |
| `homestead.map_site@1` | `HomesteadPlan@1` and freshness-visible resource evidence |
| `homestead.reconcile_stores@2` | reconciled lots, `InventorySnapshot@1`, or purpose-limited `SupplySnapshot@1` |
| `homestead.plan_provision@2` | provision plan, cart, or `ProvisionResult@1` from an admitted need |
| `homestead.apply_environment@1` | `HomesteadEnvironmentResult@1` for one bounded resource or commissioned control request |
| `homestead.maintain_site@1` | bounded work order, verification, or unresolved fault |
The finer observation, balance, receipt, shop, cart, checkout, and control names remain proposed Spell contracts placed by these Patterns. One `map_site` casting cannot claim every household outcome.
Admission fixes a reviewed household boundary, assets and resource evidence, responsible people, provision policy, hazards, budgets, and commissioned device limits. Depending on its Pattern, the result may be `HomesteadPlan@1`, freshness-visible resource or stores ledgers, `InventorySnapshot@1`, a provision plan or cart, acknowledged/refused/unknown checkout, bounded work or control intents, alerts, or effect receipts.
## The household
Every request declares what kind of involvement is permitted: observation, advice, bounded
stewardship inside a live commissioned envelope, or deterministic safe containment. A Mind
interprets and proposes within that posture.
Tools make the checks that an explanation cannot replace. Units, identities, money, and
reconciliation establish what is being accounted for. Freshness, thresholds, resource balance,
and set-point limits constrain what can be requested. Effect predicates and idempotency govern
the admitted action. These checks remain deterministic; professionals, manufacturers, utilities,
merchants, controllers, and the Magus retain their own judgment. Schedules create finite
Occurrences.
Homestead maintains the household models, physical asset identity, resource policy, stores, recurring provision, forecasts, alerts, maintenance, and work orders, and admits its own effects. When that infrastructure supports living subjects, Keeper and Cultivator retain care profiles, subject histories, biological suitability, and care outcomes.
The household contract supplies no health or consumption judgment, unapproved purchase/disclosure, design certification, permits, construction, potability claim, unsafe energization, interlock bypass, hazardous repair, or general robot authority. There is no accepted general smart-home or physical-actuator Domain; [Multinode](../../adr/42-multinode.md), Workflow, Security, IAM, Vision, and host owners retain their boundaries.
## Portfolio seams
[Wellbeing](../wellbeing/index.md) decides what fits a consenting adult's eating and movement. [Scavenger](../scavenger/index.md) handles irregular, high-value, compatibility-heavy, property, and seller-negotiated acquisition. Exact inventory, needs, provision results, requirements, and confirmed consumption cross these seams. Credentials, private records, and authority stay with their owners. Scout supplies attributed research observations, never physical instructions.
Keeper and Cultivator may reference the same enclosure, greenhouse, tank, or circuit. Their placements and requirements remain separately owned. [Utilities](utilities.md#meet-an-environment-request) checks the joint commissioned envelope; a technical acknowledgement establishes no animal or plant care outcome. Settled needs, yields, and receipts need no Suite. Starting and recovering several owners' live work follows the [Suite boundary](../products-and-suites.md#homestead-keeper-and-cultivator).
Coordinates, plans, camera material, and device access remain restricted throughout the work. Before deletion removes permitted material, revoke grants, disable schedules and checkout, drain or contain admitted motion, and inventory hazards, orders, and handoffs. Keep external merchant and other custody explicit after local removal.
## Proving the household
The required network-disabled flat-and-cottage fixture combines pantry/cold stores, feed and substrate lots, a synthetic receipt, bounded Kaufland/Lidl offers, attributed yield receipts, PV/battery/BMS, well/tank, segmented devices, and a watering droid. Follow these linked checks:
- Reconcile stores and provision through receipt correction without inferred consumption, minimal Wellbeing handoffs, and unknown-checkout recovery.
- Import a yield twice and correct it without duplicate stock; keep feed issued distinct from animal consumption.
- Test shared-enclosure demands through conflicting requirements, stale-sensor refusal, reserve-aware advice, and bounded irrigation without assuming biological success.
- Restart without duplicate commands or orders, then complete export and deletion.
Live merchants, accounts, addresses, payments, mains, batteries, pumps, wells, cameras, networks, robots, permits, and construction remain outside the slice.
## Revision continuity
Revision `2` retains Homestead's place, stores, provision, and maintenance ownership. It retires revision `1`: cultivation is extracted into the new `cultivator.cultivation` identity, and `homestead.tend_land@1` has no executable alias. [The former cultivation route](cultivation.md) preserves that boundary. Keeper's animal-care contract is new work, not a renamed Homestead Pattern.
The new stores and provision Pattern revisions admit attributed care supplies and yield handoffs; `InventorySnapshot@1` and `ProvisionResult@1` keep their existing meaning. Existing Product, Suite, or profile pins require explicit review before selecting revision `2`; no pin silently follows the successor. Revision `1`, including its original five-Pattern catalogue, remains meaningful in history. No registry, Run, or stored Composition record used it, so there is no executable data migration. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery evidence.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Utilities"
plain_name: "Homestead: energy and water"
section: "Compositions > Stewardship & Acquisition > Homestead"
status: "Designed"
original: https://hexanomicon.dev/compositions/homestead/utilities/
guide: https://lychd.snayu.ai/docs/compositions/homestead/utilities/
---
# Utilities (Homestead: energy and water)
## Plain-English summary (Snayu)
**What it is:** How Homestead observes and balances energy, water, fuel and network resources, and handles environment requests from Keeper or Cultivator within commissioned device limits.
**Why it matters:** Read when working on solar and battery logic, water control, or device actuation.
- Local battery, inverter, pump and fire vetoes always win.
- LychD sends typed requests, never prompt-made shell or relay commands.
- The home must stay safe without internet, model or cloud.
**Status:** Designed
## Original text (Hexanomicon)
Before spending the afternoon's solar surplus, the household must know what remains reserved for the night. Utilities makes energy, water, gas or stored fuel, network, and device systems separately inspectable. It can observe, advise, or request an effect inside a commissioned envelope.
## Map and observe
`homestead.map_site@1` creates `HomesteadPlan@1` from the dwelling, water points, circuits, critical loads, generation, storage, fuel/service boundaries, network zones, devices, work zones, hazards, unknowns, and professional or permit needs. `homestead.observe_cycle@1` checks the attribution, calibration, age, and contradictions in bounded telemetry and weather before updating a ledger or showing a gap.
A device report, calibrated derivation, and reconciled estimate are different evidence stages. Energy, water, fuel, habitat, network, camera, and embodied-node ledgers keep their own truth. Observations, calibration, forecasts, plans, alerts, approvals, commands, receipts, laboratory evidence, professional documents, and configuration retain independent revisions. Gas and fuel remain observe-or-advise only: this contract supplies no burner, combustion, or valve-control Pattern.
## Balance without bypass
`homestead.balance_energy@1` uses critical-load policy with PV, load, battery, grid, alarm, and forecast evidence. Its advice or exact set-point intent stays inside inverter, BMS, anti-islanding, thermal, fire, and electrician-set protection. Model/GPU work is an ordinary household load. A finite surplus window may inform compute admission, but cannot schedule a model job, grant peer authority, or outrank refrigeration, habitat, communications, water, safety, or the declared battery reserve.
`homestead.guard_water@1` works from well, tank, pressure, quality, weather, and allocation evidence. Pump or valve intent remains inside dry-run, pressure, level, freeze, contamination, and reserve interlocks. Sensor readings cannot establish potability.
The freshest local BMS, inverter, pump, float, pressure, and fire veto wins. Each effect binds asset/controller identity, configuration generation, commissioned envelope, live observations, preconditions, expiry, local reservation, expected postcondition, and compensation or containment. LychD sends typed requests; it does not emit prompt-produced shell, bus, GPIO, relay, or manufacturer commands.
## Meet an environment request
A greenhouse needs water while an animal enclosure shares the same reserve. `homestead.apply_environment@1` receives an exact `KeeperEnvironmentNeed@1` or `CultivatorEnvironmentNeed@1`, or a reviewed household requirement, and proposes or admits one bounded environmental action. The care owner supplies suitability and source-reviewed needs. Homestead checks physical feasibility and its commissioned limits.
Before admitting the action, account for everyone it could affect. The site envelope must enumerate other affected occupants and their current admitted constraints, including shared water or energy consumers. Admission binds the exact need and originating owner, subject/placement/profile revisions, asset and controller generations, affected zones, units and bounds, resource ceiling, live evidence, validity window, and expected technical postcondition.
Unknown occupancy, expired requirements, conflicting bounds, or insufficient reserves yields a blocker or refusal. Arrival order and model preference cannot decide whose needs to discard. Return any feasible alternative to the affected owners for review.
After the attempt, `HomesteadEnvironmentResult@1` records the requirement and admission identities, action/attempt id, reserved and observed resource quantities, controller receipt and independent observations, technical result, and unresolved effects. Its outcome distinguishes a proposal, refusal, verified completion, partial completion, interruption, and unknown effect.
The receiving care owner then assesses what that technical evidence establishes for its subject. A command acknowledgement alone cannot prove the measured postcondition, and reaching a set-point cannot establish a biological care verdict.
For a [Legion](../../sepulcher/extensions/legion.md) body, the request carries only the fenced task, zone, resources, expiry, and stop conditions. Fresh body admission and local emergency control remain decisive. Lost acknowledgement blocks blind repetition until controller state, reservations, and effect evidence reconcile; cancellation cannot reverse already delivered water or heat. Ongoing environmental protection belongs to the commissioned local controller, even when an Invocation or network connection ends.
Keeper and Cultivator can use human observations and work without Homestead. Exact settled requirements and result references do not grant access to either owner's database. Live multi-owner initiation, waiting, cancellation, or recovery needs the separately admitted [Suite contract](../products-and-suites.md#homestead-keeper-and-cultivator).
## Follow the sun without moving the Lich
Beyond the household utility contract, a separately admitted coordination profile may offer delay-tolerant labor to a sovereign [A2A peer](../../adr/26-a2a.md) from fresh evidence of surplus PV, battery margin, and compatible compute. The offer is coarse, expiring, and bounded by energy, time, task class, and local policy. Raw household telemetry need not travel. The destination rechecks load, forecast, thermals, reservations, and safety margin; no remote scheduler can override its local veto.
Only bounded labor and admitted artifacts cross. Identity, private Graph, memory, household records, and infrastructure authority remain with the Lich. Context and Security separately admit egress. Price cannot widen those limits, and an unmeasured remote route cannot claim to be greener. Homestead supplies the energy evidence; the coordination profile must separately establish work admission, remote settlement, and recovery.
## Return to observed state
The household must remain safe without internet, Wi-Fi, Master, model, or cloud. Lost acknowledgement leaves a physical effect unknown until the exact controller and independent sensors reconcile it. Restore keeps admission closed while clocks, controller generations, envelopes, pending effects, alarms, and local state are checked. Replacement devices and changed calibration add evidence instead of rewriting history.
Return to [Homestead](index.md).
---
title: "Stores"
plain_name: "Homestead: pantry and stores"
section: "Compositions > Stewardship & Acquisition > Homestead"
status: "Designed"
original: https://hexanomicon.dev/compositions/homestead/stores/
guide: https://lychd.snayu.ai/docs/compositions/homestead/stores/
---
# Stores (Homestead: pantry and stores)
## Plain-English summary (Snayu)
**What it is:** How Homestead tracks food and supplies as lots with quantity ranges built from receipts, harvests, confirmed use and corrections.
**Why it matters:** Read when building receipt OCR, inventory reconciliation or supply snapshots for other apps.
- OCR is a proposal; models cannot invent barcodes or force totals to balance.
- Repeated events never deduct or add stock twice.
- Other apps get minimal snapshots; receipts and credentials stay home.
**Status:** Designed
## Original text (Hexanomicon)
The receipt says two packages; the photograph leaves their size uncertain. Stores keeps the evidence and a quantity interval until a correction resolves it. Pantry, fridge, freezer, cellar, and prepared food share this attributable custody. Feed, seed, substrate, and other care supplies keep their own identity, purpose, and storage constraints; their presence establishes no suitability for a person, animal, or culture.
## Evidence before quantity
`homestead.ingest_receipt@1` retains the admitted image or text, OCR geometry, merchant and transaction fields, exact money, line evidence, corrections, equations, and discrepancies. OCR is a proposal. A model cannot invent a barcode, merge package sizes, or force totals to balance.
Resolve product identity through GTIN or SKU, merchant product, named package, product family, then unresolved. Each lot keeps its source, location class, quantity interval, acquisition or harvest event, expiry evidence, storage uncertainty, and disposition.
`homestead.reconcile_stores@2` projects acquisition, accepted yield, confirmed consumption, disposal, transfer, correction, and preparation events into those intervals. Confirmed cooking may remove inputs and add a prepared output to household custody. It still says nothing about who ate it. A purchase, recipe, available ingredient, or silence proves neither consumption nor food safety.
## Care supplies and collected yields
`SupplySnapshot@1` exposes only the requested material identity, lot reference, quantity interval and units, purpose class, storage/expiry uncertainty, provenance, and snapshot revision/time. [Keeper](../keeper/feeding.md) and [Cultivator](../cultivator/tending.md) assess suitability from this minimal view; the human-food `InventorySnapshot@1` below remains unchanged. Credentials, receipts, unrelated lots, and private care records do not travel with either projection.
When an exact `KeeperCareEvent@1` or `CultivatorWorkEvent@1` confirms material issued from a named lot, reconcile it by source owner/event/revision and quantity with units. Repeated delivery of the event cannot remove stock twice. Likewise, the separate observations of feed offered, feed eaten, and leftovers disposed must not each deduct the original serving. Apply a later correction as an attributable adjustment, not another full deduction.
To bring collected material into stores, separately accept its exact `KeeperYieldReceipt@1` or `CultivatorHarvestReceipt@1` as a sourced lot. The receipt identifies source subject/culture, collection time, material, quantity interval/unit, condition uncertainty, and disposition. Deduplicate by source owner and collection-event identity, retain its revision, and reconcile amendments against the quantity already accepted.
Collection may have succeeded while stock acceptance is still pending. A missing import acknowledgement therefore never authorizes collecting again. Nor do live subjects, births, deaths, or projected yields automatically become stock. Even accepted custody supplies no food-safety, treatment, or consumption verdict.
## Minimal view for Wellbeing
[Wellbeing](../wellbeing/eating.md) receives only `InventorySnapshot@1`: attributed food identity, quantity interval, location class, expiry/freshness evidence, storage-condition uncertainty, and provenance. Merchant credentials, payment, addresses, whole receipts, and unrelated stock do not cross.
An explicit confirmed-consumption event may return for reconciliation. Journals, measurements, symptoms, diagnoses, medication, clinical records, movement history, and genetics have no place in the stores ledger. Unknown identity, quantity, condition, and expiry remain visible, and restart duplicates neither receipt acceptance nor reconciliation.
Return to [Homestead](index.md).
---
title: "Provision"
plain_name: "Homestead: shopping and orders"
section: "Compositions > Stewardship & Acquisition > Homestead"
status: "Designed"
original: https://hexanomicon.dev/compositions/homestead/provision/
guide: https://lychd.snayu.ai/docs/compositions/homestead/provision/
---
# Provision (Homestead: shopping and orders)
## Plain-English summary (Snayu)
**What it is:** How Homestead turns approved needs into shop offers, carts and a single checkout, reporting what became available, substituted or uncertain.
**Why it matters:** Read when building shopping, merchant integrations or checkout.
- Fetching, login, cart edits, address disclosure, ordering and payment are separate powers.
- Checkout rechecks price, stock and terms; material changes return to you.
- A missing merchant acknowledgement stays unknown until reconciled.
**Status:** Designed
## Original text (Hexanomicon)
An approved need is still several steps away from an order. Provision brings ordinary food, cleaning goods, toiletries, feed, substrate, and other consumables into shared household custody, keeping each step separately reviewable.
## From need to result
`homestead.observe_shops@1` admits dated, attributed offers from Kaufland, Lidl, another merchant, a local market, or another eligible source. A shop profile is independently revocable. Public fetch, rendered observation, authentication, cart mutation, address disclosure, order submission, and payment remain separate powers.
`homestead.plan_provision@2` brings policy, stores, budget, and offers together with the needs being supplied: `FoodNeed@1` from [Eating](../wellbeing/eating.md), `KeeperSupplyNeed@1` from [Feeding](../keeper/feeding.md), or `CultivatorSupplyNeed@1` from [Tending](../cultivator/tending.md).
Each need gives Provision enough information to find the supply: its originating owner and revision, required quantities and units, exclusions, useful product traits, validity/expiry, privacy class, and unresolved flags. The care owner retains the subject and profile behind that requirement. No diagnosis, care journal, measurement history, medication record, genetics, movement history, or merchant instruction accompanies it.
A supply's availability cannot establish biological suitability. A material substitution outside the reviewed need returns to its owner before approval and checkout; Homestead cannot weaken species, culture, or human-food constraints to finish a cart. Live-animal acquisition, breeding commitments, clinical treatments, and hazardous or regulated agricultural interventions are not ordinary-consumable checkout paths.
`homestead.build_cart@1` prepares the cart. Before `homestead.checkout@1` submits it once, it rechecks merchant, product, package, price, stock, fees, delivery, substitutions, recurring terms, disclosure, and worst-case budget. A material change returns to the Magus. Raw addresses, payment data, credentials, and one-time codes never enter prompts.
`ProvisionResult@1` closes this work by reporting what became available, unavailable, substituted, refused, or uncertain. Eating, health, and adherence require their own evidence. Keep offers, plans, carts, orders, deliveries, and reconciliation independently revisioned so a later correction can identify the affected step.
If the merchant acknowledgement is missing, checkout or payment remains unknown. Reconcile that effect before retrying. Restart cannot duplicate cart changes, orders, notifications, or delivery reconciliation.
Personal meal choice, preparation guidance, and eating out remain with Wellbeing; confirmed cooking becomes a stock transformation in [Stores](stores.md). [Scavenger](../scavenger/index.md) owns irregular, high-value, compatibility-heavy, property, and seller-negotiated acquisitions.
Return to [Homestead](index.md).
---
title: "Maintenance"
plain_name: "Homestead: repairs and maintenance"
section: "Compositions > Stewardship & Acquisition > Homestead"
status: "Designed"
original: https://hexanomicon.dev/compositions/homestead/maintenance/
guide: https://lychd.snayu.ai/docs/compositions/homestead/maintenance/
---
# Maintenance (Homestead: repairs and maintenance)
## Plain-English summary (Snayu)
**What it is:** How Homestead tracks a fault from first report through a bounded work order to verified closure, including parts sourcing and inspection cameras.
**Why it matters:** Read when building fault tracking, work orders or inspection features.
- A work order names asset, tools, expiry, stop conditions and expected verification.
- Cameras need purpose, masks and retention; no face recognition by default.
- Silence never closes a fault; verification evidence does.
**Status:** Designed
## Original text (Hexanomicon)
An inspection reports a leak. Before anyone can close the work, the household needs an account of the fault, the work requested, and the evidence of its result. Homestead's maintenance design follows that account from the first report through verification.
`homestead.maintain_site@1` can begin with an attributed alarm, inspection, runtime record, or calendar event. It may lead to containment advice, research, a bounded work order, verification, or an unresolved result.
## Begin with the fault record
An uncertain cause may call for research or containment advice before a work order can be defined.
If the work needs a part, the requirement passes to [Scavenger](../scavenger/index.md) with the compatibility, certification, serviceability, environmental, budget, and evidence requirements that a candidate must meet. Scavenger returns dated evidence about candidates and sellers. Purchasing a candidate and commissioning it each require their own admission.
## Define the work before acting
A work order identifies the asset and zone, the tools and resources, its expiry, and the conditions that require work to stop. It also says what verification is expected, so the result can be assessed against the work that was authorized. For the leak example, it could require a follow-up inspection of the same asset, with the findings reviewed before closure.
A human or droid works within that envelope. For controller-backed work, the local controller or emergency stop can refuse fresh work or halt work already underway, even after LychD admitted it. Human professional judgment remains with the responsible person. Design certification, construction, and hazardous repairs remain outside this contract. The [Homestead contract](index.md#the-household) gives the full exclusions, including permits, unsafe energization, interlock bypass, and general robot authority.
## Admit an inspection channel for its purpose
A future [Tether](../../sepulcher/extensions/tether.md) route could carry private inspection and exact approved controls. Principal identity and effect authorization would still be validated independently of network access. A public dashboard is never the fallback for that private route.
Where a camera is involved, its admission specifies the purpose, masks, active hours, viewers, and retention. Face recognition, neighbour surveillance, ambient audio, public streaming, and indefinite retention are absent by default. [Sight](../../sepulcher/extensions/prism/sight.md) may analyze an admitted feed; authority over the camera, site, maintenance work, and droid remains separately owned. An inspection view supplies evidence without extending the work order.
## Verify the effect before closing the work
An alarm opens work; silence does not close it.
Use the verification named in the work order to assess the result. A lost acknowledgement after an action leaves its effect unknown, so recovery must inspect the controller, independent evidence, open work, and remaining hazards before repeating the action or declaring completion. If that evidence cannot establish the required result, keep the work unresolved.
Return to [Homestead](index.md).
---
title: "Keeper"
plain_name: "App: Keeper (animal care)"
section: "Compositions > Stewardship & Acquisition"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/
guide: https://lychd.snayu.ai/docs/compositions/keeper/
---
# Keeper (App: Keeper (animal care))
## Plain-English summary (Snayu)
**What it is:** Keeper records the life of animals and colonies, from pets to livestock and ant colonies: identity, housing, life changes, feeding and care events.
**Why it matters:** Read before working on pet, livestock or colony care features.
- Five workflows: subjects, territory, lifecycle, feeding and care records.
- No clinical diagnosis or treatment authority.
- Deleting a record never means abandoning an animal.
**Status:** Designed
## Original text (Hexanomicon)
A queen arrives in a test tube. Months of observations, feeding, and changes of accommodation
must remain attached to the same colony. Keeper preserves that history for animals and colonies,
from a household pet to a livestock group. Its identity is `keeper.husbandry`, revision `1`.
Pet and livestock purposes may overlap; neither determines a subject's entire record.
## Enter through the work
| Reader journey | Pinned Pattern | Primary records |
| --- | --- | --- |
| [Identify a subject and preserve observations](subjects.md) | `keeper.record_subject@1` | `KeeperSubject@1`, `KeeperObservation@1`, `KeeperCareProfile@1` |
| [Assess accommodation and placement](territory.md) | `keeper.assess_territory@1` | `KeeperTerritory@1`, `KeeperPlacement@1`, `KeeperEnvironmentNeed@1` |
| [Review changing life requirements](lifecycle.md) | `keeper.review_lifecycle@1` | `KeeperLifecycle@1` |
| [Propose feeding and request supplies](feeding.md) | `keeper.plan_feeding@1` | `KeeperFeedingPlan@1`, `KeeperSupplyNeed@1` |
| [Record care and collected material](care.md) | `keeper.record_care@1` | `KeeperCareEvent@1`, `KeeperCareResult@1`, optional `KeeperYieldReceipt@1` |
These five Patterns are independently invocable. Each Invocation ends with a committed observation or assessment,
proposed plan, confirmed care result, refusal, blocked or infeasible result, partial result,
cancellation or interruption, or an explicitly unknown physical effect. Continuing subject
history does not create an endless Run. [Workflow law](../../adr/28-workflow.md) governs execution;
a proposal grants no authority to perform it.
## Admission, privacy, and recovery
Admission identifies the responsible keeper, custody and permissions, exact subject, placement and
care-profile revisions, the requested work, observe/advise/record posture, hazards and resource
limits, and permitted disclosures. Uncertain identity or suitability must
remain visible; insufficient evidence can stop a plan. Keeper supplies no clinical diagnosis or
treatment authority. Human-approved bounds and separately admitted owners constrain physical work.
A later keeper must be able to reconstruct what was known when care was planned or performed.
Retain relational links, record and profile versions, authored observation time and recording
time, actor and source, units and uncertainty, permitted attachment references, idempotency
identity, and correlation. Corrections preserve earlier claims, and current views derive from
that history. The same event identity with changed contents requires an explicit correction or
refuses as a conflict. Subject, placement, lifecycle, plan, and event references remain
independently versioned; an edit to one never silently changes a previously admitted action.
These records belong in local PostgreSQL under [persistence law](../../adr/06-persistence.md).
The logical contracts describe their meaning and relationships; they prescribe neither a physical
SQL schema nor a Markdown shadow database.
[Homestead](../homestead/index.md) owns optional infrastructure, supply custody, and commissioned
effects; [Cultivator](../cultivator/index.md) owns plants and cultivated fungi even in a shared
enclosure. Neither is required to record manual animal care. The [stewardship handoff](../products-and-suites.md#homestead-keeper-and-cultivator)
defines when exact references suffice and when a Suite must coordinate live work.
Minimize access to addresses, human photographs, and veterinary documents. Export and deletion
respect custody and retention. Deletion stops schedules and disclosure; pending care effects need
reconciliation or handoff before authorized erasure. Deleting a record never means abandoning or
releasing an animal. After restart, recover the last settled result and outstanding effects;
lost acknowledgments block blind retries.
## Falsifying fixture
The acceptance fixture begins a synthetic colony with uncertain
identity and counts in a tube; add an arena, then leave a move unconfirmed. Review seasonal mode
independently of placement. Duplicate a feeding event and lose its acknowledgment; reconcile exact
supply-use events without inventing consumption. Reuse the model for a dog with a pet role and a
hen group with a collected-egg receipt. Restart, correct an observation, export, and request
deletion. Fail the design if it duplicates an effect, assumes the move succeeded, collapses life
axes, or erases unresolved custody obligations.
---
[Composition portfolio](../index.md)
---
title: "Keeper subjects"
plain_name: "Keeper: animals and observations"
section: "Compositions > Stewardship & Acquisition > Keeper"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/subjects/
guide: https://lychd.snayu.ai/docs/compositions/keeper/subjects/
---
# Keeper subjects (Keeper: animals and observations)
## Plain-English summary (Snayu)
**What it is:** How Keeper establishes a durable identity for an animal, group or colony, attaches a reviewed care profile, and records observations.
**Why it matters:** Read when building animal records, lineage or observations.
- Uncertain species or counts stay uncertain.
- Splits, merges and transfers keep predecessor links.
- A species label cannot pick an unreviewed generic care schedule.
**Status:** Designed
## Original text (Hexanomicon)
A colony remains the same subject when its accommodation changes. Begin with
`keeper.record_subject@1` to establish a durable identity and attach evidence, producing
`KeeperSubject@1` and `KeeperObservation@1`.
## Establish identity without inventing certainty
A subject may be an individual, pair, group, or colony. Record its stable identifier, responsible
keeper and permissions, acquisition origin, species identification with confidence and care-profile reference,
age estimates, count intervals, membership and lineage, purpose roles, and status history. Pet and
livestock are non-exclusive roles. An uncertain identification remains uncertain when a later
observation is recorded.
An ant colony can reference an individually identified queen while keeping worker and brood
counts aggregate. Do not manufacture individual identities from an estimated count. Explicit
split, merge, and transfer events preserve predecessor and successor links, custody changes, and
effective times. Corrections cannot silently merge subjects or rewrite lineage.
For example, subject `colony-a` can link queen `queen-a`, placement `placement-1` in territory
`tube-t1`, a lifecycle review, and separate feeding and observation events. `placement-2` can later
refer to `formicarium-f1` without replacing `colony-a`. These are illustrative record keys, not
deployed database rows. The colony's current view joins those references; it is not one journal
entry whose latest text replaces the previous account.
## Keep the care profile attributable
Use `KeeperCareProfile@1` to retain the husbandry requirements being considered for the subject.
Keeper versions this profile with a stable id and revision, applicable species or group, source
references and dates, reviewed life/seasonal conditions, care requirements with units and bounds,
excluded or uncertain cases, and reviewer. It may be recorded alongside the subject through
`keeper.record_subject@1`.
Accepting that source material and admitting its use for a particular subject are separate
judgments. A species label cannot select an unreviewed generic care schedule. Each plan pins the
applicable profile revision; a successor identifies active plans that need review while leaving
previous care intact.
## Preserve the evidence
Each observation separates what was seen from interpretation, with effective and recorded times,
actor or source, units, uncertainty, applicable profile revision, and permitted attachment
references. Idempotency identity and correlation distinguish retries from new observations.
Amend an older claim through a linked correction; derive the current snapshot without erasing the
claim it replaces.
Shared enclosure flora and fauna need not fit an exclusive taxonomy. Keeper records animals and
their husbandry relationships; it does not put live animals into Homestead's stock ledger.
## Finish with a record
The outcome is a committed subject or observation, a partial record with named gaps, or a stopped
result explaining missing evidence or permission. Registration neither certifies species identity
nor authorizes acquisition, movement, or care. Export and deletion follow the custody and recovery
boundary in [Keeper](index.md).
---
[Keeper](index.md) · [Composition portfolio](../index.md)
---
title: "Keeper territory"
plain_name: "Keeper: housing and placement"
section: "Compositions > Stewardship & Acquisition > Keeper"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/territory/
guide: https://lychd.snayu.ai/docs/compositions/keeper/territory/
---
# Keeper territory (Keeper: housing and placement)
## Plain-English summary (Snayu)
**What it is:** How Keeper records enclosures, where an animal actually is, proposed moves, and environment requests sent to Homestead.
**Why it matters:** Read when building enclosure tracking or environment requests for animals.
- A proposed move stays proposed until confirmed.
- Missing measurements stay unknown.
- Environment needs are bound to exact revisions; local controller safety wins.
**Status:** Designed
## Original text (Hexanomicon)
Observed occupancy, accessible space, and suitable accommodation answer different questions.
`keeper.assess_territory@1` records their relationship through `KeeperTerritory@1`,
`KeeperPlacement@1`, and `KeeperEnvironmentNeed@1`.
## Describe the arrangement
For a generic ant-colony data model, colony A starts in test tube T1. Record the tube's dimensions,
material, setup condition, and nest zone. Later add arena A1 and formicarium F1 with their zones
and connections. Record where ants were observed, which connections permit access, and the
evidence supporting a suitability assessment separately. This example establishes no species
temperature, diet, diapause, or other care rules.
A proposed move names its source and destination and remains proposed until confirmed. A
confirmed move retains the same colony identity. Missing acknowledgment leaves placement effects
unknown; it does not establish arrival or justify repeating the move.
Each territory has an identity and arrangement revision; each placement links a subject to zones,
with proposed and observed occupancy intervals. Setup history includes water provision, substrate
or lining, ventilation, access barriers, cleaning, and observed condition where relevant to the
profile. Missing measurements stay unknown. A single colony may occupy connected zones, and one
enclosure may hold several separately identified subjects.
Keeper owns the husbandry arrangement even without sensors or Homestead. An actual device or
enclosure asset may reference [Homestead](../homestead/index.md); reuse its infrastructure record
instead of copying it. Shared enclosure relationships can include flora and fauna.
## Bound environmental requests
Before requesting an environmental change, record the conditions, source evidence, units,
observation freshness, validity and expiry, resource ceiling, uncertainties, and human-approved
bounds. Bind that environment need to its originating owner, subject, placement and profile
revisions, admission generation, and target zones/assets. A later profile or arrangement change requires review of whether the need still applies; these
references identify the requirements under review.
Once settled, the requirement can enter separately admitted [Homestead work](../homestead/utilities.md#meet-an-environment-request).
Keeper assesses the technical evidence returned in its exact `HomesteadEnvironmentResult@1`.
If one joint result must start and await that work, a Suite owns the coordination. Keeper's
assessment supplies neither controller credentials nor direct actuation authority, and local
controller safety takes precedence over the proposed husbandry condition.
## Finish with an assessment
The outcome is a committed assessment or proposed placement and environmental needs, including
unresolved suitability. Block or mark infeasible a request whose bounds cannot be supported.
Assessment does not execute relocation or prove a controller achieved a condition; confirmed
physical work returns through [care](care.md).
---
[Keeper](index.md) · [Composition portfolio](../index.md)
---
title: "Keeper lifecycle"
plain_name: "Keeper: life stages"
section: "Compositions > Stewardship & Acquisition > Keeper"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/lifecycle/
guide: https://lychd.snayu.ai/docs/compositions/keeper/lifecycle/
---
# Keeper lifecycle (Keeper: life stages)
## Plain-English summary (Snayu)
**What it is:** How Keeper reviews development, breeding, seasonal mode and placement as separate axes and proposes changed requirements.
**Why it matters:** Read when building lifecycle or seasonal tracking for animals.
- No universal life-stage sequence across species.
- Reduced activity does not prove seasonal mode, illness or death.
- Profile changes never silently change active plans.
**Status:** Designed
## Original text (Hexanomicon)
A seasonal review must not silently relocate a colony or declare its reproductive state.
`keeper.review_lifecycle@1` produces `KeeperLifecycle@1` by considering distinct axes together
without collapsing them into one stage.
## Review the relevant axes
Keep development, reproductive or brood observations, recurring seasonal mode such as diapause,
current placement, and care or health observations separately addressable. There is no universal
sequence covering a dog, a hen group, and a colony. A recurring seasonal mode can be reviewed
while placement and development remain unchanged.
For the colony example, a review may distinguish founding or worker growth from an observed
brood phase, a proposed or confirmed seasonal regime, and its current tube or formicarium
placement. The admitted profile defines applicable phases and evidence requirements. Preparation
for diapause, diapause, and return to activity are possible recurring regime labels, not a
universal timetable or the final stages of colony development. A mixed-age group retains its
cohorts or observations instead of assigning every member the same life stage.
Link observed behavior to its observation record. Identify model interpretation as interpretation,
with its source, uncertainty, effective time, and profile revision. An observation of reduced
activity does not itself establish a seasonal mode, illness, or death. Missing telemetry is not
evidence of death.
## Change requirements deliberately
When the evidence supports changed feeding or environmental requirements, use an admitted,
source-reviewed profile to propose them. Identify both the previous and proposed profile revisions
and the needs that require review. Dates or counts alone cannot authorize the transition, and
updating a profile cannot silently change an active plan. Refer any resulting work to
[territory](territory.md), [feeding](feeding.md), or [care](care.md), retaining explicit dependencies.
## Finish with a review
The result is a committed review, proposed requirements, or a partial or blocked result naming
missing evidence. It grants no diagnostic or treatment authority and performs no physical action.
Later observations start another finite review while preserving earlier interpretations and
corrections in the subject's history.
---
[Keeper](index.md) · [Composition portfolio](../index.md)
---
title: "Keeper feeding"
plain_name: "Keeper: feeding plans"
section: "Compositions > Stewardship & Acquisition > Keeper"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/feeding/
guide: https://lychd.snayu.ai/docs/compositions/keeper/feeding/
---
# Keeper feeding (Keeper: feeding plans)
## Plain-English summary (Snayu)
**What it is:** How Keeper proposes feeding plans from reviewed profiles, requests supplies from Homestead, and keeps food offered separate from food eaten.
**Why it matters:** Read when building animal feeding or supply requests.
- Available products are not automatically suitable.
- Offered, eaten, leftover and disposed amounts are separate records.
- Duplicate events never deduct stock twice.
**Status:** Designed
## Original text (Hexanomicon)
Food removed from storage is not proof that an animal consumed it. `keeper.plan_feeding@1`
produces a proposed `KeeperFeedingPlan@1` and any `KeeperSupplyNeed@1`, preserving that distinction.
## Propose from reviewed requirements
Tie a plan to its subjects, current life-state evidence, source-reviewed [care profile](subjects.md#keep-the-care-profile-attributable),
revision, and review window. Keep quantities, units, uncertainties, and exclusions explicit. These
contracts prescribe no generic food or clinical diet. Missing applicable evidence can block the
plan; a proposed substitution requires Keeper review before changing it.
Check stock and availability through exact Homestead `SupplySnapshot@1` and `ProvisionResult@1`
references. When supplies are needed, bind the request to its originating owner and revision and
include only necessary product traits, quantity and units, exclusions, purpose, validity/expiry,
privacy class, and unknowns. Raw husbandry histories and veterinary journals stay out of that
request. Keeper must still judge suitability; an available product is not thereby suitable.
## Reconcile distinct evidence
Record offered or delivered quantities separately from observed consumption, leftovers, and
disposal. Each has its own source, time, units, and uncertainty; unknown consumption stays unknown.
Confirmed feeding work is recorded through [care](care.md).
Use exact supply-use event identifiers to reconcile stock changes. Repeated delivery must resolve to the same event and must not remove stock twice or create a
second feeding. The stock
change still does not establish consumption. If an acknowledgment is lost, reconcile before
repeating physical work; correcting the ledger alone cannot establish whether feeding occurred.
## Finish with a proposed plan
Return a plan and bounded supply needs, or a partial, refused, blocked, or infeasible result.
Execution needs human confirmation or a separately admitted owner. Close the invocation when its
result is recorded; the plan's review window does not keep it open.
---
[Keeper](index.md) · [Homestead](../homestead/index.md) · [Composition portfolio](../index.md)
---
title: "Keeper care"
plain_name: "Keeper: care records and yields"
section: "Compositions > Stewardship & Acquisition > Keeper"
status: "Designed"
original: https://hexanomicon.dev/compositions/keeper/care/
guide: https://lychd.snayu.ai/docs/compositions/keeper/care/
---
# Keeper care (Keeper: care records and yields)
## Plain-English summary (Snayu)
**What it is:** How Keeper records care that was done (feeding, cleaning, transfers) and collected material like eggs or milk as yield receipts for Homestead stores.
**Why it matters:** Read when building care logs or yield handoff to stores.
- Intended and actual care are recorded together.
- A lost acknowledgement never justifies repeating care.
- Yield receipts give no food-safety verdict; duplicates add no stock.
**Status:** Designed
## Original text (Hexanomicon)
A missed due window is unfinished care, even when its reminder has expired.
`keeper.record_care@1` records `KeeperCareEvent@1` and `KeeperCareResult@1`, with an optional
`KeeperYieldReceipt@1` for confirmed collected material.
## Record what happened
For feeding completion, water inspection, cleaning, confirmed transfer, appointments, or other
care, record what was intended alongside what happened. Preserve the subject and placement
references, due window, actor, effective and recorded times, evidence, uncertainty, and outcome.
If professional instructions guided the work, link their exact reference and version. Recording
them does not broaden their authority: clinical diagnosis and treatment decisions remain with
the external professional.
Physical work belongs to a human or separately admitted owner. Local controller safety wins.
Distinguish proposed, confirmed, partial, missed, cancelled, interrupted, and unknown-effect work.
A lost acknowledgment cannot justify repeating feeding, cleaning, or a transfer. Reconcile the
effect and exact event identities first; record unresolved effects explicitly.
## Receive collected material
A yield receipt records confirmed eggs, milk, or other collected material with source individual
or group, collection-event identity and revision, actor, effective and recorded times, material,
quantity and units, condition and uncertainty, and disposition. A hen
group can remain a durable subject while successive collections produce separate receipts.
Neither birth nor death automatically creates a product or stock lot.
[Homestead](../homestead/index.md) separately accepts exact sourced lots, referencing the receipt.
Keeper's collection record supplies no food-safety or consumption verdict and does not equate
collection with acceptance into stores.
Duplicate receipt delivery cannot create another collection or stock lot. Amendments preserve
the original collection identity and trigger an explicit stock adjustment against prior acceptance.
## Finish or hand off
Close the invocation with the confirmed result, named partial completion, refusal, blockage, or
unresolved physical effect. A care schedule can identify future work after this invocation ends.
On restart, recover its settled result and reconcile pending effects before retrying.
Deletion also requires attention to unfinished care. Stop schedules and disclosure, then reconcile
or hand off pending obligations before authorized erasure. The animal's custody and welfare
obligations remain even when records are removed.
---
[Keeper](index.md) · [Composition portfolio](../index.md)
---
title: "Cultivator"
plain_name: "App: Cultivator (plants and fungi)"
section: "Compositions > Stewardship & Acquisition"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/
---
# Cultivator (App: Cultivator (plants and fungi))
## Plain-English summary (Snayu)
**What it is:** Cultivator records the life of plants and cultivated fungi: identity, growing space, cycles, tending and harvests, for ornament, food, seed or propagation.
**Why it matters:** Read before working on plant, garden or fungi features.
- Six workflows: cultures, space, cycle, tending, work records, harvest.
- Works with manual records; automation needs the controls' owner.
- No pesticide, diagnosis or food-safety authority.
**Status:** Designed
## Original text (Hexanomicon)
A plant changes pots; a bed produces several partial harvests. Cultivator keeps the growing
subject, its conditions, and the work behind each result connected across those changes.
The Native Reference Composition identity is `cultivator.cultivation`, revision `1`.
It covers plants and cultivated fungi for ornament, food, seed, or propagation; purpose is
independent of taxonomy and place.
## Contract and map
The record and Pattern catalogue follows [persistence law](../../adr/06-persistence.md) and
[workflow law](../../adr/28-workflow.md).
| Work and Pattern | Durable records |
| --- | --- |
| [Identify the culture and record observations](cultures.md)
`cultivator.record_culture@1` | `CultivatorCulture@1`, `CultivatorObservation@1`, `CultivatorGrowingProfile@1` |
| [Assess its growing space and placement](growing-space.md)
`cultivator.assess_space@1` | `CultivatorGrowingSpace@1`, `CultivatorPlacement@1`, `CultivatorEnvironmentNeed@1` |
| [Review its changing cycle](lifecycle.md)
`cultivator.review_cycle@1` | `CultivatorCycle@1` |
| [Plan tending and request supplies](tending.md)
`cultivator.plan_tending@1` | `CultivatorTendingPlan@1`, `CultivatorSupplyNeed@1` |
| [Record work and its result](tending.md#execution-and-results)
`cultivator.record_work@1` | `CultivatorWorkEvent@1`, `CultivatorWorkResult@1` |
| [Confirm a collected harvest](harvest.md)
`cultivator.record_harvest@1` | `CultivatorHarvestReceipt@1` |
These six Patterns are independently invocable. Enter through a culture's identity, its growing
space or lifecycle, the tending work due, or a collected harvest.
## Boundaries and admission
[Keeper](../keeper/index.md) owns animals and colonies; Cultivator owns plants and cultivated fungi.
[Homestead](../homestead/index.md) retains infrastructure, stores, and utilities.
Cultivator owns the cultivation capability extracted into its new identity; retired
`homestead.tend_land@1` is neither an alias nor reinterpreted history.
Admission fixes the responsible grower and permissions, exact culture/placement/profile revisions,
requested observe/advise/record work, source evidence, hazards, resource limits, and permitted
disclosure. Missing identity may permit an uncertain observation while blocking a specific action.
Manual evidence and human work remain valid without Homestead. Automation requires
separate admission by the owner of the actual controls. Deterministic safety checks
cannot establish biological appropriateness. Diagnostic authority, pesticide approval,
agricultural treatment permits, and food-safety certification remain outside this contract.
Use a [Suite](../products-and-suites.md) only for live start, await, retry, cancel,
or recovery across multiple owners. Settled references and receipts alone need no Suite.
## Privacy and recovery
Records remain local, Composition-owned PostgreSQL records under persistence law;
these logical contracts define record meaning and links, not physical tables or migrations.
Sharing selects exact records and purposes; there is no ambient database sharing. Media references
carry retention purpose because images can expose people and locations.
Each Invocation ends with the applicable result: a proposed plan, recorded completion, refusal,
infeasibility, partial, unknown, or interrupted outcome. During recovery, reconcile the exact
events and acknowledgments before taking new action.
Export keeps identifiers, corrections, evidence references, and custody metadata while care
continues. Deletion or an explicitly admitted custody migration requires more: close affected
schedules and resolve or hand off outstanding care and effect custody under the retention and
owner contracts. Closing a record does not remove a plant or dismantle its environment.
## First proof
The acceptance fixture must preserve a synthetic ornamental plant through repotting
and movement; split a seed batch into bed cohorts; refuse watering on unknown sensor
or reserve evidence; reconcile repeated partial harvest, duplicate import, and a
correction; exercise a perennial or fungi profile without universal stages; and recover
lost action acknowledgment after restart. Export must leave care active; deletion must close
affected schedules and settle or hand off custody.
Return to [Compositions](../index.md).
---
title: "Culture records"
plain_name: "Cultivator: plant records"
section: "Compositions > Stewardship & Acquisition > Cultivator"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/cultures/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/cultures/
---
# Culture records (Cultivator: plant records)
## Plain-English summary (Snayu)
**What it is:** How Cultivator identifies a plant, batch or fungi culture, tracks lineage through cuttings and splits, pins a growing profile and records observations.
**Why it matters:** Read when building plant records or lineage.
- Repotting keeps identity; a cutting creates a linked child.
- Unknown species stays explicit.
- Corrections keep earlier claims; current views derive from history.
**Status:** Designed
## Original text (Hexanomicon)
A cutting can start a new culture while its parent continues growing. A move to a larger pot
preserves the existing plant. Culture records keep those two kinds of change distinguishable.
## Identity and lineage
`CultivatorCulture@1` represents a plant individual, sowing or planting batch, bed
cohort, perennial, or cultivated fungi culture. A stable identifier survives a change
of name, purpose, placement, or responsible person. Record species and cultivar when
known; an unknown identification remains explicit.
The record carries name, source and provenance, responsible people, profile revision,
origin and lineage, current count or quantity intervals, and exact lifecycle and
placement references. Quantity includes units and uncertainty; an estimate is not an
exact census.
Propagation, division, and explicit group splits or merges retain parent references
and their evidence. A cutting may establish a linked child culture. Transplanting or
moving an existing plant preserves its identity. Repeated harvest does not create
replacement cultures or silently terminate the source.
## Pin the growing profile
The growing profile explains which reviewed requirements apply to this culture. Cultivator owns
that account as `CultivatorGrowingProfile@1`: stable identity and revision, applicable
species/cultivar or culture class, attributed sources and dates, reviewed cycle and tending
requirements with units and bounds, exclusions, unresolved cases, and reviewer.
`cultivator.record_culture@1` may record it alongside the culture.
Review must still establish whether a source recommendation fits this culture and growing space.
An active plan pins the reviewed profile revision; a replacement identifies which plans need
fresh review. Ornamental, food, and fungi profiles share this record discipline while retaining
their different cycles and care schedules.
## Evidence graph
`cultivator.record_culture@1` produces culture records and
`CultivatorObservation@1` evidence. Observed symptoms, interpretations, and expert
findings remain distinguishable. An observation records its subject, effective time,
recorded time, source or actor, evidence references, units, uncertainty, and applicable
profile revision.
Later work must be able to trace these observations, so preserve exact parent and artifact
references, correlation identifiers, and deduplication identity throughout the composition.
A late report keeps its actual effective time. A correction retains the earlier claim
and identifies what it supersedes; the latest view is derived from retained claims,
rather than overwriting history.
Replaying an event identity with different contents is a conflict unless admitted as an explicit
linked correction. Culture, placement, cycle, plan, and work revisions remain independent; changing
one cannot silently amend an already admitted action.
Placement, cycle, tending, work, and harvest records join through exact references.
No helper infers a missing collection, completed action, or healthy state from a gap
in that graph. Purpose-scoped media references carry retention context and access
boundaries alongside the evidence they support.
Return to [Cultivator](index.md).
---
title: "Growing space"
plain_name: "Cultivator: pots and beds"
section: "Compositions > Stewardship & Acquisition > Cultivator"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/growing-space/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/growing-space/
---
# Growing space (Cultivator: pots and beds)
## Plain-English summary (Snayu)
**What it is:** How Cultivator records containers, substrate and placement, and sends reviewed environment needs to Homestead.
**Why it matters:** Read when building growing-space tracking or plant environment requests.
- Unknown substrate or light is never treated as suitable.
- Planned transplants don't change actual placement until confirmed.
- Conflicting needs in shared spaces need explicit assessment.
**Status:** Designed
## Original text (Hexanomicon)
A pot may be suitable for one culture and poorly understood for another. Keep the container,
growing medium, occupants, and the evidence behind suitability separately inspectable.
## Place and arrangement
`cultivator.assess_space@1` produces `CultivatorGrowingSpace@1`,
`CultivatorPlacement@1`, and `CultivatorEnvironmentNeed@1`.
A growing space may be a pot, bed, greenhouse compartment, or indoor grow container.
It records substrate or growing medium, batch and change history, and evidence about
drainage, light, and other relevant conditions. These are evidence fields, not universal
care recommendations. Unknown substrate or light cannot become fabricated suitability.
Record where the culture actually is through its placement: the occupancy interval and count or
density estimates. Planning a transplant does not change that observation. Once movement is
confirmed, close the prior interval and establish another under the same culture identity. If
the move is uncertain, retain both its intended destination and the unresolved observation.
Cultivator owns this biological arrangement and the assessment of its suitability.
## Reviewed needs
To request a condition for a culture, record an environment need with a unit and reviewed desired
interval. Bind it to the originating owner, exact subject, growing-space and placement revisions,
target zones/assets, profile revision, and admission generation. Include freshness, validity,
expiry, resource limits, and supporting evidence. This lets review distinguish the desired range
from an actual measurement without losing uncertainty.
[Homestead utilities](../homestead/utilities.md#meet-an-environment-request) may receive exact place, asset, or
controller references and the reviewed need. The infrastructure owner retains actual
control limits and actuation authority; Cultivator's need does not grant them.
Without that connection, human work and manual evidence still support assessment.
An exact `HomesteadEnvironmentResult@1` supplies technical evidence; Cultivator separately
assesses what the result establishes for the culture. A shared physical asset has one
infrastructure record, referenced rather than copied into this biological arrangement.
A mixed habitat may link [Keeper placements](../keeper/territory.md). Each Composition retains its subjects
and needs; neither silently overrides the other's requirements. Conflicting needs
require an explicit assessment outcome before action, including infeasible or unknown
where the evidence cannot support a coherent arrangement.
Return to [Cultivator](index.md).
---
title: "Lifecycle"
plain_name: "Cultivator: growth cycles"
section: "Compositions > Stewardship & Acquisition > Cultivator"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/lifecycle/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/lifecycle/
---
# Lifecycle (Cultivator: growth cycles)
## Plain-English summary (Snayu)
**What it is:** How Cultivator reviews development and recurring seasons for annuals, perennials and fungi without forcing universal stages.
**Why it matters:** Read when building growth-stage or season tracking.
- Fungi don't inherit plant stages.
- Calendar dates alone cannot advance a stage.
- Missing reports prove neither health nor death.
**Status:** Designed
## Original text (Hexanomicon)
A perennial can enter another growing season without becoming a new subject. Cycle reviews
retain both the recurring season and the longer history that preceded it.
## Development and recurring cycles
`cultivator.review_cycle@1` produces `CultivatorCycle@1`, linking a culture,
its reviewed profile revision, evidence, and cycle history. Development, recurring
season, placement, and completed work are independent dimensions.
Annual, perennial, and cultivated fungi profiles may describe different cycles.
Fungi must not inherit botanically false plant stages. A perennial's recurring season
does not reset its identity or erase earlier development. Profile-qualified states
and transitions require evidence; calendar dates alone cannot advance a stage.
A newly reviewed profile does not silently rewrite earlier state claims. Record the
revision and evidence supporting each change, including corrections and unresolved
interpretations.
## Review boundaries
An observed symptom is distinct from an interpretation or expert finding. Missing
reports establish neither health nor death. Users may record suggestions and
professional guidance with their source; the composition claims no diagnostic,
pesticide approval, or food safety authority.
End each review with an evidence-supported change, refusal, infeasibility, or unknown outcome.
The growing season and a perennial's longer history continue as durable records across those
completed reviews, rather than keeping a Run open indefinitely. Tending completion and harvest
receipts can inform the next review, but neither automatically proves a developmental transition
or the end of the culture's life.
Return to [Cultivator](index.md).
---
title: "Tending"
plain_name: "Cultivator: watering and tending"
section: "Compositions > Stewardship & Acquisition > Cultivator"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/tending/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/tending/
---
# Tending (Cultivator: watering and tending)
## Plain-English summary (Snayu)
**What it is:** How Cultivator plans watering, repotting and pruning with safe bounds, requests supplies, and records what work actually happened.
**Why it matters:** Read when building tending plans, supply requests or work logs.
- Stale or unknown evidence cannot satisfy safety bounds.
- Partial work records both the result and the remainder.
- A lost acknowledgement means unknown; no blind retry.
**Status:** Designed
## Original text (Hexanomicon)
A bed needs water, but the latest tank reading is stale. Tending must preserve the need and the
resource uncertainty together until a reviewed plan can name feasible work.
## Assessed work
`cultivator.plan_tending@1` produces `CultivatorTendingPlan@1` and
`CultivatorSupplyNeed@1`. A coherent assessed plan links subjects, placement,
source evidence, and reviewed profile revision to watering, resource, substrate,
repotting, or pruning work.
Each action carries its own safe bounds, due window, expiry, stop conditions, and
expected evidence. Unknown or stale evidence cannot silently satisfy those bounds.
Planning may refuse an action or record infeasibility rather than manufacture care
advice.
A supply need binds its originating owner and revision and records minimum necessary quantity,
unit, product traits, constraints, purpose, validity/expiry, privacy class, and unknowns.
[Homestead stores](../homestead/stores.md) may return an exact `SupplySnapshot@1`, while
[Provision](../homestead/provision.md) returns `ProvisionResult@1`. These establish stock or
availability, not biological suitability or completed use.
A material substitution returns for Cultivator review before changing the plan or submitting an
order; availability cannot weaken the reviewed culture requirements.
## Execution and results
After work, use `cultivator.record_work@1` to produce `CultivatorWorkEvent@1` and
`CultivatorWorkResult@1`. Record what actually happened: action, actor, effective and recorded
times, quantity and unit uncertainty, evidence, plan reference, and outcome. If only part was
done, retain both the actual result and unresolved remainder. Reconcile and deduplicate stock
use by that event; neither a plan nor a provision receipt establishes consumption.
When Homestead supplies water, its actual resource limits remain decisive. Automatic actuation requires a separately
admitted owner, current evidence, and applicable vetoes. A missing acknowledgment
means unknown execution; do not retry an action merely because its reply was lost.
Any exact [Legion](../../sepulcher/extensions/legion.md) request passes through the commissioned owner with a fenced task,
zone, resources, expiry, and stop conditions. The body retains a fresh veto. Such a
request grants no general robot authority.
## Finite recovery
Settle a work attempt as completed, refused, infeasible, partial, unknown, or interrupted, as
applicable. On restart, use event identity, owner evidence, and acknowledgments to establish
what occurred before deciding further work. Cancellation closes only that admitted work and
preserves any effect already performed. Disable future schedule Occurrences separately.
Cross-owner live recovery follows
the [Suite boundary](../products-and-suites.md); settled receipt exchange alone does
not require a Suite.
Return to [Cultivator](index.md).
---
title: "Harvest"
plain_name: "Cultivator: harvest records"
section: "Compositions > Stewardship & Acquisition > Cultivator"
status: "Designed"
original: https://hexanomicon.dev/compositions/cultivator/harvest/
guide: https://lychd.snayu.ai/docs/compositions/cultivator/harvest/
---
# Harvest (Cultivator: harvest records)
## Plain-English summary (Snayu)
**What it is:** How Cultivator records each harvest as a receipt and hands it to Homestead stores, keeping collection and store acceptance separate.
**Why it matters:** Read when building harvest logging or yield import.
- Estimated, collected, accepted and eaten are separate claims.
- Duplicate imports never add stock twice.
- Never re-harvest to fix a message failure.
**Status:** Designed
## Original text (Hexanomicon)
The first basket is collected while the rest of the crop remains growing. A receipt must preserve
that partial result even if accepting the basket into household stores fails.
## Collection evidence
Use `cultivator.record_harvest@1` to record a collection in `CultivatorHarvestReceipt@1`. Identify
the source culture and cycle, collection event, effective and recorded times, actor, material
identity, quantity, unit, uncertainty, condition, and disposition. When collection happens in
several parts, give each part a distinct event identity. The source culture continues unless
explicit evidence ends it.
Estimated yield, collected harvest, accepted stock, and consumption are separate
claims. Collection does not establish food safety. Amendments preserve the earlier
claim and identify the corrected evidence.
## Store acceptance
[Homestead stores](../homestead/stores.md) may accept an exact harvest receipt once
as a source-lot event. Collection and store acceptance are tracked independently.
An unaccepted collection remains collected; accepted quantity requires the store
owner's evidence.
On import, use correlation and the exact receipt references to find the original source event.
A duplicate must resolve to that event without adding stock again. If the receipt was corrected,
reconcile its delta against prior acceptance, including changes to quantity, units, and
disposition. Merely replacing the latest receipt view cannot repair inventory already accepted.
A failed or lost acknowledgment leaves acceptance unknown. Reconcile the store event
before resending or amending; never recut the crop to repair a message failure.
Partial acceptance retains both the collected amount and the independently accepted
amount, with the remaining disposition unresolved or explicitly recorded.
Return to [Cultivator](index.md).
---
title: "Scavenger"
plain_name: "App: Scavenger (smart shopping)"
section: "Compositions > Stewardship & Acquisition"
status: "Partial"
original: https://hexanomicon.dev/compositions/scavenger/
guide: https://lychd.snayu.ai/docs/compositions/scavenger/
---
# Scavenger (App: Scavenger (smart shopping))
## Plain-English summary (Snayu)
**What it is:** Scavenger runs a finite buying campaign for second-hand items, tech parts or property: watching listings, qualifying and ranking candidates, negotiating, committing and receiving parcels.
**Why it matters:** Read before working on marketplace watching, ranking or negotiation features.
- You decide disclosure, commitment, payment and every property transaction.
- Only the finite feed observation (Bazos PC titles and links) runs today.
- No unbounded scraping, spam or false identity.
**Status:** Partial. Finite feed observation runs behind a selector; the rest is designed.
## Original text (Hexanomicon)
The cheapest listing may be the wrong part; the attractive vehicle may carry unanswered questions. Scavenger keeps a finite acquisition campaign open to inspection until its evidence supports a decision, a commitment, a parcel outcome, or an honest stopping point.
## Contract
`scavenger` revision `3` publishes `scavenger.plan_campaign@1`, `scavenger.observe_market@2`, `scavenger.qualify_candidate@1`, `scavenger.rank_candidates@1`, `scavenger.negotiate@1`, `scavenger.commit@1`, and `scavenger.receive@1`.
A campaign begins with its revisioned subject profile, concrete need, known inventory, budget, deadline, region, evidence standard, source policy, and autonomy ceiling. It may return a durable campaign, reviewed field, explicit preference revision, shortlist, seller thread, negotiated outcome, commitment, parcel result, or diligence packet.
Scavenger retains the campaign and the criteria, observations, evidence, rankings, judgments, preference revisions, offers, commitments, parcels, inspections, and diligence that support its decisions. Scout separately owns the bounded acquisition/interaction receipts. The Magus decides private disclosure, final commitment, payment, acceptance, dispute, and every property transaction; a campaign result cannot make those decisions on its own.
Unbounded scraping, spam, false identity or leverage, hidden criteria changes, professional certification, and unapproved commitment, payment, deposit, signature, or settlement remain outside the contract. Scavenger searches a finite market; [Hunter](../../sepulcher/extensions/shadow/hunter.md) instead adversarially challenges an already formed candidate.
## Revision continuity
Revision 2 selected `scavenger.observe_market@1` alongside the other six Pattern references.
It remains the historical finite-market design; its meaning is not rewritten into a new custody
or recovery protocol. Revision 3 keeps the application and those other references, and selects
`scavenger.observe_market@2` for the explicit [finite feed observation](market.md#finite-feed-observation)
request, retained whole field, deletion and recovery contract. The direct complete-seed admission
is part of that successor, not evidence that `plan_campaign` executed.
The tracked registry and application stores have no revision-2 Scavenger implementation or
executable data migration. This records that source boundary; it does not claim knowledge of
private implementations. [State](../../state-of-the-work.md#composition-portfolio-delivery)
separately records registration and native acceptance. The first observation profile does not
implement qualification, ranking, bargaining, commitment, receipt or preference learning.
## Open the campaign
[Campaign](campaign.md) fixes the need and permitted consequence. [Market](market.md) follows
the whole candidate field into evidence, ranking, and correction; [Bargain](bargain.md) takes approved questions to a seller.
When exact terms are ready, [Acquisition](acquisition.md) follows commitment into receipt,
inspection, dispute, or diligence.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Campaign"
plain_name: "Scavenger: campaign setup"
section: "Compositions > Stewardship & Acquisition > Scavenger"
status: "Partial"
original: https://hexanomicon.dev/compositions/scavenger/campaign/
guide: https://lychd.snayu.ai/docs/compositions/scavenger/campaign/
---
# Campaign (Scavenger: campaign setup)
## Plain-English summary (Snayu)
**What it is:** How a Scavenger campaign fixes the need, budget, deadline, region, criteria and autonomy level, with subject profiles for Bazaar, Technology and Property.
**Why it matters:** Read when building campaign setup or preference learning for Scavenger.
- Modes: Watch, Concierge, Bounded Autopilot.
- Property campaigns stop at diligence; no contact, offer or payment.
- Learned preferences reorder candidates but cannot fix failed hard gates.
**Status:** Partial. Complete campaign seeds are accepted; the planning workflow is not built.
## Original text (Hexanomicon)
Before opening a listing, decide what an acquisition would accomplish and how far this campaign may go. `scavenger.plan_campaign@1` pins the desired result, existing inventory, hard criteria, weighted preferences, budget, deadline, region, evidence tier, travel/delivery semantics, disclosure policy, and operating mode.
The revision-3 [finite feed observation](market.md#finite-feed-observation) also accepts a
complete immutable campaign seed directly. Its admission retains and validates those facts before
publishing the held Run; it neither invokes `plan_campaign` nor fabricates a completed planning
Run. Missing budget, deadline, region or policy is not inferred. Explicit empty or not-assessed
values are permitted only by the seed schema and establish no suitability or eligibility.
## Subject profiles
| Profile | Evidence and judgment | Revision-one consequence |
| --- | --- | --- |
| **Bazaar** | Item identity, condition, attributed seller claims, landed cost and bounded bargaining for Bazoš-style listings. | Terms, one approved cash-on-delivery (COD) commitment, parcel inspection, dispute or refusal. |
| **Technology** | Exact CPU, board, BIOS, cooling, memory, GPU, storage, case, PSU, firmware and connector compatibility. | Bazaar consequence after fresh compatibility and evidence checks. |
| **Property** | Transaction type, area, rooms, locality, route/amenity observations, contradictions and professional questions. | Shortlist and diligence only: no contact, viewing, offer, reservation, deposit, signature or payment. |
Choose these versioned Scavenger rules according to the subject being acquired. Technology may refine Bazaar, while property rules cannot silently become parcel or hardware judgment. Selecting a profile creates neither a Composition nor a source adapter, and supplies no source, credential, private anchor, money, or effect authority.
`Watch` observes and reports. `Concierge` prepares questions and offers for review. `Bounded Autopilot` acts only within its fully pinned envelope. Changing subject, ceilings, permitted disclosure, payment rail, evidence requirement, or deadline creates a successor campaign revision.
## Preference within the boundary
A candidate may meet every hard gate and still be unattractive to the buyer. `PreferenceRevision@1` can refine that soft ordering while retaining the reviewed field, admitted judgments, scope, provenance, and predecessor. It cannot repair a failed hard gate, widen budget or authority, change disclosure, or rewrite earlier rankings.
Before the next observation uses a reviewed preference revision, check the campaign's declared learning mode. If that mode does not allow activation, keep the revision as a proposal awaiting explicit acceptance. [Market](market.md) exposes the full candidate field so the person can assess what the learning changed.
---
title: "Market"
plain_name: "Scavenger: watching listings"
section: "Compositions > Stewardship & Acquisition > Scavenger"
status: "Partial"
original: https://hexanomicon.dev/compositions/scavenger/market/
guide: https://lychd.snayu.ai/docs/compositions/scavenger/market/
---
# Market (Scavenger: watching listings)
## Plain-English summary (Snayu)
**What it is:** How Scavenger observes a finite market snapshot, keeps the whole candidate field, filters it locally, qualifies and ranks candidates, and learns from your judgments.
**Why it matters:** Read when working on the Bazos feed observation, the /scavenger view, or ranking logic.
- The working profile fetches one Bazos PC RSS feed and keeps titles and links only.
- Every listing is kept, including duplicates; filtering never changes the field.
- Ranking shows lower and upper utility bounds for unknown values.
**Status:** Partial. Feed observation, filter and delete work; qualification and ranking are designed.
## Original text (Hexanomicon)
Each morning brings a changed market: new, removed, relisted, repriced, reworded, and rephotographed candidates. The useful view shows the whole field, including the reasons some listings cannot qualify. A shortlist alone would hide the evidence needed to correct it.
`scavenger.observe_market@2` admits finite snapshots, normalizes and deduplicates listings, and preserves retrieval time and source claims. Scheduled observations coalesce rather than accumulate an endless backlog. The Scout profile fixes origins/paths, user agent, pacing, concurrency, bytes/pages, expiry, robots decision, selectors, sessions, CAPTCHA handling, fixtures, and kill switch. A `bazos.sk` adapter observes a source; the campaign decides what it means.
## Finite feed observation
Scavenger revision 3 selects `scavenger.observe_market@2` with the explicit
`bazos-pc-title-link@1` profile. It accepts one complete immutable `CampaignSeed@1` and one exact
public feed declaration. The seed pins subject/profile revision, concrete need, inventory, hard
criteria, weighted preferences, budget, deadline, region, evidence standard, travel/delivery
semantics, source/disclosure policy, learning mode and a `Watch` autonomy ceiling. Admission
retains the seed before held Run publication; it does not execute `plan_campaign`.
This profile permits one bounded RSS Fetch/Extract and a local title/link projection. It admits
no model call, qualification, ranking, item acquisition, seller contact, purchase, polling or
preference learning. The source profile fixes the exact advertised Bazoš PC feed, the native RSS
media/extraction profile and finite effect ceilings. A public declaration remains an authenticated
operator assertion, not a technical proof of publicness or a reusable contact grant.
### Initial seed encoding
`CampaignSeed@1` requires every fact explicitly, including empty inventory, hard-criteria and
preference arrays. `subject_profile` is `Bazaar@1` or `Technology@1`; `need` is nonblank bounded
text. Inventory, hard criteria and preferences each permit at most 16 entries. A preference
carries nonblank `criterion` text and a nonnegative integer `weight`; this profile does not
normalize, rank or learn from it. `budget_minor` is a nonnegative integer number of EUR cents or
explicit `null` (not assessed), with `currency: EUR`. `region` is bounded nonblank text or explicit
`null`; neither unknown establishes eligibility. `deadline` carries a timezone; admission checks
its current validity without making historical seed decoding depend on wall time.
`evidence_standard` and `travel_delivery` are required nonblank descriptions, never grants.
`source_policy: admitted-public-feed-only@1`, `disclosure_policy: none`, `learning_mode: none`
and `operating_mode: Watch` close this initial profile. Need text permits 2048 UTF-8 bytes;
individual inventory/criterion/preference/evidence/travel values permit 1024 bytes and region 256.
The complete 16 KiB bound still applies. No complete seed is copied into Run or consent facts.
### Whole field and local views
Retain the response in an immutable `MarketObservation@1` owned by Scavenger. Its exact
subject/request binds the canonical seed digest, Run and selected Composition/Pattern/manifest,
source and acquisition profiles, purpose, retention profile and initial filter revision. Replaying
that exact binding resolves the same admission/result; a changed binding refuses. The first
profile allows only one pending or retained observation per selected profile database and creates
no additional Scout allowance store.
The whole field contains every item returned by the admitted bounded extraction, in source order,
including unmatched, duplicate and unjudged occurrences. Each occurrence retains an internal
identity, source ordinal, duplicate grouping, optional original plain title, inert original item
link and source-record identity. Deduplication groups exact item locators without erasing their
occurrences or query/path spelling. Missing values and unresolved facts remain visible; no
eligibility or seller judgment is inferred. This field is the finite response, not the source's
entire market.
Keep the field within the qualified RSS mechanism's limits: at most 100 observations, titles of
at most 1024 UTF-8 bytes, and links of at most 4096 bytes. The complete seed is bounded to 16 KiB
and the canonical application observation to 256 KiB. If the result overflows, refuse it whole
rather than hide items or shorten fields.
To show what the field represents, retain the requested/contacted locator, retrieval time, Scout
receipt, source/record/field digests, selected profiles, omissions, duplicate/missing counts and
declared coverage. Source dates/GUIDs alone establish neither identity nor freshness.
Only the admitted title/link field and necessary attribution survive in application custody.
Feed bodies, channel text, summaries, images, publisher dates/identifiers and separate contact
fields are discarded after transient consumption. Titles and links are deliberately retained
source claims; the profile does not promise that source text contains no personal information.
Run/Graph state, generic events/logs and Bridge history carry opaque references, safe counts/status
and closed reasons, never item values or a copied campaign seed. Scout retains its independently
owned contact attribution and positively selected extraction metadata, not this field.
An authorized read returns the complete field. A bounded literal, versioned case-folded substring
filter over retained title/link values derives a local view of that same field digest. It is not
regex, semantic ranking or qualification. The view reports total, visible, unmatched, duplicate
and missing counts and keeps an all-observations view available. A new filter changes no field
and performs no acquisition. Read and re-filter require current application retrieval authority;
a receipt or opaque UUID supplies neither.
### Retention, deletion and recovery
Retain this one field until its owner explicitly deletes it. Deletion is a distinct current-authority
operation over the exact observation identity/digest, available only after acquisition and result
disposition are proved terminal. Pending work must be cancelled through the Run owner first;
unknown acquisition cannot be declared settled by deletion. The first profile supplies no
automatic unknown-attempt reconciliation.
Once terminal disposition permits deletion, atomically remove the application seed, item payload
and content projections. Keep only a content-free tombstone and necessary immutable execution/
Scout receipts, whose contact metadata is not erased. The tombstone fences late writes and exact
replay so neither can recreate the payload. Report deletion distinctly from an empty market and
do not imply backup erasure.
Reopening the application slot does not reset spent counters, unknown reservations or an issued
claim. To replace an observation, visibly delete it and obtain a fresh request and consent.
Recovery depends on whether acquisition has been claimed. Before claim, the exact retained
consent may resume under current authority and expiry. After claim or an uncertain acknowledgement,
lost transient material cannot be reconstructed or refetched.
After current CONSUME and result-adoption checks, commit the entire consumer field once, atomically
under its request/claim identity. If settlement has no confirmed consumer commit, return material
unavailable unless that same key proves a committed result. Reconcile a lost commit acknowledgement
against the same key/digest; ambiguity remains unknown and creates no acquisition. Once committed,
the field supports fresh authorized reads/re-filters after restart. Once deleted, that identity
stays deleted.
The first native profile uses one active Scout binding in a fresh profile database. Existing page
budget rows refuse a page/RSS switch or coexistence without mutation. This is an explicit initial
compatibility boundary, not a reset, migration or second budget store.
The Altar presents source/time/coverage, omissions, total/filtered counts, complete title/link rows,
unknown/refused/deleted states and distinct new-fetch, local-filter and terminal-delete actions.
Item links remain displayed data, with no automatic preview/contact. The native source and
[State](../../state-of-the-work.md#composition-portfolio-delivery) must prove these operations before
the interface can claim they are available.
## Evidence before preference
`scavenger.qualify_candidate@1` applies hard gates: `false` rejects, `true` admits, and `unknown` stays visible. No model may invent an address, fee, area, socket, clearance, firmware, condition, serial, stock, or seller fact. Only eligible candidates enter the proposed order from `scavenger.rank_candidates@1`:
```text
known utility = Σ(known weight × normalized preference)
lower bound = known utility / total configured weight
upper bound = (known utility + unknown weight) / total configured weight
```
These bounds assume finite, nonnegative configured weights with a positive total, and preference values normalized to `[0, 1]`. They apply only when the selected profile establishes those conditions. Here, unknown weight is the configured preference weight whose candidate value is still unknown. The lower bound counts only known utility; the upper bound shows the contribution those unresolved preferences could still make. Neither bound changes hard eligibility.
Price itself remains an attributable interval across condition, warranty, age, bundle value, fees, and uncertainty. A route observation proves access at one time, not title, structural condition, financing, insurance, development, or final transaction cost.
## The whole candidate field is the review surface
The Magus can move a candidate, score it, assign `contact`, `watch`, `ask`, or `reject`, choose a reason, and explain a judgment. A marked image region keeps observable evidence separate from suspicion. Later seller answers or outcomes can revise the judgment.
Each action appends `CandidateJudgment@1`. `RankingReview@1` seals the snapshot, original system order, reviewed order, judged subset, unjudged candidates, and judgment references. Hard-false candidates remain in a rejected lane; unknowns and unjudged material remain inspectable.
A derived `PreferenceRevision@1` may contain scoped weights, rules, examples, exceptions, provenance, and confidence. It is Scavenger decision memory, separate from [Archive](../../adr/27-memory.md) and model weights. The next ranking pins the accepted revision and explains which evidence and preferences affected each score. The person can still correct any candidate or inferred reason.
## Bazaar worked example: a daily vehicle market
A seven-day automotive campaign observes one finite Bazoš search each morning. The diagnostic view retains all changes from yesterday. The Magus reorders vehicles, scores them, marks image regions worth checking, and chooses what to contact, watch, ask, or reject.
A missing VIN, service history, condition detail, photo, or video can become an approved [Bargain](bargain.md) question. Its reply updates attributed evidence and may change qualification and order. It cannot authorize purchase or widen negotiation. Tomorrow's order uses the accepted preference revision; today's rejected and unjudged cars remain available for inspection. Technology, property, equipment, collectibles, and other finite markets use the same review contract with their own subject criteria.
## Images, messages, and learned contact style
For an image judgment, retain the source identity/digest, region, observed cue, interpretation, confidence, and correction. This keeps a model's suggested inspection region separate from proof of damage, identity, condition, or value. Eligible public listing images may go to a named remote vision provider only under an exact source/egress policy, for bounded inference with provider/model provenance. Public availability grants no training or republication rights.
Already approved questions and truthful automation disclosures can be compared for decision-useful answers. Bargain still owns every send, limit, stop signal, uncertain acknowledgement, and seller thread. Phone numbers, private replies, credentials, and private anchors never enter a preference revision as ambient context.
## Prove that preference learning earns its cost
Take the first snapshot as an unaided baseline, collect intermediate corrections, and test the accepted revision on a held-out final snapshot. Measure order agreement, manual move/score correction effort, reason and image-region agreement with calibrated uncertainty, seller answers that change judgments, and human review time.
A representative seven-day pilot may target at least 50 explicit candidate judgments and 30 to 60 image-region corrections; the campaign declares its own minimum. Continue only when held-out ordering or decision time improves without hiding unknowns or spending more annotation effort than it saves. Otherwise retain the evidence, reject the revision, and change or stop the pilot.
School, work, family, health, routine, exact address, and phone data receive least-data treatment. Sources receive only the needed coarse region, opaque anchor, or derived observation. Listings and replies remain evidence; only admitted human judgments and accepted application revisions enter decision memory. Model-weight changes require a separate [Training](../../adr/33-training.md) admission and promotion.
Continue with [Bargain](bargain.md), or finish with the evidence-bound shortlist.
---
title: "Bargain"
plain_name: "Scavenger: seller negotiation"
section: "Compositions > Stewardship & Acquisition > Scavenger"
status: "Designed"
original: https://hexanomicon.dev/compositions/scavenger/bargain/
guide: https://lychd.snayu.ai/docs/compositions/scavenger/bargain/
---
# Bargain (Scavenger: seller negotiation)
## Plain-English summary (Snayu)
**What it is:** How Scavenger sends approved questions or offers to sellers within fixed limits and stops automatic messaging on refusal, silence or expiry.
**Why it matters:** Read when building seller messaging or negotiation.
- Each thread has fixed ceilings, disclosures and stop signals.
- Seller replies are untrusted and cannot change policy.
- A lost send acknowledgement parks the thread until reconciled.
**Status:** Designed
## Original text (Hexanomicon)
A missing specification can justify a question; a seller's answer cannot rewrite the campaign. `scavenger.negotiate@1` sends approved questions or offers inside one immutable envelope: candidate, missing evidence, opening/all-in ceilings, currency, delivery constraints, concessions, truthful automation disclosure, prohibited claims, caps, expiry, and stop signals.
Refusal, opt-out, abuse, silence, sale, changed subject, changed payment rail, failed evidence, expiry, or exhausted caps closes automatic messaging. A persuasive reply grants no extra budget, item substitution, private data, or payment method.
Give each send a stable effect identity and redacted receipt. If its acknowledgement disappears, retain `unknown_send` and park that same thread. Reconcile the destination before restart can resend or create a second commitment. Any reply remains attributable hostile input; it cannot change the policy governing the thread.
Close the thread with exact terms, unanswered questions, refusal, expiry, or an offer for fresh human review. None of those bargaining results approves commitment or payment. Before proceeding to [Acquisition](acquisition.md), revalidate current evidence, terms, budget, exposure, authority, delivery, and disclosure.
---
title: "Acquisition"
plain_name: "Scavenger: purchase and delivery"
section: "Compositions > Stewardship & Acquisition > Scavenger"
status: "Designed"
original: https://hexanomicon.dev/compositions/scavenger/acquisition/
guide: https://lychd.snayu.ai/docs/compositions/scavenger/acquisition/
---
# Acquisition (Scavenger: purchase and delivery)
## Plain-English summary (Snayu)
**What it is:** How Scavenger commits to approved terms, checks arriving parcels, and records acceptance, dispute, return or loss.
**Why it matters:** Read when building commitment, parcel tracking or dispute handling.
- Cash on delivery proves neither contents nor condition.
- Property campaigns end at a diligence packet.
- Restart reuses idempotency keys; deleting locally can't erase the seller's copy.
**Status:** Designed
## Original text (Hexanomicon)
A parcel arrives with the right tracking number and amount. Its contents and condition still need inspection. `scavenger.receive@1` compares carrier, tracking, amount, expected identity, and package notes, then records acceptance, rejection, dispute, return, or loss. Cash on delivery (COD) alone proves neither what is inside nor its condition; the Magus makes the final payment, acceptance, dispute, and return decisions.
To judge the parcel, return to the exact terms freshly authorized through `scavenger.commit@1`. Property revision one never reaches that effect: it ends at a diligence packet, without contact, viewing, offer, reservation, deposit, signature, or settlement.
Retain enough attribution to follow the parcel back to the decision: campaigns, snapshots, score inputs, seller claims, messages, approvals, commitments, parcels, inspections, disputes, and diligence questions stay separately identifiable. Checkpoints pin Pattern, source, selector, catalogue, parser, template, and policy revisions so recovery can reconstruct the work it is resuming.
On restart, reuse the pinned observations and idempotency keys. Park the occurrence if source state has changed, and reconcile an unknown commitment or send before retrying. For export, keep private anchors, messages, evidence, and delivery data separate. For deletion, disable schedules/sessions and inventory open commitments and disputes; removing local material cannot erase the seller's copy.
## Proving the campaign
Network-disabled Slovak fixtures cover a Bazoš RAM campaign and a two-room property campaign. Prove DDR4/DDR5 and SODIMM/UDIMM rejection, dated price intervals, bounded replies and stop rules, lost-acknowledgement recovery, deleted-listing uncertainty, reproducible score intervals, and restart without duplicate observations or messages. No live crawl, seller, credential, private coordinate, payment, deposit, signature, or professional query enters the proof.
Return to [Scavenger](index.md).
---
title: "Presence & Embodiment"
plain_name: "Apps: Presence and embodiment"
section: "Compositions"
original: https://hexanomicon.dev/compositions/presence-and-embodiment/
guide: https://lychd.snayu.ai/docs/compositions/presence-and-embodiment/
---
# Presence & Embodiment (Apps: Presence and embodiment)
## Plain-English summary (Snayu)
**What it is:** Index of the apps that put the Assistant somewhere: a chat channel, a game world, a VR room, a physical robot or a phone. It lists each app and the single outcome it owns.
**Why it matters:** Start here to find which app owns a place or body before working on games, Discord, VR, robots or the phone client.
- Six apps: Blockworld (Minecraft), Reach (external channels), Avatar (appearance), Spectre (VR), Familiar (physical bodies), Companion (phone client).
- Avatar carries the Assistant's look across places, but each place still decides what may happen there.
- On a phone, Companion owns the session while Familiar owns the device's capabilities and safety.
## Original text (Hexanomicon)
Where should the encounter happen: a social channel, a virtual place, or a physical device?
Choose the owner of that setting below. Avatar can carry the Lich's appearance across settings;
each place still judges what may happen there. On a phone, Companion keeps the session while
Familiar keeps the body's capabilities and safety.
| Composition | Outcome |
| --- | --- |
| [Blockworld](../blockworld/index.md) | One finite mission in a block world, with evidence of what changed and a way to recover. |
| [Reach](../reach/index.md) | One bounded social turn, summon, or presence effect in an admitted external place. |
| [Avatar](../avatar/index.md) | The Lich’s chosen appearance across places, with each projection’s outcome kept distinct. |
| [Spectre](../spectre/index.md) | A virtual place and a bounded meeting that people can enter, leave, or interrupt. |
| [Familiar](../familiar/index.md) | A physical body carrying a bounded task or presence, with its local limits and outcome preserved. |
| [Companion](../companion/index.md) | A configurable phone client for bounded sessions over an admitted Familiar body. |
For the phone route, Companion's first client target is native Android and Communion names its
bounded interaction, without creating another Composition or Product. Follow
[the worked handoffs](../products-and-suites.md#avatar-and-spectre) to decide when these owners can
exchange settled references and when their live work needs a Suite.
[Composition Areas](../index.md#areas)
---
title: "Blockworld"
plain_name: "App: Blockworld (Minecraft missions)"
section: "Compositions > Presence & Embodiment"
status: "Partial"
original: https://hexanomicon.dev/compositions/blockworld/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/
---
# Blockworld (App: Blockworld (Minecraft missions))
## Plain-English summary (Snayu)
**What it is:** An app that lets the Assistant act in a Minecraft-style world for one finite mission, such as building a reviewed blueprint on a private plot, with receipts for every placed block and recovery after interruption.
**Why it matters:** Read this before any Minecraft or game-world work, to understand the mission contract and what is and is not wired up.
- A mission is bound to a specific bot, world, plot lease, blueprint, tools and budgets; no public autonomy, admin commands or cross-plot power.
- The game server stays the truth for blocks and inventory; Blockworld keeps mission, lease, action and receipt records.
- Today only an inactive one-block test workflow exists; it is not registered at boot and does not connect to Minecraft.
**Status:** Partial. Inactive one-block test workflow only; no live server or bot deployment.
## Original text (Hexanomicon)
The inhabitant wakes for one mission. When its Mind goes quiet, the wall it placed may remain. Blockworld keeps the purpose, lease, placements, and receipts beside that consequence so the next awakening can begin from reconciled world truth.
A reviewed blueprint on a private plot is the first journey: establish the finite mission and its memory, have Sentinel guard each crossing into the server, then reconcile world truth after interruption or restoration.
## Contract
`blockworld.inhabitant` revision `2` publishes `blockworld.bounded_mission@2`. Admission binds a finite mission, server mode, authenticated bot, exact world epoch and capabilities, plot lease, blueprint, tools, and budgets. Its return is verified action receipts, a durable mission cursor, and completion or exact non-completion. Public autonomy, unrestricted exploration, administrator commands, remote shell, and cross-plot power remain outside the mission.
Revision `1` and `blockworld.bounded_mission@1` remain historical design contracts, retired in favour of revision `2`. Their mission authority, five reads and five effects, verified receipts, and refusal to repeat an uncertain placement remain unchanged. Revision `2` adds required preparation, exact command/review binding, and native action continuity for the bounded placement operation. These requirements do not reinterpret revision `1` or establish parked-state compatibility. This design retirement defines no executable migration; [State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns registration and delivery.
The bounded-mission code slice is an inactive, one-block test workflow assembled explicitly with
inert effects. It is not registered at normal boot and does not connect to Minecraft. The separate
[Horizon-assist profile](horizon-assist.md) supplies an experimental attached-client passage.
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery) keeps their evidence and
remaining game checks distinct.
Blockworld records why the inhabitant acts and what it can account for: inhabitant, mission, world-local relationship, project, memory-candidate, lease, action, and receipt records. The server remains authoritative for blocks, entities, inventory, and game time. An [Avatar](../avatar/index.md) may project the Lich through the inhabitant, but gains no mission, inventory, lease, or world effect.
## Your Minecraft client
[Prism Launcher](https://prismlauncher.org/wiki/getting-started/create-instance/) manages your
Minecraft client instances, including the game version and modloader. In this design, you join
the world through that human client; the inhabitant connects separately through an admitted bot
identity and client adapter. The server owns the world, and [Sentinel](sentinel.md) guards
admitted effects.
A singleplayer world opened to LAN, or an existing external server, can be considered for
`attached` mode only when its endpoint is reachable and bot access is explicitly authorized.
Admission remains limited to the capabilities the server actually offers; client observation
cannot supply missing server proof. The first managed fixture below remains the proving target.
A [Prism Launcher client on macOS](https://prismlauncher.org/download/macos/) is separate from
[LychD's Linux host requirement](../../adr/08-containers.md#supported-host-policy). LychD
[Prism](../../sepulcher/extensions/prism/voxel-and-block-export.md) is a different component: its
designed block-export path supplies blueprints for separate mission admission. An existing launcher
instance does not establish game/modpack compatibility or provide Blockworld integration;
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery) records delivery.
## Server
Choose one closed mode before admission:
```toml
[blockworld.server]
mode = "managed" # managed | attached
```
| Mode | Admitted control | Limit |
| --- | --- | --- |
| **`managed`** | Rootless server Quadlet, declared world volume, configuration, exact mod/plug-in set, lifecycle and recovery receipts. | Server or modpack changes require a separately admitted deployment and operator approval. The bot receives no administrator power. |
| **`attached`** | Bot identity, endpoint, credentials and client adapter. | No server files, console, lifecycle, snapshot, plug-in or mod authority. Admit only capabilities the external server offers. |
The first proving fixture uses managed mode: a private, allowlisted, online-mode server and a dedicated non-operator bot. An attached server may offer weaker observation or verification. Before the bot wakes in either mode, pin mode, server identity, protocol, capability/modpack revision, and Sentinel availability. A mode change must drain missions and create a new server generation and world epoch.
## Enter by question
[Companion lab](companion-lab.md) develops a separate opt-in Fabric NPC actuator with native
command admission, a finite operator queue and CPU-ready speech. Its actor and experimental
delivery boundary do not replace the authenticated-player bounded mission.
[Horizon assist](horizon-assist.md) defines the separate experimental attached-client passage
for bounded spoken or typed actions. It does not weaken the managed mission's receipt contract.
[Playing with a companion](horizon-play.md) gives user stories, acceptance trials and the order
of preparation for multilingual voice, following and shared building.
[Mission](mission.md) defines the work the inhabitant may attempt. [Sentinel](sentinel.md)
guards each crossing into the server. After interruption or restoration,
[Continuity](continuity.md) reconciles what remains before another awakening begins.
[Workflow](../../adr/28-workflow.md) · [Containers](../../adr/08-containers.md) · [Security](../../adr/09-security.md) · [Composition Portfolio](../index.md)
---
title: "Companion lab"
plain_name: "Blockworld: Companion lab"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Partial"
original: https://hexanomicon.dev/compositions/blockworld/companion-lab/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/companion-lab/
---
# Companion lab (Blockworld: Companion lab)
## Plain-English summary (Snayu)
**What it is:** An experimental Minecraft profile where you speak or type a short instruction (Slovak, Czech or English) to a controlled wolf NPC, see it queued, and get a result tied to what the server actually did.
**Why it matters:** Read this if you work on the Minecraft companion, its voice/text commands, queueing, stop handling or the Fabric mod.
- The body is a vanilla wolf NPC: it can look, move a short distance and follow, but cannot mine, build or use inventory.
- Commands go through a bounded first-in-first-out queue with expiry; a priority stop clears older requests and is confirmed on the server tick.
- Optional weather and day/night effects, reviewed phrases and a local model for paraphrases are separately enabled.
**Status:** Partial. Opt-in lab works with tests; no qualified live microphone, playback or Windows operation.
## Original text (Hexanomicon)
**Unofficial Minecraft integration. Neither Mojang nor Microsoft approves or is associated with this project.**
Publisher: LychD contributors · Contact: [hexanomicon@proton.me](mailto:hexanomicon@proton.me).
Speak a short instruction, see it enter the companion's queue, and receive a result tied to what
the server actually did. This experimental profile develops that journey separately from the
authenticated-player [bounded mission](index.md#contract). Its first body is a controlled vanilla
wolf. It is an NPC, with no player account, inventory privileges, mining or building authority.
## First session
| Story | Required behavior |
| --- | --- |
| Ask for the current state in Slovak, Czech or English | Exact supported wording reaches the same typed request as text. An explicitly selected local interpreter can classify a bounded paraphrase; ambiguous requests clarify or refuse. |
| Say `prepni deň/noc` or `počasie jasno` | Separately enabled clock/weather effects return their own correlated engine readback. Exact named modes remain available without a model. |
| Tell the companion to look, move a short distance or follow | The server validates the actor, world generation, bounds, target and deadline. Starting navigation is reported separately from reaching a destination. |
| Walk with a companion that leaves room | Following waits inside its configured stopping distance and resumes only outside a larger distance. The band prevents close-contact repathing; target loss and the finite lease still end following. |
| Give another instruction while work is active | A finite FIFO retains operator commands with a capacity and expiry. New movement instructions replace the prior movement goal when executed. Read/chat requests need not cancel movement. |
| Leave the companion idle | It may look around under a finite lease, without wandering, mining or model calls. Idle ticks do not build a command backlog. |
| Stop at any time | A priority path fences older requests and clears their queue. The server acknowledges stopping only after applying the fence on its tick thread. Gravity and unrelated game physics can continue. |
| Match every queued outcome to its instruction | Even expiration or cancellation before native admission retains the operator request UUID and private evidence; it does not invent a Run UUID. |
| Hear a useful answer | A state reply describes the correlated observed mode and coordinates. Movement replies describe activation, and uncertainty remains explicit in Slovak, Czech and English. |
| Lose a reply or restart | An uncertain action is not replayed. Server restart changes its boot identity and starts idle; the caller must bind again. |
| Test without free GPUs | Compilation, dedicated server, deterministic native graphs and the speech profile use CPU only. Optional interpretation needs its separately selected model service. Client rendering and microphone/listening checks have separate acceptance. |
## Chosen construction
The first target is Fabric on Minecraft 26.3, matching the currently prepared human client version.
Fabric and NeoForge both satisfy the necessary API floor; this is a reversible implementation
choice, not evidence that Fabric is faster, more reliable or inherently more agentic. No required
modpack or measured maintenance advantage currently breaks that comparison. The complete Java,
Gradle, Loom, Loader and Fabric API tuple must be pinned and built before delivery is claimed.
The adversarial comparison tested the same requirements against both loaders, then exchanged
their strongest objections. Fabric supplies [entity](https://docs.fabricmc.net/develop/entities/first-entity),
[networking](https://docs.fabricmc.net/develop/networking) and
[testing](https://docs.fabricmc.net/develop/automatic-testing) seams; NeoForge supplies corresponding
[entity](https://docs.neoforged.net/docs/entities/),
[payload](https://docs.neoforged.net/docs/networking/payload/) and
[GameTest](https://docs.neoforged.net/docs/misc/gametest/) seams. These establish suitability, not
comparative reliability. NeoForge's capabilities are useful when a required content ecosystem
needs them; Fabric also has typed lookup, transfer and attachment facilities. Neither eliminates
Minecraft version migrations or turns a helper fake player into an authenticated visible player.
The first slice therefore chooses one small working actuator and keeps the wire boundary portable.
Reopen the loader choice for a required incompatible modpack, a measured upgrade burden or a
missing concrete engine hook. Hypothetical future agents writing more code do not settle those costs.
LychD owns intent, language interpretation, native Run/Graph execution, the operator queue and
private evidence. The Java delivery client owns a bounded transport mailbox and Minecraft-thread
actuation. The wire protocol addresses actor UUIDs and capabilities, not a wolf-specific graph.
No model inference executes in a server tick. A later custom entity, talking item or client UI
can reuse this boundary without moving cognition into Minecraft.
```mermaid
flowchart LR
Voice[Explicit recording / WAV] --> STT[CPU speech service]
STT --> Parse[Typed instruction]
Text[Text] --> Parse
Parse --> Queue[Finite operator FIFO]
Queue --> Run[Native Run: validate → optional interpretation → execute → report]
Run --> Bridge[Loopback HTTP bridge]
Bridge --> Tick[Minecraft server tick]
Tick --> NPC[Owned NPC controller]
Tick --> Result[Correlated result / observation]
Result --> Logs[Private events and optional spoken reply]
Stop[Priority stop] --> Queue
Stop --> Bridge
```
The local bridge authenticates a private token and listens only on literal loopback. It binds
each action to protocol version, server boot, actor, native Run, action identity, stop generation
and expiry before handing it to the game. HTTP acceptance alone does not establish execution.
World and entity access occurs only on the server thread; endpoint workers see immutable
observations, and stop takes priority over ordinary commands.
Within one boot, duplicate identities must recover the same action without repeating its effects.
Changed content under an old identity refuses. Queue and result storage stay finite. After a
crash or lost acknowledgement, retain unknown rather than infer a result: these process-local
records establish no durable exactly-once guarantee.
Keep a separate finite history for stop identities so ordinary action capacity cannot consume it.
A newer stop may supersede a pending stop before its tick barrier; settle the earlier record as
cancelled and keep it queryable. When the final stop-history slot is used, seal new ordinary
admission for that boot while preserving the priority barrier. Further unknown identities refuse
until an explicit server restart. Never evict or reuse a retained identity silently.
Only the owned actor is controlled. Vanilla movement and target-selection goals must not compete
with its admitted controller. A missing, unloaded, dead or changed actor refuses dependent work.
Following binds an exact target UUID and finite distance/lease; loss stops it. Movement remains
bounded and does not authorize teleportation, digging or chunk exploration. Ordinary chat never
becomes a server console command.
### Explicit server weather
The separate `weather@1` contract changes shared server weather, rather than extending the NPC's
spatial authority. Its closed arguments are revision `1`, scope `server_weather`, mode `clear`
or `rain`, and duration `600` engine ticks. The overworld is an observation anchor; Minecraft
26.3 keeps weather data on the server, shared by weather-capable dimensions. Thunder, arbitrary
durations, console commands and gamerule changes are outside this operation.
Host policy `allow_weather` and server configuration `allow_weather` default to false. A trusted
local session must explicitly select `--allow-weather`; its native admission then also carries
`blockworld:weather`, checked again before physical handoff. Neither the existing companion
scope nor the NPC's control box grants this effect. The server independently checks its opt-in
and current weather advancement setting before applying anything. Disabled advancement refuses.
After admission, the weather owner calls the engine's typed API on the server thread. It returns
a separate `blockworld.weather@1` observation recording requested mode/timer, actual flags/timers,
global scope, overworld anchor, boot/actor/generation, world tick and timestamp. The outer record
binds action and Run identities; a pose or cell observation cannot confirm this weather result.
The timer programme is finite, but it promises neither thirty wall-clock seconds nor restoration
of earlier weather or immunity from later world changes. Ordinary natural cycling resumes, and
later natural thunder is not excluded.
Exact text or transcript forms include `weather clear`, `weather rain`, Slovak `počasie jasno`
and `počasie dážď`, Czech `počasí jasno` and `počasí déšť`, and the fixed phrases `daj jasno`,
`spusti dážď`, `nastav jasno`, `spusť déšť`, `clear weather` and `make it rain`.
Bare weather toggles and malformed weather commands refuse rather than entering interpretation.
The shared finite FIFO, native Graph, mailbox, deduplication and original instruction deadline
remain their existing owners. A composite actuator routes weather beside the NPC controller;
weather cannot replace or renew its movement goal or lease. Priority stop cancels queued weather
and stops the NPC; it does not undo weather already applied. Unknown acknowledgement never
authorizes replay. Existing NPC-only sessions retain their authority ceiling.
This expands the experimental lab Pattern to revision `3`, implementation `py.5`, checkpoint
`companion-state-v5`; it does not change the authenticated-player bounded-mission contract.
Earlier Pattern closures are not migrated by shape compatibility. Delivery evidence remains in
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery).
### Explicit day and night clock
The independent `time@1` operation advances the selected `minecraft:overworld` clock to the
next or equal day marker (1000) or night marker (13000) in its 24000-tick cycle. Its closed
arguments are revision `1`, scope `overworld_clock`, and mode `day`, `night` or `toggle`.
Toggle samples the clock at execution: phase below 12000 selects night; otherwise day.
No operation sets the clock backward. An already-day request just after marker `1000` can advance
23999 ticks; repeated distinct toggles can advance calendar and moon counts. This is an explicit
placement policy, not proof of safety for every consumer. Linked schedules outside the overworld
can also change. An operator preference for same-cycle editing reopens this choice.
Host policy `allow_time` and server configuration `allow_time` default false. Explicit local
`--allow-time` adds native `blockworld:time`; policy and scope are checked again at handoff.
The server independently checks its permission and current bound clock/timeline/markers and
overworld default-clock/timeline/fixed-time profile. Missing or incompatible profiles refuse
before mutation. Other timeline tracks and visible brightness are not certified by this check.
With nonnegative cumulative ticks, the owner computes the forward delta modulo `24000` and refuses
64-bit overflow. An equal marker skips the setter, preserving fractional progress; a positive
placement resets the fraction to zero through the engine API. Existing finite rate (including
zero or negative), pause and time-advancement settings are preserved and reported. No response
promises future cycling. Simulation ticks, weather and the original NPC controller/lease are
separate and remain unchanged by this immediate operation.
Verify the clock placement through its own closed `blockworld.clock@1` readback. It retains
requested/resolved modes, clock/scope/anchor, before/after ticks, phases, cycles and cycle increment,
exact delta, fractional readings, rate, pause and advancement settings, plus
boot/actor/generation/world tick/timestamp. The outer record binds action and Run. The host
recomputes placement from this evidence; another observation kind cannot confirm it.
Stop cancels queued clock work but cannot undo an applied placement. Unknown acknowledgement
never authorizes replay. The existing FIFO, mailbox, history and original deadlines retain their
owners.
Exact forms include `time day`, `time night`, `time toggle`, Slovak `čas deň`, `čas noc`,
`prepni deň noc` and `prepni deň/noc`, Czech `čas den`, `čas noc`, `přepni den noc`, and English
`toggle day night`. Documented ASCII forms are accepted. Malformed clock wording stays outside
the optional state/idle/follow interpreter. This expands the experimental Pattern to revision
`4`, implementation `py.6`, checkpoint `companion-state-v6`; it migrates no older pinned closure.
Delivery and human speech checks remain in State of Work.
The explicit `inspect@1` operation reads one integer cell: `inspect X Y Z`, Slovak
`blok X Y Z`, or Czech `blok X Y Z`. It shares the ordinary FIFO, native Run, mailbox,
identity history, stop fence and original deadline. Both cell corners must fit the host and
server boxes; the integer cell origin must be within the admitted distance of the owned NPC.
The server reads an already loaded chunk on its tick thread without loading or generating one.
It returns a separate closed `blockworld.cell@1` observation with dimension, complete registry
block state/properties, coordinates, boot/actor/generation and server time/tick. This provenance
is neither a canonical world epoch nor permission or evidence for placement. An unloaded cell
refuses; a missing or mismatched observation remains unknown.
The protocol-1 action envelope and existing pose observation retain their exact shapes.
`inspect` has explicit argument revision 1 and its own typed observation variant; existing
actions cannot accept that variant, and inspection cannot accept a pose as its answer. An older
server may refuse the new operation. Reading preserves any valid movement/follow controller
and its original lease. Full state stays in the private result; bounded localized feedback
describes the observed cell without reading block-entity text, inventories or other contents.
This is world observation only; building and material custody remain unfinished.
The private server configuration owns the follow distance band. Optional `follow_stop_distance`
and `follow_resume_distance` default to two and three blocks respectively. Require
`0.5 <= follow_stop_distance < follow_resume_distance <= 8`. A companion waiting near its target
retains the finite follow controller, so a later short walk can resume navigation. Distance
selection does not widen the control box, the maximum target separation or the action lease.
The bridge holds one private, nonpersistent entity-ticking ticket at the home chunk. Minecraft
requires a supporting halo around that anchor. Shutdown and initialization failure remove the
owned ticket; the persistent created marker remains with the world. This keeps the home actor
available without a human client. It does not establish entity ticking throughout the entire
control box: movement beyond the home chunk can depend on ordinary player loading. Snapshot
`yaw` and `pitch` describe head gaze, so a turned head can be observed independently of body yaw.
The CLI's bounds narrow admission; the server configuration owns the continuing control box.
## Explicit operation
### Reviewed phrases and confirmations
The opt-in `--dialogue` console profile develops a model-free conversation before the ordinary
FIFO. Ask `možnosti`, `možnosti počasia`, `možnosti času` (or Czech/English equivalents), choose
a numbered option or give an exact supported command, then answer its confirmation. An unknown
phrase can be associated with the selected command after execution. The catalogue describes
the host's closed operations and selected permissions; it is not a live registry of every game
command. Structure placement and `/summon` currently have no admitted actuator and must be
reported unavailable, without inventing choices or executing chat as a console command.
`--confirmation unremembered` is the dialogue default. Effects require confirmation unless an
exact reviewed phrase explicitly permits skipping it. `always` requires it even for remembered
phrases; `never` omits this conversational check. State and cell reads do not need effect
confirmation. These settings do not replace native admission, server permissions or stop.
The confirmation repeats the concrete command. Only an unambiguous `áno`/`ano`/`yes` admits that
frozen proposal. Rejection, another instruction, expiry, target change or stop discards it.
Selection and confirmation cannot renew the original instruction deadline or stop generation.
Ask `Je to v poriadku?` only after a matched applied result. A positive answer can then offer
remembering: `áno` retains the meaning, while `áno bez potvrdenia` also permits future confirmation
skipping in `unremembered` mode. A negative, unknown, cancelled or failed outcome never teaches
a phrase.
Reuse is exact after Unicode normalization, case folding and outer whitespace removal, partitioned
by language and configured server/actor namespace. Each reuse creates a fresh request and passes
the ordinary native checks. A remembered follow command binds the currently selected target anew
instead of retaining an old player UUID. Original strict commands cannot be redefined as a
different action.
Without a separately selected memory database profile, reviewed phrases last only for this
console session. Cross-session records belong to Phylactery, not a JSON shadow database or the
public-note Archive. The explicit private `--memory-profile` selects a prepared local PostgreSQL
connection and owner; startup neither provisions nor migrates it. A missing schema or storage
failure refuses memory access rather than pretending it was a cache miss or retrying an action.
The profile is separate from voice/model selection. `:forget PHRASE` removes one exact phrase
in the current language and namespace; forgetting does not undo a game action.
This is a bounded lab dialogue, not durable Consent, full agent memory, semantic matching or an
arbitrary-command interpreter. Its pending conversation does not survive restart. Live voice,
game, PostgreSQL and timing qualification remain separate from offline source checks.
For a later voice trial, append `--dialogue --confirmation unremembered
--instruction-timeout 60` to the existing launch command. Selection and a spoken confirmation
share that original sixty-second lifetime. No model interpreter is selected by this profile.
The memory profile has exactly `version` (integer 1), `owner_id` (UUID), literal-loopback `host`,
`port`, `user`, `database` and private `password`. Use the prepared data-only runtime role;
administrative credentials are refused by the ordinary connection authority guard. Keep this
file in the declared private workspace. Never put it in the checkout or command-line arguments.
### Dump & Search score
`blockworld.companion.search@1` is an explicitly assembled, inactive native Pattern:
Dump → LiteralSearch → Report. A source adapter returns at most 256 items/128 KiB, exact
source/revision/digest and whether the catalogue is complete. Escaped literal matching first
narrows a request such as `castle` or `hrad`; the result keeps the match count, at most sixteen
candidates and three short choices with source-provided characteristics. A truncated dump cannot
claim how many matches exist in its unseen remainder. Data labels are discovery facts, never
instructions or executable commands.
A separately supplied ranking proposal contains only candidate IDs and binds the exact source,
query and candidate digest. It can reorder those choices but cannot invent an item or authorize
its execution. This is the input boundary for later admitted agent work, not a delivered
subagent adapter. It launches no agent, model or foreign runtime. A future delegation must use
the existing AgentJob/Graph authority and privacy boundaries; this score cannot bypass them.
The current game bridge has no structure/entity catalogue adapter. Consequently this score is
testable with an injected catalogue but is not connected to spoken castle search or live
structure/summon execution. Those require their own authoritative catalogue and typed game
operations. The spoken companion continues to report them unavailable.
The [Java project](https://github.com/hexanomicon/lychd/blob/main/clients/minecraft/README.md) owns the pinned build and server-side
installation. The Python entry is `scripts/companion_lab.py`; it opens one private external
workspace, an exact bridge profile, fresh finite policy and the existing native memory runtime.
Text commands and explicitly recorded or supplied WAV use the same parser and FIFO. `:record 3`
arms one three-second utterance; it does not enable continuous listening. `stop` and Ctrl-C remain
independent of speech inference. A failed or uncertain recorder/player retirement closes further
audio admission while preserving text control and the known game result. A recording failure
with proved recorder retirement refuses that utterance but permits a new explicit gesture;
it neither retries nor reuses the failed request identity. Stop during final recorder retirement
still cancels the utterance before transcription. Unknown launch or retirement cannot report
recording off or reopen capture and replies.
The console stamps each line's first bytes observed by its reader, before the consumer can wait
on stop settlement. This is reader observation, not the time a key was pressed in the terminal.
Its original stop generation and finite deadline cannot be renewed by that
wait. Ordinary input received during console stop settlement refuses, including recording and
target changes; stop and quit retain priority. An explicitly new line after settlement remains
usable. Target changes follow console order, and a recording binds that ordered target before
asynchronous capture starts. Waiting for audio ownership does not extend a recording trigger's
deadline or permit an expired trigger to start the microphone.
Select `--output human` for a private, readable foreground console; JSON remains the default.
The human view shows the original recognized words before command parsing, including refused
wording. It escapes terminal controls and bounds visible text while keeping the retained
transcript unchanged. This explicit private display is separate from structural diagnostics;
ordinary JSON output does not add raw recognized words. Existing localized feedback remains
the game-result wording, and speech generation, player settlement and evidence retention are
shown separately. A failed native receipt is reported even when a queued cancellation resolved
before publication; a failed audio artifact remains distinct from successfully generated bytes
and a retained reply record. No result or display failure authorizes replay.
`:status` reads a process-local snapshot of the existing operator FIFO and current audio
operations. It performs no game/model request, native Run admission, queue expiry or evidence
settlement. A passed deadline is not a terminal disposition until its owner settles it. The
local pending queue is distinct from the server mailbox. Target changes and ordinary controls
retain the same reader generation/deadline rule. Stop notices distinguish requested from
acknowledged or unknown; presentation failure cannot erase a known outcome or bypass retirement.
Audio labels describe finite operations requested or pending, not verified device readiness,
audible start or human hearing. This console view is separate from the optional focused-game
controls below; it does not qualify a physical microphone.
The shared [Linux recorder](../../sepulcher/extensions/echo-local-probe.md#probe-contract) uses
the host's ALSA `default` input. Select the intended microphone in the host sound settings;
the lab neither changes routing nor retries on another device.
Selected reply playback likewise uses the host's ALSA `default` output. The shared helper accepts
only an explicit supported `pulse` alternative; failure never selects another output. Playback
forwards the inspected WAV unchanged and does not alter host routing or volume.
To inspect delay, use the private `REQUEST_ID-timing.json` (`companion-host-timing@1`) retained
for each accepted voice input. Timing begins at host voice admission, before the utterance is
scheduled; it does not begin at a physical key press or speech onset.
Fixed stages distinguish audio ownership wait, capture or supplied-WAV read, source/transcript
retention, transcription, instruction admission, queue/native outcome wait, reply audio wait,
synthesis, reply artifact retention, player retirement and the existing evidence-write attempts.
Spoken stop has its own stage. Relative monotonic milliseconds and directly measured local elapsed
time are observations, not deadlines. Unavailable clocks yield null, and unattempted work differs
from a measured zero. Stages may overlap, so their durations must not be summed.
Queue/native outcome wait includes local scheduling, FIFO, Run/Graph and transport, and often
native evidence publication. It does not separate queue time from game computation. The record
distinguishes a supplied native result from local settlement without one. It closes once the
existing voice and optional reply watcher retire, including cancellation before coroutine entry
and disabled replies; it adds no wait or retry. Open intervals close as locally retired with
work unknown. Failed/cancelled speech calls do not establish remote computation stopped, and
player retirement does not establish hearing. The timing record's own write/presentation is
outside its elapsed interval. Timing retention failure is reported separately and cannot change
the game result, audio ownership or original input identity/deadline. This host-lab observation
does not claim native Echo timing or physical microphone qualification.
The prepared CPU speech route is an engineering baseline, not a completed SK/CS/EN quality
qualification. A twelve-case generated-WAV check applied four ordinary commands, applied spoken
stop and refused a negative instruction; six other examples refused, including synthetic Slovak
`stav` and all three basic Czech examples. This does not isolate the synthesizer from the
recognizer, nor predict human accuracy. Start a human test with a fresh explicit recording,
compare its unmodified transcript to the supported text grammar and keep text control available.
Do not turn a similar-sounding refusal into a guessed action. The
[provider study](../../sepulcher/extensions/echo-research.md) lists comparison candidates;
none is selected automatically after a failure.
For an explicit comparison in the same console, `:language` reports the configured input and
reply languages without a speech or game request. `:language cs` selects Czech transcription
for later input and preserves the reply setting; `:language cs cs` explicitly selects Czech
input and generated replies. Only `sk`, `cs` and `en` are accepted, and both requested settings
must be declared by the already selected profile before either changes. An omitted reply
argument preserves disabled replies. Enabling replies this way does not enable playback.
A change refuses while a voice input or reply is still owned; it is never queued or retried.
Finish or stop that work before entering a fresh change. Querying remains observational, and
the existing reader generation/deadline and stop rules still apply. Selection changes no
provider, model, device, profile file or game authority and does not qualify language quality.
### Optional focused-game controls
The held-input extension adds a third, initially unbound push-to-talk mapping beside
fixed-duration recording and stop. With the matching private control and speech profiles,
explicit `--hold-seconds 15` enables held capture with a fifteen-second maximum. The six-field
control profile stays unchanged; `record_seconds` still selects the fixed recording duration.
Choose each binding in the private Minecraft instance's Controls screen; no particular key is
a universal default.
Press requests capture for one original voice occurrence. Release finishes that same capture
and permits its existing transcription/native admission only after at least 250 milliseconds
of usable captured PCM and confirmed recorder retirement. Releasing before capture arms
discards the gesture. Reaching the hard limit without release also discards it. Holding either
capture key never repeats an utterance. Continuous listening and wake words remain unimplemented;
these controls need no global keyboard hook or administrator privileges.
Menu, pause, focus, world and observed host-context boundaries suppress a held release and
request best-effort stop for outstanding dispatched input. They also discard unsent old work.
All three controls must be released before another fresh edge. A console `:target` change
selects later input; an already-owned hold retains its captured target. A host-context change can
trigger client cancellation only after the client observes it.
Private `/v1/hold` and `/v1/release` control mutations retain the original voice UUID, context,
generation and absolute instruction expiry. Release has a separately frozen three-second
forwarding window; it cannot renew the original deadline. Per-phase digests retain duplicate
observations, and bounded release-before-start tombstones prevent delayed capture. The exact
six-field private profile and fixed `/v1/record` operation retain their existing meanings.
Held capture accepts only bounded even PCM after intentional SIGINT and confirmed recorder-group
retirement; canceled, too-short, forced or uncertain retirement never supplies transcription.
The early-finish exit-status rule is qualified against local ALSA `arecord` 1.2.16 on its `null`
device; it does not establish compatibility with every recorder version or a physical input.
Release requests and actual captured PCM/retirement remain distinct from physical microphone or
hearing proof. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns
qualification; physical keys, microphone capture and human hearing still need live acceptance.
The separate [voice client](https://github.com/hexanomicon/lychd/tree/main/clients/minecraft-voice)
installs only in the local Fabric player instance. Its README owns the pinned build, private
profile shape and installation. The dedicated-server actuator remains a separate artifact.
Without the instance's explicit `config/lychd-voice.json`, controls and network workers are absent.
All three mappings default to unbound; select fixed recording, held recording and stop in
Minecraft's Controls screen. A function key for stop also works through the client's menu input
path. Stop keeps priority over capture. Physical focus, key handling and audio require their
own live acceptance.
Opt the foreground console into the matching private control profile with `--control-profile`;
that file must be inside its declared private workspace. The distinct control bearer never uses
the game actuator credential. Its literal-loopback endpoint exposes only finite recording,
priority stop and query-only local operation state. It accepts no transcript, media path, target,
provider selection or game command. The profile's player and server address guard the local
client context; they neither select the host's follow target nor authenticate the game server.
Linux/POSIX private-file custody is required; Windows and remote multiplayer are unqualified.
One fresh press requests one bounded utterance. Original UUID, context, generation and deadlines
precede worker waiting. The complete instruction lifetime must fit the remaining console session;
it is never shortened or renewed. Ordinary work, held release and stop use separately reserved
bounded workers, so a blocked start exchange cannot occupy the release or stop lane. Identity
histories remain finite. Stop fences the existing console queue synchronously, and a fresh
same-session stop remains available after recording authority expires to retire
already-owned audio. Final console shutdown seals recording before its final audio retirement.
A lost mutation acknowledgement permits only lookup of that original UUID, never replay.
The local Slovak/Czech/English multiline HUD follows the host's observations. It distinguishes
a capture request from the first observed PCM (`recording`) and recorder retirement (`finishing`).
Known game outcome, reply generation, playback and retained evidence remain separate stages. The
HUD receives no recognized words or foreign diagnostic prose, and terminal native evidence cannot
regress to an older pending snapshot.
These context guards and status labels are source contracts, not proof of a physical key press,
active microphone or heard reply. Retire uncertain audio through the console before starting a
new session. If the console session changes, restart the client explicitly.
The view wraps the complete result within current scaled GUI bounds and leaves missing fields
unreported. If it cannot fit, retain the own ID in a notice directing the player to enlarge the
display or use the foreground console. Never replace the full result with a success-only subset.
Without `--intent-profile`, commands use the exact parser. Select a private version 1 intent
profile explicitly to enable state, idle and bound-follow paraphrases. It requires a literal
loopback HTTP `/v1` endpoint with an explicit port, exact served model ID and finite budgets.
Defaults are 4096 context tokens, 512 output tokens, fifteen seconds per model attempt and sixteen
model requests per session. The respective ceilings are 8192, 512, fifteen seconds and thirty-two
requests. The model service must already be available; this entry cannot install or activate it.
`--instruction-timeout` defaults to thirty seconds and accepts one to sixty seconds, measured
from original capture rather than after transcription or queuing.
Exact look, movement and chat commands bypass the model even when interpretation is enabled.
In particular, `say`, `povedz` and `řekni` begin ordinary game-chat syntax. Malformed reserved
commands, embedded controls, slash commands, UUIDs and coordinate-bearing paraphrases are not
repaired through inference. A clarification ends the current instruction; the operator supplies
a fresh instruction rather than starting an autonomous model loop.
Speech profiles select their recognizer explicitly. A version 1 profile uses audio.cpp for both
operations; a version 2 profile can select whisper.cpp transcription and retain audio.cpp
synthesis with separate operation pins. Whisper requires `--language sk`, `cs` or another language
declared by that exact profile. No failed request switches recognizers or selects a hosted service.
The voice path removes only outer spaces, tabs and line endings before strict parsing while
retaining the original transcript. It does not repair misrecognized words or admit embedded
control characters. Synthetic success does not qualify the player's microphone or pronunciation.
A voice instruction captures its request identity, stop generation, absolute expiry and explicitly bound player
before recording or transcription begins. Changing `:target` affects later utterances; it cannot
redirect an utterance already being processed or supply a target that was absent at capture.
Its private source, transcript and voice record correlate with the subsequently admitted command
by the same request identity. An unrecognized utterance records no invented native Run.
Voice failures retain their failed host boundary: input eligibility, recording, supplied audio,
source retention, transcription, transcript retention or instruction admission. Fixed
Slovak/Czech/English feedback reaches both the foreground and the existing game-control feedback
field. It names the failed operation, not a guessed device/provider cause. A known pre-admission
rejection has no game disposition; an uncertain admission cannot assert that no game action was
sent. A later known native result remains authoritative. Failed spoken-stop settlement reports
an unknown stop for the original voice identity without inventing a server-stop ID or retrying.
A capture failure permits fresh recording only when recorder retirement is proved. Unknown audio
ownership keeps audio disabled and directs the person to text control; this recovery advice cannot
turn uncertain command admission into a refusal. Other recoverable failures require an
explicit new input; the original request, expiry and stop generation are never renewed or
automatically replayed. Failure feedback makes no claim that remote speech inference retired.
Keep the request UUID even when an admitted command expires or is cancelled before a Run exists.
Resolve those early results immediately with private evidence pending, then retain eventual
evidence status separately. The session joins publication on stop or close. A failure to retain
evidence cannot rewrite a known game outcome.
Use only the matched observation's mode and rounded coordinates in state feedback; do not speak
player identifiers or raw diagnostic prose. Movement feedback describes the applied instruction
without claiming observed progress or arrival.
An applied idle, look, movement or follow result retains `controller_expires_at_ms`, the exact
outgoing host authorization deadline after the lease, session and original instruction limits
are combined. This optional local metadata is separate from the Minecraft wire receipt.
Correlated feedback describes a finite upper bound and can direct a fresh `stav`/`state`
instruction to inspect the current server mode. The controller may end earlier. A passed host
deadline is not an observed stop acknowledgement or an explanation for why the controller ended;
`:status` remains a local queue/audio snapshot. Identical request identities never renew a lease.
`scripts/qualify_companion_lab.py` is the explicit CPU-only functional proof against an already
prepared, empty test server. It moves only the admitted NPC within its home chunk, exercises the
real native Graph/HTTP boundary, and writes private evidence outside every checkout. It is not a
server provisioner and must not be used against a shared play session. Human microphone, playback
and Prism joining have their own next-session checks.
## Qualification boundary
### Focused-input boundary
A focused-game input adapter must originate in the explicitly opted-in local player client.
A game-server packet, chat message or shared-world command cannot authorize local microphone
capture. The adapter must preserve the original gesture identity, context, stop generation and
finite deadline through the existing voice path. One held key must not become repeated utterances;
focus or world changes must discard unsent old gestures. Stop needs independent admission and a
synchronous fence before asynchronous retirement. A displayed request is not verified recording,
a game result or human hearing.
Any such adapter remains separate from the dedicated-server actuator and native cognition. Its
private control credential, finite capture-attempt budget, operation observations, unknown-result
handling and cleanup need their own evidence. Passing server or synthetic voice tests does not
qualify actual focused-client interaction.
The separate opt-in client GameTest has exercised the actual production initializer, mappings,
ticks, menu transitions and disconnect against a synthetic local protocol fixture. Five record
requests and four stops retained their original identities and deadlines; a held key did not
replay, and the reserved stop arrived before a blocked ordinary response. The actual stopping
event recorded retired production and fixture workers. Minecraft selected Vulkan llvmpipe inside
a resource-limited CPU container; no GPU/audio nodes, human account or existing world were supplied.
This qualifies client ingress and submitted HUD projection, with no native host/game action or
speech request. Fabric substitutes input/focus, so physical interaction remains outside the proof.
Five display cases cover three synthetic mixed-result payloads: SK/CS/EN game-applied/reply-failed
with 400-character literal feedback, uncertain playback/server work, and player exit with hearing
unconfirmed. At 640×480 with the default font, all complete rows fit the 320×240 scaled GUI and
the settled screenshots retain the own ID and independent outcomes. F1/menu checks require GUI
extraction progress; recovery requires a fresh matching panel. Other fonts and transient overlay
occlusion remain unqualified. The voice-client README owns fixture preparation and artifact exclusion.
### Optional local interpretation
The optional slice interprets one short paraphrase as state, idle, following the explicitly
bound player, no action, or a clarification. Exact look, movement and chat syntax remains
available through the strict path. Interpretation creates one native Run in the existing FIFO;
it does not create a second command queue or let a model enqueue its own tasks.
One explicitly selected literal-loopback model profile supplies a native Dispatcher chat grant
to an Agent with no tools or writes. It may return only bounded plain text that must decode to
the closed decision schema. There is one model request, no repair retry, a finite token/time
budget and no model or remote-provider fallback. An unavailable or incomplete interpretation
produces no game action. Deterministic commands remain usable independently of that model.
Exact response identity and explicit completion metadata are checked before Agent output
processing. A bounded provider reasoning part is discarded there; only the closed decision can
enter Agent history, Graph state and the native decision log.
The original request identity, target, stop generation, material references and absolute
instruction expiry survive capture, queuing and inference. Expiry is checked again after model
waiting and at physical handoff; a new lease cannot renew an old instruction. The host resolves
the bound player, validates the resulting typed command and retains stop priority. A model cannot
invent coordinates, choose another player or issue an arbitrary Minecraft command. No-action and
clarification results are explicit terminal outcomes, with private input custody even before Run
admission. Restored Graph state must preserve the original envelope and the exact derived command.
Optional interpretation entered at Pattern revision 2; typed requests retain their original three-node path.
The clock-result shape uses Pattern `4`, implementation `py.6` and checkpoint schema
`companion-state-v6`. The weather cohort used `3`/`py.5`/`companion-state-v5`; the cell cohort used `py.4`/`companion-state-v4`; the earlier
controller-deadline cohort used `py.3`/`companion-state-v3`.
An older result without optional clock/weather/cell/deadline facts remains structurally parseable; that does
not migrate or rebind an older Run's exact retained Pattern closure.
A bounded live check used the explicitly selected local Qwen service and CPU Whisper/Supertonic
speech. Synthetic Slovak idle, Czech state and English idle crossed the native Graph into the
game. Negative follow, unsupported building and multiple-action examples produced no game action;
the model decision was checked separately so an offline player could not mask a wrong proposal.
An affirmative bound-follow proposal was refused by the host while its configured player was
offline. This qualifies those particular examples, not general language accuracy or human following.
The optional model check is separate from the CPU-only deterministic server and speech proof.
### Controller and refusal acceptance
The opt-in controller qualification runs the same production controller and mailbox in a fresh,
disposable server GameTest world. A synthetic server player must enter Minecraft's actual player
list, so UUID lookup and real pathfinding are exercised. Observed wolf displacement, waiting,
resuming, lease expiry, target loss and stop acknowledgement matter separately from action
acceptance. The fixture owns controller and player cleanup on success, failure and shutdown;
it never opens the operator's saved world or substitutes for authenticated-human following.
The Java project's `-PcontrollerGameTest=true` profile owns the exact command and retained
observations. It uses normal entity physics and an explicit synthetic lease clock advancing
50 milliseconds per controller tick. An independent copy whose follow policy always waited
failed on missing displacement; both positive and negative worlds released their owned actors,
players and controller tickets. This establishes a useful motion oracle, not human latency or
navigation across chunks. Default builds do not start the GameTest server, and delivery archives
exclude its test-only mod and accessor.
Operator feedback distinguishes host-known reasons for refusal using a closed vocabulary.
A target absent from the bounded observation is described as unavailable, rather than assumed
offline. Bounds refusal, an exhausted interpretation budget and a command cancelled before native
admission have different recovery guidance. Foreign diagnostic text is never classified or spoken
as authority. Interrupted effects retain uncertainty; a reason cannot authorize another attempt.
When both native and session dispositions are supplied, their request identity, kind and reason
must agree before feedback describes a specific outcome. Conflicting records report uncertainty.
An unavailable interpreter, exhausted interpretation budget or rejected model response leaves
exact commands such as `stav` usable without model dispatch. These reasons stay outside the
Minecraft action-record wire schema; they do not reinterpret arbitrary server diagnostics.
### Reply evidence acceptance
The experimental reply path keeps the known game outcome separate from speech generation, retained
audio and player settlement. Each admitted command must retain its request identity and real
Run identity, or an explicit absent Run for outcomes settled before native admission. Optional
audio records identify the same instruction; synthesis metadata stays unchanged and cannot
claim playback. Player exit means the owned player and descendants settled, not that a human
heard or understood the reply.
Retain generated bytes in private `REQUEST_ID-reply.wav` and the unchanged synthesis observation
in `REQUEST_ID-reply.json`. Use `REQUEST_ID-reply-evidence.json` to correlate the request, real or
absent/unknown Run, game disposition, retained artifacts and player settlement separately.
If retaining that evidence fails, report the failure rather than claim a saved receipt. Cancelling
the caller's wait still leaves the console-owned native outcome available for the reply.
Stop must settle owned reply work even when requested before its coroutine starts, while
synthesis is pending, or during playback. A cancelled synthesis wait cannot prove that the
speech server stopped working. Unknown player retirement keeps audio admission closed;
text control and known game outcomes survive. Reply/evidence failure never causes game replay
or erases a known action result. Operator diagnostics remain value-free and correlated.
This page initially records the construction and acceptance contract. Executable delivery and
the actual build, server, transport, native graph and speech evidence belong in
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery). A generated Quadlet or
configuration file alone is not a running service receipt. An opt-in local lab does not register
the profile at normal application boot or implement managed Sentinel placement.
The first live proof must cross the real native graph and local transport into a headless server,
then return an identity-correlated observation. Challenge malformed/full/expired requests, stale
boot and stop generations, duplicate identities, cancellation, missing actors, lost replies and
restart. Human Prism joining, microphone recognition and listening remain separately recorded
checks. Keep this first slice small before admitting inventory, building or arbitrary mod tools.
Return to [Blockworld](index.md).
---
title: "Horizon assist"
plain_name: "Blockworld: Horizon assist"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Partial"
original: https://hexanomicon.dev/compositions/blockworld/horizon-assist/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/horizon-assist/
---
# Horizon assist (Blockworld: Horizon assist)
## Plain-English summary (Snayu)
**What it is:** An experimental profile where the operator speaks a short instruction while playing and a separately controlled Horizon game client performs one bounded action (follow, build a few cells, look) and reports what it observed.
**Why it matters:** Read this if you work on the attached-client Minecraft path, its admission rules, following/building behaviour or qualification tests.
- It is a separate experimental contract; its records cannot count as proof for the managed Blockworld mission.
- One session owns one pinned local control endpoint and allows only one active action at a time.
- Single-player lab mode and remote mode are distinct bindings and refuse each other's state.
**Status:** Partial. Opt-in local profile; no live multiplayer following, shared building or speech playback.
## Original text (Hexanomicon)
**Unofficial Minecraft integration. Neither Mojang nor Microsoft approves or is associated with this project.**
Publisher: LychD contributors · Contact: [hexanomicon@proton.me](mailto:hexanomicon@proton.me).
An operator speaks a short instruction while playing; a separately controlled Horizon client
performs one bounded action and reports what that client observed. This experimental attached
profile develops that interaction before the managed inhabitant fixture is available.
[Playing with a companion](horizon-play.md) turns that boundary into user stories, experience
criteria and a staged playtest, including useful feedback and quiet idle behavior.
## Execution contract
`blockworld.horizon_assist@1` is a separate experimental score, not an implementation or migration
of `blockworld.bounded_mission@2`. Its records cannot satisfy `PlacementReceiptV1`. The managed,
online-mode, dedicated non-operator bot fixture and its server-authoritative receipts remain the
proving target for the bounded mission.
Admission pins one explicitly supplied local control endpoint, expected client/world identity,
finite permitted actions, coordinate and time bounds, and an external private workspace. One
session exclusively owns that endpoint and permits only one active action. A human player's
endpoint is not implicitly a companion. A companion needs its own client, identity and endpoint;
the pinned Horizon client's authentication limits must be reported before connecting it.
An explicit `singleplayer_lab` binding may qualify the control mechanism in a disposable local
world. It requires the pinned process/socket and exact world/dimension with no remote server;
it supplies no second player or multiplayer evidence. A `remote` binding instead requires the
exact remote client/server observations. The two modes must refuse each other's state.
The `world` field pins the client's reported cosmetic label. A fresh remote Horizon client can
report an empty string; an explicitly pinned empty label is accepted as that observation, never
replaced with an invented server world name. The exact server address, client process generation,
own-client name, dimension and loaded/joined state remain required. These observations do not
authenticate a server world or detect every server-side world replacement at the same address.
The first action passage is attributed transcript or explicit text, a closed typed command,
validation, one serial Graph action, and a client-observed result. Unrecognized or ambiguous
instructions refuse. Text never becomes an arbitrary control command, shell command, administrator
command or MCP tool name. Speech capture, transcription and synthesis retain their own
[Echo](../../sepulcher/extensions/echo.md) boundary.
The adapter exposes `status` as a closed operational projection: client screen/dimension,
creative mode, frame/tick/chunk counters and finite performance measurements, selected renderer
identity/memory fields, and the pinned server's address/name/joined/loaded fields. Each exposed
leaf keeps its expected scalar or fixed-size numeric shape; an allowed key cannot carry an
arbitrary nested payload. Missing server data remains missing and malformed server identity
cannot become a single-player null binding. The raw status reply's debug/clipboard, keyboard
state, name tags and unrecognized fields never become returned observations, Graph state or
events. Binding checks and explicit status queries use the same projection boundary.
The adapter checks current session authority immediately before sending. It records an attempt
before the physical send, never automatically replays an action, and distinguishes refusal,
client-reported completion, cancellation and unknown outcome. A lost reply or process crash does
not prove that an effect failed. Process-local execution supplies no restart continuation,
durable Phylactery custody or server-authoritative world proof.
Treat each Run as one attempt. Once any claim is fenced, this adapter permanently retires that
Run identity, including a claim with a nonzero delivery sequence. It admits no successor worker
claim. Resuming or replaying a failed claim would require a different profile with an explicit
claim-aware handoff.
The local ownership record also remembers whether the client generation was interrupted or
left unknown. Starting another controller or changing the socket path cannot reopen it. To admit
a successor, prove that the prior client process generation ended or reconcile it explicitly
outside this profile. The record prevents unsafe reuse; it cannot resume a Run, reconstruct a
lost world outcome, or turn observations into placement receipts.
Cancellation fences new sends and uses a separate control connection to stop the owned client's
active action and release movement. Closing a waiting socket alone does not stop Horizon.
Cancellation completes only after the stop boundary is observed; otherwise the outcome remains
unknown. Stopping cannot undo a block already placed or movement already performed.
## Following and building
Following requires a separately bound, read-only position feed for the exact person being followed,
finite duration and distance bounds, and stop-on-lost-target behavior. An unordered list of player
positions cannot establish that identity. Building requires an admitted finite placement plan,
plot and inventory limits, and honest per-action outcomes; a spoken request for a house is not a
blueprint or proof of completion.
The first building qualification is `blockworld.horizon_build_step@1`: an explicitly admitted,
immutable one-cell or three-cell plan of ordinary `minecraft:oak_planks`, with exact integer
coordinates, plot, session, expected client labels/dimension, mode, expiry, placement and read
budgets, and a canonical content digest. Each cell is one fresh native Run. It shares the assist
service's session authority and attempt budget; a plan grants no selection, inventory rearrangement,
item creation, movement, administrator command or arbitrary material.
The initial plan read budget counts logical composition calls: eight per cell and at most 24
for three cells. A cell/inventory inspection performs one fresh state/status pair and its fixed
query under a combined timeout. Together with the effect's binding checks, a successful cell can
issue 26 read query lines; three cells can issue 78, plus admission reads. The adapter exposes
physical query counts separately. Containment has its own finite priority path and is never
refused because the plan used its read budget.
Preflight first establishes that the placement is eligible: a loaded exact-air target, plain
stone immediately below, an idle healthy client in the admitted mode, and a target within the
shared session's maximum distance and conservative eye reach. Ordinary planks must already be
selected with enough held inventory; offhand and carried stacks must be empty.
The adapter then emits only `place X Y Z`. It omits `--item` because Horizon changes selection
before some placement checks. Afterwards, a fresh cell/inventory/state read must match the
intended material and expected delta: one consumed item in survival, or zero consumption in
explicitly admitted creative mode. Only then may the cursor advance. Existing blocks refuse and
are never credited as this bot's work. Any failed, changed, cancelled or unknown step stops the
plan without automatic replay or repair.
Horizon's stock placement primitive has no atomic expected-before/material/support comparison.
Its click is consumed on a later game tick, and its `ok` means any target state change. These
preflight reads therefore refuse **observed** changed conditions; they cannot exclude every
concurrent world change or interaction. The first live proof requires a dedicated controlled
disposable fixture without concurrent human input or entities around the cell. Records retain
client observations and partial effects honestly; they are not server receipts or an atomic
placement guarantee. A shared-world house plan needs further qualification or a guarded upstream
primitive. The explicit local assembly now registers this score only when supplied its shared
build service. Portable native-Run tests and real synthetic-game socket tests exercise one and
three cells, expected query counts, the last shared action slot, uncertain partial effects and
cancellation. Live placement remains a separate qualification.
The supervisor admits a successor cell only after the preceding native delivery reaches `DONE`
and its exact Run has a known build result. A report may have observed a cell before native
settlement; cancellation in that gap fences the whole plan. Operator instructions and capture
invalidate building authority synchronously, then settle the previous Run and effect before
continuing. A missing or unknown result disarms the controller. No cell resumes after restart.
## Perception and model proposals
The current action and behavior graphs use deterministic policy, without a planning model.
Speech recognition and synthesis do not observe the game. A future Mind passage must receive
explicitly attributed game observations; a model being available does not give it sight or
action authority. This passage can use the existing Animator, Dispatcher and Agent contracts
without adding a second model runtime or changing the Core execution contract.
The first perception target is a bounded structured sample: pinned client generation, session,
sample identity, observation interval, pose, health, held item and exact queried cells. Select
only required fields; a raw diagnostic status document may include unrelated host data. Missing
cells, unloaded terrain and unobserved players remain unknown. Exact cell queries must also
respect the dimension's vertical bounds: a horizontally resident chunk does not establish valid
height. Separate state and status replies are observations over an interval, not an atomic world
snapshot or authenticated server proof.
A finite reasoning step leases one exact capability and returns a typed proposal tied to the
provided sample. It receives no game effect tools, arbitrary command grammar or runtime lifecycle
authority. Hostile world labels, chat and other game text remain data. Missing, old or changed
observations require fresh observation rather than invented facts. Schema validity establishes
shape only; the proposal still needs independent session, freshness, bounds, material and action
admission. A model response never calls the effect port directly.
Qualification separates structured perception from pixel vision. A screenshot needs an owned
private destination, bounded capture and image validation, including the renderer's actual pixel
format. Seeing a captured image during an operator test does not establish native agent image
materialization. Before any broader autonomy, test observe, propose, validate, act and observe
again, including stale samples, unknown terrain, misleading game text, cancellation and a game
reply that reports success without the expected change. Measure reasoning separately; planning
does not belong in every idle or follow tick.
## Behavior graphs and idle
The intended supervisor selects finite behavior scores from explicit operator policy: handle a
spoken instruction, observe while idle, follow the bound target, or advance an admitted building
plan. Each invocation pins its trigger, session, deadline, action budget and stop conditions.
World events are observations, not instructions or authority. A missing or stale observation
stops the dependent behavior; it cannot justify invented player identity or world facts.
Idle means bounded observation or waiting for an admitted event. It grants no exploration,
building, inventory use or open-ended model loop. Effects during idle require a separately
selected finite task. Follow and build yield to explicit stop and new operator instructions;
replacing a task first settles or reconciles its active effect.
Scheduling coalesces repeated observations, uses bounded cadence and cooldowns, and avoids model
calls when deterministic policy can wait or select a known command. At most one effect owns the
client. Each tick or action receives a deadline and freshness bound, with finite retry policy for
reads and no replay of uncertain effects. Logs distinguish time waiting, speech inference,
reasoning, Graph execution and game response. Optimizations must preserve cancellation, authority
and outcome semantics, and be supported by measurements of the exact runtime profile.
The first behavior cut uses separate `blockworld.horizon_idle_tick@1` and
`blockworld.horizon_follow_tick@1` scores. Each tick is a fresh native Run with a pinned typed
trigger and at most one physical command, using the same assist policy and action budget as
operator commands. Nodes never submit a nested Run. The process-local supervisor owns cadence;
an in-memory timer is not a durable Graph wait or restart schedule.
An initial directive lasts at most 60 seconds and 60 ticks, at a cadence of at least one second.
One session admits at most 20 directives by default, with an explicit ceiling of 100.
Idle reads the bound bot and reports changes without movement, inventory use or model calls.
Follow additionally reads the exact target client's own pose through a query-only port; that
port has no action, stop or arbitrary-command operation. Both clients must have distinct pinned
processes and endpoints, and explicit `remote` bindings to the same server. Integrated-host LAN
and single-player associations are outside this first follow profile.
The engineering voice assembly explicitly opts its concrete target observer into owned read
settlement. If a tick expires or is interrupted during an already started target read, the
observer joins that read under its independent observation timeout, discards the late sample
and propagates the original cancellation. Replacement waits for settlement; neither the sample
nor cleanup extends effect authority. Whole-read timeout is twice the binding timeout, with
bounded connection cleanup, so teardown can finish after the behavior deadline.
Default direct observation still retires on cancellation. In both modes, actual timeout,
invalid identity, disconnect, malformed response or explicit closure permanently retires the
observer. It never reopens itself, discovers another player or reuses a cancelled sample.
Follow uses a stop-distance deadband and segments of at most four blocks, with a game action
timeout of at most one second. A target sample carries a local monotonic time, sequence and task
generation. Stale samples, health loss, loading, changed world/dimension/server, excessive
separation, elapsed task authority or exhausted budgets fence the task. Freshness and generation
are checked again immediately before action bytes are sent. A deadline watcher cancels an action
that outlives its sample or task; a command already handed off still requires containment.
One arbiter admits operator commands and ticks. It coalesces repeated tick requests into one
pending request, leaving no catch-up backlog. When replacing a behavior, it invalidates that
generation before yielding, settles the previous Run and owned effect, and only then admits a
successor. Operator commands take priority and clear the prior behavior.
If an outcome is unknown, disarm the controller rather than advance the task. Explicit stop ends
the session. The logs retain tick decisions, native Run events, action/observation counts and
monotonic timing. Deterministic idle and follow use zero model calls.
The stock `goto` dialect stops within 1.5 blocks of its waypoint. Follow accounts for that radius
when selecting a waypoint and requires a segment ceiling greater than 1.5 blocks; an already
reached waypoint cannot serve as evidence of movement toward the target. A successful response
remains a client report, including when pathfinding made no displacement.
A client-reported follow completion still needs a progress check. Read the bot again and compare
its pose with the pose validated immediately before sending the command, using the tick's original
target sample. Report `moved` only after at least 0.05 blocks of observed progress toward that
sample, with a current in-bounds, healthy, idle client in the same world/dimension. This proves
neither that the target stayed there nor that the command caused the displacement.
If there was no progress, stop the finite task instead of spending its remaining budget on
repeated segments. Missing, stale or changed post-observation also stops the task, preserving the
known client response and leaving movement unverified. Count this extra logical read. Any later
operator instruction needs ordinary fresh admission; no automatic retry follows.
The explicit local assembly registers these finite behavior scores only when supplied the shared
behavior service. Portable tests cover their native checkpoints and the supervisor's arbitration;
live two-client following remains a separate qualification. The initial one-action score alone
establishes neither following nor autonomous building. The separately supplied finite build
service starts with one-cell and three-cell qualification before a house blueprint.
## Qualification
The explicit checkout tools run as `python -m scripts.horizon_assist` for one typed/text action,
or `python -m scripts.blockworld_voice` for a supplied WAV or an Enter-to-record session. Their
help owns the exact option grammar. Normal application boot selects neither profile.
The private game profile binds `binding`, `policy`, `workspace` and nonempty `checkout_roots`.
The workspace is disjoint from every declared checkout in both directions; its profile and
evidence stay inside it. The speech entry additionally receives an exact local speech profile.
Both profiles must refer to the same private evidence workspace. The operator pins the actual
client PID/start ticks, socket, world/dimension, mode, finite bounds, action budget and expiry.
The initial command grammar supports `state`/`stav`, `status`, `goto`/`choď X Y Z`,
`look-at`/`pozri X Y Z`, and `say`/`povedz TEXT`. Coordinates must be explicit finite numbers;
unknown wording refuses. This parser uses no LLM and promises no free-form language understanding.
`stop`, `quit` or SIGINT ends the voice session and fences future sends. A new explicit session
is required afterward. Spoken stop supplements the independent keyboard/control stop; transcription
quality is not a guarantee that an emergency word will be recognized.
The behavior-enabled voice entry additionally recognizes exact `idle`/`čakaj`/`čekej` and
`follow me`/`nasleduj ma`/`následuj mě` phrases. A finite `--behavior-seconds` duration defaults to
30 seconds. Idle can observe the explicit single-player lab. Follow requires an additional
`--target-profile` inside the same private workspace: a closed JSON object with only `binding`,
using the same binding fields as the bot profile. It grants query access only. Both bindings must
be remote with matching expected world labels, dimension and server address, and different clients
and endpoints. Starting
capture interrupts and settles a previous behavior before the microphone opens.
An optional `--build-plan` supplies a private JSON `BuildPlan` inside that same workspace.
Duplicate keys, nonfinite numbers and oversized documents refuse. The exact phrase
`build approved plan` or `postav schválený plán` admits those frozen bytes once; it cannot generate
coordinates or materials from speech. The plan pins the existing session and expires within its
authority; its finite duration is at most 60 seconds. The game policy must explicitly permit
`place`, and the binding timeout must be at least six seconds for Horizon's fixed five-second
placement task. `place` remains absent from the general typed/text action grammar. The voice
source-file mode joins the finite build before closing; interactive capture interrupts it.
The voice entry privately retains the source WAV, attributed transcript, native events and a
monotonic stage timing receipt. It presents the retained outcome in fixed Slovak/Czech/English
wording, distinguishing task start, client report, refusal and unknown effect. Unchanged idle
ticks keep their private evidence without repeated console announcements.
Read timing according to the work being measured. Pre-capture settlement has its own field. For
a one-action command, the Graph stage includes native admission, game work and event custody. For
a background behavior or build, it measures acceptance and scheduling only; each tick or cell
records its own native events, elapsed time and process CPU. Reply generation may overlap that
background work. Source-file mode joins the finite task before closing, but the utterance's Graph
timing still cannot stand for task completion time.
Optional replies produce a WAV and generation facts with playback `not_attempted`. Explicit
`--play-replies`, together with `--reply-language`, additionally invokes a fixed local player on
those validated bounded bytes after capture has closed. Player exit is recorded separately as
`player_exited`, not human hearing. Playback has its own timing. Stop joins the owned process
group; a late process launch is adopted and retired without audio even after its work deadline.
Required OS ownership settlement may exceed that deadline. Unproven player retirement ends the
session and keeps capture closed. This helper is not native Echo playback admission or a physical
speaker qualification.
The shared [local player](../../sepulcher/extensions/echo-local-probe.md#probe-contract) uses
the host's ALSA `default` output unless `pulse` is explicitly selected at its helper boundary.
There is no device fallback, routing change or volume adjustment.
An optional synthesis or settled player failure preserves the game result and records the failed
reply stage without replay. Synthesis observations remain generation facts; later playback is a
separate observation. Capture starts only after the person explicitly requests that finite
recording, with active/off indicators. Continuous microphone listening, conversational barge-in
and automatic music ducking are outside this profile.
The shared recorder distinguishes a failed recording with proved group retirement from unknown
ownership. The former permits a fresh explicit gesture; the latter reports unknown and fences
this session before another capture or reply. Cancellation during final retirement still
propagates after settlement. An uncertain recorder never produces a normal off indication.
Portable tests must cover command refusal, endpoint exclusivity, identity and bounds changes,
cancel-before-send, stop during a waiting action, lost replies and absence of automatic replay.
Live qualification uses a disposable world and a dedicated client. The operator verifies
microphone capture, transcript meaning, audible playback, movement, interruption and later
collaborative play. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
owns delivery evidence; this contract alone does not establish a working adapter.
---
title: "Playing with a companion"
plain_name: "Blockworld: Playing with a companion"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Designed"
original: https://hexanomicon.dev/compositions/blockworld/horizon-play/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/horizon-play/
---
# Playing with a companion (Blockworld: Playing with a companion)
## Plain-English summary (Snayu)
**What it is:** User stories and acceptance trials for playing Minecraft with a companion: prepare, speak, observe, follow, build a few blocks and leave, with clear feedback and a quiet idle state.
**Why it matters:** Read this to understand the target player experience and acceptance criteria for the Horizon-assist companion.
- The first fifteen minutes are scripted: check microphone and models, speak one instruction, follow, build three cells, then stop cleanly.
- The companion must stay quiet when idle: no game actions, no planning calls and no repeated notices.
- These are goals and playtest criteria, not an announcement of delivered features.
**Status:** Designed. Targets for the experimental profile, not delivered features.
## Original text (Hexanomicon)
**Unofficial Minecraft integration. Neither Mojang nor Microsoft approves or is associated with this project.**
Publisher: LychD contributors · Contact: [hexanomicon@proton.me](mailto:hexanomicon@proton.me).
You start a world, ask the companion to follow, and begin a small building project together.
You should spend your attention on the world: know when the companion heard you, understand
what it can do, and interrupt it without navigating a technical console. A companion earns trust
by being useful, quiet when appropriate, and precise about work it did not finish.
These user stories and acceptance trials guide the experimental
[Horizon-assist profile](horizon-assist.md). They are targets, not a feature announcement.
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery;
the [managed mission](mission.md) retains its separate authority and receipt contract.
## The first fifteen minutes
1. **Prepare:** inspect the selected microphone, models, disposable world and separate bot
identity. Show what is ready and what needs attention before recording. A muted input is a
useful diagnosis, not a reason to change the person's audio settings silently.
2. **Speak:** record one short Slovak, Czech or English utterance. A visible indicator says when
capture is active. A text view and concise response make misunderstood words recoverable.
3. **Observe:** ask for state, then ask the companion to wait. It remains still and quiet while
bounded observations continue. Its presence must not turn into a stream of repeated speech.
4. **Follow:** bind the exact human client, stand still, then walk a few blocks. Check personal
distance, bounded movement, target loss and keyboard stop before attempting a longer walk.
5. **Build:** inspect one exact plank cell, supply materials, then try three cells. Compare the
world, inventory and retained outcomes. Stop during a step and inspect any partial result.
6. **Leave:** stop the controller before leaving the world. A new session rechecks client and
world identity and offers reconciliation; it never silently repeats an uncertain action.
The first enjoyable slice is reliable short interaction, following and a tiny shared task.
A free-form house builder, background worker and persistent personality each need additional
contracts and trials. They do not follow automatically from connecting speech to a game command.
## User stories and acceptance trials
| ID | As a player, I want… | Observable acceptance and difficult ending | Execution path |
| --- | --- | --- | --- |
| BW-01 | one clear start, so setup does not consume the play session | Preflight names the selected input, model readiness and exact bot/target bindings. Missing model, muted input, loading client and quarantined generation each produce a useful next step. No recording starts during preflight. | Local preparation and admission; launcher operation remains separate from a game Run. |
| BW-02 | to speak Slovak, Czech or English naturally | A human recording in each language reaches the intended closed command. A different accent, short word, noise and numbers are included in the trial. Unsupported wording refuses; no confidence score or detected language is invented. | Echo interpretation, then the same bounded command parser. General paraphrase understanding needs a separately evaluated resolver. |
| BW-03 | to understand what the companion accepted | Show a concise result in the selected reply language. Distinguish instruction received, behavior started, client-reported outcome, refusal and unknown effect. Starting a build must never announce that the house is finished. | Deterministic presentation of retained results; no planning model is needed. |
| BW-04 | to correct an ambiguous instruction without accidental work | “Build a house here” cannot become guessed coordinates or a control string. Explain the supported next step. A later resolver may ask one precise clarification and bind its answer to the exact draft; it still needs ordinary action admission. | Current strict refusal; a future typed intent/clarification draft precedes the action Graph. |
| BW-05 | to keep playing while the companion follows at a comfortable distance | A stationary target causes no movement. Small motion inside the deadband does not produce jitter; longer motion produces finite segments. A lost, distant or stale target stops following. Pathfinding without measured progress stops the task; missing post-observation reports movement unverified. | Separate finite follow ticks, exact-person observer and supervisor. Post-observation compares with the final pre-command pose and the original target sample; a 0.05-block progress floor excludes negligible motion. |
| BW-06 | the companion to wait quietly when I am busy | Waiting grants no wandering, mining, inventory use or unsolicited conversation. Unchanged idle observations stay in private evidence without repeated console announcements or TTS. A meaningful state change can produce one concise notice. | Idle ticks with bounded cadence; presentation suppresses unchanged notices without discarding Run evidence. |
| BW-07 | stop and new instructions to take priority | Keyboard stop works during capture, inference, action and optional playback. New capture settles the prior background task before opening the microphone. The voice target observer joins an already started finite read and discards its cancelled sample; valid completion keeps that same bound feed usable for a fresh task. Actual read failure still retires it. Repeated cancellation must join owned work. Already placed blocks remain honestly recorded. | Existing synchronous fences, native cancellation and explicit control containment; speech-server work can remain unknown. |
| BW-08 | to hear useful replies without feeding them back into the microphone | Playback is explicitly selected and occurs after capture closes. Default operation retains a private WAV. Player failure preserves the game result and never repeats the action. Player exit is distinguished from human hearing. Stop retires the owned player process group. | Optional finite local playback after synthesis, outside the game action slot; no continuous listening or full-duplex claim. |
| BW-09 | a text fallback when speech is inconvenient | A future text entry uses the same typed intent, budgets, supervisor and outcome path. It does not simulate a transcript or acquire separate authority. Supported commands are discoverable while the game is focused. | The one-action text tool exists; an integrated in-game text/activation surface remains further work. |
| BW-10 | help with a precise small building task | Review one or three exact cells and the material. Require air, stone support, reach, selected ordinary planks and expected consumption. Each known cell outcome and native completion precedes the next cell. Changed conditions or an unknown result stop the plan. | Finite build steps and shared arbiter; stock client observations retain their concurrency limits. |
| BW-11 | to build a house together without rebuilding or destroying my work | Preview a finite blueprint, material list, plot and exclusions. Agree on phases and which person owns each area. Existing blocks are classified before admission; partial work is reconciled rather than counted as new work or demolished. Missing materials produce a useful handoff. | Future blueprint/phase admission and guarded placement; no mining, item spawning or demolition is implied by a request to build. |
| BW-12 | nearby danger and interruptions to produce predictable reactions | Health loss, death, loading, menus and world changes suspend dependent activity and explain why. “Help” does not silently authorize combat, destructive digging, teleportation or emergency administrator commands. | Bounded world observations fence dependent behavior. Any rescue or combat score needs explicit capabilities and its own acceptance. |
| BW-13 | the companion to remember our project when I return | Retain the admitted project, verified progress and unresolved outcomes with provenance. On reconnect, reconcile the new client/world generation before continuing. User preferences need their own reviewed retention boundary. | Future durable project/session continuity; process-local records do not establish memory admission or automatic restart. |
| BW-14 | control over privacy, voices and cost | Local mode remains usable without a paid account. Choosing a hosted provider explicitly binds destination, purpose, language, retention and spend. No quiet fallback sends a recording elsewhere. Voice style and verbosity are explicit preferences. | Existing local profile; hosted routing and paid adapters require separate implementation and admission. |
| BW-15 | the game to remain responsive | Measure frame behavior while speech and a finite task run together. Idle makes zero planning calls; follow does not accumulate stale ticks. Speech, game and logs expose separate costs. Reducing checks cannot weaken freshness or containment. | Deterministic selection, bounded cadence, deadband and shared budgets; resource allocation is measured on the exact host/profile. |
| BW-16 | a useful explanation after something goes wrong | Retain what was requested, which Run owned it, known/unknown outcome and a concrete next action. Offer a compact playtest summary with timings and refusal reasons. Never recommend replay merely because a reply or voice response was lost. | Private native events and stage timings; a session summary may aggregate these records without reading raw audio. |
| BW-17 | to agree on a useful task for otherwise idle time | “Finish these approved floor cells, then wait” binds the exact finite plan and terminal idle state. No pending task means no work. Danger, expiry or missing material interrupts the chore and reports the handoff rather than selecting a new goal. | Future explicit finite task selection, reusing admitted scores; idle itself still grants no effects. |
| BW-18 | help bringing materials without losing my supplies | Name the permitted source, destination, item and quantity. Show missing materials and account for every transfer. Do not raid another player's inventory, open an unrelated chest or start mining when a transfer fails. | Future typed inventory/transfer capability and receipts; today's inventory port is read-only. |
| BW-19 | the companion to know what it can actually observe | Correctly describe held material, health and queried terrain. Missing cells and unseen players stay unknown; old observations trigger a fresh read. Misleading names or chat cannot authorize work. After an action, compare a new observation with the intended change. | Future attributed perception and typed model proposal passage, followed by independent action admission; structured data and pixel vision are qualified separately. |
## Feedback and sound contract
Choose feedback from the actual result using the first presentation cut's fixed Slovak, Czech
and English wording. When idle/follow/build begins, say it was **started**. Completion needs its
own evidence. An ordinary command result remains a **client report**.
Make the next step clear when work cannot proceed. Refusal means no eligible action was admitted;
an unknown effect means work stopped and must not be replayed. Keep provider-private detail and
raw exceptions out of the spoken explanation while leaving full diagnostics privately accessible.
After the game result, settle optional speech separately. If synthesis or playback fails, keep
the game result and mark the speech stage failed. The failed reply cannot make an already
attempted game action safe to retry. Cancellation still propagates and settles owned work.
Generated audio and successful local player exit remain evidence about their own stages, not
proof that the person heard the reply.
An explicit playback option uses only validated bounded PCM bytes with a fixed local player
invocation. It accepts no shell command, arbitrary player option or voice-controlled device name.
Capture and playback do not overlap in this first half-duplex profile. Keyboard stop retires the
owned process group, including cancellation during player launch. No playback is launched during
setup or automated game qualification. Music ducking, positional audio, a global push-to-talk
key, overlays, wake words and conversational barge-in remain separate design work.
## Optimizing the experience
Optimize measured pain rather than the shortest isolated inference. Keep capture time separate
from STT, Graph/game response, TTS and optional playback; a fixed recording window can dominate
the perceived delay even when warm inference is fast. Record cold/warm conditions, utterance
length, language, model/runtime pins, CPU allocation and concurrent game load.
Wall time and process CPU are independent measurements: process CPU includes all threads and
can exceed wall time. Preserve both observations rather than clamping one to resemble the other.
| Trial | Acceptance target to evaluate; not a claimed service level |
| --- | --- |
| Quiet idle | Zero game effects and planning calls; no repeated unchanged notices. Native evidence and cancellation remain available. |
| Follow stability | No command while inside the deadband; finite command rate and no catch-up queue. Measure actual displacement, stop distance and missed/stale samples. |
| Turn responsiveness | Measure median and p95 after capture closes to first useful feedback, plus each stage. A first local trial aims for feedback within two seconds on warm simple commands; report failures rather than removing them from the sample. |
| Stop | Measure key event to fenced send, owned game stop and player/recorder retirement separately. The local fence should precede the first await; observed stop latency is not inferred from socket closure. |
| Recognition | Use human SK/CZ/EN commands, accents, silence, noise and deliberately ambiguous requests. Track correct intent, safe refusal and wrong admitted action separately. The playtest accepts zero wrong admitted actions. |
| Building | Compare intended cells, observed blocks, expected inventory delta and exact non-completion. Include target/support/material changes and cancellation before/after send and report. |
| Resource contention | Compare game frame behavior and process CPU/RSS with speech cold, warm and absent. Preloading trades memory for latency; a GPU model is not automatically better for a GPU game. |
| Model perception | Compare stated facts against the exact sample and measure reasoning latency separately. Missing, unloaded, stale and misleading inputs must not become assumed terrain, player identity or action authority. Keep idle and ordinary follow independent of model latency. |
| Recoverability | No automatic effect replay after lost replies, restart or speech failure. Retained evidence must identify the first unresolved boundary. |
The current engineering profile has no confidence-bearing STT contract. Do not optimize by
inventing a confidence threshold. Prefer an exact parser, bounded clarification, reviewed plan
and human command corpus. Selection of different models or paid services follows the separate
[speech research](../../sepulcher/extensions/echo-research.md) and an explicit provider trial.
## Order of preparation
| Priority | Player value | Gate before broadening the slice |
| --- | --- | --- |
| First session | BW-01/03/06/07/08/15/16: start clearly, understand outcomes, wait quietly and stop independently | Microphone and listening bake; truthful failure feedback; cancellation tests; measured warm/cold timing. |
| Shared walk | BW-02/04/05/09 plus the safety/privacy baseline in BW-12/14 | Exact separate target; human command corpus; live stationary/walking/target-loss trials; no wrong admitted action. |
| Shared build | BW-10, then BW-11 | Live one-cell/three-cell outcomes and interruption, controlled fixture, explicit blueprint/plot/material agreement before a house. |
| Longer relationship | BW-13/17/18 and any broader rescue, hosted voice or autonomous task | Durable reconciliation and separately admitted retention, inventory, provider or task capabilities; no implicit authority from elapsed idle time. |
First make short turns legible: readiness, correct language, useful outcome wording, quiet idle,
and optional interruptible playback. Then qualify the actual microphone and two-client follow
fixture, including stop and target loss. Establish one-cell and three-cell live building before
adding house blueprints or a planner. Only after those trials should background errands,
persistent project memory and broader autonomy acquire their own bounded scores.
Each added score specifies trigger, required observations, authority, budgets, finish evidence,
interruption, partial effects and reconciliation. World events can select an admitted response;
they never grant the companion new powers.
---
title: "Mission"
plain_name: "Blockworld: Mission"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Partial"
original: https://hexanomicon.dev/compositions/blockworld/mission/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/mission/
---
# Mission (Blockworld: Mission)
## Plain-English summary (Snayu)
**What it is:** How one Minecraft mission is admitted (exact bot, world, plot, blueprint, deadline and budgets) and how a single block placement is prepared, frozen and reviewed before it can run.
**Why it matters:** Read this before changing mission admission, blueprint handling or the placement step in Blockworld.
- Missing or stale authority (bot, world epoch, lease) refuses the mission before the model proposes anything.
- Blueprints must be a verified block grid or pass a pinned schematic parser; a preview never proves placement.
- A placement command is validated and frozen before approval, so review and execution refer to the same action.
**Status:** Partial. Placement admission is tested in an inactive workflow; no live server.
## Original text (Hexanomicon)
The blueprint names a desired wall. The mission names the exact bot, place, resources, and finish line that could make it real. Continuing a project from yesterday does not extend today's lease.
## Admission
Pin Pattern and adapter revisions, `managed` or `attached` mode, bot UUID, world identity and epoch, attested capabilities, region lease, blueprint, deadline, budgets, and permitted reads/effects. Missing or stale authority refuses before the Mind proposes an action.
An exact `BlockGrid@1` digest can express desired blocks. A Sponge `.schem` must first pass its pinned parser, offset and `DataVersion` policy, unsupported-state handling, and canonical-grid normalization. A closed procedural blueprint must pass its admitted interpreter. Neither a preview nor an offline round trip proves placement: Sentinel resolves each bounded effect against the current epoch, lease, inventory, capabilities, and mission policy.
## Prepare one placement
The first revision `2` placement profile begins with an already admitted one-placement blueprint mission. Before accepting a proposed step, Blockworld resolves the trusted mission, blueprint, lease, and authority records; caller arguments cannot create that admission.
It then validates the exact target, full block state, one-item inventory change, and expected cursor against those records and [Sentinel](sentinel.md)'s action contract. Freeze the validated command before Consent admission or checkpoint encoding so later review and execution refer to the same placement. The operation includes no movement, equipment change, digging, or replanning.
The placement profile validates the original wire values against its closed command grammar before coercion or encoding; booleans cannot stand in for integer coordinates, cursors, or epochs. Serialization and re-entry preserve that validated command.
Carry the same native action identity through preparation, judgment, issuance, and reconciliation. Fresh corroborating evidence may support the unchanged command. A security-relevant change to the command itself instead requires new preparation and Consent.
The admitted effect policy decides how judgment happens. It may permit an exact bounded Codex preauthorization to settle the call; otherwise it requires live judgment or refusal. Either path still performs the checks immediately before issuance.
## What the inhabitant carries
| Record | Meaning that survives the turn |
| --- | --- |
| **Mission** | This finite objective, constraints, cursor, result and exact non-completion. |
| **Project** | Purposeful continuity across separately admitted missions. |
| **Relationship** | World-local social continuity and commitments; no lease, tool, Persona, or general Lich memory authority. |
| **Memory candidate** | Material proposed for remembrance, awaiting its own admission. |
Context receives only project and memory material relevant to this mission. These records cannot manufacture an endless hidden session. When Avatar appears, Blockworld retains exact profile, presence, projection-binding, and Persona references without copying their projection topology. Avatar may receive a mission result but cannot advance its cursor.
## One finite awakening
Read bounded world status, inventory, region, nearby entities, and recent chat. Recall the admitted project material, propose one typed step, and send it through [Sentinel](sentinel.md). Only after validation, execution, verification, and a durable action receipt may the mission cursor advance. Continue within budget, finish, or name the exact remaining work.
Public autonomy, unbounded exploration, destructive administrator work, remote shell, cross-plot action, or invented success after an uncertain effect are refusals. A managed server changes through a separate deployment. [Continuity](continuity.md) explains which truths must agree before this mission can return.
Return to [Blockworld](index.md).
---
title: "Sentinel"
plain_name: "Blockworld: Sentinel (action guard)"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Designed"
original: https://hexanomicon.dev/compositions/blockworld/sentinel/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/sentinel/
---
# Sentinel (Blockworld: Sentinel (action guard))
## Plain-English summary (Snayu)
**What it is:** The guard between the Assistant's proposed action and the game server: it checks each read or effect against the mission, and only issues a receipt when the server's own evidence confirms the result.
**Why it matters:** Read this if you touch the game adapter, action validation or how placements are confirmed and reviewed.
- Five reads (status, inventory, region scan, nearby entities, chat) and five effects (move, look, say, equip, place block).
- In managed mode the server-side guard sees authoritative state; in attached mode local checks can only narrow requests.
- A lost acknowledgement leads to a status check or 'unverified effect', never a repeated placement.
**Status:** Designed. No authoritative game adapter or server deployment yet.
## Original text (Hexanomicon)
One proposed placement crosses from an inhabitant's intention into a server's world. Sentinel validates that crossing; the client adapter translates it. Structured server facts supply the evidence. Screenshots, signs, books, chat, and other world prose remain untrusted observations.
In `managed` mode, the server-side Sentinel can witness authoritative state and effects. In `attached` mode, admission is the intersection of local policy and explicitly offered server capabilities. Client observation cannot fill a missing server guarantee.
## The narrow crossing
Revision `2` retains revision `1`'s five reads and five effects. The managed fixture exposes all ten; an attached profile may offer fewer.
| Reads | Effects |
| --- | --- |
| `world_status` | `move_to` |
| `inventory_summary` | `look_at` |
| `scan_region` | `say` |
| `nearby_entities` | `equip` |
| `chat_since` | `place_block` |
For each action, retain action/mission ids, bot UUID, server mode, Pattern/adapter revisions, lease, precondition digest, expected cursor, deadline, budgets, and postcondition. These facts let Sentinel check the proposed change against the mission that authorized it.
Managed Sentinel checks the plot, preconditions, cursor, and budgets on the authoritative server before issuance. Attached-mode local checks can only narrow the request; the external server decides whether to accept it. After execution, a matching response plus either an authoritative event or sufficient resulting-state proof permits one durable receipt.
## Review the prepared crossing
Blockworld produces a typed placement review from the frozen command and trusted admission records. It binds its owner, profile revision, producer, admitted audience, and exact content to that command. The authorized reviewer can identify the mission and native action, server/world epoch and bot, plot and target, full block state, inventory change, relevant lease and limits, and the proof required for completion. Required facts that cannot be disclosed to the admitted audience make this profile unavailable. Generic Consent arguments remain censored; private checkpoint contents, arbitrary tool metadata, and model-written explanations cannot supply an alternative disclosure path.
Consent binds the exact preparation and review. Keep that binding, together with the existing tool/effect definition binding, through pause and resume. If it is missing or changed, refuse issuance.
The world may have changed while review was pending. Before calling the adapter, Blockworld therefore rechecks current Principal and effect authority, policy generation, mission, server and bot identity, world epoch, lease, cursor, target, inventory, deadline, and budgets. Managed Sentinel enforces the applicable predicates at the authoritative server boundary. Local attached-mode checks still cannot supply a guarantee the external server lacks.
## Refusal remains server-side
Revision `2` retains revision `1`'s exclusion of destructive edits, fire, lava, explosives, PvP, trading, private chat, cross-plot inventory, account/plug-in changes, restoration, and public exposure. Attached mode also excludes server configuration, console, lifecycle, snapshot, plug-in, and mod effects. A mistaken or hostile adapter cannot make server authority disappear.
If acknowledgement is lost, query `action_status` where available and compare the Sentinel cursor with resulting world state. Insufficient attached-server proof narrows eligible effects or returns `unverified_effect`. It never licenses another placement to obtain a cleaner answer. Socket, pathing, animation, and unacknowledged buffers remain volatile; [Continuity](continuity.md) owns durable re-entry.
Return to [Blockworld](index.md).
---
title: "Continuity"
plain_name: "Blockworld: Recovery after interruption"
section: "Compositions > Presence & Embodiment > Blockworld"
status: "Designed"
original: https://hexanomicon.dev/compositions/blockworld/continuity/
guide: https://lychd.snayu.ai/docs/compositions/blockworld/continuity/
---
# Continuity (Blockworld: Recovery after interruption)
## Plain-English summary (Snayu)
**What it is:** Where each kind of truth lives (world, app records, mission/action records, volatile adapter state) and how Blockworld reconciles an uncertain action after a crash or restore before continuing.
**Why it matters:** Read this before working on Blockworld crash recovery, action records or world restore handling.
- World state lives on the server; mission cursors and action receipts live in the database (Memory Vault).
- One action record survives pauses; deleting a checkpoint cannot delete the action's recovery truth.
- On return, missing acknowledgements are resolved first; an unverified effect never grants permission to repeat.
**Status:** Designed. Recovery contract; no live server or deployed mission recovery.
## Original text (Hexanomicon)
The server accepted a block, but the adapter disappeared before receiving acknowledgement. On return, Blockworld must discover that consequence before advancing or repeating anything. A remembered story and a paused process cannot answer for the world.
## Four homes
| Truth | Home |
| --- | --- |
| Blocks, entities, inventory, game time | Managed world volume and Sentinel journal, or authoritative attached server. |
| Inhabitant, relationships, projects, memory candidates and meaning | Blockworld application records. |
| Mission cursor, budgets, pending work and action receipts | Blockworld mission and action records in [Phylactery](../../adr/06-persistence.md), bound to the exact Run and Pattern revision. |
| Socket, pathing, animation and unacknowledged buffers | Volatile adapter state. |
Boot reconciles server identity, world epoch, Sentinel cursor, bot UUID, and the last receipt before a [Mission](mission.md) resumes. [Sentinel](sentinel.md) resolves missing acknowledgement first. An `unverified_effect` cannot become permission to repeat.
## One action across a pause
Revision `2` retains one native action record for the prepared placement. Blockworld owns its meaning and lifecycle; Phylactery owns its durable schema and transaction boundaries. The record holds the immutable command and disclosure-approved review binding, its Consent identity, issuance disposition, and eventual receipt or exact non-completion. Core's Run ledger continues to own Run identity and status. A Graph checkpoint carries the reference and expected binding; deleting that checkpoint cannot delete the action's recovery truth.
Run and Consent identities remain immutable references in the retained action. Their deletion does not erase the frozen command, review binding, issuance judgment, or recovery disposition. A prepared action whose Run or Consent is unavailable cannot issue. On re-entry, an action that has acquired its pending claim can only reconcile, including when its checkpoint or Core records are gone. The first bounded placement schema retains mission and action records until a separately owned export or deletion operation exists.
Commit preparation and its one Consent binding together before exposing the review or parking Graph. Any consumed preauthorization belongs to the same transaction. This gives re-entry one identity to recover: the same native action resolves the committed preparation and Consent, while changed content conflicts instead of replacing them.
Repeated validation of the same call returns those retained records without minting another action. If the commit itself is unconfirmed, reconcile it by that identity before admitting further work.
Before invoking the adapter, conditionally mark the exact action pending against the current mission cursor and limits. Competing resumptions must recover that claim rather than acquire another one for the action or cursor.
The database transaction cannot include the server effect. Once invocation may have begun, a pending or unknown acknowledgement therefore requires reconciliation of the same action. A new Graph hop or missing reply cannot authorize another placement.
A matching response plus either an authoritative event or sufficient resulting-state proof permits verified settlement. The receipt and its corresponding mission cursor and budget update commit together; repeated settlement returns the same result. An observed adapter invocation, a completed Run, or the desired block appearing without sufficient attribution cannot manufacture that receipt. Missing proof remains exact non-completion.
## Restoration changes the ground
A managed cold backup follows orderly save and stop. Only the Magus restores a named snapshot; restoration increments the world epoch and invalidates old leases and assumptions. An attached client cannot snapshot or restore the server. It detects external generation change, invalidates leases, and obtains newly attested truth.
Recovery must also check compatibility across independently versioned server, protocol, Sentinel, adapter, controller, Pattern, and application schemas. Incompatible parked work drains, migrates explicitly, or settles non-complete.
For export or deletion, inventory both application custody and material derived from the world. Deleting a relationship cannot erase a world event from the journal. Restoring the blocks likewise cannot rewrite the purpose for which a mission existed.
## Proving return
Use a flat private world, server-enforced `7×7` plot, non-operator bot, controlled chest, and reviewed blueprint. Expose the exact five reads and five effects. Verify placements from Sentinel sequence and final plot diff, then interrupt after accepted placement but before acknowledgement. Recovery must create one receipt and no duplicate block. Repeat against an attached fixture with no console, files, lifecycle, snapshot, or mod capability; unsupported administration must refuse before a request reaches the server.
[Blockworld](index.md) · [Workflow](../../adr/28-workflow.md) · [Security](../../adr/09-security.md)
---
title: "Reach"
plain_name: "App: Reach (external channels)"
section: "Compositions > Presence & Embodiment"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/
guide: https://lychd.snayu.ai/docs/compositions/reach/
---
# Reach (App: Reach (external channels))
## Plain-English summary (Snayu)
**What it is:** An app that prepares and sends the Assistant's messages in outside places: email (Gmail, Fastmail), chat (Discord, Telegram, WhatsApp), code forges (GitHub) and social posts, plus a public Discord bot profile.
**Why it matters:** Start here before any work on email, chat bots, GitHub comments or social posting integrations.
- Four provider families share typed requests and exact account and target policy but keep their own protocols and limits.
- An offline preparation profile builds requests without logging in or sending anything.
- The public Discord profile answers one mention per turn under a pinned persona; deployment profiles decide where it runs.
**Status:** Partial. Offline preparation and a dev Discord profile exist; no deployable public bot.
## Original text (Hexanomicon)
Reach prepares correspondence for a selected external place. Its provider families share typed
requests and exact account/target policy while retaining different audiences, protocols and
operation limits.
## Provider families
| Family | Concrete providers | Shared concern |
| --- | --- | --- |
| [Email](email.md) | Gmail, Fastmail | Mail account, sender, recipients, subject and reply references. |
| [Chat](chat.md) | Discord, Telegram, WhatsApp Business | Exact conversation and optional reply under the selected bot/business account. |
| [Forge](forge.md) | GitHub; Radicle remains a future profile. | Repository issue/PR correspondence, separate from software-changing authority. |
| [Social](social.md) | Facebook Page, LinkedIn, X | Original public post, exact publishing actor and provider-specific payload. |
The explicit [`reach.connect.prepare@1`](connected-work/preparation.md) profile prepares these
requests through a native serial Graph, including finite WUPHF plans. It performs no account
authentication or delivery. The families organize contracts and discovery within Reach; they add
no separate Composition or provider authority. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
keeps the shared evidence boundary.
## Public Discord profile
A mention in the Necropolis wakes one bounded turn. Reach admits the event, forms an answer under a pinned Persona, and records whether the external place received it. The platform account remains a way to appear there, without becoming the Lich.
[Habitat](habitat.md) defines who and what may enter that social place. [Turn](turn.md) follows a question through committed answer and delivery. [Deployment profiles](deployments/index.md) choose where its durable authority and transport custody live.
For the configurable Discord foundation, start with [operator preparation](preparation.md)
and its [implementation boundary](architecture.md). That offline preparation profile selects
platform-qualified participants, groups, conversations and permitted requests before an explicit
native Graph. The Discord interface translates its own ids into that shared contract. It does
not activate the public Discord contract below or supply a connected bot.
The separate [Discord operator profile](operator.md) supplies an explicit development edge,
networkless native document-search worker and local reviewed server setup. It preserves the
same generic preparation policy, while retaining its own effects, generation and hosting limits.
Under `reach.discord` revision `1`, an allowlisted mention, guild command, or policy-admitted internal event may return `ReachTurn@1` and optional `ReachDelivery@1`. The contract publishes `reach.external_converse@1`, `reach.external_summon@1`, and `reach.external_presence@1` for those bounded uses.
This public profile excludes cross-place identity/continuity, moderation, ambient surveillance, attachments, DMs, shell, deployment effects, and consent settled by the platform. [Avatar](../avatar/index.md) may bind presentation, while Reach retains responsibility for the event, audience, turn, delivery, and receipt. A later projection must obtain its own authority; the result of this turn cannot supply it.
## Connected work
The [connected-work study](connected-work/index.md) proposes a successor for Gmail, Discord and
GitHub correspondence, plus optional WhatsApp business messaging and a separate owner–agent probe.
It includes private accounts, reviewed or preauthorized sends, onboarding and updates while
preserving the current public Discord contract.
The [account lifecycle](connected-work/accounts.md) and [delivery plan](connected-work/delivery.md)
retain the proposed operational boundary. [Social accounts and advertising](connected-work/social.md)
distinguishes organic publishing from later paid campaigns.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md)
---
title: "Connected preparation"
plain_name: "Reach: Offline message preparation"
section: "Compositions > Presence & Embodiment > Reach"
status: "Available"
original: https://hexanomicon.dev/compositions/reach/connected-work/preparation/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/preparation/
---
# Connected preparation (Reach: Offline message preparation)
## Plain-English summary (Snayu)
**What it is:** An offline tool that prepares a ready-to-send request for Gmail, Fastmail, Discord, Telegram, WhatsApp, GitHub or social posts, recording account, target, payload, policy and expiry, without connecting to any provider.
**Why it matters:** Read this if you work on message preparation, provider request builders or the multi-channel 'WUPHF' announcement plan.
- One semantic request is translated by each provider builder into its own protocol; unsupported operations are refused.
- No authentication, network call, draft save, send or model call happens during preparation.
- A finite multi-channel plan (WUPHF) prepares every target before returning, through one workflow.
**Status:** Available. Offline preparation works; live sending is not implemented.
## Original text (Hexanomicon)
Prepare a client reply from Gmail or Fastmail, a Telegram message, or a GitHub issue comment
through the same Reach boundary. The result records the selected account, exact target, application
payload, policy and expiry. It can be inspected without connecting an account or contacting a
provider.
**`reach.connect.prepare@1`** is an explicit offline profile. It does not activate or widen
`reach.discord@1`, and does not qualify the operational `reach.correspondence@1` successor proposed
in the [connected-work study](index.md). [State of Work](../../../state-of-the-work.md#composition-portfolio-delivery)
owns its evidence and the remaining deployment boundary.
## One intent, several concrete channels
| Family | Concrete preparation | Why the distinction survives |
| --- | --- | --- |
| [Email](../email.md) | Gmail MIME/REST; Fastmail JMAP | Mailbox, sender, recipients, reply headers and thread remain explicit. Fastmail submission identity is separate from its account. |
| [Chat](../chat.md) | Discord bot, Telegram bot, WhatsApp business text | A server/channel, bot chat and business phone/recipient have different identities and eligibility. No personal-session impersonation is selected. |
| [Forge](../forge.md) | GitHub issue or pull-request timeline comment | A repository and numbered conversation are required. Radicle needs a future provider profile and may need its own target schema; no compatibility is inferred. |
| [Social](../social.md) | Facebook Page, LinkedIn member/organization and X original text post | The external author and public audience are pinned. Advertising, direct messages and automatic AI replies are separate capabilities. |
The shared request is semantic: read bounded correspondence or prepare text for one selected
target. Provider builders translate it into their own protocol subset. They do not turn every
service into an email server or expose an arbitrary API URL, method or shell command. A provider
that cannot perform the requested operation refuses it.
The read subset is explicit: Gmail lists bounded message IDs, Fastmail queries a bounded
header/preview projection, and Discord/GitHub list bounded conversation messages/comments.
These plans do not implement arbitrary mailbox search or full Gmail message-body retrieval.
Thread-scoped email reads, Telegram chat-history reads, WhatsApp history and social reads refuse.
Telegram's bot-wide `getUpdates` would also acknowledge offset advancement; it cannot stand in for
a target-scoped read. A Discord reply fails if its exact referenced message no longer exists.
A preparation policy defines one partition, exact connection snapshots, exact targets, operations,
bounds and lifetime. Its connection IDs are local references; the provider account and actor IDs
are external observations and do not become Ward Principals. Allowing preparation therefore grants
no send authority. Nor can matching display names or email addresses link two accounts.
## Call the native Graph
The explicit factory builds an ordinary serial score. It validates the admitted request, prepares
the provider payloads, and projects the resulting plan. The state binds the canonical Run, session,
policy and exact request; live handles remain dependencies. A caller must assemble this profile
explicitly, because normal application boot installs no connected profile.
The corrected payload generator uses implementation `py.2` under the same Pattern revision `1`.
Runs pinned to `py.1` refuse execution against it; prepare a fresh offline Run instead of resuming
with different request bytes. This changes no live delivery or replay authority.
```mermaid
flowchart LR
I[Explicit bounded request] --> V[Validate account, target and policy]
V --> P[Prepare provider requests]
P --> O[Return immutable plan]
O -. later authority and durable delivery .-> E[Provider transport]
```
Inspect the plan as a prepared application request. It contains application bytes and a provider
route selector, with no bearer token, credential URL or SDK session. Later transport still needs
its own setup: the Telegram credential owner must insert a token, and Fastmail requires an
authenticated JMAP Session and admitted API endpoint. The plan's digest binds only the prepared
application request, not transport headers or the provider's eventual response.
There is no effect executor in this profile. Saving a provider draft would already disclose data
and is therefore a later admitted write. Read plans also require current authority and disclosure
checks before a future transport fetches private data. No model receives any correspondence here.
Preview the synthetic release announcement without credentials:
```bash
uv run --locked python scripts/reach_connect_prepare.py \
--policy examples/reach/connected/policy.json \
--requests examples/reach/connected/wuphf.json
```
Use `founder-policy.json` and `founder-launch.json` in the same directory for Fastmail plus
Facebook Page, LinkedIn member and X launch-copy preparation. Both fixtures use invented accounts.
The default output reports only preparation status and count. `--include-payload` explicitly
prints the private application requests for inspection; protect that output like correspondence.
For native execution, assemble
`lychd.compositions.reach.connected.workflow.connected_preparation_workflow(policy, clock=clock, record_result=sink)`
in an explicit registry and submit the Intent from
`make_connected_intent(policy, requests, session_id=session.id, now=clock())` through the ordinary
RunEngine. The registry, session and result sink belong to that caller; no startup selector or
durable correspondence ledger is implied.
## WUPHF as finite preparation
“Announce this accepted release in these three places” selects a finite tuple of explicit targets.
Reach validates every item before returning the batch. Duplicate request identities and duplicate
operation/target pairs refuse; a forbidden destination does not disappear from an apparently
successful result. Each provider payload and the complete batch have separate bindings.
This is preparation inside a serial Graph station. It uses no Graph broadcast/map/join primitive,
background sender or parallel executor. A future sender must settle each target independently:
one accepted email cannot prove that a chat message or post was accepted. An unknown result must
remain visible and cannot trigger a blind replay of the whole batch.
Reach owns correspondence and destination policy. [Broadcast](../../broadcast/release.md) owns
editorial acceptance and publication judgment. An already accepted announcement can enter Reach
as settled input. Commissioning and waiting for several live Composition Invocations would instead
need a [Suite](../../products-and-suites.md#compositions-relate-without-nesting).
## Journeys and refusal cases
| User story | Observable result | Refusal that matters |
| --- | --- | --- |
| As a founder, answer one client from the selected Gmail mailbox. | Frozen MIME and recipients, including separately bound Cc/Bcc. | A changed recipient, sender, thread, body or connection changes the preparation. Header injection refuses. |
| Use Fastmail for another company with the same application flow. | JMAP mail operations and explicit submission identity. | Gmail thread IDs and send payloads cannot be reused as JMAP identities. Another partition cannot share the policy. |
| Send a reviewed notice to an admitted Telegram chat. | A bot `sendMessage` payload with link previews disabled and no markup parser selected. | No bot credential or personal Telegram session is accepted as request data. |
| Answer a WhatsApp customer. | A business free-form text request candidate. | Preparation supplies no opt-in, current service window, AI-market eligibility, escalation or spend proof; transport qualification still requires all of them. |
| Ask Reach to answer an issue or PR discussion on GitHub. | An issue-comment request for the exact repository and timeline. | No diff review, approval, merge, release, code execution or workflow run follows. |
| Prepare AI-service promotional copy for Facebook and LinkedIn. | Separate public post candidates as the configured Page/member/organization. | A personal Facebook profile, private audience or paid advertisement cannot inherit this capability. |
| Say WUPHF for an accepted release. | One bounded, fully preflighted plan across explicit provider targets. | One bad target rejects preparation; restart is not permission to send any item twice. |
The [account lifecycle](accounts.md) and [social assessment](social.md) distinguish provider access,
organic publication and advertising. The [acceptance plan](delivery.md) retains the durable outbox,
credential, current-authority, revocation and live-provider work needed before actual delivery.
[Reach architecture](../architecture.md) · [Accounts](accounts.md)
---
title: "Email"
plain_name: "Reach: Email family"
section: "Compositions > Presence & Embodiment > Reach > Email"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/email/
guide: https://lychd.snayu.ai/docs/compositions/reach/email/
---
# Email (Reach: Email family)
## Plain-English summary (Snayu)
**What it is:** How Reach represents an email request (sender, recipients, subject, content, reply references) and how Gmail and Fastmail each translate it into their own protocol.
**Why it matters:** Read this before working on email request building or adding a mail provider.
- Gmail uses MIME encoded for its REST API; Fastmail uses JMAP with a separate sending identity.
- Reads are bounded listings without full bodies; thread-scoped reads refuse rather than widening.
- Prepared requests carry no login or send authority; accounts and delivery are separate later work.
**Status:** Partial. Request preparation works; account connection and sending do not.
## Original text (Hexanomicon)
Reply to a client from the selected mailbox without changing the application flow when the
provider changes. Email owns the request's mail semantics: sender, recipients, subject, content
and reply references. Gmail and Fastmail translate that request into different protocols.
`EmailTarget` names a local connection, a protocol account selector, the sender and exact
To/Cc/Bcc recipients. `ConnectedPolicy` selects the connection and allowed targets, operations
and limits. The connection's external account declaration does not authenticate a mailbox.
| Provider | Account selection | Prepared read | Prepared send |
| --- | --- | --- | --- |
| [Gmail](connected-work/gmail.md) | `mailbox_id = "me"`; the declared immutable Google subject remains separate. | Bounded message-ID listing, without message bodies. | Canonical RFC MIME encoded as base64url, with optional thread and reply headers. |
| [Fastmail](connected-work/fastmail.md) | `mailbox_id` is the selected JMAP account ID, not a mailbox folder. | Bounded query/get header and preview projection. | Exact email creation followed by submission with its sending identity, draft mailbox and SMTP envelope. |
`MailRequestBuilder` has two concrete implementations, `GmailRequestBuilder` and
`FastmailRequestBuilder`. Callers prepare a read or send; each implementation retains its own
identifiers, output and refusal rules. Thread-scoped reads refuse rather than widening into an
unrelated mailbox listing. JMAP does not acquire a Gmail-shaped MIME transport.
[Connected preparation](connected-work/preparation.md) shows the shared native Graph and a finite
WUPHF announcement. Its result contains application bytes and a provider route selector, with no
account authentication or send authority. [Accounts](connected-work/accounts.md) and
[delivery](connected-work/delivery.md) retain the later connected-operation contract.
[Reach](index.md)
---
title: "Gmail connection"
plain_name: "Reach: Gmail connection"
section: "Compositions > Presence & Embodiment > Reach > Email"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/gmail/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/gmail/
---
# Gmail connection (Reach: Gmail connection)
## Plain-English summary (Snayu)
**What it is:** A proposed profile for connecting one Gmail or Google Workspace mailbox, choosing what Reach may read, and preparing replies, including Google's registration, consent and verification hurdles.
**Why it matters:** Read this before building Gmail integration or promising Gmail onboarding to customers.
- Each mailbox is a separate connection; two employers' mail are never combined.
- Registration differs for own Workspace, personal Gmail, a client firm, or a shared public app (which needs verification).
- Mailbox writes like labels or drafts are separate effects from sending, each needing its own handling.
**Status:** Designed. Candidate profile; no OAuth flow or live Gmail access.
## Original text (Hexanomicon)
The operator connects one mailbox, selects the mail Reach may inspect, and prepares a reply from
that account. Connecting a second employer creates another connection, not a shared inbox or
permission to combine the two companies' Context.
This candidate profile, `reach.gmail.correspondence@1`, belongs to the
[successor study](index.md). Gmail-enabled personal accounts and Workspace accounts can use the API;
Business Standard is not a prerequisite. [Google's prerequisites](https://developers.google.com/workspace/gmail/api/quickstart/python)
require a Cloud project and Gmail access, not that subscription.
## First registration and customer friction
| Use | Proposed registration | Operational consequence |
| --- | --- | --- |
| Operator's own Workspace | Organization-owned Cloud project, Internal audience, same-organization users. | Internal verification exception; the administrator still controls access. |
| Operator's personal Gmail | Personal-use OAuth project, External audience and production publishing state. | Personal-use exception may apply; unverified warning/user limits remain. Testing is a development state, not durable unattended operation. |
| One client firm's internal deployment | Its organization-owned project and Internal audience for its own users. | Repeat registration per customer, with separate custody. Self-hosting alone creates no exception. |
| One shared application serving unrelated firms or the public | Publisher-owned External application. | Plan brand/scope verification and, where restricted data is accessed through servers, the applicable independent security assessment and recurring review. |
The [restricted-scope review rules](https://developers.google.com/identity/protocols/oauth2/production-readiness/restricted-scope-verification)
define the exemptions and annual assessment obligation. Confirm applicability against the actual
deployment/data path before promising a commercial onboarding flow or cost. Buying Workspace
does not verify a publisher's application for other companies.
External Testing grants with Gmail scopes ordinarily expire after seven days. Google's current
[app-state guidance](https://developers.google.com/identity/protocols/oauth2/production-readiness/overview)
documents an organization-local override when its Workspace administrator marks an app Trusted.
That is an admin-governed pilot option, not public verification or an Internal audience spanning
unrelated firms. A verified app can still be blocked by an administrator.
Use a dedicated agent-workflow OAuth client. Google's [client guidance](https://support.google.com/cloud/answer/15549257)
separates AI-agent and ordinary interactive clients when both coexist. The REST quickstart makes
the agent checkbox optional; the announced MCP enforcement is not a universal REST requirement.
## Consent and capability closure
The server authorization-code flow requests offline access, uses the exact registered callback,
and keeps refresh tokens with the credential owner. Ordinary token refresh needs no user click.
Retain an existing refresh token when a later response omits it. Invalid/revoked grants stop work
and enter `REAUTH_REQUIRED`; new permissions require explicit incremental authorization.
[Offline OAuth](https://developers.google.com/identity/protocols/oauth2/web-server)
Request minimal `openid`/`email` identity scopes as well as the selected Gmail scopes. Validate the
ID token's issuer, audience, expiry and flow binding; retain `(issuer, sub)` as the account identity,
with email only as display/routing data. Mail headers cannot establish that binding.
[Google identity](https://developers.google.com/identity/openid-connect/openid-connect)
| Requested capability | Provider scope | Local restriction |
| --- | --- | --- |
| Search and read selected messages/threads | `gmail.readonly` | Restricted scope; query/label selection is a Reach boundary, not provider-enforced isolation within the mailbox. |
| Save drafts and send | `gmail.compose` | Restricted scope; it already permits sending. Review-only mode must be enforced locally. |
| Optional labels, archive and read-state changes with read/draft/send | `gmail.modify` | Restricted and broader than those named actions; replace narrower grants only when required. Exclude trash/settings/destructive operations locally. |
| A separate send-only integration | `gmail.send` | Sensitive scope; cannot serve an inbox-reading agent. |
Avoid full `https://mail.google.com/` access. [Google's scope table](https://developers.google.com/workspace/gmail/api/auth/scopes)
is the authority for classification and scope coverage. Calendar, Drive and mailbox administrative
settings are later separately authorized capabilities.
## Mailbox writes are separate effects
Saving a draft is already an external effect: Google receives the body even though no recipient
does. The proposed `ReachMailboxMutationIntent@1` and `ReachMailboxMutationReceipt@1` would account
for that effect by binding one connection, operation, exact message/draft ids, MIME or label delta,
preparation/observation, authorization, expiry, effect identity and fenced attempt. Apply the same
durable outbox states and current byte-time disclosure checks used for delivery. Authority to
create a draft neither consumes nor implies authority to send it.
The first draft operation creates a Reach-owned snapshot and retains the returned draft id.
Ambiguous creation remains `UNKNOWN` until matching draft content/correlation is reconciled;
never retry creation merely because one list call did not find it. Updates to human/shared drafts
are deferred: Gmail read-before-write alone supplies no atomic compare-and-swap guarantee.
Revised preparation stays local or creates a separately admitted snapshot, without overwriting an
existing draft. The first send path submits sealed MIME directly rather than mutable draft bytes.
Optional label/read/archive changes bind the exact message set and add/remove label ids. Repeated
application is eligible only when that adapter contract proves the same desired-state operation
safe and current authority still admits it. Readback can establish observed desired state, not
exclusive authorship of a change. Unknown or conflicting observations stop for reconciliation;
trash and deletion remain excluded. [Message label changes](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/modify)
## Synchronization and sending
Begin with a bounded initial synchronization, persist a mailbox history cursor, and use outbound
incremental polling to follow subsequent changes. A later Pub/Sub option requires a topic in the
calling project, a grant for Gmail publication, and either authenticated push or outbound pull.
Renew `watch` before expiration (Google recommends daily; at least every seven days).
A notification only wakes synchronization; it contains neither the message contents nor a complete
event history. Persist admitted changes and finish pagination before advancing the processed
cursor. Repeated or out-of-order notifications therefore cannot create new sends.
[Push contract](https://developers.google.com/workspace/gmail/api/guides/push)
Expired Gmail history returns **404**. Rebuild the purpose-bounded projection with a new full sync;
do not replay every rediscovered message as a fresh request. A new watch baseline cannot overwrite
an unprocessed cursor. [Synchronization](https://developers.google.com/workspace/gmail/api/guides/sync)
Before review or standing-policy admission, freeze the canonical MIME, sender/alias, recipients,
reply headers and body. Check that the alias is eligible; it shares the mailbox's limits and
provides no separate identity grant.
Gmail's send API documents no idempotency key, so retain an application effect id and RFC Message-ID
for correlation, followed by the returned Gmail message id when available. If submission times
out, keep `UNKNOWN` while inspecting Sent mail. Matching author, destination, bytes and correlation
can support reconciliation. A missing result in one read cannot prove non-delivery. A vanished
draft alone is insufficient evidence of the send outcome, and provider acceptance still does not
establish final delivery.
[Send API](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send),
[draft lifecycle](https://developers.google.com/workspace/gmail/api/guides/drafts),
[delivery errors](https://developers.google.com/workspace/gmail/api/guides/handle-errors)
Limit concurrency and budget per mailbox and project. Respect backoff, provider retry timing and
daily sending limits independently. As checked on 2026-10-21, new-project defaults are 6,000 quota
units/minute/user/project and 1,200,000/minute/project; sending costs 100 units. Some older projects
retain prior quotas. Read the actual project's allocation rather than baking those numbers into
the application contract. [Current API quotas](https://developers.google.com/workspace/gmail/api/reference/quota)
## Privacy and maintenance
Render bounded plain text from untrusted MIME/HTML without fetching remote images. Treat `From`,
`Reply-To`, quoted instructions and authentication headers as attributed evidence, never Ward
identity. A sender can request an action but cannot grant private-record access or change the
recipient policy. Attachment parsing/download is a later explicit artifact/quarantine path.
Disclose any hosted model transfer and admit it under the user's purpose and privacy policy.
Workspace data cannot become general model-training material; current provider policy also
requires prompt-injection protection. [Workspace data policy](https://developers.google.com/workspace/workspace-api-user-data-developer-policy)
Routine releases retain the client/grant/cursor/outbox identities. Scope or material consent-screen
changes may require new authorization or verification; automatic refresh and watch renewal belong
to the service. [Approved-app changes](https://support.google.com/cloud/answer/13464018)
[Email](../email.md) · [Accounts and updates](accounts.md) · [Acceptance and delivery](delivery.md)
---
title: "Fastmail connection"
plain_name: "Reach: Fastmail connection"
section: "Compositions > Presence & Embodiment > Reach > Email"
status: "Available"
original: https://hexanomicon.dev/compositions/reach/connected-work/fastmail/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/fastmail/
---
# Fastmail connection (Reach: Fastmail connection)
## Plain-English summary (Snayu)
**What it is:** How Reach prepares a Fastmail read or send using the JMAP protocol, keeping account, sender identity, draft mailbox and recipient envelope explicit.
**Why it matters:** Read this if you work on the Fastmail request builder or JMAP mapping.
- The account ID is a JMAP account, not a folder; sending also needs an explicit sending identity and draft mailbox.
- Reads fetch IDs, addresses, subject and preview only, not full bodies or attachments.
- Preparation does not connect an account or create a remote draft; credentials belong to a later owner.
**Status:** Available. Request preparation only; no account connection or sending.
## Original text (Hexanomicon)
The founder keeps company mail in Fastmail and prepares a client reply through the same
[Email](../email.md) request used for Gmail. The Fastmail builder translates it into JMAP;
mail identity and the submission envelope remain explicit.
This page describes Fastmail request preparation in `reach.connect.prepare@1`. The
[connected-work study](index.md) retains the proposed account lifecycle and durable delivery
contract; the builder does not connect an account or create a remote draft.
## Select the protocol account and sender
| Value | Meaning |
| --- | --- |
| `Connection.account_id` and `EmailTarget.mailbox_id` | The same selected JMAP mail account ID. This is not a folder ID. |
| `Connection.actor_id` and `EmailTarget.sender` | The same declared sender address. An address alone proves no sending grant. |
| `identity_id` | The explicit JMAP sending identity required for submission. |
| `draft_mailbox_id` | The separate mailbox in which the exact new email is created. Required for sends. |
| To/Cc/Bcc | Frozen message recipients, also bound into the explicit SMTP envelope. |
## Prepare the read or submission
A read prepares bounded `Email/query` followed by `Email/get` using the query's ID result.
The selected projection contains IDs, addresses, subject, preview and receipt time; it does not
fetch full bodies or attachments. A cursor supplies the next numeric query position.
A send prepares `Email/set` to create the exact content, then `EmailSubmission/set` with the
creation reference, selected identity and complete recipient envelope. It does not submit an
existing mutable draft by ID. RFC reply references are supported; assigning a thread or preparing
a thread-scoped read refuses. A repeated preparation is not permission to repeat either write.
The route `fastmail:api` is a semantic selector. A later credential owner must obtain and validate
the authenticated JMAP Session, API URL, account and required mail/submission capabilities.
HTTP 200 can contain method-level errors, and submission acceptance would not prove recipient
delivery. [JMAP Mail](https://www.rfc-editor.org/rfc/rfc8621.html)
Own-use API tokens and registered OAuth applications are different onboarding roads. API tokens
are unavailable on Basic plans; submission access also requires Email access. Those provider
grants do not waive Reach's local restrictions.
[Fastmail developers](https://www.fastmail.com/dev/) ·
[API tokens](https://www.fastmail.help/hc/en-us/articles/5254602856719-API-tokens)
Use the `founder-policy.json` and `founder-launch.json` fixtures described in
[connected preparation](preparation.md) to inspect the JMAP plan without credentials.
[Email](../email.md) · [Accounts](accounts.md) · [Delivery gates](delivery.md)
---
title: "Chat"
plain_name: "Reach: Chat family"
section: "Compositions > Presence & Embodiment > Reach > Chat"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/chat/
guide: https://lychd.snayu.ai/docs/compositions/reach/chat/
---
# Chat (Reach: Chat family)
## Plain-English summary (Snayu)
**What it is:** How Reach represents a chat message for one exact conversation and how Discord, Telegram and WhatsApp Business each build it with their own identifiers and rules.
**Why it matters:** Read this before working on chat message preparation or adding a chat provider.
- Discord supports bounded channel reads and text sends with mentions suppressed.
- Telegram supports bot text sends only; there is no per-chat history read.
- WhatsApp prepares business text candidates; opt-in, service window and spend checks remain for later transport.
**Status:** Partial. Request preparation works; live chat delivery is not implemented.
## Original text (Hexanomicon)
Prepare a notice or reply for one conversation. A channel, bot chat and business recipient can
share that intent while retaining different audiences, identifiers and access rules.
`ChatTarget` names the local connection, exact `conversation_id` and optional `reply_to_id`.
`ConnectedPolicy` closes the selected account, target allowlist, operation and bounds. A provider
user, role or chat ID does not become local authority.
| Provider | Conversation | Prepared operations |
| --- | --- | --- |
| [Discord](connected-work/discord.md) | Numeric channel under the selected bot connection. | Bounded channel-message reads and text sends, with mentions suppressed and exact reply references. |
| [Telegram](connected-work/telegram.md) | Numeric chat addressed by the selected bot. | Text sends with previews disabled and no markup parser selected. No chat-history read. |
| [WhatsApp](connected-work/whatsapp.md) | Recipient addressed from the selected business phone. | Free-form business text candidates. No personal-chat access, history read or automatic template substitution. |
A Discord reply fails if its referenced message has disappeared. Its nonce binds the complete
preparation: exact retries retain it, while changed text, reply or preparation time changes it.
This bounded provider correlation is not a durable delivery guarantee.
Telegram's bot-wide update stream cannot implement a conversation-scoped read. WhatsApp's current
service window, recipient permission, opt-out, AI-market eligibility and spend remain prerequisites
for later transport, not facts established by constructing a payload.
The existing [Discord operator profile](operator.md) keeps its own development scope.
[Connected preparation](connected-work/preparation.md) supplies the shared serial Graph and finite
WUPHF plan; neither transfers an account's permissions to another conversation.
[Reach](index.md)
---
title: "Prepare Reachy"
plain_name: "Reach: Set up the Reachy Discord bot"
section: "Compositions > Presence & Embodiment > Reach > Chat > Discord"
status: "Available"
original: https://hexanomicon.dev/compositions/reach/preparation/
guide: https://lychd.snayu.ai/docs/compositions/reach/preparation/
---
# Prepare Reachy (Reach: Set up the Reachy Discord bot)
## Plain-English summary (Snayu)
**What it is:** A step-by-step guide to create a private Discord application named Reachy, invite it to your own server, copy IDs and validate local policy while the bot stays offline.
**Why it matters:** Follow this when setting up a Discord test server and bot for Reach development.
- Turn Public Bot off and grant only View Channel and Send Messages.
- Do not generate or paste a bot token during this preparation; the helper never uses credentials.
- Validate the policy locally and inspect a synthetic event without any live connection.
**Status:** Available. Offline helper works; no live bot connection.
## Original text (Hexanomicon)
Prepare a private Discord application named **Reachy**, invite its bot to your own server, and
validate local policy while the bot remains offline. You need your own Discord account and a
server where you can install an application.
The separate offline profile **`reach.prepare@1`** checks a prospective request. It does not
change **`reach.discord@1`** or deliver live **`reach.external_converse@1`**.
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery status;
[architecture](architecture.md) explains the preparation boundary and the remaining live path.
## 1. Create the private application
Sign in to the [Discord Developer Portal](https://discord.com/developers/applications) with your
own Discord account. Choose **New Application**, name it **Reachy**, and create it. On **General
Information**, copy the **Application ID**. This identifier is not a credential.
Open the application's **Bot** page and turn **Public Bot** off. Only the application owner can
then add the bot to a guild. Portal labels and placement may change; Discord's
[bot authorization flow](https://docs.discord.com/developers/topics/oauth2#bot-authorization-flow)
defines the behavior.
**Do not generate, reset, copy or paste a bot token during this preparation.** The local helper
never consumes credentials. A token needed by a later live adapter belongs outside the
repository, with its credential owner. Use an application bot; never obtain an ordinary user's
account token.
## 2. Configure installation and invite the bot
On **Installation**, enable **Guild Install** for this server installation. Use the scopes
`bot` and `applications.commands`, with only **View Channel** and **Send Messages** as the
initial bot permissions. The installing account needs **Manage Server** (`MANAGE_GUILD`) in
the destination server. [Discord installation contexts](https://docs.discord.com/developers/quick-start/getting-started#choosing-installation-contexts)
Use the portal's installation link if available. If a private application cannot retain a default
link, keep it private and use **OAuth2 → URL Generator** with those same scopes and permissions.
The local `--install-url` preview below is another way to construct the intended authorization URL.
Opening and authorizing the URL installs the bot; printing it does not.
Select your own test server in the authorization page and approve the installation. Reachy will
appear in the member list **offline**: no bot process is running. No public callback,
**Interactions Endpoint URL**, or public port is needed for the planned outbound Gateway.
The command scope alone does not register any slash commands.
You may use a small private server with a channel such as `#the-reach` and an optional role for
people allowed to ask questions. Channel and role names are conveniences; the policy uses IDs.
Keep the bot's channel permissions limited to the intended place. Do not grant Administrator,
moderation or voice permissions for this preparation.
## 3. Copy stable IDs
In the Discord client, enable **User Settings → Advanced → Developer Mode**. It adds ID-copy
actions to context menus. Discord's [ID guide](https://support.discord.com/hc/en-us/articles/206346498)
shows the user, server and channel actions.
| Policy value | Where to obtain it |
| --- | --- |
| `application_id` | Developer Portal → application → General Information → Application ID. |
| `bot_user_id` | Right-click the invited Reachy bot → Copy User ID. |
| `guild_id` | Right-click the server icon → Copy Server ID. |
| `allowed_channel_ids` | Right-click each intended text channel → Copy Channel ID. |
| Rule `user_ids` | Right-click each allowed person → Copy User ID. |
| Optional rule `role_ids` | Server Settings → Roles → the role's context menu → Copy Role ID. |
Copy the actual bot user ID separately; do not assume it equals the Application ID. Keep IDs as
quoted decimal strings in TOML. Display names, tags and a rule's `name` label do not authorize
anyone. Record a real server's policy in your private operator workspace outside the checkout;
keep the tracked examples synthetic.
## 4. Understand the example policy
Complete the repository setup in
[CONTRIBUTING](https://github.com/hexanomicon/lychd/blob/main/CONTRIBUTING.md), then work from
the repository root. Open
[`examples/reach/policy.toml`](https://github.com/hexanomicon/lychd/blob/main/examples/reach/policy.toml).
Use schema version `1` to describe the place where you intend Reachy to respond: one application,
bot user and guild, an allowed channel list, and ordered `rules`. Each rule lists `user_ids`,
`role_ids` and `actions`. The supported actions, `answer_docs` and `summarize_context`, name the
work you want to allow; the preparation helper only evaluates their admission.
The adapter compiles these Discord values into a platform-neutral Reach policy. Consequently,
the shared evaluator and Graph need no knowledge of Discord guilds, snowflakes or slash-command
payloads.
The first rule matching a user ID **or** one of the event's role IDs owns the allowed actions.
If that rule lacks the requested action, admission is denied without falling through to another
rule. Application, bot, guild, channel, trigger, event age and question length must also pass.
The example allows `mention` and `slash`, sets `event_ttl_seconds = 300` and
`max_question_chars = 2000`, and keeps `context_message_limit = 0` with
`context_max_age_seconds = 600`. Keep surrounding history disabled at zero. These fields bound
future context use; no history fetcher runs here.
Leave privileged **Message Content**, **Server Members**, and **Presence** intents off now.
Direct bot mentions can expose their own content without general Message Content access; that
exception does not expose arbitrary surrounding conversation. A later history feature needs
explicit policy enablement, **Read Message History**, and the **Message Content** intent for
surrounding guild content. Checking the triggering member's roles alone does not require member
or presence intents. [Message Content rules](https://docs.discord.com/developers/events/gateway#message-content-intent),
[member information without a cache](https://discordpy.readthedocs.io/en/stable/intents.html#member-cache)
## 5. Validate policy locally
Run the supplied synthetic policy:
```bash
uv run --locked python scripts/reach_prepare.py --policy examples/reach/policy.toml
```
Correct any reported policy errors before continuing. To preview an installation URL:
```bash
uv run --locked python scripts/reach_prepare.py --policy examples/reach/policy.toml --install-url
```
The example IDs do not identify your application. For an actual invitation, copy the policy to
your private workspace, replace its IDs with the values you recorded, and pass that file's path
to `--policy`. Confirm the Application ID before following the resulting URL. For the initial
invitation, the portal's URL generator avoids needing a completed local policy first.
The helper validates configuration and previews locally. It never authenticates, connects to
Discord, sends a message, answers a question, or logs the question.
## 6. Inspect a synthetic event
Optionally exercise event admission:
```bash
uv run --locked python scripts/reach_prepare.py --policy examples/reach/policy.toml --event examples/reach/event.json
```
Read the fixture as already normalized synthetic input. It uses shared Reach names: `account_id`
for the Discord application, `space_id` for the guild, `conversation_id` for the channel,
`subject_id` for the person, and `group_ids` for roles, with `platform` set to `discord`. These
IDs and roles prove no Discord identity and grant no local authority. To try a private policy,
copy the fixture outside the checkout too, then make its IDs match that policy.
The fixture has a fixed historical `occurred_at` and expires under the five-minute TTL. To
demonstrate admission, update it to the current UTC timestamp with its timezone, or run policy-only
validation instead. On Linux, `date -u +%Y-%m-%dT%H:%M:%SZ` prints a suitable timestamp. Keep the
TTL enabled. A refusal for an expired event is the intended result, not a bot connection failure.
Preparation ends with Reachy invited and offline, IDs recorded without secrets, a validated policy,
and an understood synthetic admission or refusal. Continue with the separate
[operator development profile](operator.md) for an explicitly started docs-search bot and local
server setup. The [architecture frontier](architecture.md#acceptance-before-deployment)
identifies the integrated evidence needed before live answers or deployment.
[Reach](index.md) · [Habitat](habitat.md) · [Turn](turn.md)
---
title: "Reach preparation architecture"
plain_name: "Reach: Preparation architecture"
section: "Compositions > Presence & Embodiment > Reach > Chat > Discord"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/architecture/
guide: https://lychd.snayu.ai/docs/compositions/reach/architecture/
---
# Reach preparation architecture (Reach: Preparation architecture)
## Plain-English summary (Snayu)
**What it is:** How Reach keeps platform-specific details at the edge: events are normalized into shared concepts (platform, account, space, conversation, subject), checked against policy, and only then enter a workflow.
**Why it matters:** Read this before changing Reach's core model, the Discord adapter or plans for the live bot transport.
- Identifiers are namespaced per platform and account; matching names across services grant nothing.
- Discord terms (guild, channel, role) are compiled into the shared policy before evaluation.
- The live path (Discord SDK, Security Desk admission, durable outbox) is still planned; discord.py is the provisional choice.
**Status:** Partial. Offline normalization and policy built; live transport planned.
## Original text (Hexanomicon)
A message from an external place should enter Reach through one bounded application request.
The platform adapter supplies attributed event data; Reach keeps the policy and workflow that
decide whether the request may proceed. This preparation foundation makes the boundary executable
before a live bot is connected.
The separate **`reach.prepare@1`** profile validates configuration, normalizes a synthetic event,
and evaluates its admission policy. It does not revise **`reach.discord@1`** or deliver the
conversation promised by **`reach.external_converse@1`**. The accepted [Habitat](habitat.md) and
[Turn](turn.md) keep their existing meaning; [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
owns the shared implementation evidence.
The later **[`reach.connect.prepare@1`](connected-work/preparation.md)** profile prepares bounded
provider requests for email, chat, forge and social targets. It keeps the same explicit native
Graph boundary while remaining separate from ingress normalization and connected delivery.
The [operator development profile](operator.md) now implements a separate explicit edge and
native documents worker. Its generation-local memory, source excerpts and local administration
do not supply the public contract's durable conversation, Ward or deployment acceptance.
## Keep Reach independent of the platform
Reach's core vocabulary is **platform, account, space, conversation, subject, groups**, and
the triggers **mention** or **command**. Identifiers remain namespaced by platform and account;
matching strings or display names across services establish no shared identity or authority.
The Discord configuration can retain familiar application, guild, channel, user and role names;
its adapter compiles them into the shared policy before evaluation.
| Reach concept | Discord binding |
| --- | --- |
| Platform | Discord provider identity. |
| Account | The configured application ID. |
| Agent subject | The bot user's stable ID. |
| Space | Guild. |
| Conversation | The allowed channel in this preparation profile. |
| Subject | The triggering user's stable ID. |
| Groups | The triggering member's role IDs. |
| Trigger | Direct mention becomes `mention`; a slash command becomes `command`. |
Discord snowflake validation belongs at that provider boundary. A future Telegram or WhatsApp
adapter will bring its own identifiers, audience semantics and provider constraints. The generic
vocabulary supplies no live adapter, account access or eligibility for either service. It avoids
making their eventual implementation depend on a Discord SDK or renaming all conversations as
channels.
Shared identifiers are bounded opaque strings. A missing enclosing space means exactly no
space, never a wildcard. The same preparation Graph is exercised with two platforms' synthetic
identifier shapes, without importing either provider's SDK.
## Keep transport at the edge
The planned Discord adapter uses an outbound Gateway for message events, direct mentions and
slash-command interactions. This road needs no public callback, Interactions Endpoint URL, or
new listening port. A future HTTP interactions profile would need its own verified ingress and
would not replace Gateway reception of ordinary message events.
[Discord interaction delivery](https://docs.discord.com/developers/interactions/receiving-and-responding)
```mermaid
flowchart LR
SDK["Discord SDK / Cog
planned"] -.-> N["Normalize event"]
N --> P["Evaluate shared Reach policy"]
P --> PREP["reach.prepare@1
native preparation Graph"]
P -.-> W["Ward + retained admission
planned"]
W -.-> G["Native conversation Graph
planned"]
G -.-> O["Durable output / outbox
planned"]
O -.-> S["Discord sender
planned"]
```
Solid edges describe the offline preparation path. Dashed edges require later integration and
acceptance. Tests supply synthetic wire observations to the normalizers; the CLI fixture is
already normalized. Neither supplies Discord-authenticated identity. The preparation Graph
produces an eligibility result, not an answer or a delivery.
A Cog groups Discord listeners and command callbacks. An extension installs those handlers.
Handlers normalize SDK values into Reach-owned data, acknowledge interactions,
invoke the application boundary and format an admitted result for delivery. Reach keeps policy,
context selection and application judgment outside Cogs. Ward retains identity and grants;
native Graph and Run machinery retain execution. The future credential owner sends only the
exact committed output. [Cogs](https://discordpy.readthedocs.io/en/stable/ext/commands/cogs.html)
and [extensions](https://discordpy.readthedocs.io/en/stable/ext/commands/extensions.html)
provide the transport organization.
## Admit an explicit policy
Configure the admission boundary before submitting a prospective event. The strict TOML-backed
Discord schema uses version `1` and binds one application, bot user and guild, an allowed channel
set, mention/slash triggers, ordered rules, question and event-age limits, and explicit context
bounds. The adapter compiles this into the platform-neutral preparation policy.
Use decimal unsigned 64-bit strings for Discord identifiers; display names, tags and rule labels
confer no authority. Unknown configuration or unsupported actions refuse, so a misspelled setting
cannot silently select a broader default.
Each Discord rule has a label, user IDs, role IDs and allowed actions. A rule matches a user ID
**or** one of the event's role IDs. The first matching rule owns the decision: if its actions
omit the requested action, admission is denied without looking for a more permissive later rule.
The action names `answer_docs` and `summarize_context` describe requested work; preparation
executes neither action.
The shared evaluator checks platform, account, agent subject, space, allowed conversation,
trigger, event freshness and question length. A rule cannot waive those checks. Passing them
admits only this preparation request. A supplied group is platform evidence for a later authenticated adapter, not a Principal,
Sigil, private-record entitlement, or consent.
Pure ingress normalizers and policy evaluation run before creating any Intent. The explicit
factory
`lychd.compositions.reach.workflow.reach_preparation_workflow(policy, *, clock, record_result)`
builds the native preparation Graph. It revalidates and pins the policy and event at that boundary;
its guest execution receives empty scopes. `record_result` is a supplied result sink, not a
durable application ledger. The profile has no default registry or startup installation.
The [preparation tutorial](preparation.md) exercises this contract through
`scripts/reach_prepare.py`, `examples/reach/policy.toml` and `examples/reach/event.json`.
The helper validates and previews without authentication, Gateway connection, command
registration, cognition or sending. It does not log the question. No bot credential, Ward mapping,
retrieval service, history fetch, retained application turn, outbox or delivery enters this slice.
## Choose the later Discord transport
Use **discord.py 2.7.1** as the provisional live-edge choice, with `app_commands` and thin
Cogs/extensions. This choice follows the immediate mention/command requirement and the concrete
later voice path. The comparison was checked against primary sources on **2026-10-27**.
The offline preparation foundation contains first-party payload normalization and imports no
SDK. The separate operator edge pins this SDK in its own environment; development checks also
install it to exercise the transport contract. Normal Vessel assembly does not start the edge.
| Candidate | Strongest case | Cost and fit |
| --- | --- | --- |
| [discord.py 2.7.1](https://pypi.org/project/discord.py/), released 2026-03-03; `Python >=3.8` | Events, built-in application commands and Cogs/extensions cover the immediate adapter in one library; version 2.7 adds DAVE voice connections. | Provisional default for a small listener/command edge. Keep its objects, caches and callbacks outside Reach policy and Graph state. Python 3.15 remains unqualified. |
| [Hikari 2.6.0](https://pypi.org/project/hikari/) + [Lightbulb 3.2.6](https://pypi.org/project/hikari-lightbulb/), both released 2026-08-19; both `Python >=3.10.0,<3.15` | Typed REST/Gateway transport with separate command handling, loaders, hooks and dependency injection. Python 3.14 is explicitly supported. | A valid option when those mechanisms simplify the actual edge. It introduces a separate command framework; its Python upper bound does not disqualify an isolated 3.14 adapter. |
| First-party HTTP + Gateway client | Exact control over received payloads, retention and request formation, without an SDK object model. | LychD must implement and maintain the provider lifecycle and rate limiter. The current raw-payload normalizers do not supply that live client. Prefer an SDK unless a concrete unmet transport requirement justifies this work. |
Hikari's [GatewayBot](https://docs.hikari-py.dev/en/stable/reference/hikari/impl/gateway_bot/)
exposes explicit startup/close and session-limit controls; its default startup update check must
be disabled when the adapter's egress contract does not admit a PyPI request.
Lightbulb's [dependency injection](https://hikari-lightbulb.readthedocs.io/en/latest/by-examples/050_dependencies.html)
can supply a narrow Reach port to handlers. Those are useful adapter mechanisms, without making
Lightbulb the owner of application state or authority.
An independent Discord edge may run its own qualified **Python 3.14** environment and lockfile.
It passes typed, serializable Reach requests across the admitted deployment boundary; bot
credentials and SDK objects stay with the edge. Core need not downgrade its interpreter or import
the SDK. This process separation still requires explicit route, identity, custody and lifecycle
acceptance under the selected deployment profile. No such live edge ships with preparation.
Both SDK choices require dependency resolution and focused startup, event, command and shutdown
tests on the selected interpreter. Package metadata without an upper bound does not qualify
Python 3.15. Prefer Hikari if a bounded adapter comparison demonstrates a simpler correct boundary
or a verified capability requirement changes the fit; release recency alone establishes neither.
### What a raw client would own
Choosing a raw client makes LychD responsible for the Gateway lifecycle: Hello/heartbeat
scheduling, jitter and ACK failure, sequence/session/resume-URL state, close-code decisions,
invalid sessions and Identify quotas. It must also expose gaps when resume fails. Completing
these transport duties still leaves Reach's durable event admission to be implemented separately. [Gateway lifecycle](https://docs.discord.com/developers/events/gateway)
Its HTTP layer must respect dynamic route buckets, major-resource partitions, global limits and
`Retry-After`; fixed guessed limits are insufficient.
[Discord rate limits](https://docs.discord.com/developers/topics/rate-limits)
Interactions require an initial response or deferral within **three seconds**; follow-up tokens
last **15 minutes**. A handler must acknowledge before waiting on cognition or durable execution.
[Interaction responses](https://docs.discord.com/developers/interactions/receiving-and-responding)
An SDK reduces this provider-protocol work. Neither SDK supplies LychD's durable admission,
application deduplication, Ward decisions, outbox or unknown-effect reconciliation. The integration
must also inspect SDK retries and timeouts so an ambiguous send cannot silently become a new
application effect.
## Expand context and media through separate gates
Keep `context_message_limit = 0` to disable surrounding history. A positive value only configures
a bound for later work; it does not provide a fetcher. Before enabling that later history path,
require explicit operator policy, bounded count and age, channel access, `Read Message History`,
and the privileged Message Content intent for surrounding guild content. The current preparation
requests none of that access. Checking the triggering member's roles is a narrower operation and
does not by itself require privileged member-list or presence intents. [Message Content intent](https://docs.discord.com/developers/events/gateway#message-content-intent)
and [member-cache behavior](https://discordpy.readthedocs.io/en/stable/intents.html#member-cache)
remain provider constraints.
Voice and video remain separate future capabilities. discord.py's
[2.7 changelog](https://discordpy.readthedocs.io/en/stable/whats_new.html#v2-7-0)
records DAVE support for voice connections. That does not qualify audio reception, transcription,
video, native dependency availability, or LychD's custody and privacy policy. Media should enter
through typed, bounded capabilities without moving cognition into a Cog.
## Acceptance before deployment
The next live slice must prove the complete path, including refusal and interrupted effects:
- Gateway authentication, reconnect/resume and explicit gaps; durable event identity and deduplication.
- Retained admission, Ward mapping, current grants and revocation; guest/public restrictions.
- An admitted corpus, bounded retrieval, source-backed answers and validated citations.
- Current payload-bound egress admission before any remote model or specialist call.
- Durable application turns and an outbox that binds exact targets and bytes; reconciliation of
unknown sends without blind replay.
- Explicit startup, shutdown and cancellation ownership across the transport and native workflow.
Only that integrated evidence can qualify a live deployment. The [deployment profiles](deployments/index.md)
retain placement, credential custody and recovery; installing an application in a guild does not
establish those guarantees.
[Prepare Reachy](preparation.md) · [Reach](index.md)
---
title: "Discord operator profile"
plain_name: "Reach: Discord operator profile"
section: "Compositions > Presence & Embodiment > Reach > Chat > Discord"
status: "Operator validation"
original: https://hexanomicon.dev/compositions/reach/operator/
guide: https://lychd.snayu.ai/docs/compositions/reach/operator/
---
# Discord operator profile (Reach: Discord operator profile)
## Plain-English summary (Snayu)
**What it is:** A Linux development profile that runs a real Discord bot for a small server: a token-holding edge, a networkless documents worker that answers from public docs, and local operator commands for server setup.
**Why it matters:** Read this when running or modifying the development Discord bot, its worker, server-setup plans or publication queue.
- Two isolated containers: the discord.py edge holds the token; the worker runs workflows with no network or credentials.
- Default mode is document search; an explicit private option enables bounded local-model conversation.
- Server setup uses an exact, expiring plan run from a local command; Discord chat can never approve it.
**Status:** Operator validation. Built and tested; no qualified live Discord session or restart continuity.
## Original text (Hexanomicon)
`reach.discord.operator@1` is an explicit Linux development profile for a small server: a
credential-bearing Discord edge, a networkless native documents worker, and a local operator
tool for reviewed server setup. It does not activate `reach.discord@1` or any public deployment
profile. Document search is the default; an explicit private profile can instead select bounded
local-model conversation. Independently enabled owner publications use a local queue. Neither
option supplies Ward enrollment, durable Phylactery, or restart continuation.
The two processes have different dependencies and custody. The edge runs **discord.py 2.7.1**
on Python 3.14.8 with its own lockfile. The worker runs Python 3.15.0 in the explicit OCI development
image and executes a real native Graph with a generation-local memory Run ledger. A host supervisor
relays bounded JSON over their standard streams; neither container receives an engine socket,
checkout, HOME or the other's credentials.
For document search, the worker receives a compiled policy and an immutable export of selected
public documents, then returns deterministic excerpts and source links. The optional conversation
profile adds one frozen static persona and model binding to that worker. Its model HTTP remains
in a closed host transport.
The existing generic Reach policy selects people, groups, conversations and actions. Discord
administrator permission does not grant a native Sigil, shell or host operation. Administrative
writes are separate local operator commands; Discord chat cannot approve a setup plan.
Server setup uses a fresh snapshot and an exact, expiring plan. It can create bounded roles,
categories and channels, and patch explicitly named existing channel ids. It does not delete,
ban, assign memberships, change the everyone role or grant administrator. A private operations
category and read-only orientation channels belong to the proposed developer layout.
SDK connection management and command dispatch remain at the edge. Administrative/message
writes use a single-attempt REST adapter because the pinned SDK retries some POST failures.
The edge retains content-free, fsynced attempt metadata. An unknown result fences repetition;
the journal witnesses transport effects and is not a canonical Run or conversation ledger.
An uncertain create is inspected, never blindly retried or automatically deleted.
Each launch creates a new generation. Old events are refused; process failure stops both peers.
The operator effect journal survives, while memory Runs and conversations do not. This is an
explicit development limitation, not Phylactery recovery or production hosting acceptance.
## Prepare the server and private workspace
Start with [Prepare Reachy](preparation.md): create a private application, install its bot with
`bot` and `applications.commands`, copy its stable IDs, and validate the policy. That tutorial
ends with the bot offline. The steps here deliberately continue into this separate operator
profile. The [public Discord contract](index.md) and the Designed
[home and VPS profiles](deployments/index.md) keep their existing boundaries.
Use a Linux host with the repository's host tooling installed as described in
[CONTRIBUTING](https://github.com/hexanomicon/lychd/blob/main/CONTRIBUTING.md#setup-and-commands)
and a working rootless Podman engine. Docker is an explicit alternative supported by the harness;
its build requirements remain those in CONTRIBUTING. Run the following commands from the
repository root, in one terminal. They run the host wrapper; the native documents worker itself
runs only inside its OCI image.
Choose a **new absolute directory outside every Git checkout**. Its existing parent must be a
real directory owned by you. Replace the example path and synthetic `USER_ID` below before
continuing. `USER_ID` must be the destination server's actual owner for server planning; it is
also used as the optional inspection allowlist entry at startup.
```bash
REACH_ROOT="/absolute/private/path/reach-operator-01"
USER_ID="555555555555555555"
ENGINE="podman"
umask 077
mkdir -m 700 "$REACH_ROOT"
cp -n examples/reach/policy.toml "$REACH_ROOT/policy.toml"
```
Keep this terminal's variables for the later commands. Set `ENGINE="docker"` before building if
you intentionally use Docker. The harness rejects relative paths, symlink ancestors and paths
inside a Git checkout, including ignored directories. It requires private owner-only state
folders and token/image/plan files. Token, image record and plan outputs must not exist already;
use a new filename for each new artifact. An exported corpus needs a new or empty directory.
Open `$REACH_ROOT/policy.toml` with your local text editor. Replace every synthetic application,
bot, server, channel, user and role ID using the table in [preparation](preparation.md#3-copy-stable-ids).
For a first launch, keep one existing text channel in `allowed_channel_ids`, allow your own user
ID through the first rule, and keep `context_message_limit = 0`. Remove the example developers
rule until you have recorded a real role ID, or replace it with the actual intended role ID.
The first matching user-or-role rule owns the permitted actions; a later rule cannot supply an
action missing from that first match. Keep `answer_docs` enabled for the user who will try the
bot and inspect it.
The server plan below has a fixed developer layout. Its Reach channel is exactly the **first**
ID in `allowed_channel_ids`: it preserves that channel's ID and may rename it to `the-reach`,
move it into `DEVELOPMENT`, and update its topic. If it is currently named `general`, the plan
renames it before creating the separate community `general` channel. Verify that this is the
intended existing text channel before planning. Other policy channels are not added to the
server layout by this CLI.
For setup, grant the bot **Manage Channels** and **Manage Roles** in the destination server and
check its role hierarchy in Discord. The planner requires those existing permissions or an
already present Administrator permission; it never grants Administrator itself. Prefer the two
specific permissions. The bot still needs access to the intended channel for ordinary operation.
Creating `Core`, `Developer` or `Contributor` does not assign those roles to anyone; an authorized
human manages membership in Discord and records any resulting rule role IDs in the private policy.
Discord server authority does not grant native or host authority.
## Capture the bot token locally
On your application's Bot page in the Developer Portal, obtain the **bot** token yourself. Keep
it out of chat, screenshots, tracked files, command history and environment variables. This is
the credential step omitted by offline preparation. Run:
```bash
uv run --locked python scripts/reach_operator.py token \
--file "$REACH_ROOT/discord-token"
```
The command prompts through `getpass` in your local terminal and writes a private `0600` file.
Paste the token only at that hidden prompt. The token value is never a CLI argument; later
`--token-file` arguments contain only the file's path. No ordinary Discord user token is used.
If the token file already exists, the command refuses to overwrite it. A replacement credential
needs a deliberately selected new file, followed by explicit use of that file at startup.
## Export public documents and build both images
Export the committed public documents selected by `examples/reach/public-docs.txt`:
```bash
uv run --locked python scripts/reach_operator.py export-corpus \
--revision HEAD \
--output "$REACH_ROOT/corpus-01"
```
The result reports the resolved commit. Each exported file has a manifest hash and a source link
pinned to that commit. Dirty working-tree changes and private local material do not enter this
export. The worker verifies the manifest and file bytes. To change the documents, export a
new committed revision into a new corpus directory and select it on a later explicit launch.
Do not edit the exported files in place.
Build the paired development images and retain their exact image identities:
```bash
uv run --locked python scripts/reach_operator.py build \
--engine "$ENGINE" \
--images "$REACH_ROOT/images-01.json"
```
This creates the Python 3.15.0 native check image and the separately locked Python 3.14.8
Discord edge image. The image record contains their `sha256:` identities; startup selects these
exact local images with pulling disabled. A failed build or unavailable engine stops the step.
There is no host worker fallback. This build command does not run the bot or apply server changes.
The edge's credential-bearing process talks to Discord. The native worker has `--network=none`
and receives the compiled shared policy and corpus read-only. The edge never receives the corpus
or Core runtime; the worker never receives the token or constructs a Discord client. The
development check image includes the SDK as a test dependency. Both containers have a
read-only root, bounded resources, and a private temporary filesystem. Neither receives the
checkout, host HOME, an engine socket, provider credentials or published ports. The host wrapper
owns engine calls and relays bounded JSON between their standard streams.
## Review an exact server plan
Stop any running instance before planning or applying against the same state directory. The
harness holds one exclusive instance lock across each operation. Planning contacts Discord to
verify the application, bot, server owner and current server snapshot. It writes a private plan;
it does not create or patch Discord resources.
```bash
uv run --locked python scripts/reach_operator.py admin-plan \
--engine "$ENGINE" \
--policy "$REACH_ROOT/policy.toml" \
--token-file "$REACH_ROOT/discord-token" \
--state-dir "$REACH_ROOT/state" \
--images "$REACH_ROOT/images-01.json" \
--owner-id "$USER_ID" \
--output "$REACH_ROOT/server-plan-01.json"
```
The terminal reports the plan's digest and path. Open the plan JSON locally and review its
`layout`, `snapshot`, `existing`, `operations`, and expiry. In particular, confirm all application,
bot, guild and owner IDs, the existing Reach channel ID, and every planned patch. The CLI offers
this fixed layout rather than an arbitrary layout-file option:
| Resource | Intended layout |
| --- | --- |
| Roles | `Core`, `Developer`, `Contributor`, each created with zero permission bits. |
| `START` | Text channels `start-here` and `announcements`; everyone may view/read history, while sending is denied to everyone and allowed to `Core`. |
| `DEVELOPMENT` | Text channels `dev`, `help`, and the existing channel selected as `the-reach`. |
| `COMMUNITY` | Text channel `general`; voice channels `Coworking` and `Meeting`. |
| `OPERATIONS` | Text channel `ops`; category and channel deny everyone view access and explicitly allow the named owner, `Core`, and the bot to view, send and read history. |
Existing Discord Administrator access still follows Discord's own permission semantics. The
private operations overwrites do not revoke it. The setup does not change the everyone role,
assign members, moderate, ban, delete channels or delete roles. Creating voice channels does not
provide a voice connection, transcription or other media feature.
A matching name lets the planner retain a resource without writing only when its desired fields
and permission overwrites already match exactly. Duplicate names, incompatible role permissions
or incompatible channel settings refuse planning. The first policy channel is different because
its explicit ID allows the reviewed plan to patch that exact resource. The planner cannot rename
or reconfigure arbitrary name-matched channels. Keep the existing channel ID in policy after
setup, even if the plan changes its name or category.
A plan expires after fifteen minutes. Copy the digest you actually reviewed into `PLAN_DIGEST`;
the placeholder below must be replaced with that exact 64-character lowercase hexadecimal value.
Applying is the explicit authorization for the reviewed Discord writes:
```bash
PLAN_DIGEST="REPLACE_WITH_THE_REVIEWED_PLAN_DIGEST"
uv run --locked python scripts/reach_operator.py admin-apply \
--engine "$ENGINE" \
--policy "$REACH_ROOT/policy.toml" \
--token-file "$REACH_ROOT/discord-token" \
--state-dir "$REACH_ROOT/state" \
--images "$REACH_ROOT/images-01.json" \
--plan "$REACH_ROOT/server-plan-01.json" \
--expect-digest "$PLAN_DIGEST"
```
The digest covers the exact plan, including the original snapshot. Apply obtains a fresh
snapshot and refuses if it has changed, the plan expired or the reviewed digest differs. It
checks expiry before each write, checks each applied effect against the observed server, and
stops on expiry, rejection or uncertainty while retaining earlier completed results.
A stopped apply can leave earlier operations in place; it is not a transaction or a rollback.
If a plan simply expired or became stale before any write, create a new plan at a new output
path and review its new digest. If an effect may already have occurred, follow the uncertainty
procedure below first.
## Start Reachy and try its commands
On the first launch, explicitly register commands for **this policy's guild** and allow your
admitted user to run the read-only inspection command:
```bash
uv run --locked python scripts/reach_operator.py run \
--engine "$ENGINE" \
--policy "$REACH_ROOT/policy.toml" \
--token-file "$REACH_ROOT/discord-token" \
--state-dir "$REACH_ROOT/state" \
--images "$REACH_ROOT/images-01.json" \
--corpus-dir "$REACH_ROOT/corpus-01" \
--sync-commands \
--admin-user "$USER_ID"
```
Keep this process in the foreground. It verifies the logged-in bot and application, guild
membership and all policy channel IDs before connecting. `--sync-commands` performs guild-scoped
registration only. It never performs a global command sync. On later launches with unchanged
commands, omit that flag; repeat it deliberately when guild registration needs updating.
`--admin-user` may be repeated for additional inspection users, and each must still pass the
same Reach admission policy. It grants no setup apply command and no host permission.
In an allowed channel, use an admitted account to try:
- `/reach status` for this connection's readiness.
- `/reach ask` with a documentation question, or a direct bot mention followed by the question.
- `/reach admin-inspect` for counts of server roles and channels, if your user ID was included
with `--admin-user` and your policy permits `answer_docs`.
Slash responses are ephemeral. A mention answer is sent to its allowed channel with mentions
disabled. Replies and owner publications suppress automatic link previews; links remain
clickable. An unlisted person, channel, trigger or action is refused or ignored. The edge and
native worker both evaluate the same compiled policy; Discord Administrator status is no bypass.
Default answers contain deterministic public-document excerpts and pinned source links. Opting
into [local conversation](#enable-local-conversation) changes `/reach ask` and direct mentions to
model replies under a separately permitted `converse` action. Administrative
writes remain the separate local `admin-plan`/`admin-apply` workflow; Discord chat cannot approve
a plan.
Press **Ctrl+C** in the foreground terminal to stop. The supervisor retires both peers and removes
only its validated container identities. A child exit, EOF or process failure also stops both.
The SDK may reconnect its Gateway connection within a running generation, but the harness does
not install a service, auto-restart failed processes, or resume native Runs. A new invocation is
a new generation, refuses pre-generation events, and starts with empty memory Runs and
conversations. Keep the same state directory so the durable transport attempt journal continues
to fence uncertain effects.
The optional community onboarding profile starts from a public welcome channel, a separate public
introduction channel, an existing bot-owned welcome message, and two zero-permission baseline
roles. The welcome channel may stay read-only. Its persistent button opens a private form for
optional interests and introduction text; only explicit publication confirmation creates or
updates that member's one public introduction. Those choices grant no Contributor, Maintainer,
Admin, native identity, or capabilities.
For membership, humans receive the configured Magus baseline unless they already hold an explicitly
configured elevated community role; bot accounts receive the common Bot role. When using these
exemptions, keep one community role per human—Magus, Contributor, or Maintainer—with Admin as a
separate add-on. An authorized human promotes a member by replacing the previous community role.
Onboarding itself never removes roles or grants an elevated role.
This automation requires Server Members Intent. It uses no member/presence cache and backfills at
most 1,000 existing members once per process generation. A private draft expires after five
minutes or restart.
Select it with `--onboarding-profile /absolute/private/onboarding.json` on `run`. The strict
JSON object contains `guild_id`, `channel_id`, `introduction_channel_id`, `panel_message_id`,
`magus_role_id`, and `bot_role_id`. Optional `elevated_human_role_ids` is an array of at most two
exact role ID strings for Contributor and Maintainer; omission defaults to an empty array and
preserves the baseline behavior of existing profiles. IDs must be distinct from one another,
the everyone role, Magus and Bot. Keep Admin outside this list. Role names do not
select exemptions. Startup requires each exempted role to exist and be unmanaged; these
read-only checks confer no authority to assign it. Join and startup backfill skip Magus for
humans holding either configured role, including after restart. Existing duplicate community
memberships require a separate reviewed human cleanup.
The two channel IDs must differ. The host freezes this bounded private file and mounts it only
into the Discord edge. Startup verifies both public text channels, welcome author, baseline
role authority and hierarchy before registering controls. Attaching the controls to the welcome
message is a separate reviewed operator edit. Role additions preserve other memberships; public
introductions use the content-free effect journal to retain their message identity across
restarts. Unknown
creation or update outcomes fence further publication until operator reconciliation. These
are Discord presentation and membership effects, not Ward enrollment or native Graph runs.
## Enable bounded surrounding history only when intended
The default policy keeps `context_message_limit = 0` and the run command omits `--history`.
Direct mentions and slash questions do not require general surrounding-history access. Leave
Message Content, Server Members and Presence privileged intents off for that default.
To opt into history, stop the instance, choose a positive `context_message_limit` (at most 50)
and `context_max_age_seconds` (at most 3600) in the private policy, grant **Read Message History**
in the allowed channel, and enable **Message Content** for the application in the Developer
Portal. Then add `--history` to the same run command. The policy setting and flag must agree;
a positive limit without the flag, or the flag with a zero limit, refuses startup. Member-list
and presence intents remain unnecessary.
To use `/reach context`, also add `summarize_context` to the **first matching rule's** `actions`,
for example `actions = ["answer_docs", "summarize_context"]`. Enabling history alone does not
authorize that action. The result is selected context excerpts, explicitly labelled as having
**no AI summary**. History can also inform document matching for admitted questions.
The edge fetches only bounded recent messages from the admitted channel before the triggering
event, skips webhooks, other bots and empty text, truncates each message to 2,000 characters, and caps
the history payload at 16 KiB. The worker checks its conversation, age, count and byte bounds.
Conversation mode may also include this bot's own recent replies with its configured display name.
This is per-request context, not durable native conversation history. Do not enable it in a
channel whose surrounding content you did not intend to admit.
## Enable local conversation
This option requires an already running, warm local `Qwen3.8-27B` at the fixed literal endpoint
`http://127.0.0.1:28000`. The host transport checks fresh `/health` and `/v1/models` observations
for the exact model. It cannot start, activate, evict or replace an engine. An absent or unsuitable
model refuses the turn; document search and another model are not fallbacks.
Create a private `0600` file at `$REACH_ROOT/conversation-01.json` with your local editor. This
synthetic example uses the admitted defaults:
```json
{
"schema_version": 1,
"persona_name": "Example",
"persona_instructions": "Answer clearly and state uncertainty when evidence is missing.",
"animator_id": "night-qwen38",
"model_id": "Qwen3.8-27B",
"max_context": 16384,
"max_tokens": 384,
"temperature": 0.6,
"max_input_chars": 20000,
"timeout_seconds": 60
}
```
The profile is a static instruction and exact model binding, not Mirror identity, Persona
lineage or lasting memory. The supervisor freezes its validated bytes for one generation and
mounts that snapshot read-only into the worker. It does not pass the profile or model frames to
the Discord edge. Changes require a new explicit launch.
Add `converse` to the first matching rule's actions. Keep `answer_docs` if you use
`admin-inspect`; keep `summarize_context` if you use the excerpt-only context command. To admit
recent surrounding conversation, first enable history using the preceding section. Then run:
```bash
uv run --locked python scripts/reach_operator.py run \
--engine "$ENGINE" \
--policy "$REACH_ROOT/policy.toml" \
--token-file "$REACH_ROOT/discord-token" \
--state-dir "$REACH_ROOT/state" \
--images "$REACH_ROOT/images-01.json" \
--corpus-dir "$REACH_ROOT/corpus-01" \
--conversation-profile "$REACH_ROOT/conversation-01.json" \
--model-endpoint http://127.0.0.1:28000 \
--history
```
Omit `--history` when the policy limit is zero. The corpus is still required and supplies bounded
public-document excerpts where relevant. The model receives recent messages and excerpts as
attributed untrusted data, with oldest history omitted first to meet the input bound.
For each admitted turn, the native worker creates a generation-local Run, executes
`reach.operator_converse@1`, and acquires an exact Dispatcher Chat lease without tools. One bounded
generation request crosses the host relay, with no retry, proxy, redirect, arbitrary endpoint or
model override. Its reply grants no publication or host authority. Model and Discord response
limits may truncate the answer; this profile does not qualify general answer quality.
The public slash-command group defaults to `reach`. Select an alias with `--command-name example`
and deliberately repeat `--sync-commands` when changing guild registration. Names accept a
lowercase initial letter followed by lowercase letters, digits or underscores, at most 32
characters. The alias changes the displayed commands, not the Reach Composition or permissions.
## Publish owner-supplied updates
Publication is independent of conversation. A trusted local producer supplies the finished text
and is responsible for authorizing its exact content and audience before queueing it. Neither a
chat message nor a model result can enqueue a publication. This queue is a local operator
interface, not a Ward grant, general scheduler or automatic link from completed coding work.
Add these arguments to the selected run command, using a private queue outside every checkout:
```text
--publications-dir "$REACH_ROOT/publications" --publication-channel 444444444444444444
```
Replace the synthetic channel ID with an intended text channel in the configured guild. Repeat
`--publication-channel` for each exact destination. The edge verifies the guild channel binding
at startup; chat policy does not broaden this separate host-selected destination set. Only the
edge receives the queue's writable mount. The native worker and model receive no queue access.
Using a local editor, save the finished message as a private `0600` UTF-8 file outside every
checkout, for example `$REACH_ROOT/update-01.txt`. Queue it from a separate local terminal with
the same `REACH_ROOT` value:
```bash
uv run --locked python -m lychd.interface.discord.publications queue \
--queue-dir "$REACH_ROOT/publications" \
--body-file "$REACH_ROOT/update-01.txt" \
--channel-id 444444444444444444 \
--publication-id 12345678-1234-4234-8234-123456789abc \
--ttl-seconds 3600
```
Use a fresh UUID for each separately authorized publication; retain it for inspection. The
message body stays out of argv and environment variables. The queue admits at most 32 pending
entries, 1,900 characters per body and a lifetime of at most one hour. A running edge scans the
queue and makes one REST attempt with mentions disabled. It does not ask the model to rewrite
or decide whether to publish.
After an attempt, a private queue receipt retains the publication ID, body digest, outcome and
any returned remote ID. A known settlement removes queued body and request files. An unknown
result retains them and blocks automatic repetition of that publication; the REST journal also
continues to fence uncertainty independently.
Inspect the uncertain external result before taking any further authorized action. A new UUID
cannot bypass that uncertainty. The receipt witnesses this local transport path, without
establishing a durable native outbox, cross-process producer authority or application-level
release acceptance.
## Handle refusals and uncertain effects
The harness intentionally emits fixed diagnostics such as `reach_operator_refused`, and its
children expose bounded diagnostic codes. A refusal does not print credentials, Discord bodies
or a detailed foreign exception. Check the selected file paths, owner-only permissions, policy,
image record, expected digest and engine first. Do not work around a refusal by widening mounts,
passing the token in an environment variable, or starting the native worker on the host.
Transport attempts live in `$REACH_ROOT/state/effects`. Their private JSON records contain
method, target class, hashed effect/payload/scope identities, status, and an optional remote ID
or fixed code. They do not retain the token, message text or response body. `attempting` after
an interruption and `unknown` both mean that Discord **may already have performed the write**.
The journal refuses unresolved effects in the same scope even under a newly generated plan.
To investigate, stop the instance and retain its plan and journal. Inspect the actual Discord
server and relevant audit trail manually, comparing the reviewed resource intent and recorded
remote IDs with what exists. Do not bypass the fence by rerunning an uncertain create, deleting a
possible new resource, editing/removing journal records, choosing an empty state directory, or
regenerating a plan.
This profile has no public journal reset or automated reconciliation command. Inspection may
establish what happened, but further recovery requires explicit manual reconciliation outside
the automatic apply path. Leave the effect unknown if the evidence stays inconclusive. The journal
witnesses attempts; it does not retain native Runs or durable conversations.
[Preparation](preparation.md) · [Architecture](architecture.md) · [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
---
title: "Discord connection"
plain_name: "Reach: Discord connection"
section: "Compositions > Presence & Embodiment > Reach > Chat > Discord"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/discord/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/discord/
---
# Discord connection (Reach: Discord connection)
## Plain-English summary (Snayu)
**What it is:** A proposed profile for installing Reach in a Discord server with selected channels, slash commands and direct mentions, answering one admitted question per response, plus proposed workflow views in the Run Inspector.
**Why it matters:** Read this before designing the next Discord integration beyond the development profile.
- Minimal permissions: View Channel, Send Messages, and Read Message History only for referenced replies.
- One shared bot token covers all servers, so it must never ship in a customer's self-hosted package.
- Commands are /reach ask, /reach status, and link/unlink owned by the Security Desk (Ward).
**Status:** Designed. Candidate successor study; not the delivered operator profile.
## Original text (Hexanomicon)
A server administrator installs Reach, selects allowed text channels, and permits slash commands
and direct bot mentions. One admitted question can yield one response under the selected Persona.
The visible speaker is the bot, not an automated ordinary user account.
The proposed `reach.discord.correspondence@1` profile belongs to the
[successor study](index.md). The accepted [Discord Habitat](../habitat.md), public deployment
profiles and historical `reach.discord@1` remain separately pinned.
## Installation and access
Use a guild-installed application with `bot` and `applications.commands`; the installing member
needs `MANAGE_GUILD`. A user install supports commands but does not replace guild event reception.
A publisher-operated app offers one install link. A customer-owned app requires its own Developer
Portal registration and token. [Installation contexts](https://docs.discord.com/developers/quick-start/getting-started#choosing-installation-contexts)
Bot tokens belong to the application, **not each guild installation**. One shared bot therefore
needs per-guild/channel policy and shares credential exposure across its installations. Never ship
that shared token in a customer's self-hosted package. [Bot authorization](https://docs.discord.com/developers/topics/oauth2#bot-users)
Request `View Channel` and `Send Messages` in selected channels. A referenced reply additionally
needs `Read Message History`; this does not authorize ambient history ingestion. Use `GUILDS` and
`GUILD_MESSAGES`, without privileged `MESSAGE_CONTENT`. Direct mentions are exempt from general
content suppression; arbitrary surrounding conversation is not. No administrator permission,
DMs, attachments, mass mentions, moderation or voice enter this first profile.
[Message permissions](https://docs.discord.com/developers/resources/message),
[content intent](https://docs.discord.com/developers/events/gateway#message-content-intent)
Application verification and privileged-intent review are separate provider processes. Their
thresholds have changed; the first profile avoids privileged intents and must recheck current
[verification](https://support-dev.discord.com/hc/en-us/articles/23926564536471-How-Do-I-Get-My-App-Verified)
and [intent-review rules](https://support-dev.discord.com/hc/en-us/articles/40281523410967-Changes-to-Privileged-Intent-Access-for-Discord-Apps)
before wider distribution.
## Intake, reply and interruption
The first deployment receives mentions and interactions over an outbound Gateway. On reconnect,
resume with the session id, resume URL and sequence. If resume fails, record the gap rather than
claiming complete history.
For each event, deduplicate by application/connection plus interaction or message identity and
content version. A session sequence describes transport order and cannot replace object identity.
Commit admitted work before advancing its processing checkpoint; discard non-trigger content before
persistence and apply explicit policy to ignore self/bot/webhook loops.
[Gateway resume](https://docs.discord.com/developers/events/gateway#resuming)
Interactions require an acknowledgement or deferral within **three seconds**, and their tokens
last **15 minutes**. Defer promptly without running cognition first. Commit known response identity
and token expiry; store the secret token only with its short-lived credential owner. Expired tokens
lead to local status or a separately authorized bot message, not another execution of the work.
[Interaction responses](https://docs.discord.com/developers/interactions/receiving-and-responding)
For normal messages, persist the exact response/target and deterministic nonce before send;
use `enforce_nonce` and retain the returned message id. Discord's uniqueness check covers an
unspecified recent interval, so it does not supply durable exactly-once sending. Gateway echo and
provider reads may reconcile `UNKNOWN`; otherwise keep uncertainty and block blind replay.
Use restrictive `allowed_mentions` on creates and edits and enforce the platform text limit.
[Create Message](https://docs.discord.com/developers/resources/message#create-message)
Honor dynamic route buckets, major-resource partitions and global limits, with `Retry-After` and
bounded backoff. Permission loss or an invalid token suspends the affected path rather than
spinning retries. [Rate limits](https://docs.discord.com/developers/topics/rate-limits)
## Commands and authority
The initial command set is `/reach ask`, `/reach status`, and Ward-owned link/unlink entry points.
Status is caller-owned or explicitly shared. Linking requires an independent authenticated Ward
flow; a guild role, slash command, reaction or ordinary “yes” cannot settle local native review or
broaden standing policy. Public guest answers remain an explicit restricted mode.
A later HTTP interaction profile must verify timestamp/raw-body Ed25519 signatures before intake,
protect against replay and answer provider validation requests. It needs an exact callback/ingress
manifest; selecting it replaces Gateway delivery of interactions, not Gateway reception of other
events. [Interaction verification](https://docs.discord.com/developers/interactions/overview#validating-security-request-headers)
Ordinary service updates preserve the app and installations. Command changes update definitions
through the API; wider bot permissions, channel access or privileged data require administrator
action or provider review as applicable. [Command updates](https://docs.discord.com/developers/interactions/application-commands#updating-and-deleting-a-command)
## Workflow interactions in Orb (Proposed)
This section extends the **candidate successor study**, not the delivered operator profile.
[Orb](../../../divination/altar/orb.md) should show a workflow's actual Discord intake and
external attempts: provider mark, incoming or outgoing direction, permitted channel detail and
recorded outcome. Reach contributes the meaning and static presentation metadata. Orb projects
it through its existing shared renderer and accessible evidence list. Loom continues to show the
declared score; it does not become the delivery feed.
The current [operator profile](../operator.md) has a separate, generation-local memory Run ledger
in its networkless worker. The ordinary Vessel's Orb reads its own ledger. Native reply formation,
a later Discord send and an owner-queued publication therefore have separate witnesses. Neither
a completed conversation Run nor a queue receipt proves that the main Orb observed a delivery.
The local publication queue remains an owner-supplied transport interface; it is no native outbox
or general workflow publication capability.
### Typed observations and presentation
Propose `ReachInteractionObservation@1` as a Composition-owned, immutable observation. These
are proposed record and port names, not existing Python types or a registered `ReachComposition`
service. Its native envelope carries:
| Field | Meaning and bound |
| --- | --- |
| Identity | Schema version, exact Composition/profile revision, opaque observation and owning application-record identities; the outer Run event supplies Run, event, sequence and timestamp. |
| Correlation | Exact Run and supplied station occurrence; admitted intake, communication, delivery intent and physical attempt references as applicable. References resolve under the same owner and connection. |
| Provider and direction | Closed `discord` provider key and `ingress` or `egress`; neither is inferred from station names. |
| Phase | `received`, `admitted`, `attempting`, `sent`, `rejected`, `expired`, `cancelled`, `unknown` or `reply`, with a validated direction/phase matrix. |
| Outcome | A fixed classification and optional bounded reason code, at most 64 ASCII characters. `sent` means provider acceptance, never human reading or agreement; `unknown` preserves possible transmission. |
| Place and audience | Exact qualified connection/conversation references and admission-time audience evidence in the protected Reach record. Default Orb detail contains no platform account, channel, user or role identities. |
| Receipt | Exact intake or delivery receipt reference, with no message body, prompt, token, raw error or canonical private-content hash in structural evidence. |
The phases describe observations at specific boundaries. `received` witnesses intake before
policy admission, while `admitted` follows a successful native gate. On egress, record `attempting`
only after committing a fenced physical-attempt claim and before transmission. A matching
transport receipt is then required for `sent`, `rejected` or `unknown`.
Use `reply` only when a received message passes the exact outstanding-question correlation and
admission. It says nothing about the truth of the answer's assertions. Later cancellation cannot
turn an earlier provider acceptance into an unsent message. If an observation is malformed, missing
or unsupported, leave it unclassified or unavailable instead of inferring a phase.
Reach's proposed pure presentation contribution maps validated records to a closed Discord icon,
an ingress/egress arrow, fixed phase/outcome text and optional authorized channel label. The browser
cannot supply an icon URL, HTML, phase or destination. Channel labels are bounded to 80 characters
and rendered as text; absent disclosure authority yields a generic channel label. Run-read access
alone does not disclose private channel names or resolve protected participant references.
Carry only the authorized decoration and opaque correlation in the Orb DTO. Show that same
decoration on the retained evidence row, selected-event inspector and folded graph record, using
shape, direction and text together and respecting reduced motion. These views must preserve Run
sequence, gaps and occurrence membership; playback shows only records through its supplied cursor.
A glow marks the observation itself. It cannot imply continuous connectivity or successful delivery,
and synthetic edges must not imply causality.
### Ask a named maintainer from Bridge (Proposed)
A Lich working in Bridge may propose one bounded question to explicitly designated knowledgeable
maintainers. Selection uses operator-maintained expertise and exact admitted participant mappings;
a Discord name, role, model guess or previous helpful reply cannot grant that authority.
To prepare the question, Reach retains its originating Run/occurrence, purpose, exact connection,
guild/channel/thread, recipient set, question bytes, disclosure class, expiry and finite answer
budget. Before sending, a current authenticated Sigil must authorize that audience and effect.
Bind the exact review or standing policy according to
[HitL](../../../adr/25-hitl.md#required-review-for-native-actions-designed), then recheck it against
current account, policy and revocation generations immediately before the physical attempt.
Preparing this question grants no ability to enqueue the operator's local publication queue.
The admitted workflow commits its delivery intent/outbox before the credential owner sends. It
then retains the outstanding question in a declared durable wait and releases model/worker leases.
When an answer arrives, match its selected connection, exact channel/thread and sent message
reference, admitted responder, deadline and unconsumed question generation. Specify refusal or
revision semantics for duplicate, late, edited, wrong-person and wrong-thread returns; Gateway
replay cannot consume the answer budget twice.
Even a matching Discord answer remains evidence. It is neither a Consent verdict nor a peer task,
and it cannot instruct an unrelated Run to resume.
Give the exact waiting work the accepted reply as bounded, attributed, hostile source material.
Preserve its source identity and permitted audience through Context assembly, and recheck current
Sigil and disclosure during native re-admission before resuming. Acceptance does not automatically
turn the reply into Memory, a teaching operation or authority to publish elsewhere.
If the original send remains unknown, retain that uncertainty and reconcile it without asking
another automatic question. An unanswered question, model confidence or the contents of a reply
cannot start a follow-up loop.
### Implementation order and falsifying checks
1. **Close native custody first.** Refine this successor's existing intake, communication, outbox
and receipt contracts through [the delivery plan](delivery.md). Define the typed observation
and a host-enrolled intake/receipt port with current authority and exact correlation. A shared
native ledger or an authenticated, deduplicated handoff into its owner must exist before the
ordinary Orb can observe an operator worker. Discord credentials remain exclusively at the
transport edge; filesystem queue/journal scans are not that port.
2. **Emit only actual observations.** Reach owns the bounded validator and pure presentation
contribution, proposed under `src/lychd/compositions/reach/`. Its workflow producers can use
`WorkflowServices.events`; the Run event schema/emitter is in
`src/lychd/domain/cortex/events.py`. Choose a typed semantic event contract before adding an
event kind; do not disguise interactions as fabricated station traversal or raw LOG messages.
Native intake and committed outbox/attempt owners emit their own observations. A replayed
receipt retains one observation identity, and an observer failure cannot decide Run truth.
3. **Project through the existing read seam.** Add a bounded authorized decoration to
`EvidenceItem` in `src/lychd/domain/web/contracts.py`. Enrich it through the exact Reach read port
at `src/lychd/domain/web/orb.py` and `src/lychd/interface/web/orb.py`, following the existing
protected Composition projection pattern. Snapshot and retained SSE must share validation,
recheck disclosure after awaited reads, clear revoked metadata and leave capture limits visible.
Reading Orb never creates an event or changes an outbox entry.
4. **Render the supplied meaning.** Regenerate OpenAPI/client types. Extend the closed runtime
decoder in `clients/web/src/lib/orb/live.ts`, ordinary projections in
`clients/web/src/lib/graph/orb.ts` and `graph/model.ts`, and the shared graph adapter plus Orb
row/inspector. Reach supplies static provider semantics; Orb owns presentation, selection and
folding. No renderer state, station name or terminal Run status manufactures an interaction.
5. **Prove the question lifecycle separately.** Add inert-port and disposable-database fixtures
for exact review, audience and expiry, crash before/after submission, racing claims, revoked
authority, unknown transmission and duplicate/late replies. Prove one reply resumes only its
owning wait, no scarce lease survives waiting, and no provider body enters broad evidence.
Only then qualify the Discord transport with an explicitly authorized live question.
The first projection proof needs retained ingress, provider-accepted egress and unknown-attempt
fixtures plus forged owner/reference, unsupported version, overlong label, private-name leakage,
revocation-during-read, duplicate receipt, pagination/reconnect and playback cases. Extend the
existing `tests/web/test_orb.py`, Reach composition/transport tests,
`clients/web/src/lib/orb/live.test.ts`, `graph/orb.test.ts` and Orb component tests. Run focused
Python checks through the source-bound OCI harness, then `make frontend-check` and
`make frontend-build`; complete the required Svelte documentation/autofixer workflow before any
Svelte edit. Published documentation changes also require a clean Zensical build. These are
implementation gates, not evidence that this candidate or its backend ports are delivered.
[Chat](../chat.md) · [Accounts and updates](accounts.md) · [Acceptance and delivery](delivery.md)
---
title: "Telegram connection"
plain_name: "Reach: Telegram connection"
section: "Compositions > Presence & Embodiment > Reach > Chat"
status: "Available"
original: https://hexanomicon.dev/compositions/reach/connected-work/telegram/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/telegram/
---
# Telegram connection (Reach: Telegram connection)
## Plain-English summary (Snayu)
**What it is:** How Reach prepares a Telegram bot message for an exact numeric chat, and why reading chat history and personal-account access are outside this profile.
**Why it matters:** Read this if you work on Telegram message preparation or plan Telegram intake.
- Prepares sendMessage with exact text, link previews off, and refuses text over 4,096 characters.
- Bot-wide update polling is not a per-chat read and needs its own intake design.
- Personal account login and AI use of others' chats need separate consent and are excluded.
**Status:** Available. Request preparation only; no bot login or listener.
## Original text (Hexanomicon)
Prepare a release notice for an admitted Telegram chat using a bot connection. The
[Chat](../chat.md) request retains the exact account, conversation and optional reply while
Telegram determines the payload and available operations.
This is the `reach.connect.prepare@1` request-building subset. It supplies no bot login,
update listener or personal-session integration.
## Bot message preparation
The target uses a numeric `conversation_id`, including a negative group/chat ID where applicable.
Usernames are not accepted as substitute identities. An optional numeric reply reference remains
bound to the request. The builder prepares `sendMessage` with exact text, disabled link previews
and no markup parser selected. Text exceeding 4,096 characters refuses rather than splitting one
preparation into multiple sends.
`telegram:/sendMessage` is a secret-free route selector. The bot token belongs to a later
credential owner that resolves the actual endpoint. A payload proves neither that the bot can
reach the chat nor that it may speak there. A bot cannot initiate arbitrary user chats; privacy
mode and administrator permissions affect what group content it can see.
[Bot introduction](https://core.telegram.org/bots) · [Bot API](https://core.telegram.org/bots/api)
## Intake is a separate operation
Telegram chat-history reads refuse in this subset. Bot-wide `getUpdates` is not a per-chat read:
its offset advancement confirms earlier updates and needs separately owned intake, deduplication
and cursor recovery. Webhook intake would likewise need its own authenticated custody contract.
Personal MTProto login uses an application identity and a user-authorized session, not a bot
token or mailbox OAuth grant. It is outside this profile. Telegram's content terms also constrain
AI use: the documented exception requires explicit, informed, affirmative and continued consent
from all relevant users for the specific content and context. The account owner's consent cannot
admit everyone else's chat history into a model.
[User authorization](https://core.telegram.org/api/auth) · [API terms](https://core.telegram.org/api/terms) ·
[Content licensing](https://telegram.org/tos/content-licensing)
The release WUPHF fixture in [connected preparation](preparation.md) prepares one Telegram notice
alongside Gmail and GitHub requests. No bot token, message send or model call is involved.
[Chat](../chat.md) · [Accounts](accounts.md) · [Delivery gates](delivery.md)
---
title: "WhatsApp assessment"
plain_name: "Reach: WhatsApp assessment"
section: "Compositions > Presence & Embodiment > Reach > Chat"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/whatsapp/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/whatsapp/
---
# WhatsApp assessment (Reach: WhatsApp assessment)
## Plain-English summary (Snayu)
**What it is:** An assessment of WhatsApp options for Reach: business messaging via Meta's Cloud API, general AI assistant use, and Meta's limited third-party agent platform.
**Why it matters:** Read this before promising or building any WhatsApp integration.
- Recommends an optional later business profile, after Gmail, Discord and GitHub.
- No access to personal chats; unofficial QR-linked session libraries are out of scope.
- Needs its own webhook intake, onboarding, eligibility and billing contracts; nothing is implemented.
**Status:** Designed. Assessment only; no WhatsApp connection implemented.
## Original text (Hexanomicon)
A customer asks a business a question on WhatsApp. Reach can prepare an answer and deliver it from
the business's number, subject to the recipient's permission, the response window and current
provider policy. That is useful correspondence; it does not establish access to the operator's
existing personal chats.
Reviewed **2026-10-21** for the [connected-work study](index.md). Recommend an **optional later
Business Platform profile**, `reach.whatsapp.business@1`, after the Gmail, Discord and GitHub
slices. It reuses Reach's preparation, authority and effect ledger but needs its own intake,
onboarding, eligibility and billing contracts. No WhatsApp connection is implemented or qualified.
## Three distinct routes
| Route | Useful result | Decision |
| --- | --- | --- |
| **Business Platform / Cloud API** | Receive customer messages and send from the admitted business number. | Candidate for bounded business correspondence. No personal-inbox or arbitrary existing-group import promise. |
| **General-purpose assistant over Business Platform** | A person chats with an AI assistant through its business-platform number. | Separate usage classification and current market gate. Do not disguise the primary product as ordinary customer support. |
| **Third Party Agent Platform** | The owner chats directly with their connected agent. | Separate limited-rollout probe; not the Cloud API business profile or a presently qualified Reach adapter. |
WhatsApp's official [agent help](https://faq.whatsapp.com/1050934623978152) describes up to five
connected agents, each accessible only to its owner and unable to enter or read other chats.
Availability is limited; these agent chats use Meta's service and are not considered end-to-end
encrypted. Their [Agent Terms](https://www.whatsapp.com/legal/third-party-agents-terms) apply to that
specific platform. Before proposing its adapter, verify the developer protocol, account/country
availability, sender assurance, callback custody and reconnect/recovery in the actual deployment.
The business profile uses official APIs. Reverse-engineered WhatsApp Web sessions, browser cookies
and QR-linked session libraries are outside this candidate and supply no supported shortcut to
personal-chat access.
## Business setup and existing numbers
Own-business setup needs the Meta application, business portfolio, Messaging account (older APIs
and docs call this WABA), registered business phone identity, and production token custody. Use
the necessary `whatsapp_business_messaging` permission; management access belongs only to the
setup/management service that actually requires it. Test tokens are not unattended production
credentials. [Get started](https://developers.facebook.com/documentation/business-messaging/whatsapp/get-started)
Serving other firms is a separate publisher road: partner/Tech Provider eligibility, Embedded
Signup, required Advanced Access/App Review and each customer's own assets/grants. A provider
partner may reduce development work but adds custody and fees. Self-hosting does not bypass those
requirements. Disconnect one customer without rotating a shared Meta application secret or
disrupting other accounts. [Webhook access requirements](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview)
Coexistence can connect an eligible **WhatsApp Business app** number while preserving app use; it
is not generic consumer-WhatsApp OAuth. Its onboarding requires the supported partner/Embedded
Signup flow. Optional consented history transfer has a bounded window; group chats do not sync.
Human sends can produce message echoes and do not extend the Cloud API response window. Preserve
the existing account until migration/coexistence eligibility is established; no automatic number
conversion is proposed. [Business-app onboarding](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users)
An official Groups API exists with its own eligibility and constraints. It is deferred here;
existing personal groups are not inferred to be accessible. [Groups](https://developers.facebook.com/documentation/business-messaging/whatsapp/groups)
## One permitted send
The [Messaging Policy](https://whatsappbusiness.com/policy/) requires recipient permission and
honored opt-outs. Free-form replies use the **24-hour customer service window**, refreshed by the
customer's message. Outside it, only eligible approved templates may be sent. Automation must offer
a clear escalation path to a person or business support. A template's approval does not authorize
its recipient, purpose or data disclosure.
First establish what use the connection admits. Its policy pins own-business versus AI-provider
use, business/account/phone ids, exact recipient identity, permitted purposes, opt-in/opt-out
evidence and current market rules. Each prepared send then binds the triggering message, last
eligible inbound time, conservative `latest_send_at`, message type, exact text or template
revision/language/parameters, and spend ceiling. Recheck all of these, together with current
provider eligibility, immediately before transmission.
An expired free-form reply parks or refuses; never silently convert it to a charged template.
Paused/rejected templates, opt-out, quality restriction or exhausted budget fence queued work.
Customer requests for a person or an observed manual reply can pause automation under the
conversation policy. A later resumption rechecks the window and authority rather than replaying
the old reply. Escalation itself grants no code, payment or private-record authority.
## Intake requires a different deployment
Cloud API receives messages and status through webhooks. Propose
`reach.home.connected_webhooks@1`: one authority host with an exact admitted HTTPS/Veil webhook
route, bounded raw-body intake and provider verification. The outbound-only
[`reach.home.connected@1`](accounts.md#first-deployment-road) stays unchanged. A new public route
cannot be implemented by exposing the current loopback bootstrap application.
Setting up the webhook and admitting a message require different proofs. Validate GET setup
challenges separately; for a POST, verify `X-Hub-Signature-256` over the original body with the scoped
Meta application secret. The setup verify token is not the signature secret. Before durably
admitting the POST, check configured app/account/phone ownership, allowed event kind, bytes and
generation. Acknowledge only after committing custody of that bounded intake. [Webhook endpoint](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/create-webhook-endpoint)
Deduplicate incoming provider message ids within the account/phone partition. Status updates need
their own message/status/event fingerprint; a delivered or read event is not another customer
request. Ignore own-message echoes as triggers. Retries may continue for up to seven days; provider
retry is not a complete history API. Record gaps and avoid promising Gmail-style full resync.
No remote edge carrying only refetchable hints can recover an unretained message body by assumption.
[Webhook delivery](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview)
A successful send returns a `wamid`; retain it to correlate later sent/delivered/read/failed
observations. The initial success does not prove delivery, and a later read observation does not
prove comprehension. `biz_opaque_callback_data` may carry a random effect correlation, but no
secret/customer metadata and no implied idempotency guarantee.
Keep an ambiguous send `UNKNOWN` until authenticated matching status or other independent evidence
resolves it. Without that evidence, stop instead of repeating the send. Provider queue TTL can also
delay an accepted message, so the contract assumes no instant cancellation.
[Send semantics](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages),
[status events](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
## Pricing, AI eligibility and maintenance
Do not encode “all replies within 24 hours are free.” The official [dated pricing FAQ](https://whatsappbusiness.com/resources/faq/)
states that from **2026-10-01** ordinary service messages are priced per delivered message, with
the first 1,000 monthly service messages per business phone free. Resolve the actual category,
market, rate card, free allowance, provider fees and any exception; reserve spend before sending
and reconcile observations. Enforce current throughput, recipient, quality and messaging limits
with bounded backoff rather than fixed universal rates.
General-purpose AI has distinct restrictions and pricing. Current [AI-provider documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers),
updated **2026-10-15**, includes EEA recipients such as Slovakia, Brazil and Türkiye under different
conditions; EEA service traffic has a specific exemption. This is not a universal AI ban or a
permanent worldwide permission. Pin a current eligibility observation and refuse an unknown or
expired market/classification. The [Platform Terms §4.7](https://www.facebook.com/legal/Meta-Terms-for-WhatsApp-Business-Platform),
modified **2026-09-23**, distinguish primary AI products from ancillary AI business service and
restrict model training/data reuse. Older March terms are not the current contract.
Ordinary adapter releases retain asset, secret, subscription and effect identities. New permissions,
number/custody changes, template versions and provider Graph API deprecations need their own
admission or administrator action. Automation cannot replace Meta eligibility or make an unavailable
personal agent rollout available.
Before qualifying delivery, exercise window expiry during a queue wait, template pause, opt-out
and human takeover. Also test duplicate/late webhooks, forged signatures, shared-customer
disconnect, unknown sends, exhausted spend, market-policy changes and unavailable agent rollout.
These cases must challenge the promised behavior. The common [acceptance plan](delivery.md) and
the initial three connectors remain independent of this optional work.
[Chat](../chat.md) · [Accounts and updates](accounts.md)
---
title: "Forge"
plain_name: "Reach: Forge family (code hosts)"
section: "Compositions > Presence & Embodiment > Reach > Forge"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/forge/
guide: https://lychd.snayu.ai/docs/compositions/reach/forge/
---
# Forge (Reach: Forge family (code hosts))
## Plain-English summary (Snayu)
**What it is:** How Reach reads a bounded issue conversation or prepares an issue/PR comment on a code host, kept separate from any permission to change or run code. GitHub is implemented; Radicle is not.
**Why it matters:** Read this before working on GitHub comment preparation or adding another code host.
- Targets are an exact owner/name repository and a positive issue number.
- A timeline comment is not a review approval, merge, code write, release or workflow run.
- Radicle needs its own provider profile; swapping a hostname is not compatibility.
**Status:** Partial. GitHub request preparation works; app installation and posting do not.
## Original text (Hexanomicon)
Read a bounded issue conversation or prepare a timeline comment about a release. Forge keeps
repository correspondence separate from permission to change or execute the software discussed.
The current `ForgeTarget` selects a local connection, repository and positive `issue_number`.
`ConnectedPolicy` admits exact targets and read/send operations. [GitHub](connected-work/github.md)
is the implemented provider: its request builder accepts an exact `owner/name` repository and
prepares bounded comment reads or a new issue/PR timeline comment through GitHub.com routes.
A timeline comment is not a diff review, formal approval, merge, code write, release or workflow
run. App installation and delegated user access have separate authority requirements; the offline
builder authenticates neither. The [GitHub study](connected-work/github.md) owns the proposed
installation, event, permission and reconciliation contract.
## Radicle boundary
Radicle remains unsupported by the request builder. Its node/key identity, repository RID and
issue/patch objects need their own provider profile and may need a separate target schema.
Replacing a GitHub hostname would not establish that contract. Local acceptance and peer
replication would also be different receipt claims. The
[Radicle user guide](https://radicle.dev/guides/user) is the external reference, not compatibility
evidence for this implementation.
[Connected preparation](connected-work/preparation.md) places a GitHub comment beside email and
chat in a finite WUPHF plan. It prepares every target before returning a result, without code
execution, transport or a second workflow engine.
[Reach](index.md)
---
title: "GitHub connection"
plain_name: "Reach: GitHub connection"
section: "Compositions > Presence & Embodiment > Reach > Forge"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/github/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/github/
---
# GitHub connection (Reach: GitHub connection)
## Plain-English summary (Snayu)
**What it is:** A proposed GitHub App profile where a repository owner installs Reach on selected repos so it can read issue/PR conversations and post timeline comments as a bot.
**Why it matters:** Read this before building the GitHub app, its permissions, webhook intake or comment delivery.
- Prefer a GitHub App with selected repos; request Issues write and Pull requests read, nothing more.
- Installation tokens last one hour and are minted on demand; the app signing key never ships to customers.
- Comments cannot trigger code execution, merges, releases or status checks.
**Status:** Designed. Candidate profile; no installation flow or live posting.
## Original text (Hexanomicon)
The repository owner installs Reach on selected repositories. An admitted issue or pull-request
conversation can produce a proposed timeline comment, then one delivery as the application's bot.
The conversation can ask for a code change without granting permission to execute or publish one.
The candidate `reach.github.correspondence@1` profile belongs to the [successor study](index.md).
It starts with GitHub.com; another GitHub host/version needs its own pinned compatibility and
credential configuration, not an arbitrary model-selected API URL.
## Application and permissions
Prefer a **GitHub App** with installation identity and selected-repository access. OAuth Apps bind
more broadly to user authority. Acting as a human is a separate optional authorization mode,
not implied by bot installation. [App comparison](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)
Propose Issues write and Pull requests read, with no Contents, Workflows, Checks, Commit statuses,
Administration or organization permission. Issue-comment REST endpoints cover issue and PR timeline
comments, while `issue_comment` webhooks specifically need Issues read. These permission families
are broader than this profile: the local operation allowlist admits only bounded reads and comment
creation/updates to Reach-owned comments. Issue state changes remain excluded.
[Comment endpoints](https://docs.github.com/en/rest/issues/comments),
[webhook permissions](https://docs.github.com/en/webhooks/webhook-events-and-payloads#issue_comment)
Installation tokens expire after **one hour** and can be narrowed to fewer repositories and
permissions. Mint them on demand inside the credential owner. A publisher's app signing key can
reach multiple installations and never belongs in customer software. The first self-hosted road
uses a customer-owned app; a [manifest registration](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest)
can reduce manual setup. [Installation tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)
## Events and missed work
An initial request is either operator-originated or a first-line `/reach ask` text marker from a
configured external actor in an admitted conversation. This is Reach's parser convention, not a
native GitHub slash-command facility or local authority proof. Ignore the app's own comments,
bot/automation authors by default, unconfigured actors and untriggered new activity before
cognition. Resource changes may refresh a bounded projection without creating a request.
An edit to a triggering comment invalidates any unsent preparation based on the old version.
It does not revise or resend an accepted reply. A new reply to an edited request needs a separately
admitted request/version under explicit policy; polling overlap alone cannot create that authority.
The first road polls admitted repositories/conversations with pagination, overlap windows and
conditional requests. Persist provider object id, version/update time and processed cursor; dedupe
overlaps and distinguish edits from a new request. A changed comment cannot silently revise an
already-approved response. Polling recovers accessible current state, not every deleted or
intermediate event. [Comment polling](https://docs.github.com/en/rest/issues/comments#list-issue-comments-for-a-repository),
[conditional requests](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api)
A later webhook profile would first verify HMAC-SHA256 over the original body and bind the
configured app/installation/repository and event/action. It must durably admit that intake before
returning 2xx within the provider deadline. To recognize redelivery, deduplicate `X-GitHub-Delivery`
with a payload fingerprint; GitHub retains the same GUID on redelivery. Bind each semantic action
to its resource version as well, so delivery identity does not conceal an edit. The signature
proves source bytes but gives the commenter no Ward authority.
[Signature validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries),
[webhook intake](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)
GitHub does not automatically redeliver failed webhooks, and requested redelivery is limited to
three days. App-wide delivery inspection/redelivery needs app-JWT custody rather than an ordinary
installation token. A publisher-operated service must own that repair loop; resource polling
remains the bounded reconciliation path. [Failure handling](https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries),
[redelivery](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks),
[app delivery API](https://docs.github.com/en/rest/apps/webhooks)
## Comment delivery and wider capabilities
Before review or standing policy, freeze the host, installation, repository id, issue/PR id, body,
visibility observation and actor. Recheck current installation access and destination at send time.
A proposed opaque Reach marker, carried in a hidden Markdown comment, can then help reconciliation
associate a delivery occurrence with the bot-authored comment. Although hidden in rendering, it is
externally visible source metadata: include it in the admitted bytes and keep customer/private
identifiers out of it.
Correlation does not prevent duplicate writes. Neither the marker, GraphQL `clientMutationId`,
nor check-run `external_id` establishes provider-enforced uniqueness. After an ambiguous POST,
inspect the intended thread for the matching bot, marker and body, and retain the provider id/URL
when known. If those reads are inconclusive, preserve `UNKNOWN` and do not resend. Even when the
comment is known, updating it requires a separately authorized exact edit.
PR diff comments and formal reviews have separate APIs and Pull requests write. `APPROVE` and
`REQUEST_CHANGES` are consequential review actions, not ordinary replies. Discussions use GraphQL
and need a separate compatibility probe. Checks/statuses express commit-specific results and
require their own permissions and judgment owner. Code edits, merges, releases and workflow runs
belong to the relevant software-change owner, not this communications profile.
[Reviews](https://docs.github.com/en/rest/pulls/reviews),
[Discussions](https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions)
REST installation allowance commonly starts at 5,000 requests/hour and varies with installation
and plan. Respect primary response headers and secondary limits, serialize/pause content writes,
and honor `Retry-After` and reset times on 403/429. No account/key rotation bypass.
[Rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api)
Ordinary releases preserve the app installation. Additional permissions require the installation
owner's approval; an installation that has not approved keeps its old grant. Repository removal,
installation suspension or uninstall fences pending sends without rerouting them.
[Permission changes](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app#about-changes-to-permissions)
[Forge](../forge.md) · [Accounts and updates](accounts.md) · [Acceptance and delivery](delivery.md)
---
title: "Social"
plain_name: "Reach: Social family"
section: "Compositions > Presence & Embodiment > Reach > Social"
status: "Partial"
original: https://hexanomicon.dev/compositions/reach/social/
guide: https://lychd.snayu.ai/docs/compositions/reach/social/
---
# Social (Reach: Social family)
## Plain-English summary (Snayu)
**What it is:** How Reach prepares an original public text post for a Facebook Page, a LinkedIn member or organization, or an X account, keeping the exact publishing author.
**Why it matters:** Read this before working on social post preparation.
- Only public organic posts are supported; replies, DMs, media, boosts and ads are out of scope.
- Facebook personal profiles are refused; LinkedIn text is escaped and length-limited.
- Editorial approval belongs to the Broadcast app; a prepared post does not authorize publication.
**Status:** Partial. Post preparation works; no account connection or publishing.
## Original text (Hexanomicon)
Prepare public launch copy for the founder's account or company Page. Social shares the intent
to publish an original organic text post while preserving each provider's author and payload.
`SocialTarget` selects a connection, external `account_id`, `actor_kind` and visibility. The
account must equal the connection's declared publishing actor; `ConnectedPolicy` selects its
exact allowed target. The current builders admit public posts only.
| Provider | Actor | Request-specific behavior |
| --- | --- | --- |
| Facebook | Page. | Page-feed text post; personal-profile mode refuses. |
| LinkedIn | Member/person or organization with its matching URN. | Literal text escapes the provider's `little` markup and obeys a conservative encoded-text limit. |
| X | User. | Original text post with the prepared AI-authorship field; no automatic reply bot. |
The [social account and advertising assessment](connected-work/social.md) owns access requirements,
provider versions and the founder's promotional journey. Social reads, replies, DMs, media uploads,
boosts, advertising campaigns and spending are outside the prepared operation set.
[Broadcast](../broadcast/release.md) owns editorial acceptance and publication judgment. Settled,
approved copy can enter Reach as input; coordinating several live Composition Invocations needs
a [Suite](../products-and-suites.md#compositions-relate-without-nesting).
Use [connected preparation](connected-work/preparation.md) for the founder launch example and
native serial Graph. A prepared post does not authenticate its author or authorize publication.
[Reach](index.md)
---
title: "Social accounts and advertising"
plain_name: "Reach: Social accounts and advertising"
section: "Compositions > Presence & Embodiment > Reach > Social"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/social/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/social/
---
# Social accounts and advertising (Reach: Social accounts and advertising)
## Plain-English summary (Snayu)
**What it is:** An assessment of what account access each social provider (Facebook, LinkedIn, X) requires for posting, and why posting permission never becomes permission to run paid advertising.
**Why it matters:** Read this before planning social publishing, provider app approvals or any paid promotion features.
- Facebook needs a Page and posting permission; LinkedIn organization posting needs separate approval.
- X posting needs user-delegated OAuth; automatic replies and DMs are different operations.
- Prepare content and author first; spending money on ads is a separate, later capability.
**Status:** Designed. Assessment; local preparation exists, live onboarding does not.
## Original text (Hexanomicon)
A founder wants to describe their AI service on Facebook and LinkedIn, answer interested people,
and eventually pay to distribute a campaign. Those are different operations with different account
and provider permissions. Prepare the content and exact author first; an ordinary publication
grant cannot silently become authority to spend money.
The following official-source assessment was checked **2026-10-29**. The
[connected preparation profile](preparation.md) implements local request construction. Account
onboarding, API access approval and live publication remain separate qualification work.
## Pick the account and the operation
| Service | Supported direction | What account access does not imply |
| --- | --- | --- |
| Facebook | A Page post as the configured Page with eligible tasks and `pages_manage_posts`. | A Page token does not supply ordinary personal-profile publishing. [Page posts](https://developers.facebook.com/documentation/pages-api/posts). |
| LinkedIn | Member publishing with `w_member_social`; organization publishing with `w_organization_social` and an eligible organization role. | Organization Community Management access requires its own approval; member sharing does not grant organization or advertising access. [Getting access](https://learn.microsoft.com/en-us/linkedin/shared/authentication/getting-access), [Posts API](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api?view=li-lms-2026-10). |
| X | Original public posts with user-delegated OAuth. | App-only bearer access does not authorize posting as a person. Automatic replies and private DMs are different operations. [OAuth](https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code), [Create Posts](https://docs.x.com/x-api/posts/create-post). |
[Email](../email.md), [Chat](../chat.md) and [Forge](../forge.md) own the other provider-family routes.
This assessment stays with the [Social](../social.md) post contract and its advertising boundary.
X requires prior written explicit approval for an AI reply bot. Its automation policy also
restricts unsolicited automated replies/DMs and requires a working opt-out. This profile prepares
original posts; it does not establish that approval or provide a reply bot. Prepared AI-authored
posts include the API's `made_with_ai` field. [Automation rules](https://help.x.com/en/rules-and-policies/x-automation),
[post request](https://docs.x.com/x-api/posts/create-post)
## Promotional content before paid distribution
LinkedIn commentary uses its `little` markup syntax. The builder escapes reserved characters to
preserve literal input, and conservatively caps the encoded commentary at 3,000 UTF-16 units.
It refuses excess text rather than splitting one reviewed post into several effects.
[Text syntax](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/little-text-format?view=li-lms-2026-10),
[post length](https://www.linkedin.com/help/lms/answer/a522483/differences-between-posting-updates-and-publishing-articles?lang=en)
For the first founder journey, begin by accepting the service's claims and creative assets.
Prepare one Facebook Page post and one LinkedIn post, then review each exact author, text and
audience. A future qualified delivery path must admit each publication separately because
cross-posting makes a new disclosure at each destination. Provider acceptance of a post establishes
none of its reach, engagement or sales.
Images and video require separately admitted upload artifacts and returned media references;
the present connector subset constructs text requests. It does not scrape link previews, generate
assets, upload media or boost a post. [Broadcast release](../../broadcast/release.md) retains
editorial acceptance, claims, credits, disclosures and publication judgment.
Paid campaigns need a separately reviewed request binding at least:
- The advertiser, platform, ad account, campaign objective and permitted product.
- Exact accepted creative, destination URL, audience and targeting constraints.
- Currency, daily or lifetime budget, bid constraints, start/end and total spend ceiling.
- Draft versus activation, current account role, provider policy eligibility and review identity.
- Per-operation receipt, unknown-state reconciliation, and an independently admitted pause action.
This is a design boundary, not a delivered advertising request type or campaign executor.
Do not infer activation authority from approval of the copy, a Page role, or a successful upload.
Meta's Marketing API uses `ads_read` and `ads_management` for the corresponding operations.
Own-account versus other-account access differs. Limited/Full Marketing API tiers are separate
from Standard/Advanced permission access, and development-tier calls still touch production
data. [Marketing authorization](https://developers.facebook.com/documentation/ads-commerce/marketing-api/get-started/authorization)
LinkedIn Advertising requires separate access approval and appropriate ad-account roles. Its
development tier permits edits to up to five administered ad accounts. Version `202610` adds
member/organization boost scopes, which do not follow from ordinary posting. Never silently
upgrade an organic post into a charged boost. [Access tiers and permissions](https://learn.microsoft.com/en-us/linkedin/marketing/increasing-access?view=li-lms-2026-10)
## Protocol changes and recovery
The social subset pins Meta Graph `v26.0` and LinkedIn `202610` with Rest.li `2.0.0`.
Those pins need maintenance and qualification before live transport; they are not a promise of
permanent provider compatibility.
[Page posts](https://developers.facebook.com/documentation/pages-api/posts),
[LinkedIn posts](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api?view=li-lms-2026-10)
The builders stop after constructing requests: they do not retry, rotate accounts, fetch links,
open sessions or send. A future transport must check current authority, exact destination, provider
limits and eligibility, then persist its attempt before submission. Record whether the result is
rejected, accepted or unknown. Provider acceptance alone cannot establish exactly-once delivery;
a timeout after submission must never cause WUPHF to send again to every destination.
[Social](../social.md) · [Preparation and user stories](preparation.md) · [Account lifecycle](accounts.md) · [Delivery gates](delivery.md)
---
title: "Habitat"
plain_name: "Reach: Discord server boundary"
section: "Compositions > Presence & Embodiment > Reach"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/habitat/
guide: https://lychd.snayu.ai/docs/compositions/reach/habitat/
---
# Habitat (Reach: Discord server boundary)
## Plain-English summary (Snayu)
**What it is:** Defines the first public social place: one private Discord server, one channel, and a minimal-permission bot, and how Discord identity is kept separate from local authority.
**Why it matters:** Read this to understand who may ask Reach what in Discord, and why Discord roles grant no local power.
- The bot gets only View Channel and Send Messages; non-mention messages are discarded before storage.
- Unlinked members get guest conversation only; the Security Desk maps enrolled users to real grants.
- On the VPS-edge setup, relayed identities could be faked, so home treats them as guest only.
**Status:** Designed. Public contract; not deployed.
## Original text (Hexanomicon)
The Necropolis first appears as one private Discord guild, one channel named `the-reach`, and a server-installed application named **Reach**. The outbound Gateway session admits social contact without publishing an ad hoc entrance to the loopback Vessel.
This social Habitat shares a name with the [Necropolis A2A topology](../../adr/26-a2a.md#legion-and-necropolis), not its enrollment. Guild membership creates no peer, Principal, node trust, or LychD grant.
## The channel's boundary
Revision one gives the bot only `View Channel` and `Send Messages`, with `GUILDS` and `GUILD_MESSAGES`. It receives no administrator, moderation, attachments, mass mentions, voice, or privileged intent. Non-mention content is discarded before persistence; replies disable automatic mentions.
To decide what a member may ask of Reach, distinguish the identity observed by Discord from authority granted locally. A platform subject establishes identity only to the assurance admitted for its adapter/profile. Ward may map an enrolled subject to a Principal and current object grants. An unlinked member instead receives guest conversation, without private records, tools, or effects. Discord roles may narrow visibility, but they cannot create a grant or settle consent.
On the split VPS-edge/home-core road, a compromised edge can fabricate relayed Gateway identity. Home therefore treats it as guest/public-only unless the person independently proves identity directly to Ward. Neither fluent account use nor tunnel possession repairs that gap.
## A place the Lich may return to
Returning to this place involves several kinds of continuity. Mirror preserves Persona lineage, while Discord and its adapter preserve the place, member, event, session, and delivery state. Each Reach turn keeps only material allowed for its purpose. [Avatar](../avatar/index.md) may later relate the presentation here to Blockworld or a Spectre Habitat; that relationship does not share Context or authority, or create an endless session.
Discord and an attacker compromising it can obtain projected material. Private channels and ephemeral replies narrow audience, not provide end-to-end encryption. A later forum, Reach surface, or self-hosted commons must independently preserve identity, privacy, admission, and authority rather than inherit trust from the name.
Choose a [deployment profile](deployments/index.md), then follow one [Turn](turn.md).
---
title: "Turn"
plain_name: "Reach: One question-and-answer turn"
section: "Compositions > Presence & Embodiment > Reach"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/turn/
guide: https://lychd.snayu.ai/docs/compositions/reach/turn/
---
# Turn (Reach: One question-and-answer turn)
## Plain-English summary (Snayu)
**What it is:** The step-by-step life of one Discord question: authenticate and deduplicate, resolve caller authority, assemble the briefing, commit the answer, then attempt delivery and record whether it arrived.
**Why it matters:** Read this before working on Reach's answer pipeline, privacy filtering for remote models, or delivery retries.
- The answer is committed before any send; delivery is recorded as known sent, rejected or unknown.
- Discord IDs, roles and unrelated history are stripped before any cloud model sees the question.
- An expired interaction leads to a status lookup, never to re-running the work.
**Status:** Designed. Public contract; tests use fixtures, no live Discord.
## Original text (Hexanomicon)
The question arrives with platform identity, delivery metadata, and possibly private words. Reach first decides what may enter this turn, then commits its answer before any credential-bearing edge attempts the reply.
1. Authenticate Gateway and verify application, guild, channel, trigger, size, and adapter revision; deduplicate the event before cognition.
2. Resolve guest or enrolled authority and assemble labelled Context for this person, purpose, and place.
3. Select one exact Pattern for mention, `/reach ask`, or bounded presence under audience, quiet hours, budgets, cooldown, expiry, and dedupe.
4. Commit `ReachTurn@1` with Habitat/trigger/caller evidence, Persona/AgentSpec revisions, Context references, Run correlation, output class, and terminal state.
5. Project at most one `ReachDelivery@1`, retaining target, effect identity, payload digest, platform observation, and known/unknown delivery. End the awakening.
## Choose an eligible cognition road
A public corpus cannot make the caller's question public. Before remote formation, remove Discord application/user/guild/channel/event ids, roles, presence, mentions, unrelated history, and delivery metadata unless an exact field is task-essential and independently eligible. Send only bounded question, selected public evidence, output contract, and necessary citation ids. Secrets, private people/customer facts, and unique internal incidents retain their labels and normally stay local or refuse.
For `reach.external_converse@1`, a bounded answer may use local Soulstone capability, one exact Portal model attempt while LychD owns retrieval/citations, or one outbound Intercom task to an enrolled sovereign specialist for `reach.public_corpus_answer@1`. The A2A road parks durably, quarantines the return, and adopts the first authenticated terminal. Repository inspection/mutation with an iterative CLI loop belongs to separate delegated-coding work; an admitted artifact can return later. Interactive coding subscriptions are outside Reach and Spellweaver automation.
Before each remote attempt, obtain its exact `EgressDecision` and any Privacy Cut required by policy. Obtain another decision for a retry or fallback, or when the payload, model, peer, or destination changes. The returned output remains attributed hostile input until the attempt explicitly settles as success, refusal, dependency, expiry, failure, or indeterminate.
Formation alone cannot send the answer: only a committed delivery intent reaches the Discord credential owner. [Deployment](deployments/index.md) owns placement and custody, and the [standalone E2E contract](deployments/vps-public.md#first-e2e-contract-one-public-discord-question) follows the full ledger chain.
## Commands and interrupted delivery
`/reach link` and `/reach unlink` belong to Ward. `/reach status` shows only caller-owned or explicitly shared committed state. Messages, buttons, reactions, roles, and a fluent yes cannot authorize consent, deployment, repository/host mutation, deletion, secrets, authority change, or publication.
On Gateway replay, deduplicate against the namespaced event identity and payload digest. An expired interaction token may lead to status lookup, never to running the work again to manufacture a reply. A disconnect after send leaves delivery **unknown** until reconciliation accounts for the effect identity and payload.
If compromise is contained to the adapter, revoke its Principal, rotate the bot token, close Gateway, and mark deliveries uncertain while preserving secret-free evidence. Prove the containment boundary before recreating the unit from zero authority. A host/root compromise requires the selected profile's [clean rebuild](deployments/vps-public.md#restart-uncertainty-and-compromise); an in-place restart cannot restore trust.
## Proving one turn
Deterministic Gateway fixtures and fake text capability prove mention/command, no ambient-message records, guest/member separation, consequential-request refusal, restart dedupe, quiet-hour budgets, revocation, and no duplicate after uncertain delivery. No live Discord/model enters the proof.
[Execution roads](../../sepulcher/extensions/weaver/execution-roads.md) · [Deployment profiles](deployments/index.md)
---
title: "Deployment profiles"
plain_name: "Reach: Deployment profiles"
section: "Compositions > Presence & Embodiment > Reach"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/deployments/
guide: https://lychd.snayu.ai/docs/compositions/reach/deployments/
---
# Deployment profiles (Reach: Deployment profiles)
## Plain-English summary (Snayu)
**What it is:** Compares three ways to deploy the public Reach bot: all at home, a VPS edge relaying to a home core, or a standalone VPS, and what each means for availability and security.
**Why it matters:** Read this before choosing or building a Reach deployment.
- Home-only keeps all truth at home but goes silent when home is down.
- VPS edge plus home core can hold incoming messages while home is offline, at the cost of a two-host protocol.
- Standalone VPS is independent but a VPS compromise exposes that whole restricted body.
**Status:** Designed. Profiles are designed; none is deployable yet.
## Original text (Hexanomicon)
When home loses power, should Reach go quiet, retain bounded incoming messages elsewhere, or continue as an independent restricted body? That availability choice determines where authority and credentials must live.
[Configuration](../../../adr/12-configuration.md) selects one exact immutable profile. The profiles below define its service placement and authority boundaries; [State of Work](../../../state-of-the-work.md#composition-portfolio-delivery) records the implementation prerequisites for deploying them.
## Choose the body
| Profile | Sole application authority | Roads and trade-off |
| --- | --- | --- |
| [`reach.home.public@1`](home-public.md) | Home Ward, Vessel, Workers, corpus, effect ledger, Phylactery. | All outbound; no Tether/Veil. Durable truth stays home and Reach is unavailable with that host. |
| [`reach.edge-home.public@1`](vps-edge-home-core.md) | The same home authority; VPS has only bounded Discord transport/effect custody. | Exact Tether and private home Veil. Bounded offline intake adds a security-critical two-host protocol. |
| [`reach.vps.public@1`](vps-public.md) | Independent VPS-local Ward, Vessel, Workers, corpus, ledger, Phylactery. | Outbound baseline without Tether/Veil. VPS compromise exposes this entire restricted public body. |
The [one-question E2E contract](vps-public.md#first-e2e-contract-one-public-discord-question) is shared by all three profiles; its standalone VPS page also explains that profile's particular custody and recovery. Home-only is the default for home durability unless bounded offline intake justifies the edge. A backup elsewhere is recovery material, never a second authority. These are mutually exclusive profiles, not security levels or independent `use_vps`, `trusted`, `tether`, `veil`, or `local_db` options.
Tether grants an exact private road, not application power. Veil constrains an admitted HTTP entrance and need not be public. The split profile needs both because VPS initiates private HTTP to home. Later callbacks or A2A serving need a different profile revision. Compare authority location, data exposure, home dependency, compromise consequences, complexity, and recovery; no public label, guild membership, tunnel, or VPS ownership proves identity or egress permission.
## Invariants across every profile
Every `(Discord application, Habitat partition)` has one active deployment generation. Its binding identifies the profile revision, `ReachAuthorityEpoch`, active Phylactery, `ReachEdgeEpoch`, Gateway/delivery credential owner, corpus authority, and provider/A2A gate. To establish which generation owned any work, pin the per-host manifest digests, service Principals, credentials/routes, and both epochs in every event, attempt, settlement, backup, and migration receipt.
Reject an unknown combination, simultaneous activation, or stale epoch before Bind/admission. PostgreSQL is never WAN-exposed, shared, live-replicated, dual-written, or failed over. A transport journal can witness bytes and effects, but Run, Context, Ward, Sigil, corpus judgment, turn, and terminal truth remain with their owners.
Co-locating services does not remove their separation requirements. Likewise, every remote attempt still needs exact destination/task policy, any required Cut, and a fresh egress decision bound to its payload.
## Selection and migration
Changing profile is a quiesced Evolution effect:
1. Close admission and freeze the target generation.
2. Drain or classify all provider/A2A attempts, delivery intents, `UNKNOWN` effects, Gateway cursors, and spool rows.
3. Fence authority/edge epochs, stop the old Gateway owner, and revoke its routes/credentials.
4. When authority moves, export only the admitted public Reach partition with schema/profile/corpus/source/retention/dedupe/external-effect identity closure; restore transactionally into an inactive body. Never copy the whole home Phylactery or live-replicate it.
5. Attest new host manifests, rotate custody-changing bot/provider/Tether/Veil credentials, and enroll service Principals.
6. Activate the new authority last; reopen admission while rejecting old-generation messages.
Moving between home-only and edge-home retains the home database, but still requires transfer of the Discord edge. A transition involving the standalone profile must refuse if it cannot safely preserve nonterminal or indeterminate effects. Once the new body begins admitting work, rolling back requires another quiesced migration; the old database stays fenced/read-only.
## Administrative separation
Application peers, routes, and service credentials cannot authorize SSH, Podman, systemd, deployment, rotation, provider consoles, or `magus:*`. Infrastructure administration and any later operator VPN peer require separate keys, routes, identity, and authorization.
[Home-only](home-public.md) · [VPS edge + home core](vps-edge-home-core.md) · [Standalone VPS](vps-public.md)
---
title: "Home-only"
plain_name: "Reach deployment: Home-only"
section: "Compositions > Presence & Embodiment > Reach > Deployment profiles"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/deployments/home-public/
guide: https://lychd.snayu.ai/docs/compositions/reach/deployments/home-public/
---
# Home-only (Reach deployment: Home-only)
## Plain-English summary (Snayu)
**What it is:** The home-only Reach profile: every service, record and credential stays on one home machine with outbound-only connections, so Reach is unavailable whenever home is down.
**Why it matters:** Read this if you are planning a single-host Reach deployment.
- No VPS, tunnel, public listener or inbound callbacks; all connections are outbound.
- Discord edge holds the bot token only; other services split credentials by job.
- After a reboot, only events Discord still supplies can be recovered.
**Status:** Designed. Page states: designed, not deployable.
## Original text (Hexanomicon)
Reach sleeps when home sleeps. `reach.home.public@1` keeps its Ward, Vessel, Workers, corpus, effect ledger, and Phylactery in one home-local `ApplicationDeploymentManifest@1`, with no VPS, Tether, Veil, public listener, callback, or inbound A2A road.
This profile is **Designed, not deployable**. [State of Work](../../../state-of-the-work.md#composition-portfolio-delivery) records Reach’s delivery boundary.
The profile admits public corpus/Context and guest effects. Its separated services narrow parser and credential compromise, but do not isolate the body from home-account or Vessel compromise, which may expose private home truth and resident credentials.
## Services and roads
The Discord edge holds the bot token and Gateway/event/delivery observations. It has no provider credentials, corpus writer, database secret, policy, or ambient Sigil. Core/Ward/Workers own admissions, task Sigils, Runs, turns, and policy, but receive no bot/provider bearers, non-local listeners, or host control.
Fetching evidence and making remote attempts also have separate owners. The corpus refresher holds allowlisted HTTPS access and staging custody; the Portal/A2A gate holds only the credentials and attempts for its exact destination. Phylactery owns canonical Core/Reach records and has neither a non-local listener nor a replica.
Gateway WSS and Discord REST, source HTTPS, and exact provider/A2A HTTPS are outbound. Authenticated typed local ports connect services; other ingress is closed. The [standalone E2E contract](vps-public.md#first-e2e-contract-one-public-discord-question) supplies the same corpus, fresh egress, quarantine, turn, nonce, and known/unknown delivery law. Every canonical record commits at home.
## Failure and recovery
After reboot, use Run/outbox truth to resume safe pre-submit work and reconcile uncertain provider/Discord effects. Reconnecting recovers only the events Discord still supplies, so older missed events have no promised recovery. While power or Internet access is lost, Reach performs no cognition, provider/A2A work, or delivery.
Home compromise closes admission, revokes bot/provider/A2A/database/service credentials, and reconciles external identities. Recovery follows the [clean-rebuild contract](vps-public.md#restart-uncertainty-and-compromise): rebuild a trusted body, restore only independently verified non-secret records from an admitted backup, and reenroll from zero authority before activating a fresh epoch. An off-host backup cannot operate as a second Phylactery.
## Acceptance
Qualification must follow a public turn across two boots and prove dedupe, corpus citations, and per-attempt egress. It must also exercise uncertain provider/A2A and Discord effects, service-secret/network isolation, zero non-local listeners, and restore. Private Context, consequential effects, callbacks, inbound peers, and simultaneous epochs must all refuse.
[Deployment matrix](index.md) · [Reach turn](../turn.md)
---
title: "VPS edge + home core"
plain_name: "Reach deployment: VPS edge, home core"
section: "Compositions > Presence & Embodiment > Reach > Deployment profiles"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/deployments/vps-edge-home-core/
guide: https://lychd.snayu.ai/docs/compositions/reach/deployments/vps-edge-home-core/
---
# VPS edge + home core (Reach deployment: VPS edge, home core)
## Plain-English summary (Snayu)
**What it is:** A split profile where a VPS only holds the Discord connection and a bounded message spool, relaying over a private WireGuard tunnel to home, where all thinking, data and authority stay.
**Why it matters:** Read this if you need Reach to capture messages while the home server is offline.
- The VPS cannot think or write replies; it only receives, spools and delivers Discord traffic.
- Home's private gateway exposes only event admission, delivery claim, settlement and health operations.
- Because a compromised edge could fake identities, the profile is guest/public-only.
**Status:** Designed. Designed profile; not deployable.
## Original text (Hexanomicon)
A mention arrives while home is offline. The VPS can preserve it within exact limits, but it cannot choose evidence, think, or author a reply. `reach.edge-home.public@1` leaves Ward, Vessel, Workers, corpus, provider/A2A gate, effect ledger, and Phylactery solely at home.
The edge is bounded Discord transport/effect custody, not a Vessel, replica, Legionnaire, sovereign peer, or fallback cognition service. Its relayed Gateway identities can be fabricated if it is compromised, so the profile is guest/public-only. Private enrollment would require separate human proof directly to home Ward; roles, fluency, tunnel membership, and edge assertions cannot supply it.
## Two sealed host manifests
The generation pins both manifests, service Principals, schema range, Tether peer generation, private Veil route, and `ReachAuthorityEpoch`/`ReachEdgeEpoch` in a compatibility/enrollment receipt.
The VPS needs enough custody to receive and relay Discord work: the bot token, encrypted spool key, exact Tether key, relay mTLS/service credential, Gateway/delivery adapter, bounded journals, and relay. It has no PostgreSQL road or home Codex.
Home retains database credentials, Ward/task Sigils, corpus/index, private Context, provider/A2A credentials and the application ledger. It also runs core/Workers/refresher/gates/isolated edge adapter/private Veil. On both hosts, distinct rootless services have exact mounts, secrets, networks, budgets, and local authentication.
```text
home Tether peer -- outbound UDP/keepalive --> public VPS WireGuard endpoint
VPS Discord edge -- outbound WSS/HTTPS --> Discord
VPS relay -- HTTPS/mTLS over Tether --> private home Veil --> isolated Reach edge adapter
home provider/A2A gate -- outbound HTTPS --> exact admitted destination
```
Veil binds only its Tether address and exact event-admission, delivery-claim, settlement, and unauthoritative-health operations. It never routes to database, core, corpus writer, provider gate, Altar, model API, host control, or public listener. VPS initiates application HTTP, so home needs no public application entrance.
## Ingress custody
The edge commits `EdgeIngressEnvelope@1` before forwarding:
```text
BUFFERED → FORWARDING → HOME_ADMITTED | HOME_REFUSED
BUFFERED | FORWARDING → EXPIRED | QUARANTINED
RECEIVED → EDGE_REFUSED_SIZE
```
The envelope binds the epochs, edge Principal, adapter, platform application/Habitat/event identity, canonical digest, bounded encrypted payload, receipt/expiry times, forwarding generation, and eventual admission identity. Home uses that binding to recheck credentials/epochs, freshness, guild/channel/subject, digest, quotas, and guest policy before atomically committing or deduplicating `DiscordEventAdmission@1`. Reusing an identity with changed bytes is a security fault.
Forwarding alone does not establish home custody. Retire a successfully forwarded raw payload only after receiving an authenticated commit receipt. Local expiry or refusal instead follows the limits below and must never claim home admission.
Ingress custody and delivery custody have separate ceilings:
| Material | Ceiling | Action at the boundary |
| --- | --- | --- |
| Ingress payload | 32 KiB encoded; 64 KiB expanded | Enforce while streaming, before canonical allocation/encryption. Overflow retains bounded identity/digest/observed-size and `EDGE_REFUSED_SIZE`, never body or home admission. |
| Encrypted ingress spool | 5,000 rows; 128 MiB; 24 hours | At any limit, visibly expire/refuse oldest unadmitted custody and stop new work before heartbeat/reconciliation suffers. |
| Delivery payload | 16 KiB canonical; 32 KiB projected | Home returns `KNOWN_REJECTED(size_limit)` before committing `SUBMITTING` or releasing oversize bytes. |
| Delivery journal | 2,000 rows; 64 MiB | Stop new claims at 80% pressure; exact retry/settlement outranks new work. |
| Delivery terminal evidence | Seven days | Keep the terminal record for this bounded retention. |
Offline home permits no edge cognition, corpus selection, provider/A2A calls, Sigils, judgment, or synthesized reply. Offline slash commands expire without edge response and never later become turns. Even static operational replies would need a separate delegated-effect profile and home-committed payload, scope, expiry, budgets, deterministic nonce/effect, revocation, and reconciliation.
## Discord effect custody
Home commits `ReachTurn@1` and `DiscordDeliveryIntent@1`. The edge's `EdgeDeliveryAttempt@1` binds epochs/Principal, intent/effect, payload digest, deterministic nonce, attempt, claim generation, observation, and settlement:
1. Persist `CLAIM_REQUESTED` with one attempt identity, then request that claim.
2. Home atomically binds the intent and commits `SUBMITTING` before returning bytes.
3. Edge persists `PREPARED`, then `SUBMITTING`, before Discord REST.
4. Record known/unknown result and retry only authenticated settlement to home.
5. Home idempotently adopts evidence and alone settles `ReachDelivery@1`.
A network partition can hide whether the edge sent, so elapsed time cannot reassign cross-host `SUBMITTING`. Only the same durable attempt may resume or reconcile. If its journal is lost, retain `UNKNOWN`; refuse a changed payload or attempt.
## Failure, compromise, and acceptance
When Tether is lost, enforce the spool limits and use no alternate route. A compromised VPS requires revoking the bot, edge Principal/mTLS, spool key, Tether peer, and edge epoch. Close the route, quarantine the spool, treat public queries as exposed, and reconcile Discord before rebuilding. Rotate provider keys only if evidence shows they crossed to the edge.
Home compromise has a different scope. Stop claims, revoke home/provider/A2A/Veil/Tether credentials, and mark issued work as tainted. Preserve edge journals without allowing new execution, then restore fresh home authority.
Qualification must show that hostile, replayed and old-epoch relay cannot obtain admission or upgrade the profile to private access, and that no WAN database route exists. Exercise every spool limit, offline slash expiry with zero reply, dedupe, and every partition between claim, send and settlement. Prove that submission cannot be reassigned and that journal loss preserves uncertainty. Finally, verify isolation, both compromise drills, and migration without duplicate Gateway owners or authorities.
[Deployment matrix](index.md) · [Tether](../../../sepulcher/extensions/tether.md) · [Veil](../../../sepulcher/extensions/veil.md)
---
title: "Standalone VPS"
plain_name: "Reach deployment: Standalone VPS"
section: "Compositions > Presence & Embodiment > Reach > Deployment profiles"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/deployments/vps-public/
guide: https://lychd.snayu.ai/docs/compositions/reach/deployments/vps-public/
---
# Standalone VPS (Reach deployment: Standalone VPS)
## Plain-English summary (Snayu)
**What it is:** A standalone restricted Reach on a VPS with its own database and services, plus the shared end-to-end contract for answering one public Discord question from a public docs corpus.
**Why it matters:** Read this before deploying Reach on a VPS or implementing the end-to-end Discord question flow.
- No road to home data, models or credentials; guest/public questions only.
- The public corpus is fetched from pinned HTTPS sources, built offline and expires after 24 hours.
- Turn outcome and delivery outcome are recorded separately; unknown sends are never retried blindly.
**Status:** Designed. Acceptance target; current app cannot be exposed this way.
## Original text (Hexanomicon)
One public Discord question is enough to test the entire restricted VPS body: event admission, corpus evidence, cognition, committed answer, external send, and recovery. `reach.vps.public@1` owns that standalone deployment profile and end-to-end acceptance target.
The [worked question](#first-e2e-contract-one-public-discord-question) also states the common turn and delivery chain used by the [home-only](home-public.md) and [edge/home](vps-edge-home-core.md) profiles. Those profiles keep their own placement, custody, and recovery boundaries.
The profile requires the separate service and authority boundaries below. Before deployment, check their [implementation evidence](../../../state-of-the-work.md#composition-portfolio-delivery); the current loopback application cannot be exposed as this VPS body. Exporting Discord material requires its own admission.
## One restricted deployment
The VPS has its own Vessel, Workers, local Ward, and [Phylactery](../../../adr/06-persistence.md) for Core Run/Ward/queue and Reach truth. It has no road to home database, private Context, Altar, model services, Podman, Reactor, host authority, reusable home credentials, or ambient Sigils. Ward may mint a secret-free task-scoped Sigil after admission; it expires with the task and never crosses to a model or peer.
The baseline is outbound-only and guest/public-only, using one admitted Habitat/corpus and a question eligible for disclosure. It has no Tether, Veil, callback, inbound A2A, Agent Card, private home data, enrolled caller powers, or dynamic discovery. Private Context, missing privacy boundaries, and greater authority refuse. Enrolled/private attachment is a later profile requiring delivered remote Ward and an exact private backend, never guild membership.
## First E2E contract: one public Discord question
1. **Receive:** edge validates application, guild, channel/thread, trigger, bytes, and adapter on an outbound-Gateway event.
2. **Reserve:** atomically insert `DiscordEventAdmission@1` under `(platform, adapter revision, application id, event kind, external event id)` and payload digest. Exact replay in the same Habitat/owner partition returns committed status; changed-content/cross-partition reuse is a security fault.
3. **Admit:** Ward maps guest scope under `(platform, application, guild, channel-or-thread, external-subject)`, with no retained personal history, then mints the task Sigil.
4. **Ground:** select the active snapshot, bounded passages, and sealed evidence bundle.
5. **Form:** exact Pattern/Run assembles labels and required [Privacy Cut](../../../adr/21-context.md#privatization-and-the-privacy-cut); missing lineage/verifier/Cut/receipt refuses remote formation.
6. **Admit egress:** immediately before bytes, the trusted gate issues fresh `EgressDecision` binding Principal/Sigil, Run/attempt, provider/peer/destination/purpose, payload digest, labels, policy, transformation receipt, expiry, and budgets. Retry, fallback, redirect, resume, payload, actor, model, peer, or destination change needs another decision.
7. **Call:** persist `ServiceJobAttempt@1` or the enrolled/task-authorized Intercom task/outbox, then `SUBMITTING` before transmission. Adapter receives no Sigil or undisclosed Context.
8. **Quarantine:** validate attributed return protocol/schema, size, terminal, correlation, citations, privacy, and output class before adoption.
9. **Commit:** one transaction writes `ReachTurn@1` and `DiscordDeliveryIntent@1` in `PENDING` with effect, digest, and deterministic nonce. Authenticated claim grants a generation-fenced lease; ledger persists `CLAIMED`, then `SUBMITTING`, before edge REST with `enforce_nonce=true`. Edge holds no database credential.
10. **Settle:** authenticated settlement writes `ReachDelivery@1` with effect/digest, platform status, nonce, claim generation, and known message id. Expired pre-submit claims may be reclaimed under the same intent. After possible send, keep `UNKNOWN` and do not resend until independent evidence reconciles the effect.
Discord's [Create Message reference](https://docs.discord.com/developers/resources/message#create-message) describes nonce uniqueness only for “the past few minutes”; it supplies no bounded safe retry deadline. A future adapter may admit same-nonce, matching-payload retry only under an exact platform guarantee that excludes duplication for that attempt.
```text
DiscordEventAdmission
-> Run / Pattern revision
-> PublicCorpusSnapshot + CorpusEvidenceBundle
-> Context lineage + Cut receipt + EgressDecision
-> ServiceJobAttempt or Intercom task/outbox
-> ReachTurn + DiscordDeliveryIntent
-> ReachDelivery
```
This binds event, turn, Run/station attempt, provider/A2A request/task/message/idempotency identities, effect, digest, and Discord message. HTTP success or provider prose replaces none of those committed edges.
Keep the outcome of the turn separate from the outcome of sending it. `ReachTurn@1` terminates as `SUCCEEDED`, `REFUSED`, `DEPENDENCY_UNAVAILABLE`, `EXPIRED`, `FAILED`, or `INDETERMINATE`; `ReachDelivery@1` returns `NOT_ATTEMPTED`, `KNOWN_SENT`, `KNOWN_REJECTED`, or `UNKNOWN`.
The intent follows `PENDING -> CLAIMED -> SUBMITTING -> KNOWN_SENT | KNOWN_REJECTED | UNKNOWN`, with durable claims/generations/leases/attempts. A crash after submission may have left an external effect, so recovery cannot reclaim that work as unsent.
## Enforced service and secret split
Provision a non-root, non-login host account and platform floor separately from Reach. `ApplicationDeploymentManifest@1` pins every role as a distinct rootless unit/container with exact image, command, ordering, mounts, namespaces, ceilings, and secret files; Scribe alone materializes it. Shared Pods, environment, credentials, or writable volumes cannot replace typed ports/inboxes/outboxes.
| Service | May hold or do | Must not receive |
| --- | --- | --- |
| **Discord edge** | bot token; outbound Gateway; outbound Discord REST; emit validated events; consume one-delivery intents | corpus, provider/peer credentials, policy authority, general database write, public listener |
| **Reach core** | turn policy; local task-scoped Sigil; read-only active corpus; typed Phylactery port | bot token, long-lived provider/peer bearer, arbitrary Internet, corpus staging |
| **Portal/A2A egress adapter** | exact provider/peer credentials and destinations; execute one egress-admitted attempt | bot token, Sigil, raw private Context, dynamic routing, general proxying |
| **Corpus refresher** | allowlisted public-source network; bounded staging; atomic snapshot publication | bot/provider/peer credentials, application records, content-directed network |
| **Local Phylactery** | Core Run/Ward/queue plus Reach records, outboxes, dedupe, checkpoints, and admitted migrations | public or Tether listener, home-database replication, ambient service access |
| **Intercom ingress, separate later profile** | hostile decode; peer authentication; replay fence; bounded durable inbox | bot/provider credentials, Discord delivery path, direct work or effect authority |
| **Veil, separate later profile** | TLS, canonical ingress, exact route and coarse limit | application bearer, database, corpus writer, delivery authority |
| **Tether, separate later profile** | exact WireGuard peer and routes | default route, application credential, authorization decision |
Each egress instance serves one provider/peer trust class with only its credential reference and short-lived occurrence grant. Core supplies payload and decision id, never Sigil or another bearer's credential.
Authenticate both ends of each local port using the manifest-pinned service Principals, credentials, audience, object/message types, expiry, replay fences, and receiver authorization. Discard identity supplied by the caller itself: loopback, shared bearers, DNS, and possession of a route establish no workload identity. This boundary must still reject cross-service impersonation when a non-owning service is compromised.
Firewall policy denies metadata/private-network egress except exact local service roads; later Tether needs another profile. This limits lateral movement without claiming resistance to root, operator-account, or VPS-control-plane compromise, which can expose all resident secrets and payloads.
## Public corpus contract
Reach judges source eligibility, interpretation, selection, and citations. Acquisition follows [Webcrawler](../../../adr/30-webcrawler.md#destination-and-data-boundary); a checkout or static site alone is no retrieval system.
Start acquisition from canonical HTTPS Git/static sources only. Refuse git/SSH/SCP/local/file origins, credential helpers, and ambient credentials. Bind the source to pinned paths, an operator-admitted commit or verified immutable release provenance, digests, builder/parser/index revisions, and file/byte/expansion/depth/work ceilings. A moving branch may reveal a candidate but cannot activate it.
Process that candidate without hooks, submodules, smudge/LFS, or content-directed network. Reject escaping symlinks, unsupported media, malformed encoding, and archive/parser bombs. Build the index offline and validate all staging before atomically activating the snapshot. If any stage fails, keep the previous snapshot.
Record the admitted source in `PublicCorpusSnapshot@1`, retaining source/revision/digests, accepted paths, tools, build receipt, activation, and freshness. Its passages remain attributed, instruction-fenced data. The snapshot's `fresh_until` is 24 hours after activation; after expiry, return `DEPENDENCY_UNAVAILABLE`. An explicitly historical question may instead use a separately admitted frozen historical source, with that revision displayed.
`CorpusEvidenceBundle@1` pins one snapshot, passage ids/digests, canonical URLs/sections, and retrieval/count/token/size limits. Only the bounded bundle can travel remotely. Missing, altered, or unbound citations refuse validation.
## Outbound A2A without an inbound edge
The first independent interoperability receipt pins one A2A 1.0 binding/adapter, enrolled peer, authentication, task, destination, and budgets. Advertised Agent Cards prove none of enrollment, authority, destination admission, or availability.
| Field | `reach.vps.public@1` A2A receipt |
| --- | --- |
| protocol | A2A `1.0`, HTTP+JSON binding, adapter and schema fixture digests pinned |
| peer | one pre-enrolled Principal, canonical HTTPS origin, Agent Card digest, server certificate identity, and task authorization named by the receipt |
| authentication | mutual TLS with distinct audience-bound client credential; no bearer in payload |
| task | `reach.public_corpus_answer@1`; one text query plus one `CorpusEvidenceBundle@1`; text/structured response only; files, artifact URLs, tools, teaching, and continuation refused |
| operations | non-blocking `POST /message:send` with `configuration.returnImmediately=true`, returning a Task, then `GET /tasks/{id}` only; a direct Message, stream, or push notification is outside this receipt |
| polling | every 2 seconds, at most 20 polls, 45-second absolute task deadline |
| ceilings | one task; 32 KiB request; 256 KiB response; eight evidence passages; 2,000-character query; profile-pinned token and spend ceilings |
| adoption | authenticated expected task/context identity, current peer authorization, first terminal, quarantine, schema/citation validation |
A2A 1.0 makes [Send Message idempotency optional](https://a2a-protocol.org/v1.0.0/specification/#331-idempotency); `messageId` alone does not prove deduplication. Before retrying an ambiguous initial POST, the receipt must admit the selected peer's guarantee that the exact same message and payload resolve to the original Task without duplicate work for that redelivery. Without that guarantee, preserve the uncertain task for reconciliation and do not resend. An admitted retry preserves the exact envelope and message/task identities; every physical attempt, including retries and polls, needs a fresh byte-time `EgressDecision` and consumes its transmission budget.
Replace each peer field with an observed independent endpoint; placeholders or same-process fakes prove conformance only. A model Portal is a separate E2E case under the same egress/attempt/quarantine/delivery law.
Commit the task/outbox before sending, then park in Durable Stasis while waiting. The baseline obtains updates through outbound response/polling and disables push callbacks. Authenticate and correlate each update against current authorization/revocation, and record the first authenticated protocol terminal. Even then, keep the returned content quarantined until validation and Composition adoption.
Preserve the distinction between `SUCCEEDED`, `REFUSED`, `FAILED`, `EXPIRED`, `REVOKED`, `CANCELLED`, and `LOST`. Silence alone establishes none of these outcomes and cannot authorize a blind repeat.
Map `TASK_STATE_COMPLETED`, `TASK_STATE_REJECTED`, `TASK_STATE_FAILED`, and `TASK_STATE_CANCELED` to their respective success/refusal/failure/cancellation. One-shot work refuses `TASK_STATE_INPUT_REQUIRED`/`TASK_STATE_AUTH_REQUIRED` without new credentials. Local deadline, current revocation, or irreconcilable loss settles expiry/revocation/loss with evidence.
| Profile | Exact boundary |
| --- | --- |
| **Callback-only client** | Veil may route a notification only to isolated Intercom ingress; it may update one existing outbound task after authentication, replay fencing, task/token correlation, current authorization, and durable admission. |
| **Full A2A server** | A distinct server profile needs Veil, Ward, Intercom durable inbox/outbox, Workers, quotas, and its own result path. A new peer task is not a Reach/Discord turn. |
An incoming peer task never creates a Discord delivery. Cards and task routes grant no foreign use of the bot identity.
## Destination and abuse boundary
Admit canonical HTTPS origin/port/path/purpose without ambient proxy or credentials. Reject loopback, private, link-local, multicast, unspecified, metadata, and mixed-resolution addresses. Pin the admitted address through connection; peer, TLS, SNI, and Host must match. Re-admit each redirect/new connection.
Before Core sees a return, the egress adapter bounds status/type, headers, wire/expanded bytes and ratio, chunks/count/size, stream/idle time, JSON depth/items, parsing/tokens, and total result. Violation closes response and returns dependency failure without further parsing.
Set limits on platform events per application/guild/channel/subject, as well as concurrency, evidence/results, and tokens/time/retries/spend. A later ingress profile must additionally bound pre-auth connections, headers/compressed/expanded bodies, signature work, per-IP/peer/route/global quotas, durable queues/streams, and CPU/memory/process/disk/connections. Apply those limits so overload cannot displace heartbeat, committed delivery, or recovery work.
## Retention and provider custody
These are maximums; shorter policy is allowed, longer retention needs a declared decision.
| Material | Maximum and retained form |
| --- | --- |
| raw Discord event/query | 24 hours after terminal; up to 7 days only while reconciliation is unresolved, then digest and minimum admission fields |
| caller/admission evidence | 30 days; partition, policy, decision and abuse facts without copied profile content |
| evidence bundle and every terminal turn | 30 days; structural terminal record plus exact selected public passages or their independently retrievable digests and refs |
| raw egress payload or quarantined return | 24 hours after terminal; up to 7 days for `INDETERMINATE`, then decision/result digests and receipts |
| delivery and external idempotency identities | 90 days; event/effect ids, payload digest, status, and Discord message id |
| edge address and coarse abuse log | 7 days, access-controlled and minimized |
| corpus snapshots | active plus previous generation; evidence retained with a turn remains separately bounded above |
Telemetry excludes raw prompts/passages/results, credentials, and pseudonym maps. Admit provider storage/training/region/subcontractor/deletion policy before egress; local deletion cannot erase its copies. Limits also cover replicas, exports, encrypted backups, VPS snapshots, journals, swap, and dumps. Disable raw payload/credential dumps/logs and encrypt or disable swap.
The manifest must choose a recovery policy: either disable backups and declare loss unrecoverable, or pin encrypted off-host backup/expiry/restore with an offline key. If Phylactery is lost, disable Reach until effects inside the idempotency horizon have been reconciled. Starting with an empty database proves nothing about old Discord/A2A effects. On decommission, destroy volumes and expire secondary copies.
## Restart, uncertainty, and compromise
On replay, return the committed admission/turn. A failed corpus refresh preserves the earlier snapshot with degraded freshness. Recover remote work according to what the attempt record proves: a proved pre-submit failure may create a new attempt/egress decision, while possible post-submit failure remains `INDETERMINATE` until reconciliation. Parked A2A survives through protocol identities/checkpoints, never SDK objects. An unknown Discord delivery needs independent evidence before any retry.
For a service compromise, revoke leases/credentials, quarantine output, mark tasks/deliveries as tainted, and preserve bounded secret-free correlation. A root/operator/VPS-control-plane compromise requires rebuilding the body. Stop Reach and withdraw routes/callback DNS/cards, then revoke every potentially exposed Discord/provider/A2A/Tether/Veil/ACME/operator/source/deployment credential. Mark and reconcile uncertain external effects before destroying and reprovisioning from a trusted pinned image.
Restore only independently verified non-secret records. Rebuild the corpus, issue disjoint credentials, and enroll from zero authority before returning the body to service.
## Acceptance gates
Tests cover identity/digest collision, replay/partition isolation, Cut/egress binding, destination/redirect rebinding, malicious corpus/path/parser and compressed/chunked/deep return cases, timeout at each commit, quarantine/revocation, restart/overload, and nonce/claim expiry without duplication.
To assess the deployed body, the live-host receipt must identify source/images, OS/systemd/Podman/users, manifest/compiler, units/mounts, local mTLS Principals/credentials and impersonation refusals, network/firewall/DNS, secrets/resources, corpus, Mirror/Ward, and external adapters. It must also account for reboot, secret isolation, backup/restore or loss, reconciliation, shutdown, and clean rebuild/rotation. Only the evidence owners and State can use that evidence to promote delivery.
[Deployment matrix](index.md) · [Reach turn](../turn.md)
---
title: "Avatar"
plain_name: "App: Avatar (appearance across places)"
section: "Compositions > Presence & Embodiment"
status: "Designed"
original: https://hexanomicon.dev/compositions/avatar/
guide: https://lychd.snayu.ai/docs/compositions/avatar/
---
# Avatar (App: Avatar (appearance across places))
## Plain-English summary (Snayu)
**What it is:** An app that keeps the Assistant's chosen appearance (look, voice, motion) consistent and attributable across places like VR and Minecraft, recording what each place reported.
**Why it matters:** Read this before working on how the Assistant is presented visually or by voice in games, VR or devices.
- A profile defines the allowed presentation; a Morphe selects one form within it.
- Each place gets its own projection record and reports its own result.
- Avatar grants no identity change, device ownership or authority to act in a world.
**Status:** Designed. Contract only; no implementation path enabled.
## Original text (Hexanomicon)
One Lich can appear in a VR room while a Blockworld inhabitant continues elsewhere. Avatar keeps the presentation attributable across those places: which Persona and eligible form appeared, which projection was admitted, and what each target reported when it ended.
An eligible profile supplies the presentation envelope; a Morphe selects a form inside it. Separate target bindings carry the appearance through interruption and partial settlement. The Lich, its Persona, memory, and each target's effects remain with their owners.
## Contract
The work progresses through composing an eligible profile, binding a form, and projecting its presence. `avatar.presence` revision `2` publishes `avatar.compose_profile@2`, `avatar.bind_morphe@2`, and `avatar.project_presence@2` for those purposes. Results are immutable `AvatarProfile@2`, `MorpheBinding@2`, `AvatarPresence@2`, and per-target `ProjectionBinding@2` records/receipts, or exact partial/non-completion.
Those records grant no identity change, unbounded ambient presence, target-world/device ownership, unobserved delivery/motion claim, or physical/virtual effect authority.
## Follow the appearance
| You want to understand… | Continue with… |
| --- | --- |
| what is selected, and what is bound to a target | [the profile](profile.md) and [projection epochs](presence.md#admit-each-projection) |
| how a new form remains the same Persona | [selecting a Morphe](profile.md#select-a-morphe) |
| how separate places can share a presentation | [mirrored and parallel presence](presence.md#one-lich-many-projections) |
| what happens when one place disappears | [the interrupted greeting](presence.md#follow-the-interrupted-greeting) |
| what a projection may claim about a world or body | [each target's boundary](presence.md#target-truth-stays-local) |
| how this design could first be proved | [independent settlement](presence.md#proving-independent-settlement) and [revision continuity](profile.md#a-changed-form-starts-new-work) |
[Identity](../../adr/32-identity.md) · [Composition Portfolio](../index.md)
---
title: "Profile and Morphe"
plain_name: "Avatar: Profile and form selection"
section: "Compositions > Presence & Embodiment > Avatar"
status: "Designed"
original: https://hexanomicon.dev/compositions/avatar/profile/
guide: https://lychd.snayu.ai/docs/compositions/avatar/profile/
---
# Profile and Morphe (Avatar: Profile and form selection)
## Plain-English summary (Snayu)
**What it is:** How an avatar profile bundles visual, voice, motion, locale and disclosure references for one persona, and how a Morphe picks a style within it without changing who the persona is.
**Why it matters:** Read this before adding avatar looks, voices or forms, especially anything resembling a real person.
- The profile is tied to an exact persona revision and records provenance and licence limits.
- A Morphe (e.g. a cat or game character) cannot claim separate memory, authority or personhood.
- Likeness and voice need explicit consent, licence and revocation; resemblance grants nothing.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
The Lich may wear a stylized character in one place and use a different eligible voice in another. The change begins with a presentation envelope tied to an exact Persona; it cannot rewrite who that Persona is.
## Compose the eligible envelope
`avatar.compose_profile@2` begins with an eligible Persona revision and exact visual, acoustic speech-voice, motion, output-locale, disclosure, and fallback references. Its immutable `AvatarProfile@2` retains their provenance and licence limits. It specifies eligibility and defaults, not a live target, translated text, or evidence that every facet has been rendered.
[Mirror](../../sepulcher/extensions/mirror.md) owns Persona identity, discourse manner, orientation, commitments, and lineage. The [media ownership comparison](../choosing-a-home.md#media-owners-do-not-follow-file-extensions) follows visual, acoustic, musical, and timed-language sources; [Kinesis](../../sepulcher/extensions/prism/kinesis.md) retains technical motion. Avatar references those exact revisions and judges the coherence of the assembled presentation for its intended targets.
## Select a Morphe
`avatar.bind_morphe@2` returns `MorpheBinding@2`: one immutable selection of presentation style and already eligible output locale within that profile. Bind audience, target class, purpose, time window, disclosure, compatibility, and fallback. Appearance, acoustic voice, and animation can vary within the admitted envelope; the profile itself remains unchanged.
A cat, game character, or performer-inspired form may be a **Morphe** of the same Lich. It cannot claim separate memory, commitments, relationships, authority, or personhood. A requested change crossing those boundaries is refused by Avatar and needs an explicit Persona revision or distinct Persona from Mirror. Resemblance grants no performer authority; likeness and voice retain exact consent, licence, provenance, disclosure, and revocation.
To choose a voice, first identify what is being chosen. Persona voice means discourse and orientation; acoustic voice means Echo capability or a synthesized artifact. Riffmaw owns singing, and Language Edition owns spoken timed performance. A Morphe narrows use of an eligible reference without manufacturing or upgrading any of these.
The same distinction applies to language. Output locale selects wording already localized by its content owner or Language Edition. Morphe neither translates that wording nor changes discourse manner.
## A changed form starts new work
The current identity is `avatar.presence` revision `2`. Its `@2` Pattern/record family supersedes revision `1`, replacing ambiguous manner/language wording with presentation style and eligible output locale. No registry or Run used revision `1`; its meaning remains historical without executable migration.
When form, source eligibility, consent, audience, or disclosure changes, preserve what the existing binding admitted. [Presence](presence.md) either closes the affected projection under its policy or admits a fresh compatible epoch; it cannot rewrite an open or historical binding. Revocation likewise requires an explicit response. It never triggers silent substitution of a similar face, voice, motion, or body.
Continue to [Presence](presence.md) to project the profile into separately admitted targets, or return to [Avatar](index.md).
---
title: "Presence across places"
plain_name: "Avatar: Presence across places"
section: "Compositions > Presence & Embodiment > Avatar"
status: "Designed"
original: https://hexanomicon.dev/compositions/avatar/presence/
guide: https://lychd.snayu.ai/docs/compositions/avatar/presence/
---
# Presence across places (Avatar: Presence across places)
## Plain-English summary (Snayu)
**What it is:** How Avatar admits a separate projection for each place (VR room, game world), supports mirrored or parallel presence, and handles one place dropping out without inventing its state.
**Why it matters:** Read this when designing multi-place appearances or what happens when one target disconnects.
- Each projection binds one target epoch with its own consent, capabilities and result.
- Mirrored means one act shown in several places; parallel means separate tasks with the same persona.
- Coordinated stop, wait or recovery across places needs an App Bundle (Suite), not Avatar.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
The greeting reaches a VR room and a Blockworld inhabitant. Each place must report what happened there. If the headset runtime disappears, a continuing Blockworld mission does not prove the missing VR experience continued too.
## Admit each projection
`avatar.project_presence@2` begins with an immutable `AvatarProfile@2`, participant and target references, exact capability snapshots, synchronization policy, consent/privacy, budgets, and stop conditions. An optional `MorpheBinding@2` selects an eligible form for the target.
`ProjectionBinding@2` admits one target epoch with profile/Morphe, target capability receipt, participants, consent, disclosure, fallback, stops, and attributed terminal result. It records membership in Avatar's presence, without owning the target world, device, Invocation, provider session, or effects. Changed form, capability set, target epoch, participants, consent, or disclosure closes or replaces the affected binding according to its declared policy.
`AvatarPresence@2` brings these Avatar-owned bindings together for one purpose. It identifies required/optional members, presentation-synchronization intent, local ceilings, and the policy for evaluating attributed target results. This gives Avatar an account of the presentation. A [Suite](../products-and-suites.md) must own any promised live coordination: Avatar itself cannot initiate, admit, await, cancel, retry, recover, or correlate the lifecycle of target-owned Invocations.
## One Lich, many projections
Two closed modes keep shared presentation distinct from shared execution:
- **mirrored** declares one attributed semantic act for presentation in separately admitted targets; each target performs its own work and returns its own delivery/effect receipt;
- **parallel** permits distinct bounded target Invocations with the same Persona revision but separate Context, authority, chronology, observations, and outcomes.
Neither proves a universal session or indivisible field of attention. A projection can join, downgrade, refuse, disconnect, or finish without inventing another's state. Avatar judges only results made available to its bindings:
| Result | Meaning |
| --- | --- |
| **completed** | Every required binding returned an eligible attributed terminal result. |
| **partial** | Policy permits the exact settled subset and names absent, refused, interrupted, or still-running members. |
| **refused** | Presence or a required binding failed admission before beginning. |
| **unresolved** | A required outcome is unknown or cannot be reconciled without guessing. |
## Follow the interrupted greeting
Compose the exact profile and target-scoped Morphe. Spectre and Blockworld independently admit a VR Habitat and mission; Avatar declares required projections and mirrored/parallel policy, then creates separate binding epochs.
A participant meets the Lich in a Spectre Encounter. The greeting may also appear in Blockworld, but its separate receipt proves only the world-local result. When XR is lost, Spectre records interruption or offers explicit recovery. Avatar settles the VR binding only from Spectre's attributed result. Blockworld keeps its own mission and authority.
If Spectre re-admits recovery, Avatar can close or link the old VR epoch and open a fresh binding under recovered facts. Otherwise it remains interrupted. Avatar does not wait for or stop the world mission; it evaluates available results. A Product promising coordinated stop, wait, or recovery must pin a Suite.
## Target truth stays local
Each target keeps the authority needed to judge what happened there:
| Target owner | Retained truth and authority |
| --- | --- |
| [Reach](../reach/index.md) | Social events, audience, platform delivery, and replies. |
| [Blockworld](../blockworld/index.md) | World epoch, inhabitant, mission, inventory, lease, and effects. |
| [Spectre](../spectre/index.md) | Habitat, Encounter, comfort, interruption, and exit. |
| [Homestead](../homestead/index.md), for a room display | Place policy, bystanders, indicators, purpose, and controls. |
| Vehicle controller | Occupants, safety, motion, and local override. |
| [Familiar](../familiar/index.md) | Body, capabilities, geofence, emergency stop, mission, observations, and effects. |
| [Companion](../companion/index.md) | Mobile session, privacy, disclosure, configuration, reconnect, and separate stop-speaking/cancel-session controls over an admitted Familiar phone body. |
For VR, Avatar binds to an exact `VRHabitat@1` and may select eligible head, hands, body, voice, motion, captions, disclosure, and fallback. The target retains authority over the XR session/reference space, locomotion, haptics, tracking capture, entry, and exit.
Tracking tells Avatar which presentations are eligible. Head/hand/gaze/face/body signals prove no identity, intent, attention, emotion, consent, co-location, or remembered experience. Keep raw high-rate inputs with the engine/runtime; Avatar retains only minimum capability facts and semantic results.
## Proving independent settlement
A network-disabled synthetic profile appears in mock text/voice, Blockworld, Spectre, and Familiar adapters. Prove mirrored/parallel modes, one-target refusal, downgrade, Morphe change, disconnect/restart, consent revocation, partial settlement, export, and deletion. Public platforms, real performer clones, headsets, drones, vehicles, and robots are outside the fixture.
A later Avatar Studio Product may package customization/preview. Packaging and Suites do not move target authority into Avatar. Return to [Avatar](index.md).
---
title: "Spectre"
plain_name: "App: Spectre (VR meetings)"
section: "Compositions > Presence & Embodiment"
status: "Designed"
original: https://hexanomicon.dev/compositions/spectre/
guide: https://lychd.snayu.ai/docs/compositions/spectre/
---
# Spectre (App: Spectre (VR meetings))
## Plain-English summary (Snayu)
**What it is:** The VR app: it admits a virtual place (VR Habitat) and runs one bounded meeting (Encounter) with participants, consent, events, interruption and exit.
**Why it matters:** Read this before any VR work, to understand what Spectre owns versus Avatar and the VR runtime.
- Two operations: admit a VR place, and enter a bounded encounter in it.
- Outcomes are completed, safely exited, interrupted, refused or unresolved.
- Spectre does not own the world build, headset, raw tracking data or the avatar.
**Status:** Designed. Contract only; first hardware integration is a hypothesis.
## Original text (Hexanomicon)
A compelling apparition still needs a door through which its visitors can leave. Spectre is the Virtual Reality Composition: it admits a virtual place as `VRHabitat@1`, then keeps one bounded **Encounter**—participants, purpose, consent, significant events, interruption, and exit—inside it.
The name follows _spectre_, an appearance or apparition. The experience can matter without becoming Persona identity, physical truth, or authority. An Avatar may present the Lich there; Avatar retains presentation and binding membership while Spectre keeps the place and meeting.
## Contract
Use `spectre.admit_habitat@1` to admit the place and `spectre.enter_encounter@2` for the bounded meeting; both belong to `spectre.virtual_reality` revision `2`. The result is immutable `VRHabitat@1` or settled `SpectreEncounter@2`, with an outcome of completed, safely exited, interrupted, refused, or unresolved.
These results do not take ownership of world authorship, persistent-world effects, headset/runtime, raw tracking archives, or Persona/Avatar. Generic multiplayer, public release, and claims of physical presence also remain outside the contract.
## From place to meeting
| You want to understand… | Continue with… |
| --- | --- |
| what makes this place eligible, and this meeting distinct | [Habitat binding](habitat.md#bind-the-place-and-its-capabilities) and [Encounter admission](encounter.md#admit-this-meeting) |
| how different people can enter, participate, and leave | [admitted modalities](habitat.md#admit-the-space-the-participant-will-use) and [each participant's departure](encounter.md#each-participant-may-leave) |
| what survives a lost runtime | [runtime state and experienced events](encounter.md#runtime-state-and-experienced-events) |
| how a greeting can end or recover | [settling what happened](encounter.md#settle-what-happened) |
| where the first experiment begins | [hardware/runtime hypotheses](habitat.md#first-integration-hypothesis) and [contract proof](encounter.md#first-proof-and-revision-continuity) |
[Composition Portfolio](../index.md) · [Avatar](../avatar/index.md) · [Foundry](../foundry/index.md)
---
title: "Admitting a VR Habitat"
plain_name: "Spectre: Admitting a VR place"
section: "Compositions > Presence & Embodiment > Spectre"
status: "Designed"
original: https://hexanomicon.dev/compositions/spectre/habitat/
guide: https://lychd.snayu.ai/docs/compositions/spectre/habitat/
---
# Admitting a VR Habitat (Spectre: Admitting a VR place)
## Plain-English summary (Snayu)
**What it is:** How a VR place is checked and recorded: exact world build, runtime capabilities, seated or room-scale space, comfort, accessibility and a visible exit.
**Why it matters:** Read this before building the VR integration or deciding hardware and engine targets.
- Missing required capabilities refuse admission; missing optional ones are recorded as downgrades.
- OpenXR 1.1 is the protocol baseline; Godot with a standalone Quest 3 app is the first candidate.
- Minimum: stereo view, head pose, tested input, explicit reference space, visible exit, runtime-loss handling.
**Status:** Designed. Design and integration hypothesis only.
## Original text (Hexanomicon)
A participant may need a seated experience with captions; another may require a bounded room-scale space. Habitat admission establishes which exact virtual place can support the requested experience and how it must make exit available.
## Bind the place and its capabilities
`spectre.admit_habitat@1` begins with exact world/scene reference, engine/runtime capability snapshot, reference-space policy, comfort, accessibility, retention, and exit policy. It returns immutable `VRHabitat@1` or refusal.
Tie the Habitat record to an exact world/build and capability epoch. Record the adapter/runtime revision, requested, required, granted, missing, and revoked features, and the admitted spatial context/reference-space policy. Bind comfort/accessibility, retention, disclosure, and exit to that same admission. The record describes the eligible place without taking ownership of its source project, engine build, headset, reference-space handle, multiplayer service, or persistent world.
Refuse admission if a required capability is missing; record an explicit downgrade for an optional one. The label “VR” cannot establish hands, haptics, room bounds, eye/face tracking, passthrough, anchors, or body tracking. If the world/build digest, required features, reference-space, comfort/accessibility, retention, or exit contract changes, require a new Habitat revision or epoch. A runtime restart alone must not rewrite the admitted Habitat.
## Admit the space the participant will use
[OpenXR reference spaces](https://registry.khronos.org/OpenXR/specs/1.1/man/html/XrReferenceSpaceType.html) distinguish view-relative, seated/local, floor-relative, and room-scale arrangements. Pin required floor/stage bounds, recenter and reference-space-change policy, permitted locomotion, and downgrade/refusal when the runtime cannot supply them. Runtime handles and observed bounds remain volatile provider facts.
Seated, standing, captioned, controller-free, companion-screen, and audio-led routes enter only when explicitly supported. An Encounter records each person's actual modality. A flat/audio companion route can support access without claiming equivalent spatial tracking, reference space, haptics, privacy, or embodiment. Every admitted modality must preserve visible exit and its declared recovery path.
[Foundry](../foundry/index.md) may supply an exact world/build/profile and playtest evidence; it retains project, controllers, derivatives, build judgment, and playability. Blockworld keeps persistent-world effects, and [Reach](../reach/index.md) keeps external social events, audience, platform delivery, and replies. Avatar may independently bind a Lich presentation to the Habitat, without owning runtime, locomotion, tracking, or entry.
Prism and [Kinesis](../../sepulcher/extensions/prism/kinesis.md) retain spatial and motion sources. The [media ownership comparison](../choosing-a-home.md#media-owners-do-not-follow-file-extensions) follows separately admitted speech, music, dialogue, and sound handoffs; a shared VR runtime does not merge their judgments.
## First integration hypothesis
The design uses [OpenXR 1.1](https://registry.khronos.org/OpenXR/) as protocol baseline; an adapter still enumerates the actual runtime and extensions. Its first engine candidate is [Godot](https://docs.godotengine.org/en/4.7/tutorials/xr/setting_up_xr.html), with a standalone Quest 3 application as the smallest hardware hypothesis. [WiVRn](https://github.com/WiVRn/WiVRn) and [Monado](https://monado.freedesktop.org/) remain later Linux/FOSS-first candidates; SteamVR/vendor runtimes are optional compatibility profiles. These are hypotheses, not newly proved hardware compatibility.
The minimum profile requires stereo view, head pose, a tested action/input profile, explicit reference space, visible exit, and runtime-loss handling. Additional tracking, passthrough, anchors, haptics, and room bounds remain optional and honestly absent when unavailable. Revision one's scope did not promise multiplayer, persistent social worlds, full-body embodiment, eye/face tracking, mixed-reality mapping, or a production hardware profile.
Continue with [Encounter](encounter.md) for participants, chronology, interruption, and exit, or return to [Spectre](index.md).
---
title: "Entering and leaving an Encounter"
plain_name: "Spectre: Entering and leaving a meeting"
section: "Compositions > Presence & Embodiment > Spectre"
status: "Designed"
original: https://hexanomicon.dev/compositions/spectre/encounter/
guide: https://lychd.snayu.ai/docs/compositions/spectre/encounter/
---
# Entering and leaving an Encounter (Spectre: Entering and leaving a meeting)
## Plain-English summary (Snayu)
**What it is:** How one VR meeting is admitted, how runtime events (focus loss, revoked tracking, disconnects) are recorded, how each participant can leave, and how the meeting is settled.
**Why it matters:** Read this when designing VR session handling, consent tracking or exit behaviour.
- A meeting binds a VR place, participants, purpose, consent and optionally an avatar projection.
- Runtime events are evidence only; they do not prove attendance, understanding or consent.
- Changes in participants, purpose or consent require fresh admission.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
The participant enters an admitted VR Habitat to meet the Lich. Later the runtime loses focus, a tracking permission is revoked, or the headset connection disappears. An Encounter keeps those events attributable and ends according to what can actually be observed.
## Admit this meeting
`spectre.enter_encounter@2` begins with exact `VRHabitat@1`, participants, purpose, consent, and—when meeting the Lich—an already admitted Avatar `ProjectionBinding@2` for that Habitat. A generic Encounter needs no Avatar. Spectre may report the target result but cannot create, revise, replace, or close Avatar's binding.
Follow the meeting in `SpectreEncounter@2`: retain participant/entry admission, purpose, Habitat revision, consent chronology, optional Avatar reference, significant semantic interactions, focus/pause/recenter, interruption/recovery, exit, and terminal judgment. If participants, purpose, consent scope, or Avatar binding change, require fresh admission or an explicit recovery boundary. The Habitat can support many such Encounters while each meeting remains finite.
```mermaid
flowchart TD
F["Foundry world/
build reference"] --> H["VRHabitat@1"]
C["Capabilities ·
reference space ·
comfort · exit"] --> H
H --> E["SpectreEncounter@2"]
P["Participants ·
purpose · consent"] --> E
A["Avatar
ProjectionBinding@2 ·
optional"] --> E
R["Volatile runtime
session facts"] --> E
E --> T["Attributed
terminal settlement"]
T --> AS["Avatar settles
its binding
separately"]
```
## Runtime state and experienced events
The [OpenXR lifecycle](https://registry.khronos.org/OpenXR/specs/1.1/man/html/XrSessionState.html) describes readiness, visibility, focus, stopping, pending loss, and exit. Spectre records attributed events such as `runtime_ready`, `input_suspended`, `exit_requested`, `runtime_stopping`, and `runtime_lost`. These observations prove neither attendance, perception, consent, understanding, nor memory.
An `XrSession`, game process, socket, device handle, or pose stream remains volatile provider state. Preserve runtime version, session-state changes, selected space kind, capabilities, start/stop/loss, and session epoch as observations. They cannot replace durable Encounter identity.
When the runtime reports `XR_SESSION_STATE_LOSS_PENDING` or equivalent loss, open an interruption. Policy must either settle it or offer explicit recovery by enumerating capabilities again, rechecking purpose/consent, and creating and linking a fresh provider epoch. A runtime `EXITING` request ends the XR road without automatic restart. Do not fabricate rendering or input across the gap.
## Each participant may leave
Participants independently pause, recenter, leave, or revoke consent. Departure removes that person; continuation requires the remaining participants, purpose, consent, and comfort policy to permit it. A required participant's departure can settle the whole Encounter as safely exited or interrupted.
The admitted modality determines what each person actually received. Optional tracking revocation removes or degrades the feature under policy. If the remaining mode no longer meets purpose or comfort requirements, expose exit and settle instead of inventing an equivalent experience.
Safe exit means following the declared local pause, disclosure, handoff, and exit protocol and settling observed results. It guarantees neither physical safety, device behavior, comfort for every body, nor unseen effects. [WebXR's privacy model](https://www.w3.org/TR/webxr/#security-privacy-and-comfort-considerations) motivates retaining semantic events and minimum capability facts rather than raw tracking archives.
Head/hand/gaze/face/body/room-mesh/camera/microphone/device-id/per-frame streams remain volatile in the admitted runtime or separately governed owner. They are never used to infer identity, attention, affect, intent, consent, co-location, or remembered experience. Spectre receives no ambient engine console, filesystem, tracking database, microphone, world mutation, or body authority.
## Settle what happened
Return `completed`, `safely_exited`, `interrupted`, `refused`, or `unresolved`, with exact externally owned Avatar/world/audio/effect receipts. No terminal can claim that every frame, gesture, utterance, or external effect occurred.
In the reference journey, the Habitat admits required features and records optional downgrade; Avatar independently supplies its binding. The participant enters through a declared immersive or companion modality. Spectre records pause, focus, recenter, reference-space changes, consent and semantic events. Tracking revocation may narrow participation or lead to exit. Runtime loss then either settles interruption or receives explicit fresh-epoch recovery. Avatar separately settles its projection from that attributed result.
## First proof and revision continuity
A network-disabled synthetic fixture admits seated, separate bounded room-scale, and companion-screen Encounters, with a static or head-and-hands Avatar. Prove required-feature refusal, optional downgrade, focus loss, recenter/space change, participant exit, consent revocation, visible exit request, abrupt loss, new-epoch recovery, export, and deletion. It proves no hardware compatibility, universal comfort, content quality, multiplayer, physical safety, or delivery.
`spectre.virtual_reality` revision `2` replaces revision `1` for Lich encounters: `spectre.enter_encounter@2`/`SpectreEncounter@2` consume Avatar's corrected `ProjectionBinding@2`. Habitat admission and `VRHabitat@1` stay unchanged. No registry or Run used revision `1`; historical references retain meaning without executable migration.
Return to [Spectre](index.md).
---
title: "Familiar"
plain_name: "App: Familiar (physical bodies)"
section: "Compositions > Presence & Embodiment"
status: "Designed"
original: https://hexanomicon.dev/compositions/familiar/
guide: https://lychd.snayu.ai/docs/compositions/familiar/
---
# Familiar (App: Familiar (physical bodies))
## Plain-English summary (Snayu)
**What it is:** An app for physical bodies such as drones, rovers, robots and phones: it admits a body's exact capabilities and stop path, then runs bounded missions like following a person, keeping observations and effects attributable.
**Why it matters:** Read this before any robotics or device-control work.
- First admit the body (controller, capabilities, safety limits, geofence, emergency stop), then run missions on it.
- Excludes weapons, non-consensual following, restricted airspace and any universal physical authority.
- Each form factor needs its own admitted controller or device profile.
**Status:** Designed. Contract only; no supported hardware.
## Original text (Hexanomicon)
A body can carry a voice, follow an admitted subject, or perform a bounded task. Familiar keeps the physical body's capabilities, local limits, observations, and consequences attributable. The name recalls a _familiar_ as a bound companion spirit: serving one Lich does not make the chassis its identity or grant power over the physical world.
Body admission establishes the exact capabilities and independent stop path. A finite follow mission then carries its subject designation through loss, speaking presence, and settlement. Cars, drones, rovers, legged robots, manipulators, phones, cards, displays, and other explicit forms need their own admitted controller or device profile.
[Robotic Dance](dance.md) sketches a candidate use case: wear motion trackers and lead physical
familiars in a shared dance, with research references and a possible Live Kinesis integration.
## Contract
`familiar.embodiment` revision `3` publishes `familiar.admit_body@3`, `familiar.bounded_mission@3`, and `familiar.follow@3`. Additional body-specific Patterns may be admitted without changing the body contract.
First admit the body by binding its exact controller/device attachment, form, capability snapshot, safety envelope, relevant geofence, and emergency-stop policy. A mission can then use that immutable `FamiliarBody@3` with an objective kind, subject/target designation, budgets, stops, and optional Avatar `ProjectionBinding@2`. The records distinguish admitted body from performed work: results include `FamiliarBody@3`, settled `FamiliarMission@3`, `FamiliarObservation@1`, `FamiliarEffect@1`, and exact partial/non-completion.
Familiar excludes weaponization, non-consensual following, unadmitted private-property or restricted-airspace entry, operation beyond signal range without admitted return policy, inferred identity/consent from proximity, and universal physical authority.
## Records and lifecycle
Familiar retains the body binding and capability epoch, then follows the mission through objectives, constraints, observation chronology, effects, and final judgment. It relies on other owners for enrollment/credentials, hardware, firmware, motor drivers, PID loops, client implementation, and live control handles; enrollment/credentials specifically remain with the attachment owner. A MAVLink connection, ROS2 node, PWM signal, or sensor stream cannot replace durable mission identity.
The control link contributes observed protocol version, link quality, controller health, firmware revision, start, stop, and loss, tied to its provider epoch. Recovery reads those facts alongside the body journal and mission record; a reconnected handle alone cannot establish what the body did during the gap.
For phones, [Ward enrollment precedes Familiar body admission](embodiment.md#body-admission), which precedes Companion's device/session. Both Compositions retain the exact Ward references. Remote bodies may instead attach through Legion; neither route is universal Familiar law.
## Orthogonal axes, one Lich
```mermaid
flowchart TB
subgraph W["World / body target axis · examples, not an exhaustive set"]
S["Spectre · VR Habitat / Encounter"]
B["Blockworld · game world / mission"]
F["Familiar · physical body / mission"]
end
subgraph P["Presentation / interaction axis"]
A["Avatar · presentation / projection membership"]
C["Companion · mobile client / device session"]
end
A -. "optional projection" .-> S
A -. "optional projection" .-> B
A -. "optional projection" .-> F
F -->|"exact admitted phone body"| C
A -. "optional presentation through phone" .-> C
```
These examples are not exhaustive realms. [Avatar](../avatar/index.md) chooses eligible presentation across targets; each target owns what happens there. [Companion](../companion/index.md) owns an independent mobile interaction/session over a phone-shaped Familiar. New capabilities need not distort this map into a closed cosmology.
## Core capability before packaging
A Product may package Familiar, Companion, and Avatar, and a Suite may coordinate their live work. Neither moves body, mission, or safety authority into the client. Familiar does not require a current packaged application.
The first network-disabled mock body supplies simulated GPS, IMU, camera, mic, speaker, battery, recorded path, obstacle, speaking transition, and low-battery landing evidence. It proves the follow/settlement contract, not flight dynamics, actual avoidance, or hardware compatibility. No real drone, vehicle, public airspace, or non-consenting subject enters it.
Revision `3` supersedes revision `2` by naming exact Ward phone enrollment and advancing body admission/`FamiliarBody` to `@3`. Revision `2` had replaced revision `1`'s universal Legion precondition with owner-qualified attachment. Mission/follow and `FamiliarMission` advance to `@3` for the new body and Avatar bindings. No registry or Run used those retired revisions; history remains unchanged without executable migration.
## Enter by question
[Embodiment](embodiment.md) asks which body and capabilities can be admitted.
[Follow](follow.md) carries one subject designation through a finite mission, loss, and return.
[Robotic Dance](dance.md) explores the candidate use case of shared physical movement.
Return to the [Composition Portfolio](../index.md) for other settings in which the Lich may act.
---
title: "Embodiment"
plain_name: "Familiar: Admitting a physical body"
section: "Compositions > Presence & Embodiment > Familiar"
status: "Designed"
original: https://hexanomicon.dev/compositions/familiar/embodiment/
guide: https://lychd.snayu.ai/docs/compositions/familiar/embodiment/
---
# Embodiment (Familiar: Admitting a physical body)
## Plain-English summary (Snayu)
**What it is:** How a specific physical body is admitted with its exact hardware, sensors, actuators, operating limits and stop behaviour, with example considerations for drones, rovers, legged robots, phones and cars.
**Why it matters:** Read this before integrating any physical device or robot controller.
- Missing required capability refuses admission; changed hardware or firmware creates a new body revision.
- A phone must first be enrolled by the Security Desk (Ward) before Familiar admits it.
- The local controller keeps fast motion and safety; example forms are not tested builds.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
A phone, a wheeled body, and an airborne body cannot share one emergency action. Embodiment admits the exact capabilities and commissioned local behavior that make a particular body eligible for a bounded task. A form-factor name is only orientation.
## Body admission
Begin with an already admitted controller or device attachment. `familiar.admit_body@3` checks that attachment and returns immutable `FamiliarBody@3`. Legion may own remote enrollment/reservation, while a bounded local adapter may own another controller binding.
For a phone, Ward must first supply the device/application `Principal`, revocable `Credential` and generation, current object-scoped `Authority Grant`, and policy generation. Familiar can then admit the body. Companion opens its device/session afterwards; no prior Companion record is needed.
The body record pins:
- attachment owner, typed identity, revision/epoch, credential generation, fencing, and local/remote road;
- admitted form factor and exact make/model, hardware and controller revisions;
- requested, required, granted, missing, and revoked sensor/actuator capabilities;
- commissioned operating limits, relevant geofence, altitude/speed/battery/terrain limits where applicable;
- autonomous stop triggers, independently reachable manual override, form-specific stopped/contained state, and recovery policy.
Missing required capability refuses admission. Optional absence is a recorded downgrade. A changed hardware, firmware, attachment, or safety envelope creates a new body revision; no running mission wakes to a silently widened body.
## Example forms
These comparisons name the contracts a future profile must close, not tested builds, shopping recommendations, operating limits, or safety certification.
### Drone
An airborne profile must prove its exact flight-controller/companion-computer road, positioning, motion and altitude envelope, obstacle policy, battery/signal behavior, permitted geography, and locally executable recovery. Pixhawk-class, ArduPilot, PX4, and MAVLink are possible controller/mechanism references, not interchangeable or admitted implementations. The controller must distinguish actions that maintain controlled flight from disarm and other terminal actions; a generic immediate motor stop is no universal emergency policy.
### Rover
A wheeled/tracked profile must prove steering, braking/holding, slope/terrain, obstacle and water-crossing policy, local positioning, power, override, and loss recovery. ESP32, Arduino, or SBC examples grant no compatibility or Node Agent capability without an exact profile. The body's stop state must account for its actual mechanics and environment.
### Legged
A legged profile must close gait/posture, joint/load limits, falls, terrain/stairs, self-righting, local sensing, and recoverable stop behavior. Neither a ROS2 route nor a marketed robot name proves stair capability or that freezing its motors is safe.
[Robotic Dance](dance.md) explores human-led motion imitation as a candidate task for such bodies.
### Manipulator, phone, card, and display
Locomotion is optional. A manipulator or personal presentation device still needs an exact capability snapshot, bounded effect vocabulary, local safety envelope, and reachable stop. A phone may host [Companion](../companion/index.md), while Familiar keeps its physical capability and stop truth. These forms inherit no vehicle or flight authority.
### Car and other vehicles
The vehicle profile retains occupants, route/motion envelope, controller, local override, and emergency policy. Familiar receives semantic tasks and attributed receipts without raw steering, throttle, brake, or actuator authority.
## Capability admission is honest
Capabilities must be proved by the attachment/profile rather than inferred from make or form. Positioning may use `gps`, `optical_flow`, `wheel_odometry`, or another admitted local reference. `obstacle_avoidance` and `lidar` require exact detection/control and failure evidence. `rgb_camera` or `thermal_camera` can support declared observation or subject designation, without proving identity or consent.
`microphone` permits only separately admitted Echo capture/transcription and authorized activation. `speaker` permits admitted playback, alerts, or Avatar voice presentation. Missing capabilities narrow eligible missions or produce the required refusal; another sensor is not a silent equivalent.
## One body, many missions
Every `FamiliarMission@3` pins the body revision. Broken or withdrawn capabilities remain visible; required ones block new missions and affect live work according to its stop/downgrade policy. An eligible body may host many finite missions without becoming an endless control session.
## The body decides what fits
The exact controller owns fast motion loops, actuation, and local safety interrupts. Familiar issues admitted semantic waypoint/task intents and receives receipts, never prompt-produced `motor_pwm=1400` or generic actuator commands.
The body must enforce its admitted stop policy locally without a LychD round trip, including when it cannot reach LychD. An admitted Legion node carries that responsibility on its route; local/mobile attachments must prove their equivalent. When the link is lost, the commissioned body-specific policy decides the response. Hover, land, brake, disarm, or freeze cannot serve as a universal instruction. Before re-entry, observe the controller's actual state and satisfy the profile's recovery admission.
Continue with [Follow](follow.md), or return to [Familiar](index.md).
---
title: "Follow"
plain_name: "Familiar: Follow mission"
section: "Compositions > Presence & Embodiment > Familiar"
status: "Designed"
original: https://hexanomicon.dev/compositions/familiar/follow/
guide: https://lychd.snayu.ai/docs/compositions/familiar/follow/
---
# Follow (Familiar: Follow mission)
## Plain-English summary (Snayu)
**What it is:** A bounded mission where a body follows a designated, consenting person along a path, pauses to talk, handles obstacles and signal loss, and reports exactly where it stopped.
**Why it matters:** Read this when designing following behaviour, speaking mode or safety envelopes for a physical body.
- All physical limits come from the commissioned body profile; there are no universal safe defaults.
- Speaking mode opens a disclosed capture window and closes it before following resumes.
- A synthetic fixture with a mock body is the representative proof journey.
**Status:** Designed. Contract and synthetic proof plan.
## Original text (Hexanomicon)
A finite follow mission begins with an explicitly designated, consenting subject and a body proved fit for the task. It can track a path, pause for speaking presence, and report exactly where work stopped. `familiar.follow@3` owns that semantic journey while the local controller keeps the fast motion and safety loop.
## Admission
Before movement, bind the mission to `FamiliarBody@3`, its confirmed capability epoch, designation/fallback chain, path constraints, and stop conditions. Then declare the envelope it must preserve: target-distance limits, relevant altitude/speed/terrain limits, obstacle policy by class, signal-loss behavior, speaking triggers and media settings, duration/distance/battery budgets, and optional Avatar `ProjectionBinding@2`.
The commissioned body/profile and applicable authority supply every physical value. This shared contract cannot supply universal safety distances or operating defaults.
Required capabilities—such as the admitted camera for visual lock or positioning method for a particular route—must be available before movement. Safety, geography, authority, or designation failure refuses admission.
## Representative journey
The synthetic fixture admits a mock body with simulated positioning, camera, microphone, speaker, battery, and locally proved stop behavior. A beacon and declared visual fallback identify the subject. Following a recorded outdoor path produces waypoint receipts; an obstacle and occlusion produce deviation/degraded-lock evidence.
At a workbench, the subject stops beside a tray of seedlings: “Hey Lich, what do you notice about these leaves?” The admitted activation requests a speaking window. Disclosure precedes separate Sight and Echo capture; their observations and transcript enter Context with uncertainty. An admitted response returns through Avatar/Echo/device receipts. The resume request closes capture before the follow loop continues. A simulated battery floor then triggers the declared local policy and settles the exact completed subset, with battery-depleted reason rather than invented destination success.
This proves workflow and receipt behavior, not drone dynamics, obstacle avoidance, hardware compatibility, plant diagnosis, or physical safety.
## Subject designation
The subject is explicit, attributable, and pinned. “Follow whoever is nearby” is inadmissible. A profile may use an admitted BLE/UWB beacon, GPS tag, AprilTag/ArUco marker, visual signature, thermal cue, or other bounded visual tracker. Each needs exact sensor, tracking, confidence, ambiguity, and loss behavior. A face embedding or similar cue proves no identity, attention, relationship, or consent.
A declared fallback chain can move from beacon to marker to a selected visual cue. Each transition records `subject_lock_degraded`; it cannot select an arbitrary nearby replacement. Occlusion, lighting, RF loss, tag battery, accumulating positioning error, thermal ambiguity, and lookalike cues must remain visible. Exhausting the chain returns `subject_lost` and invokes the admitted containment/stop policy.
## Path-tracing loop
```text
acquire → plan → move → observe → adjust → check → acquire …
```
Acquire the designated subject and lock-quality evidence. Plan a bounded waypoint intent against distance, terrain, obstacles, and geofence. The controller admits and executes motion locally; Familiar records its receipt. Observe again, account for movement/obstacle/lock changes, and check budget, stops, and speaking triggers before the next intent.
The controller runs at its pinned measured rate. LychD declares no universal frequency and does not micromanage avoidance. Between semantic updates, the controller maintains or rejects the last admitted command under its local envelope.
## Distance, altitude, and speed envelopes
Admission must supply the exact body-specific limits and required sensing. A deviation records what crossed the envelope and how the controller responded. Sustained inability to maintain the target relation invokes the pinned stop policy; an appealing follow path cannot widen speed, clearance, geography, or authority.
## Obstacle avoidance
Static objects, moving people/animals/vehicles, narrow passages, water, and stairs require separately admitted responses. The profile may permit bounded stopping, rerouting, or another controller-proved maneuver; unsupported passages and terrain refuse. Controller observations and response receipts establish what happened. No general table can make an airborne climb, vehicle brake, or legged freeze safe for every body or situation.
## Signal loss
The attachment's bounded control link may disappear—Intercom for a Legion-backed route or the exact local/mobile equivalent. A body-specific policy defines the autonomous transition, deadline, contained/stopped state, and evidence/recovery path without waiting for LychD.
Candidate policy names such as hover-and-wait, land-in-place, return-to-home, brake-and-wait, or freeze are meaningful only inside a commissioned profile that proves their applicability. A label itself promises no physical safety. Reconnect reads the body journal, epoch, pending intent, and actual state before any continuation. Once the loss policy has executed, a late signal cannot silently resume the old mission: settle `signal_lost` and use explicit recovery admission.
## Speaking mode
A speaking window is a transition within the mission, not a second speech ledger. The trigger is declared at admission: an Echo Listener's exact activation phrase, authorized operator/application request, or an admitted proximity/gesture request. Proximity or visual resemblance cannot authorize capture, identity, or consent.
### Activation
First obtain the body's admitted stationary/contained presentation posture. Activate visible camera/microphone disclosure and any required audible announcement before separately admitted capture. Exact body policy determines whether this transition is possible; it never assumes a drone, rover, or legged body can use the same stabilization action.
### Active session
With the presentation posture established, open a separately admitted camera epoch for Prism/Sight source-bound observations and an Echo capture window. The transcript retains source, timing, provider, language assumptions, and uncertainty. Avatar may select an eligible presentation for the reply. Echo keeps synthesis and playback chronology, and the device supplies the physical delivery evidence.
Familiar records the bounded window's exact Companion controls when present, Prism/Echo epochs, transcript, disclosures, and receipts. It creates no duplicate `FamiliarSpeakingSession` chronology.
### Deactivation
An admitted goodbye/resume request, subject departure beyond grace, authorized instruction, exhausted speaking/mission budget, or mission stop closes the window. Stop camera/mic and settle their owner records before withdrawing indicators. Resume following only if the original mission's current admission and body policy permit it; otherwise settle the mission. A spoken request never acquires consequential effect authority by itself.
## Terminal settlement
| Result | Required account |
| --- | --- |
| `completed` | Declared destination reached, or the admitted duration finish reached with subject locked, and every completed segment has waypoint receipts. |
| `partial` | Policy permits the exact completed subset; refused, absent, or interrupted segments are named. |
| `subject_lost` | Designation chain exhausted; last position/quality, loss event, and admitted policy execution retained. |
| `emergency_stopped` | Autonomous/manual trigger, source, stopped body state, and post-stop telemetry retained. |
| `signal_lost` | Control-loss policy executed; journal remains available for reconciliation. |
| `battery_depleted` | Declared floor reached and body-specific low-battery behavior executed before power loss, with final position/charge evidence. |
| `refused` | Admission failed before movement: capability, route, geofence, designation, or other required condition. |
| `unresolved` | Required effect/result evidence remains unknown or unreconcilable. |
Return to [Familiar](index.md).
---
title: "Robotic Dance"
plain_name: "Familiar: Robotic dance (idea)"
section: "Compositions > Presence & Embodiment > Familiar"
status: "Designed"
original: https://hexanomicon.dev/compositions/familiar/dance/
guide: https://lychd.snayu.ai/docs/compositions/familiar/dance/
---
# Robotic Dance (Familiar: Robotic dance (idea))
## Plain-English summary (Snayu)
**What it is:** A candidate use case where a person wearing motion trackers leads a group of robots in a dance, with each robot adapting the movement to its body, plus related research.
**Why it matters:** Read this if exploring motion retargeting or multi-robot synchronisation ideas.
- Modes: Mirror (follow together), Echo (deliberate delay) and Ensemble (variations per body).
- Live Kinesis would retarget motion; each robot's local controller keeps balance and safety.
- Adds no published workflow or supported hardware; research checked 2026-09-17.
**Status:** Designed. Candidate use case only.
## Original text (Hexanomicon)
Put on motion trackers, step into the admitted dance space, and lead a group of physical
familiars with your own body. Each robot adapts the movement to its proportions and capabilities.
Candidate modes are **Mirror** (follow together), **Echo** (a deliberate time offset), and
**Ensemble** (declared variations for different bodies).
This is a **candidate Familiar use case**, with research checked on **2026-09-17**. It suggests a
dance Pattern and exact body/controller profiles; it adds no published Pattern or supported
hardware to the [Familiar contract](index.md#contract). [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
keeps the shared delivery boundary.
## How it could fit
```text
armed wearable / optical mocap source
→ calibrated human motion with timestamps
→ Live Kinesis retargeting for each exact robot rig
→ separately admitted local tracking controller
→ Familiar mission observations, effects, and settlement
```
[Live Kinesis](../../sepulcher/extensions/prism/live-kinesis.md) is the proposed seam for source
epochs, clocks, retargeting, gaps, and expiring motion segments. A pinned GMR adapter is one
candidate for its technical mapping. Familiar would bind each `FamiliarBody@3` to a finite dance
mission, the designated consenting performer, dance mode, space, duration, and stop policy.
The [body's controller](embodiment.md#the-body-decides-what-fits) retains balance, contacts, joint
limits, collision response, and fast actuation; an LLM can select an admitted mode or request a
stop while this local loop runs independently.
Admit and map each robot separately before using shared source timing to synchronize the group.
The group policy must say what happens when one member drops out, and intentional Echo delay must
remain distinguishable from stale tracking. Lost tracking, changed calibration, or an expired
segment invokes the commissioned local response; reconnect requires fresh admission.
At settlement, record performed intervals, deviations, stopped members, and unknown effects.
Participation alone does not authorize all uses of the source: capture, recording, and reuse of
the performer's motion remain separate consent choices.
## Research and existing demonstrations
These are integration leads, with different evidence boundaries:
| Reference | What it contributes |
| --- | --- |
| [TWIST](https://arxiv.org/abs/2505.02833) and [TWIST2](https://yanjieze.com/projects/TWIST2/) | Whole-body human-to-humanoid teleoperation. TWIST2 uses a PICO 4 Ultra and two PICO Motion Trackers, making it a concrete wearable-input reference for a Unitree G1 profile. |
| [GMR — General Motion Retargeting](https://github.com/YanjieZe/GMR) | Maps human motion onto different humanoid bodies and supports live teleoperation. A candidate retargeting component; mapping a pose does not establish balance or successful physical execution. |
| [ASAP](https://agile.human2humanoid.com/) | Demonstrates learned agile skills, including APT Dance, on a real G1. Useful for controller training and a rehearsed-clip route; it does not establish live imitation of an arbitrary dancer. |
| [CHINGMU × Unitree, WRC 2026](https://en.chingmu.com/case/10801.html) | The vendor's September 3 report describes a dancer's captured movement driving a humanoid synchronously. A direct demonstration of the intended experience, without an independently verified latency or general compatibility claim. |
Selecting a profile would still require its exact capture interface, robot/controller revision,
measured timing, and code, weights, body-model, and data-use terms. None of these references is
an installed LychD dependency.
## First bounded probe
Start with one recorded performer trace and two simulated bodies with different mappings.
Exercise Mirror and Echo, then inject stale frames, calibration changes, one-body refusal, and
an operator stop. Check timing and per-body partial settlement before attempting a separately
commissioned single-robot live trial. Ensemble variations can follow; the fixture establishes
no physical safety or hardware compatibility.
Return to [Familiar](index.md) or [Embodiment](embodiment.md).
---
title: "Companion"
plain_name: "App: Companion (phone client)"
section: "Compositions > Presence & Embodiment"
status: "Partial"
original: https://hexanomicon.dev/compositions/companion/
guide: https://lychd.snayu.ai/docs/compositions/companion/
---
# Companion (App: Companion (phone client))
## Plain-English summary (Snayu)
**What it is:** The mobile app: press to speak, review the words, submit a request, and later see or hear the result. It owns privacy, configuration, reconnect and the difference between text and actually played audio.
**Why it matters:** Read this before working on the phone client or voice-on-phone features.
- Enrollment order: Security Desk enrolls, Familiar admits the phone body, then Companion opens the session.
- No persona changes, ambient listening, phone administration or voice-only approvals.
- First target is native Android; an early development slice exists.
**Status:** Partial. Android development slice with fixtures; no live host connection.
## Original text (Hexanomicon)
Press to speak, inspect the words, and submit a bounded handoff. Later, an exact settled result can appear as text, with speech governed by the admitted presentation policy. Companion owns this mobile device experience—including privacy, disclosure, configuration, reconnect, and the difference between committed text and sound the handset actually delivered.
The phone itself is a [Familiar](../familiar/index.md) body. [Avatar](../avatar/index.md) may present the Lich through it. Those relations grant neither body authority to the client nor identity to the screen.
## Contract
`companion.mobile` revision `3` publishes `companion.admit_device@3`, `companion.open_session@3`,
`companion.submit_turn@1`, and `companion.present_result@1`. Admission fixes three parts of the
session:
- **The device:** exact `FamiliarBody@3` and capability epoch, with its Ward-owned
device/application `Principal` and `Credential` generation.
- **The permitted work:** initiating Principal, current object-scoped `Authority Grant`,
purpose, and configuration/feature profile.
- **The local experience:** capture and playback, privacy and retention, reconnect, and visible
stop.
These bindings let the session recognize when the body, authority, or conditions on which it
began have changed.
Results are immutable `CompanionDevice@3`, settled `CompanionSession@3`, `CompanionTurnHandoff@1`, and `CompanionPresentationReceipt@1`, optionally synthesized speech/local delivery, or exact partial/non-completion. Persona changes, ambient capture, mobile administration, voice-only approval, and direct deferred external effects remain outside the contract.
The enrollment order is fixed:
1. Ward owns enrollment and grants before either Composition acts.
2. Familiar admits the body, hardware, capabilities, local safety, and stops.
3. Companion pins those exact body, credential, and policy generations in its device record.
Revoked or changed facts prevent new admission and invoke the live session's downgrade/stop policy. So does a missing required microphone, speaker, display, secure storage, notification, or connectivity capability. A replacement handset or credential is no guessed continuation.
## Mobile client
The first target is native Android in Kotlin/Jetpack Compose under `clients/android/**`.
The first development slice uses an explicit Bridge fixture and bounded local foreground audio;
it does not establish enrolled mobile access or a native Composition round trip. The client owns
platform integration and local UI state while Composition records, policy, effects, and finish
judgment remain native domain truth. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
owns the delivery boundary.
Configure each session explicitly with capability requirements, local routes, presentation/privacy settings, and admitted feature bindings. Extension packages may supply features without becoming an application-owned extension set. Companion then owns the passage through disclosure, draft, commit, playback, reconnect, expiry, and revocation. That independent lifecycle makes it a Composition rather than only a Familiar profile.
[Android Development](android-development.md) describes the implemented fixture/local-audio slice
and its build route. [Android Foundation](android-foundation.md) studies the first Bridge and foreground voice client,
including shared API contracts and the path to later phone capabilities.
[Phone Workspace](phone-workspace.md) studies a broader candidate direction: an offline music
player, progressively admitted phone actions, selected photos, and explicit sync over local Wi-Fi
before later VPN reach. That proposal remains separate from this revision's accepted contract.
## Communion route
**Communion** is the bounded foreground interaction route inside Companion. [Utterance](utterance.md) follows its separately settled submission and presentation handoffs: submission does not admit destination work, and presentation begins from an already-settled result. A Product promising one live capture-to-result journey needs a named [Suite](../products-and-suites.md#compositions-relate-without-nesting) to coordinate the separate Invocations.
## Boundaries
[Access and Views](access-and-views.md) applies Ward's existing account/profile law to mobile
screens, action offers, device conditions and context changes. The current fixture supplies no
live User or remote authorization.
Begin speech through visible, foreground, revocable push-to-talk activation. Companion owns the physical controls and indicators, local state, configuration, features, and reconnect that make this a device experience. Echo retains speech admission, audio custody and derivation, transcription/synthesis/delivery/playback chronology, and revocation.
Stop speaking and cancel session are separate controls. A spoken response or microphone indicator grants no consequential authority. Text remains visible before or beside speech.
Raw voice is `restricted`; transcripts and replies are at least `private`. Audio is ephemeral by default, and recording supplies no training permission. Malformed, stale, replayed, unordered, and oversized frames fail closed.
[Utterance](utterance.md) follows the handoff; [Return](return.md) handles reconnect and custody.
Revision `3` supersedes revision `2` with exact Ward enrollment and independently versioned handoff/presentation Patterns. Revision `2` had replaced revision `1`'s body claim with an exact Familiar dependency. No registry or Run used them; historical meanings remain unchanged without executable migration.
[Composition Portfolio](../index.md) · [Echo](../../sepulcher/extensions/echo.md) · [Ward](../../sepulcher/extensions/ward.md)
---
title: "Utterance"
plain_name: "Companion: One spoken request"
section: "Compositions > Presence & Embodiment > Companion"
status: "Designed"
original: https://hexanomicon.dev/compositions/companion/utterance/
guide: https://lychd.snayu.ai/docs/compositions/companion/utterance/
---
# Utterance (Companion: One spoken request)
## Plain-English summary (Snayu)
**What it is:** How one push-to-talk utterance is authenticated, transcribed, reviewed and submitted as a request handoff, and how the result is later presented as text or speech.
**Why it matters:** Read this when working on the voice request flow from phone to workflow and back.
- Each utterance gets a fresh identity with fixed size, duration and expiry limits.
- Raw audio is dropped after transcription per retention; low confidence asks for clarification.
- Submitting ends Companion's job; the workflow engine separately decides whether to run the work.
**Status:** Designed. Contract; transcription and handoff are not live.
## Original text (Hexanomicon)
One deliberate utterance starts a bounded foreground route. It can settle a request handoff even when the destination has not yet admitted work.
When push-to-talk opens, the client creates a fresh utterance identity and fixes its frame sequence, codec, byte/duration limits, and expiry. Tether may make the host reachable, but Ward independently proves application, device, Principal, scopes, and object authority.
Echo then admits the frames, retains an attributed transcript, and drops raw audio under the chosen retention. Low confidence returns clarification. Where preview is required, the person reviews the words before submitting them.
`companion.submit_turn@1` commits an idempotent `CompanionTurnHandoff@1` binding exact Intent, requested Pattern, Principal, device/session/utterance identities, expiry, disclosure, and correlation. That submission action then ends. Spellweaver independently decides whether to admit the exact registered destination; its owner handles clarification, consent, work, cancellation, and recovery.
```text
push-to-talk → authenticate → transcribe → preview or clarify
→ typed Intent → settled CompanionTurnHandoff@1
|| independently admitted destination Invocation
settled terminal-result reference → Companion presentation under its admitted output policy
```
Once a terminal-result reference has settled elsewhere, a fresh authorized `companion.present_result@1` may present it against this utterance/device. The presentation has its own finish. Committed text survives synthesis or playback failure, but text alone cannot complete a presentation that requires speech.
Text-only fallback counts as completion only when the admitted configuration explicitly accepts it. Otherwise return exact partial or non-completion for the presentation. This leaves the independently settled destination result unchanged: Companion cannot reopen or relabel it and owns no wait, cancellation, retry, or recovery for that destination Invocation.
The two handoffs therefore promise separate settled results. A Product needing one coordinated round trip must pin a named Suite with aggregate wait, cancellation, recovery, and settlement. [Return](return.md) explains what reconnect can retrieve without replaying the request.
---
title: "Return"
plain_name: "Companion: Reconnecting"
section: "Compositions > Presence & Embodiment > Companion"
status: "Partial"
original: https://hexanomicon.dev/compositions/companion/return/
guide: https://lychd.snayu.ai/docs/compositions/companion/return/
---
# Return (Companion: Reconnecting)
## Plain-English summary (Snayu)
**What it is:** What happens when the phone reconnects: it looks up the settled handoff or result instead of resending audio, and how local drafts expire and stay in memory only.
**Why it matters:** Read this when working on reconnect logic or the phone's local draft handling.
- Reconnect never resends audio, replays a request or delivers expired commands.
- Offline recordings are short-lived drafts needing review, never auto-queued actions.
- Local drafts have fixed deadlines that edits do not renew; a faulty clock cannot revive them.
**Status:** Partial. Client-local draft model exists; live reconnect does not.
## Original text (Hexanomicon)
The connection drops after the utterance. Reconnect looks up Companion's settled handoff or presentation receipt by Principal and utterance identity; it does not resend audio, replay Intent, deliver expired commands, or take over the destination's work.
If an authorized terminal-result reference has already settled, a fresh presentation action can show or speak it. An offline recording is instead a short-lived draft requiring review after reconnect, never an automatically queued effect.
Reconnect preserves [Companion's control, speech, and custody boundaries](index.md#boundaries). Companion also retains local disclosure and interaction state. Tether supplies reachability; Ward still proves application, device, Principal, scopes, and object authority. Spellweaver, Workers, and Phylactery keep admission and Run delivery; the destination keeps its domain result and effects. The client carries no provider, database, workflow, or host-lifecycle credential.
Reconnection reapplies the original frame-admission rules and the session's separately admitted stop, presentation, privacy, and retention policy; it widens none of them. Enrollment revocation and destination export/deletion remain separate owner actions.
## Client-local interaction
The first client-only profile holds text drafts and observed presentations in memory. It handles
no recording bytes, credentials, transport, or authoritative Companion records. Every local session
has a fresh generation; restarting the process discards this local state. Native session and result
identities remain opaque inputs to a future authorized adapter.
Give each draft a fresh local identity and fixed deadline, using a positive caller-supplied
lifetime and monotonic clock. Editing, review, and reconnect do not renew it. Both review and
submission check the time, and equality with the deadline means expired.
A faulty clock must not revive the draft. Invalid or regressed time refuses eligibility without
moving the retained clock or deadline; equal readings are valid. Disconnection still invalidates
review, and local stop and cancel remain usable despite a clock fault. This profile supplies no
default retention lifetime and cannot prove elapsed time when its supplied clock is faulty.
Review binds the exact visible draft revision and connection generation. Editing or losing the
connection invalidates it; reconnect requires fresh review followed by a separate explicit submit.
Submission emits only a local request to submit that reviewed snapshot, correlated to its local
draft identity. It establishes no admission or settled handoff. That draft then becomes terminal:
editing, duplicate submit, reconnect, or a lost response cannot rearm it. Another utterance needs a
fresh draft identity. At most one signal follows along the accepted local state transitions; this
is no network deduplication or process-restart idempotency guarantee.
Bind connection updates to the expected current connection identity so an older generation cannot
change the current connection. Asynchronous observations similarly name the exact local session
generation and applicable draft, request, presentation, and playback-attempt identities. Stale
observations change neither current state nor its clock.
A presentation request accepts at most one terminal text observation; another result needs a
fresh request identity. That text is an opaque projection, not a client-minted Companion receipt.
Keep a playback request separate from observed start, completion, failure, or local stop. Late
callbacks cannot reopen a stopped attempt or replace a newer presentation.
Stopping speech closes local playback while keeping the interaction open. Cancelling the local
session closes interaction and invalidates its callbacks. Neither control cancels a destination
Invocation, and synthesis or playback failure preserves the observed committed text.
For the initial Android screen, the person chooses a positive whole-second lifetime before
starting a draft; there is no prefilled lifetime. Clock or arithmetic failure refuses eligibility
without replacing the existing draft. Configuration recreation within the same process preserves
the current session and deadline. Process death restores neither a draft nor unsubmitted form input.
The screen projects expiry from valid monotonic observations even while idle. A stale or regressed
observation cannot revive eligibility or affect a replacement session or draft. Expiry and local
cancellation do not claim erasure of retained text. Review and Submit remain unavailable while
disconnected; a simulation switch or device connectivity observation supplies no native admission.
## Proving the route
A fifteen-second local Android fixture uses distinct tunnel/application keys, local recognition, typed handoff sink, pre-settled text result, optional synthesis, ephemeral audio, durable text, and utterance-id reconnect. Prove no destination wait/cancel, stolen-tunnel-key refusal, revoked app key, replay, object guessing, transcript injection, disconnect, expiry, and locked-device playback. No public proxy, ambient capture, mobile approval, administration, or medical promise enters it.
Return to [Companion](index.md), or follow a new [Utterance](utterance.md).
---
title: "Companion Android Development"
plain_name: "Companion: Android development slice"
section: "Compositions > Presence & Embodiment > Companion"
status: "Partial"
original: https://hexanomicon.dev/compositions/companion/android-development/
guide: https://lychd.snayu.ai/docs/compositions/companion/android-development/
---
# Companion Android Development (Companion: Android development slice)
## Plain-English summary (Snayu)
**What it is:** The first Android implementation: a Kotlin/Compose debug screen talking to a fake Chat fixture, plus bounded microphone recording and local replay.
**Why it matters:** Read this before building, running or extending the Android client.
- Replies come from a labelled development fixture; no real host work is done.
- Recording is mono 16 kHz WAV, capped at 15 seconds and 512 KiB, replayed via Media3.
- Capture and replay stop on onStop (backgrounding/lock); recording does not fill the text editor.
**Status:** Partial. Development slice built; no transport, transcription or enrollment.
## Original text (Hexanomicon)
The first implementation lives in [the Android client](https://github.com/hexanomicon/lychd/tree/main/clients/android).
It provides a native Kotlin/Compose development screen, a schema-derived Bridge fixture, and
bounded foreground microphone capture with local replay. [State of Work](../../state-of-the-work.md#companion-android-client)
owns its delivery boundary. [Android Foundation](android-foundation.md) retains the researched
live-client direction and its host prerequisites. [Access and Views](access-and-views.md) applies
the accepted account and working-interface rules to this client.
## Running the slice
Follow the client [build and installation instructions](https://github.com/hexanomicon/lychd/blob/main/clients/android/README.md).
The debug application has a separate `.dev` identity. Open Companion, type words, mark them
reviewed, and send. The reply explicitly identifies itself as a development fixture. Refresh reads
the fixture conversation; New conversation starts a separate local fixture session. These actions
exercise the current Bridge JSON dialect without performing a native Companion handoff or
admitting host work.
Start recording requests Android microphone permission. Stop recording finishes a mono PCM16
WAV at 16 kHz. Capture stops automatically at 15 seconds, with a second byte cap of 512 KiB
including the WAV header. Replay plays that local recording through Media3; Discard removes it.
The words editor is manual: recording does not fill it, and replay is not synthesized speech.
On `onStop`—including the normal background/lock route—the client stops capture and replay,
attempts to discard its current recording, and fences late callbacks. Activity destruction closes audio
resources. Rotation may retain the ViewModel's draft while discarding audio. This boundary is
`onStop`; the implementation does not claim capture ends merely on `onPause` or against every
Samsung-specific lifecycle condition before a handset probe.
## Code and contract ownership
| Path | Responsibility |
| --- | --- |
| `clients/android/app` | Compose views, lifecycle and permission handling, testable handset interaction, AudioRecord capture and Media3 replay adapters. |
| `clients/android/core` | Local Bridge state, bounded Ktor transport, explicitly in-process HTTP fixture, local presentation offers and recovery tests. |
| `clients/android/tools/generate_wire.py` | Deterministic Kotlin wire models and JSON token-shape checks from the current Altar OpenAPI export. |
| `clients/web/openapi.json` | Existing host-owned transport schema; Android does not own a second copy. |
| `clients/android/gradle/libs.versions.toml` | Pinned direct build and library versions. |
One pure JVM `core` module permits protocol tests without an Android SDK; it does not introduce
a shared Android/iOS UI or a new domain authority. The generated fields preserve required
nullable fields and supplied defaults. Optional fields with no schema default use nullable local
representation; generated token-shape checks run before decoding so quoted numbers and explicit
null cannot stand in for their schema-owned types. Object/array error extras stay opaque.
Generated shape evidence does not establish authentication, authorization, valid state transitions,
or recovery.
The HTTP fixture uses Ktor MockEngine at a reserved `.invalid` origin. No live-engine factory,
URL editor, cookie store, credential, Internet permission, analytics SDK, retry plugin, or audio
upload exists. CIO is a candidate for a later tested TLS/Keystore transport. The host's current
loopback possession credential must not be copied into the client or exposed over LAN/VPN.
## Local state and custody
Bridge state and fixture records live only in memory. A submission uses a fresh request UUID;
after success, the client reads the session snapshot. If acknowledgement is missing or malformed,
mark the outcome unknown and block further sends in that session. Matching text during Refresh
cannot prove the missing outcome. An explicit new session clears this local latch, but the fixture
has no durable request lookup.
Cancellation, background invalidation, new session and close fence stale responses. Explicit
presentation-context replacement also clears history, draft and review state from the local
projection. Disposing of that state does not settle the original external outcome, and there are
no automatic retries.
Caller cancellation propagates through transport and local interaction while an unacknowledged
submission remains unknown. The transport's own 15-second deadline is a bounded request failure;
it does not turn a cancelled caller into a successful return.
Drafts are limited to 100,000 characters and 256 KiB of UTF-8, responses to 512 KiB, session
history to 128 turns and each HTTP action to 15 seconds. The fixture caps its memory holdings and
HTTP history; reaching its development limit requires restarting the app. It checks serialized
acknowledgement and full snapshot bounds before admitting a new fixture message, including JSON
escaping and accumulated history. Request UUID spelling does not create a second admission.
These are local bounds, not host admission policy.
## Access-aware presentation
The accepted IAM design already permits different working views for different accounts and
contexts. The client now has a closed local policy for Conversation, Words and Local recording,
with separate open, refresh, edit, review, send, record and replay offers. Compose and interaction
handlers consult the same policy. Missing policy offers no work. A read-only offer cannot create
a conversation through startup or the Refresh fallback; an offered screen alone grants no action.
Queued actions and callbacks must still belong to the current presentation generation.
The debug build uses explicitly labelled development offers; release starts unavailable. There
is no account picker, Role parser or live Ward projection adapter. Replacing the policy disposes
of the old local context and stops audio. Stop, discard and cleanup retry remain callable after
work offers disappear. This is a client integration seam and does not deliver remote identity,
object authorization or profile management.
## Audio custody
Keep audio only in the app's `noBackupFilesDir/companion-recordings` directory. The manifest
disables backup and explicitly excludes cloud/device transfer. During capture, cancellation
closes the recorder and attempts to remove partial or unclaimed completed files. A bounded retry
guard blocks another capture if disposal fails. Successful stop transfers file cleanup to the
interaction controller.
Background/discard then attempts deletion of that transferred recording. Make a failed deletion
visible, retain it for bounded retry, and prevent another recording until cleanup succeeds.
Overflow asks for a process restart so startup cleanup can recover the abandoned directory.
At process startup, the recorder's IO initialization removes abandoned `capture-*.wav` files
from an earlier process; the first recording waits for cleanup. This is ordinary file deletion,
not a secure-erasure or flash-forensics guarantee. Partial/unclaimed and transferred-file cleanup
share the visible capture guard. Cleanup failure survives adapter destruction and late start
cancellation or storage failure; releasing the recorder does not discharge its byte custody.
No recording supplies training permission.
The controller observes capture completion and early failure directly rather than waiting for the
display timer or a user stop. Playback callbacks distinguish a replay request from Media3's
playing state and clear it on end/error. These are local adapter facts, not physical delivery or
remote voice settlement.
Process death may clear the draft/conversation and leave audio until the next successful startup
cleanup. The app has no retained conversation database or reboot recovery. Its local microphone
and replay facts are not Echo transcription, synthesis or delivery receipts.
## Verification and remaining probes
Core tests exercise the fixture's actual JSON routes, duplicate/conflicting request behavior,
invalid input, bounded bodies, malformed/null/enum replies, framework errors, lost acknowledgement,
local state races and stale responses. The WAV tests exercise sample/header correctness, byte and
duration bounds, empty capture, cancellation, completion races and custody transfer. Generator
tests exercise required/null/default fidelity, reference closure and unsupported schema refusal.
Presentation and controller tests exercise unavailable/read-only offers, direct-call denial,
queued actions, context loss, early audio failures, late callbacks and cleanup across adapter
destruction. Cleanup retry cannot erase a current recording-failure message or resurrect a closed
owner's recorder.
Android lint and an APK build verify platform compilation; they do not operate a microphone.
The reviewed aggregate passed **31 Bridge tests, 12 presentation tests, 24 controller tests,
17 audio tests, five deletion-recovery tests and nine generator tests**—98 client tests in total—
Android lint with no issues, and the debug APK build. Lockfiles retain the
resolved dependency graph. These checks do not prove supply-chain provenance or reproducible
APK bytes across machines.
The wrapper verifies its distribution SHA-256 and Gradle verification metadata retains artifact
hashes observed during this first build. This establishes a baseline for detecting artifact changes,
not independent provenance. Keep library license resources in the APK. The merged manifest
includes Media3's network-state/wake-lock permissions and AndroidX's initialization/profile
components alongside microphone permission; it has no Internet permission. The app owns its
source and local behavior while Samsung's system software and hardware remain separate layers.
Before treating the client as handset-validated, record the S20 FE's exact model and Android/API
version and test permission refusal/revocation, repeated recording, the automatic cap, lock,
background, rotation, process kill/relaunch cleanup, audio focus, wired/Bluetooth route changes,
and stop/discard while finishing or replaying. A local completed WAV is not evidence of a remote
voice journey. This first slice contains no instrumented-device test receipt.
## Next integration
The next useful work is a protected host-owned mobile API with enrolled device identity,
object-scoped grants and exact retained handoff/result lookup. It needs the accepted
Ward → Familiar → Companion order and a separately settled submission/presentation contract.
Then qualify the chosen live Ktor engine on the handset, wire the exact generated contract,
and connect Echo's bounded transcription/synthesis custody through the proposed Communion Suite.
Only that sequence can establish the capture → reviewed words → host work → settled reply journey.
Before replacing the fixture with a live connection, establish how the host reports uncertain
admission. Current Altar Bridge can fail after admission while constructing its acknowledgement.
That acknowledgement also omits the request identity, which the current client attaches locally.
Neither an HTTP status nor that local attachment establishes an exact retained host outcome.
The fixture's known-refusal classification therefore cannot become live recovery policy. The
owning host contract needs tests for pre-admission refusal, post-admission failure, lost
acknowledgement and lookup in the original account/context.
| Review follow-up | Required evidence |
| --- | --- |
| Remote account and view integration | Ward enrollment, application-owned filtered projection, exact object/action grants; two accounts, sharing, revocation, expiry and context-switch tests. |
| Live Bridge recovery | Protected mobile ingress and retained request/handoff/result lookup; transport failures cannot cause duplicate admission or retargeting. |
| Remote voice journey | Echo custody and bounded capture/transcription/review/synthesis settlement, followed by handset delivery evidence. |
| Android operation | The S20 FE lifecycle, permission, microphone, cleanup, focus and route probes listed above. |
Folder-first offline music can reuse the platform/lifecycle project but requires its own library
selection, media session and background playback behavior. Selected photos and explicit copy sync
follow the [Phone Workspace](phone-workspace.md) study. Those features do not turn client modules
into host-owned extension execution or confer broad control of the phone.
[Companion](index.md) · [Return](return.md) · [Android Foundation](android-foundation.md)
---
title: "Companion Access and Views"
plain_name: "Companion: Access and views"
section: "Compositions > Presence & Embodiment > Companion"
status: "Partial"
original: https://hexanomicon.dev/compositions/companion/access-and-views/
guide: https://lychd.snayu.ai/docs/compositions/companion/access-and-views/
---
# Companion Access and Views (Companion: Access and views)
## Plain-English summary (Snayu)
**What it is:** How the phone app decides which screens and actions to show, based on the authorized instance, account, work context and enrolled device, never on role names alone.
**Why it matters:** Read this before adding screens or actions to the Android client that depend on user permissions.
- The phone is never the authority for accounts, grants or ownership; the Security Desk decides.
- Each view (conversation, editor, voice) needs its own current permission; missing ones show denied or unavailable.
- Remote account management (IAM) is not yet delivered.
**Status:** Partial. Client presentation seam exists; host integration still required.
## Original text (Hexanomicon)
Companion presents the working interface authorized for the selected instance, human account,
work context and enrolled device. [IAM](../../adr/38-iam.md#profiles-and-working-interfaces)
already defines this rule. A profile or Role may influence Ward's decision; its name is not a
client permission. The mobile client never becomes the authority for User accounts, grants or
object ownership. [State of Work](../../state-of-the-work.md#remote-iam) owns the undelivered
remote IAM boundary.
## Views follow an authorized projection
An administrator, employee, household member or guest may receive different views, but these
labels alone select no screen. Two people with the same Role may be authorized for different
objects. One person may have different interfaces in personal and workplace instances. Human
identity, device/application identity, authentication session, Bridge conversation and Companion
session remain separate facts.
| Working view | Required current facts | When those facts are missing |
| --- | --- | --- |
| Connection and account choice | A locally supported enrollment/sign-in flow for the selected instance; no protected content before authentication. | Show connection/access status and public client information. The first fixture has no live enrollment or sign-in flow. |
| Applications and work contexts | Ward-filtered offered applications and individually permitted contexts. | Omit unavailable entries; do not download a global catalogue and filter private objects locally. |
| Conversation and results | Read access to each exact session/result and a compatible presentation profile. | Show a denied/unavailable state without retaining or fetching another person's history. |
| Words editor and submission | An offered submission action, its exact object/context, current authority and an allowed workflow state. | Read-only conversation may remain available; create/edit/review/send are separate decisions. |
| Voice capture and presentation | The relevant offered voice action, admitted privacy/custody policy, current device capabilities and Android permission/audio conditions. | Keep text where independently permitted. Microphone permission alone grants no host voice operation. |
| Local privacy and safety controls | Ownership of the current local effect or bytes. | Stop and discard stay callable even after work access disappears. |
Companion revision 3 excludes mobile administration and voice-only approval. Administrative
powers do not automatically expose Altar's operator instruments or grant access to all content.
A later administrative mobile product needs its own admitted contract and explicit Ward actions.
Workflow and action state also constrain controls: an allowed view cannot change a Scroll, resume
an Invocation, approve an effect or replay a submission by itself.
## First client implementation seam
The current `core` presentation policy is local offering logic with a closed screen/action
catalogue. It distinguishes unavailable access from an explicitly labelled development fixture.
It has no live Ward projection factory, role parser, Principal, Credential or Grant DTO. The
fixture's local offers can be narrowed in tests; the app exposes no user-controlled role or
capability selector.
The current surfaces are Conversation, Words and Local recording. Their actions remain separate:
creation/opening is distinct from reading/refreshing a conversation. A read-only offer therefore
cannot invoke the initial POST or Refresh's create fallback.
Check the exact offer whenever work is requested. Missing policy denies work by default; an
omitted offer denies its corresponding surface/action. A stale local context cannot authorize
a callback or queued action. Also distinguish unknown access from an already attempted submission
whose external outcome is unknown.
Compose and its controller use the same policy. Hiding a button is presentation; the controller
also checks policy and local conditions before invoking transport or capture. This is preparation
for a future trusted projection adapter, not delivered server authorization. A local test can
assert that read-only offers cannot create/send and voice-disabled offers cannot record/replay;
it cannot establish Ward enforcement.
## Context change and loss of access
When the person selects another instance/account, signs out, loses access or replaces the current
projection, advance the local generation before any new work. Clear affected session IDs, history,
draft, reviewed-word state and pending presentation. Cancel local microphone/replay and attempt
bounded file cleanup.
Keep late transport and audio results bound to their originating generation; they cannot populate
the replacement context. Safety stops and deletion retries remain available so losing work access
does not prevent local cleanup.
Changing context does not cancel server work, transfer its authority or prove whether an
in-flight submission was admitted. Do not replay or retarget it. Reconciliation belongs to its
original context and exact retained request identity. Ordinary background invalidation can retain
one account's transient draft; explicit context loss must clear it. Reconnect requires fresh
authorization before receiving protected state or submitting work.
## Host integration still required
The host must first provide Ward enrollment for the human and device/application Principals,
then an authenticated, versioned mobile projection from the owning application. Its contract
needs the selected instance/account/context binding,
current credential/policy/revocation and device-capability generations, validity, offered views,
and actions bound to named objects and workflow states. Missing, unknown, expired or mismatched
facts refuse access. Only then should the generated mobile wire model be derived from its owning
host schema; a handwritten client model must not become that API by accident.
The host filters protected records in ownership-aware queries before delivery and rechecks
current authority at request/effect time. It must test two accounts, shared and unshared objects,
revocation, expiry, stale callbacks and instance switching. Authentication, UI projection and
authorization require distinct evidence. Current Bridge's fixed loopback Sigil and local Basic
credential supply none of this remote account boundary and must not be exposed over LAN/VPN.
[Companion](index.md) · [Android Development](android-development.md) · [Ward](../../sepulcher/extensions/ward.md)
---
title: "Professional Operations"
plain_name: "Apps: Professional operations"
section: "Compositions"
original: https://hexanomicon.dev/compositions/professional-operations/
guide: https://lychd.snayu.ai/docs/compositions/professional-operations/
---
# Professional Operations (Apps: Professional operations)
## Plain-English summary (Snayu)
**What it is:** Index of apps for client casework: Broker (insurance office cases) and Creation investigation (software questions), with a pointer to the Accounting Office study.
**Why it matters:** Start here to find the app for business casework, software investigation or accounting.
- Broker answers a client question, prepares an act, or hands off with a clear blocker.
- Creation investigation answers a public-source software question with a separately reviewed verdict.
- Accounting Office is a candidate study outside the accepted app list.
## Original text (Hexanomicon)
Client casework needs attributable answers, prepared actions, and clear handoffs. Broker provides
the first route in this Area. Professional uses may also appear in other Areas, according to the
application's records and judgment.
| Composition | Outcome |
| --- | --- |
| [Broker](../broker/index.md) | A client question answered from current offer knowledge, a prepared act, or a clear handoff or blocker. |
| [Creation investigation](../creation/index.md) | A public-source software question, exact analysis candidate and separately attributed verdict. |
For business records, reconciliation, and accounting handoffs, continue to the
[Accounting Office candidate study](../accounting-office/index.md). It explores those attributable
results outside the accepted Portfolio.
[Composition Areas](../index.md#areas)
---
title: "Creation investigation"
plain_name: "App: Creation (software investigation)"
section: "Compositions > Professional Operations"
status: "Partial"
original: https://hexanomicon.dev/compositions/creation/
guide: https://lychd.snayu.ai/docs/compositions/creation/
---
# Creation investigation (App: Creation (software investigation))
## Plain-English summary (Snayu)
**What it is:** An app that answers one bounded question about public source code, such as whether a test proves a change, by building an answer and then having a separate reviewer challenge it, keeping everything retained.
**Why it matters:** Read this when working on code-investigation workflows, verifier/reviewer roles or its Control Panel report.
- Inputs are tightly limited: up to 8 sources and 4096 source bytes, 512-byte question, 4 criteria.
- A separate reviewer gets the source, question and candidate, not the builder's conversation.
- No source edits, executable workspace or external fetching; a finished job does not mean a correct answer.
**Status:** Partial. Revision 2 workflow is implemented behind an explicit selector.
## Original text (Hexanomicon)
An engineer asks whether a test proves the change it claims to prove. Keep the exact source,
question and acceptance beside the answer, then ask a separate reviewer to challenge it. The
investigation should remain intelligible when its conversation and worker have ended.
## Contract
**`creation.investigation` revision `2`** publishes **`creation.investigate@2`** for bounded
public-source software investigation. It owns the immutable request, source bundle, role
reservations, inference attempts, candidate and attributed verdict. Run owns execution and delivery;
Dispatcher owns grants. The wider [Creation method](../../sepulcher/extensions/weaver/creation.md)
still guides design, editing and delivery under [SDLC law](../../adr/16-sdlc.md).
The return is a retained report and an accepted, rejected, partial or incomplete review, or exact
noncompletion. A complete response and a DONE Run do not establish semantic correctness. This
profile requests no source edit, executable workspace, external acquisition, promotion or automatic successor.
[State of Work](../../state-of-the-work.md#smith-forge-promotion) records implementation separately.
## Admit one question
Begin by preserving exactly what the investigation will examine. Admission retains canonical
request bytes, an explicit public-material declaration, literal UTF-8 source bytes and their
relative names, lengths and digests. It pins the declared repository/base or patch identity,
question, non-goals, criterion IDs, omissions, exact role bindings and acceptance.
The retained bytes let another reviewer reconstruct the question. A filename or hash alone is
insufficient, and the declared base identity is not an independently observed live Git tree.
Changed inputs require another request; an old report keeps its original target.
Revision 2 permits at most 8 sources and 4096 total source bytes, 512 question bytes and 4 criteria of
192 bytes each. Relative source names are bounded and cannot escape a root; duplicate keys/names,
malformed UTF-8 and inconsistent byte spans refuse. Canonical candidate and verdict each have a
1536-byte ceiling. Citations identify retained source bytes and valid spans; valid citations do
not make their interpretation correct.
Each role packet binds the canonical full request digest and its metadata, then projects ordered
sources as their original names, literal-byte digests and explicitly numbered lines. Line text
preserves its original UTF-8 bytes and terminators using the same byte-splitting convention as
citation validation. Rejoining those lines reconstructs each source and the canonical original
request exactly. Source text is not duplicated within the packet. Original request/source custody
stays unchanged; the model sees an attributed projection, not replacement source truth.
Deterministic line counts retain the inclusive, one-based citation limits. Both roles are guided
to cite the operative statement that supports a claim rather than an adjacent check. Explicit
numbers aid selection; neither valid addresses nor this presentation prove semantic entailment.
The model never repairs, clamps or extends its own citation. Projection overhead remains inside
the unchanged packet and verifier-candidate reservation limits: a dense short-line source may
refuse admission even within the source-byte maximum. No truncation makes it fit.
Role instructions state the existing per-field character maxima and 1536-byte total canonical
result ceiling, prefer concise findings and a short summary where present, and retain a writing
margin. These are model guidance; strict schema, source-span and byte validation remain the
acceptance boundary. Output schemas, hard limits, zero retries and original evidence stay
unchanged. Changed projection and instructions receive new instruction and implementation
identities under the same captured-profile fences; historical packets are not converted.
The fixed `public-source-qwen@2` profile selects one exact configured shared, non-dedicated local
Soulstone/vLLM/Qwen3.8-27B Chat capability. Its captured generation is 4096 context, 512 output,
temperature 0 and `qwen3.8-non-thinking`. Missing or changed binding, unsupported profile, unavailable
WARM grant or fallback refuses. No model lifecycle request is admitted. Agent and SDK retries are 0;
only structured final output is available, with no executable toolsets.
Reserve the work before construction: one logical application slot, one constructor attempt,
one verifier attempt and 30 seconds per role, plus 30 seconds for recovery, all within the
180-second original lifetime. An unresolved investigation continues to occupy that slot. These
are application allowances; they reserve neither exclusive GPU capacity nor a hard aggregate
quota. At each stage, recheck authority, expiry and grant.
The complete serialized role packet includes instructions, source, question, criteria and output
schema. Its 12288-byte envelope reserves the verifier's maximum candidate before construction.
Never truncate source, criteria or candidate to make it fit. Use supported pre-counts and the
existing per-request context/output guard. This local Chat profile has no pre-transmission token
counter: record that absence and check observed usage before adoption. Its observed input ceiling
is 3584 tokens, reserving 512 of the 4096 context tokens for output. A byte envelope does not prove
a hard 4096-token transmission bound or future provider availability. Invalid or over-budget
complete output settles as retained noncompletion, without a repair call.
## Construct, challenge and retain
The serial score is `PrepareInvestigation` → `ConstructInvestigation` → `VerifyInvestigation` →
`ProjectInvestigation`. Preparation may go directly to verification only for the exact continuation
below; known noncompletion goes to projection. Graph state contains owned references, not live
clients or a second copy of application truth.
Persist the stage's exact input binding and inference claim before its call. Retain the complete
provider response (at most 65536 canonical UTF-8 bytes) before interpreting or adopting it. Keep response identity, actual
usage, participant/capability identity and failure class. Immutable candidate bytes cannot be
replaced by a later answer.
Constructor and verifier have distinct AgentSpecs and fresh messages. The verifier receives the
original source, question, criteria and exact candidate; it receives no constructor conversation,
private deliberation or unrelated history. Record shared model/infrastructure and exposures.
Context separation is attributable review, not proof of a different sovereign or infallible judge.
A verdict links findings, contradictions and unknowns to criteria. No recursive judging or automatic
repair follows. [Tree faculties](../../sepulcher/extensions/weaver/creation.md#tree-relations-in-practice)
recur in framing, making, challenge and return; they do not require ten Agents or one universal score.
## Current local authority
The local profile has one credential-backed `local-operator` role. An actual current
`LocalOperatorAccess` marker plus the required Sigil scopes authorizes submit, read and cancel of
this application's local cases. Creation implements that explicit object/action policy; a scope
guard alone supplies none. This is not person-level tenancy or remote Ward identity.
Retained subject/generation fields are attribution, never credentials. Check the actual current
marker at each HTTP action, and the admission's current binding, exact case/action policy and Run
fence before inference claim and adoption. Revocation or startup change ends old authority. A new
credential holder reads historical cases under fresh current-role policy. Original initiator and
all later admission records remain immutable.
Explicit opt-in assembly selects revision 2 and its exact capability:
```toml
[weaver.creation]
revision = "2"
capability_key = ""
```
PostgreSQL and current local operator credentials are required. The capability must satisfy the
profile above; this selection cannot make a cold model ready. The protected local API exposes:
| Action | Route | Body |
| --- | --- | --- |
| Submit or replay | `POST /api/v1/creation/investigations` | Immutable request, including its request UUID, public declaration and literal sources. |
| Read retained state | `GET /api/v1/creation/investigations/{case_id}` | None. |
| Cancel adoption | `POST /api/v1/creation/investigations/{case_id}/cancel` | None. |
| Admit eligible continuation | `POST /api/v1/creation/investigations/{case_id}/continue` | New admission UUID and exact request, candidate and profile digests from retained state. |
Responses project the case, original request, admissions, attempts, candidate, verdict and exact
noncompletion. Generated OpenAPI owns the transport schema. Authentication, Origin and CSRF remain
server gates. The browser and callers do not create durable truth by display.
## Ordinary Altar intake and report
Bridge may offer this existing protected contract through an investigation focus at `/bridge`,
with only a case UUID in navigation. It submits the immutable public-source request and links
the returned exact admission Run to Orb; it does not convert an ordinary chat message or Atlas
next step into an investigation. The fixed profile, source/packet bounds and all server gates
remain unchanged. The [Bridge guide](../../divination/altar/bridge.md#investigate-public-source)
owns the ordinary interaction.
Browser sources and the submitted body remain transient. If submission is ambiguous, keep its
UUID and exact body without automatic retry. An explicit Check cannot turn an in-flight 404 into
proof of non-admission. Identical replay requires the original body, which reload does not recover.
Reading the protected detail can perform existing expiration and returns retained operational
records. The report renders validated request/candidate/verdict text. After awaited storage, it
still requires current read authority and fences a changed selection.
Use **Load feedback** for the separate protected historical projection; this read does not expire
execution. Current assessment/decision IDs select the displayed judgments. A later assessment
leaves an earlier owner hold historical. **Reload feedback** is explicit, and a refused read
clears protected feedback.
Distinguish Run completion from the native verdict, external assessment, and owner decision.
These are four separate facts. Report/reason text and server annotation coverage cannot establish a semantic
pass. Viewing authorizes no continuation, feedback mutation, successor, source edit or promotion;
explicit Refresh is needed to see later case changes.
## Selected-Run summary
The existing Orb selected-Run snapshot and retained-evidence feed may include an authorized
Creation summary. Its identity comes only from the retained exact admission-to-Run relationship;
workflow names, adjacent Sessions and browser state cannot establish it. Each read checks current
local-role authority, including every active stream poll. Missing metadata establishes neither the
existence of a case nor whether Creation is configured.
This dedicated metadata read does not expire or settle a case, release its execution slot, adopt a
response or load source, provider response, candidate or report bodies. It can report an elapsed
deadline while the slot remains encumbered. It separates constructor/verifier retention and
adoption, native status/verdict, latest external assessment and current owner decision. A historical
admission remains linked to its original Run while the summary explicitly describes the case's
current outcome, which may include later admissions. A newer assessment makes an older decision
non-current according to the feedback contract below.
Orb labels these details separately from Run execution status and its recorded-evidence playback.
The feed still closes when retained terminal evidence drains; later assessment and owner updates
need Refresh. This projection grants no Creation action or source-edit authority.
## External assessment and owner hold
The first feedback contract appends an external report and explicit local owner `hold` or `reject`
to a completed revision 2 case. It preserves the original CaseView, candidate, native verdict,
execution status, deadline and reservation. Implementation is recorded separately in
[State of Work](../../state-of-the-work.md#smith-forge-promotion).
An assessment UUID binds the retained request, profile, candidate and canonical native-verdict
digests. Derive its source identity from the canonical ordered list of `{name, digest}` entries,
where each digest covers the literal UTF-8 source text; derive criterion identity from the
canonical original ordered `{id, predicate}` list. Retain exact report UTF-8 bytes and digest
separately from the canonical intake body. Claimed reviewer label
and revision are bounded attribution, not authenticated external identity. Record actual current
submitting Sigil and authentication generation separately, with disclosed exposure and limitations.
External disposition is `accepted`, `rejected`, `partial`, `incomplete` or `not_assessed`.
Optional criterion/citation annotations belong explicitly to the submitter; absent criteria remain
not assessed rather than acquiring invented reviewer judgments. Citations resolve only to the
original sources and valid byte spans; they do not prove semantic entailment.
The report is at most 8192 UTF-8 bytes; reviewer label and revision are each at most 128 bytes.
Exposure and limitation lists each hold at most four 192-byte items. At most four annotations
identify distinct original criteria and use the existing bounded finding/citation shape. Canonical
assessment and decision bodies each fit 16384 bytes. Duplicate JSON keys, mismatched target,
unknown criterion/source, invalid spans and missing candidate/verdict refuse.
Feedback appends require an unencumbered completed case, all its inference claims resolved,
each bound Run terminal and its current delivery settled, and no corresponding active local Run
lease. Check these conditions and current local authority while holding the case lock, without
expiring or altering execution. Retained revision 2 closures need no current model/profile readiness
merely to receive feedback. Revision 1 writes remain refused.
To record the owner's judgment, bind a new decision UUID to the exact assessment id/digest and
target. Choose `hold` or `reject`, with a non-empty reason of at most 1024 UTF-8 bytes and an
optional distinguishing observation of at most 512 bytes. New decisions target the latest
assessment. All appends share one per-case sequence, and the latest decision for that assessment
is current. Another assessment makes earlier decisions historical and projects `review_required`
until the owner addresses it separately.
Replay preserves the original record. Before latest-target or capacity checks, an identical
canonical body returns its original row; changed or cross-case identity refuses. Every replay
still requires fresh current authority, and original attribution is never overwritten. The case
admits at most 16 assessments and 16 decisions, while identical replay continues to work at
capacity. There is no update or delete. Additive persistence preserves original custody, and
downgrade refuses while feedback exists.
The protected local routes use the same actual operator marker, object/action policy, Origin and
CSRF gates. Append requires `runs:submit`; read requires `altar:read`.
| Action | Route |
| --- | --- |
| Append or replay assessment | `POST /api/v1/creation/investigations/{case_id}/assessments` |
| Append or replay owner decision | `POST /api/v1/creation/investigations/{case_id}/decisions` |
| Read attributed feedback | `GET /api/v1/creation/investigations/{case_id}/feedback` |
The separate feedback view projects `unassessed`, `review_required`, `hold` or `rejected`, with
native status and external judgments alongside it. Native `accepted`, external `partial` and owner
`hold` can therefore remain visible together. A hold records this application's disposition; it
claims no global block on unrelated submissions or effects. Intake has no inference, queue,
continuation, profile renewal or execution-state mutation path. A next evaluation, source edit,
Atlas projection, training and promotion require their own contracts and admission. This first
attachment establishes neither a complete feedback handoff nor measured recursive improvement.
## Explicit successor admission
A separate current local operator may authorize **one new investigation** from exact settled
feedback. This is a new evaluation with its own immutable sources, question, criteria, acceptance,
current profile and reservation. It is not continuation of an expired case or retry of an inference
attempt. The parent keeps its deadline, candidate, verdict, feedback and disposition unchanged.
[State of Work](../../state-of-the-work.md#smith-forge-promotion) records implementation evidence;
this contract alone does not deliver a native handoff.
`POST /api/v1/creation/investigations/{case_id}/successor` requires current local authority,
`runs:submit`, Origin and CSRF. Its typed body retains a fresh complete `InvestigationRequest`,
`authorize_one_child: true`, the exact parent `FeedbackTarget`, latest assessment and current
owner-decision UUIDs and canonical-body digests, and a non-empty `changed_hypothesis` of at most
512 UTF-8 bytes. The operator supplies the new acceptance; report text and a hold or rejection
cannot authorize it. Raw and canonical intake each fit 16384 bytes; the nested request and both
role packets also satisfy all ordinary investigation bounds. No truncation or inferred fields
make an intake admissible.
The parent must satisfy the existing settled-feedback conditions, including resolved inference
claims, terminal bound Runs, settled delivery and absent active local leases. Its retained revision
2 contract may differ from the current execution profile, and its original deadline may have
passed: neither is renewed. Match the exact retained target and latest assessment/decision while
holding its case lock. An existing child cannot be retroactively attached. A case admitted as a
child cannot itself become a parent through this operation. Ordinary unrelated submissions remain
separately governed; this is not a global execution prohibition.
Before publishing the new Run, atomically retain the fresh child case, admission, exact lineage
body/digest and authenticated attribution. This commit permanently consumes the parent's one-child
allowance, even if publication later fails. There is no refund, second child, replacement UUID,
automatic retry or descendant chain.
The child needs its own authorized reservation: the existing one application slot, 180-second
lifetime and one constructor/verifier attempt, under the current exact profile and WARM
capability check. It neither renews nor reuses the parent's budget, and reserves no exclusive GPU
capacity or hard aggregate quota. Recheck actual authority after awaited preparation and lock
acquisition, at commit, and before releasing held Run publication.
Identical canonical-body replay under fresh current submit authority returns the original
lineage and child identities before freshness, capacity or model-readiness checks. Preserve the
original admission attribution. Repair may only reconcile that exact held delivery through the
existing Run idempotency path, under its original still-current execution binding; replay never
creates another admission, session, role attempt or reservation. Changed body, parent or child
identity refuses. A newer assessment before admission commit refuses the stale request; a newer
assessment after commit makes that lineage historical without rewriting or silently revoking the
already-admitted child. Revocation and normal Run/adoption fences still apply.
`GET /api/v1/creation/investigations/{case_id}/lineage` requires current local authority and
`altar:read`. It projects the retained incoming and outgoing lineage separately from the unchanged
CaseView and feedback views. Additive durable custody survives restart and refuses downgrade while
lineage exists. A successful child report is an observation, not evidence of semantic improvement,
independent task choice, source-editing authority, foreign-runtime containment or promotion.
## Revision continuity
Revision 2 is the only current selector and Pattern. Its exact `public-source-qwen@2` profile
raises the per-role output allowance from 256 to 512 tokens; the two-role aggregate ceiling is
1024 generated tokens. The context remains 4096, with 3584 reserved for observed input. Source,
packet, response and canonical output byte bounds, deadlines and one-shot attempts are unchanged.
The initial revision 1 live prototype retained a constructor response ending at its 256-token
limit and adopted no candidate or verdict. Keep that failed occurrence and its original bindings.
Current-role GET may read historical revision 1 cases. Creation write actions through selector 2
refuse their submit replay, cancellation and continuation; it never rewrites or executes those
records. Cancellation of a current revision 2 case checks its retained contract identity and
current local authority, not model availability or a freshly resolved capability. It grants no
execution or renewed reservation. Full profile matching remains required for admission,
continuation and stage adoption.
A later reviewed implementation closure (`py.3`) adds only this citation-coordinate guidance and
changes its instruction identities. Composition, Pattern and profile revisions stay 2: requests,
results, budgets, authority and recovery law are unchanged. Exact captured manifest/profile equality
refuses historical-closure execution or continuation; historical read and current-revision
cancellation retain their existing policy. The earlier implementation's invalid-span response remains
a failed occurrence. A new case may test the new closure; it never repairs or renews that occurrence.
A new profile requires a separately admitted case and reservation, not renewal of the old one.
Same-profile identical replay retains its existing identities without another inference.
## Interruption and continuation
Identical replay returns retained identities/results; conflicting replay refuses. Cancellation
fences application adoption before requesting Run cancellation; the actual Run state also wins
races. Late complete bytes may remain attributed evidence without accepted disposition.
A claimed call without a complete durable response remains incomplete/unknown. Timeout, cancellation,
expiry or startup cannot make it unclaimed or release its encumbered slot. Revision 2 has no automatic
unknown-outcome release. Known terminal completion or proved not-issued failure may release capacity.
Generic startup reconciliation remains unchanged: an orphan Run can become FAILED. Continuation
requires a separate decision by a fresh current local operator. At most one **new continuation
Run** may be admitted, and only while the original reservation is live, the prior Run/delivery/lease
is settled, the exact complete candidate is retained, and the verifier has never been claimed.
Match source/base/question/criteria/profile and candidate identities, retain the new authority
generation, and bind the Run before queue publication. It inherits the original deadline and
unused verifier/recovery allowance. It also has a recovery cutoff 30 seconds after its own
admission, bounded by the original deadline. The verifier therefore gets only the remaining time
and its single attempt. There is no renewed attempt or constructor replay. Cancelled, expired or
ambiguous cases cannot continue, and no scanner submits replacement Runs.
[Workflow](../../adr/28-workflow.md) · [SDLC](../../adr/16-sdlc.md) · [Portfolio](../index.md)
---
title: "Broker"
plain_name: "App: Broker (insurance office)"
section: "Compositions > Professional Operations"
status: "Designed"
original: https://hexanomicon.dev/compositions/broker/
guide: https://lychd.snayu.ai/docs/compositions/broker/
---
# Broker (App: Broker (insurance office))
## Plain-English summary (Snayu)
**What it is:** An app for a Slovak insurance intermediary handling client requests (starting with compulsory motor liability insurance): it carries each case to an answer, a prepared act, a human handoff or a clear blocker.
**Why it matters:** Read this before working on client-service casework or regulated advice workflows.
- The firm's legal role, products and named staff authority bound what the app may do.
- Must stop before unlicensed advice, payment, signature, binding cover or unsupported claims.
- Unrelated to LychD's internal queue broker despite the name.
**Status:** Designed. Contract only; no domain path enabled.
## Original text (Hexanomicon)
A client calls to check their [PZP](https://nbs.sk/en/dohlad-nad-financnym-trhom/legislativa/legislativa/detail-dokumentu/act-no-381-2001-coll-on-compulsory-motor-third-party-liability-insurance/) cover: compulsory motor third-party liability insurance. Before the office answers, it must establish the request, the product knowledge that applies, and the authority of the person handling it. Broker carries that service case to an attributable answer, a prepared act, a human handoff, or an exact blocker.
The reference office is a Slovak non-life insurance intermediary beginning with PZP. Its deployment fixes the firm's legal role, jurisdictions, represented institutions, disclosures, complaint route, record duties, and named human authority. Product configuration and fluent prose cannot expand that mandate.
## Open the office
[Cases](cases.md) follows the contact and requested action. [Insurance Product Knowledge](products.md) supplies dated coverage, eligibility, comparison, quote, and expiry evidence. [Channels](channels.md) admits contacts and projects reviewed results through separate staff, client, and technical surfaces.
## Contract
Admit one requested action with its `ClientContact@1`, business policy, product catalogue, and current staff authority. `broker.service_case@1`, published by `broker.office` revision `1`, carries that bounded case to its result. It must stop before unlicensed advice, undisclosed automation, payment, signature, binding, or unsupported product claims.
Broker names this application office. It is unrelated to LychD's internal queue broker.
[Composition Portfolio](../index.md) · [Workflow](../../adr/28-workflow.md) · [IAM](../../adr/38-iam.md)
---
title: "Cases"
plain_name: "Broker: Service cases"
section: "Compositions > Professional Operations > Broker"
status: "Designed"
original: https://hexanomicon.dev/compositions/broker/cases/
guide: https://lychd.snayu.ai/docs/compositions/broker/cases/
---
# Cases (Broker: Service cases)
## Plain-English summary (Snayu)
**What it is:** How each client contact becomes a service case with its own purpose, evidence, checks, review and single submission, so the next staff member can see exactly where it stands.
**Why it matters:** Read this when designing case records, verification checks or approval steps for Broker.
- Every fact records its source: imported, client-stated, staff-confirmed, model-proposed or provider-observed.
- The model can draft and explain but cannot invent premiums, exclusions or completed acts.
- Effects are submitted once; a missing acknowledgement parks the case for reconciliation.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
A renewal, a correction, and a request to explain cover can arrive through the same inbox. `ServiceCase` keeps each client's purpose and requested action distinct: check PZP, explain, compare, prepare renewal, correct, hand off, or name the blocker.
## Contact to outcome
Begin with the contact as it arrived. Preserve its native identity, time, attachments, provenance, and deduplication evidence before opening a case or matching an existing one. Establish the sender only to the assurance the channel actually proves. A familiar email, caller ID, or recognizable voice cannot authorize a protected read.
The case then fixes the work the office may undertake: purpose, requested action, policy, selected product releases, staff assignment, deadlines, consent, and current authority. As information arrives, retain whether each fact was imported, client-stated, staff-confirmed, model-proposed, deterministically derived, or provider-observed. A summary links back to that evidence so the next staff member can inspect its basis.
Before preparing an answer or act, run deterministic checks on identifiers, dates, money, required fields, eligibility, payload, and effect identity. A Mind may help extract, explain, and draft the material. It cannot fill a gap by inventing a premium, exclusion, client need, provider decision, or completed act. Review binds the exact answer or prepared effect; changed bytes need a new revision and review.
Submit an admitted effect once. If its acknowledgement is missing, park the same case for reconciliation. The case must tell the next worker who owns it, what it awaits, its deadline and pinned revisions, and whether its outcome is terminal or partial. On restart, stale authority, an expired quote, an unavailable Pattern, or an uncertain provider effect sends the work back to review. Replaying the conversation cannot resolve those conditions, and silence remains unknown.
Consent is also specific to the act. Conversation, record storage, call recording, disclosure of fields, and a financial effect each need their own consent. Revision one admits no medical record, credit judgment, affordability decision, payment, signature, or policy binding.
Use [Products](products.md) to establish the knowledge the case relies on and [Channels](channels.md) to understand how contacts and reviewed results enter or leave the office.
---
title: "Insurance Product Knowledge"
plain_name: "Broker: Insurance product knowledge"
section: "Compositions > Professional Operations > Broker"
status: "Designed"
original: https://hexanomicon.dev/compositions/broker/products/
guide: https://lychd.snayu.ai/docs/compositions/broker/products/
---
# Insurance Product Knowledge (Broker: Insurance product knowledge)
## Plain-English summary (Snayu)
**What it is:** How Broker keeps dated, attributable insurance product releases (coverage, exclusions, eligibility, pricing) and makes comparisons that state exactly which offers and criteria were considered.
**Why it matters:** Read this before working on product catalogues or offer comparisons in Broker.
- Refreshing the catalogue creates a new release; old comparisons keep their original reference.
- 'Best' is not a fact; a comparison must state its offer set, time, criteria and missing facts.
- The proof uses a synthetic firm and fake provider, with no live insurer or payment.
**Status:** Designed. Contract and proof plan.
## Original text (Hexanomicon)
Two eligible offers can be compared only after the office says which offers it considered and when. Broker's catalogue preserves governed business knowledge; a provider page or model answer cannot silently become its newest release.
Begin with an attributable release. It identifies the institution, coverage, exclusions, eligibility, required fields, price or quote method, fees and relationships, source evidence, effective period, jurisdiction, and expiry. A PZP case selects releases represented by the firm and validates the vehicle/client facts those releases require. Record live quotes separately so a temporary price cannot silently rewrite catalogue knowledge.
Refreshing the catalogue creates a successor release. A comparison already pinned to the predecessor keeps that reference and remains reconstructible.
The comparison must also explain its scope. “Best” is not a product fact: state the universe of offers, retrieval time, hard eligibility, criteria, fees/relationships, missing facts, and expiry. The evidence may support “lowest price among these eligible offers under these criteria.” When it cannot, narrow the answer, ask for missing facts, or block the case.
Throughout this work, pages, documents, and quotes remain hostile attributed input. Admitting a product list supplies knowledge to inspect; it conveys no advisory mandate or permission to bind, sign, purchase, or pay.
## Proving product knowledge
Give a synthetic Slovak firm a reviewed PZP release and a fake provider. The resulting eligible comparison must retain enough evidence to reconstruct its source universe. Missing facts, ineligibility, expiry, and provider timeout must produce distinguishable outcomes. No live insurer, medical data, payment, signature, or binding enters the proof.
Return to [Broker](index.md).
---
title: "Channels"
plain_name: "Broker: Channels and views"
section: "Compositions > Professional Operations > Broker"
status: "Designed"
original: https://hexanomicon.dev/compositions/broker/channels/
guide: https://lychd.snayu.ai/docs/compositions/broker/channels/
---
# Channels (Broker: Channels and views)
## Plain-English summary (Snayu)
**What it is:** How clients, staff and technical operators each get their own view (Business Console, Client Web, Control Panel) and how incoming messages and outgoing answers are handled safely.
**Why it matters:** Read this when designing Broker's user interfaces, intake channels or delivery.
- No view gives direct access to the database, model server or insurer.
- Incoming messages and attachments are treated as hostile data; credentials stay out of the briefing.
- The first proof admits email only; phone and public web need their own evidence.
**Status:** Designed. Contract only.
## Original text (Hexanomicon)
The client, staff member, and technical operator need different views of the same work. Email, forms, telephone, and future peer envelopes carry contacts and reviewed results; the case and staff mandate stay with Broker.
| Surface | What the reader can do |
| --- | --- |
| **Business Console** | Work with cases, releases, drafts, approvals, deadlines, and corrections. |
| **Client Web** | Submit bounded material and see authorized records and choices. |
| **Altar** | Inspect Runs, evidence, readiness, consent, and recovery. |
Each surface is a separate typed projection of permitted work. None opens a direct route to PostgreSQL, a model server, or an insurer.
Before using an incoming message, treat its prose, attachments, mail, audio, and provider material as hostile data. Keep credentials and raw client secrets outside Context. Processing locally still carries duties for access, retention, backup, export, and deletion. Remote inference adds another decision: the exact Context/Security privacy and egress policy must admit the transfer.
For delivery, bind the reviewed answer to its recipient and channel, payload digest, case/product revisions, current authority, expiry, and idempotency identity. A missing acknowledgement leaves delivery uncertain; reconcile it before retrying. This preserves the connection between what staff reviewed and what the client may actually have received.
Deletion begins by closing admission and draining or containing atomic work. It can then remove governed local derivatives while retaining explicit legal holds and an account of third-party custody.
The first proof admits email only. Telephone and public client routes must each establish their own authentication, recording, disclosure, and delivery evidence before joining it.
Return to [Broker](index.md).
---
title: "Connected work study"
plain_name: "Reach: Connected work study"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/
---
# Connected work study (Reach: Connected work study)
## Plain-English summary (Snayu)
**What it is:** A candidate study for a successor Reach that answers private email, GitHub issues and Discord mentions from the right account, plus optional WhatsApp, without mixing customers' data or authority.
**Why it matters:** Read this before planning Reach's real Gmail, Discord or GitHub integrations.
- Proposes a new contract, reach.correspondence revision 1, rather than widening the Discord one.
- Offline request preparation for all providers already exists; durable delivery does not.
- Covers proposed records, workflows, one durable delivery path and autonomy that survives updates.
**Status:** Designed. Candidate study; only offline preparation is implemented.
## Original text (Hexanomicon)
A client sends an email, a collaborator asks about an issue, and someone mentions the bot in a
Discord channel. Reach should be able to answer each in its own place, from the right account,
without carrying one customer's words or authority into another conversation.
This **candidate successor study**, researched **2026-10-21**, proposes native Gmail, Discord,
and GitHub connections, with an optional later [WhatsApp profile](whatsapp.md). It does not widen
the accepted [`reach.discord` revision `1`](../index.md),
its public-only deployment profiles, or their permissions. [State of Work](../../../state-of-the-work.md#composition-portfolio-delivery)
owns the implementation boundary.
The explicit [connected preparation profile](preparation.md), added **2026-10-29**, makes bounded
email, chat, forge and social request preparation executable without account access or delivery.
It adds Fastmail, Telegram and public social-post preparation alongside the initial providers,
with [account and advertising distinctions](social.md). Its finite WUPHF plan does not activate
the operational successor or supply its missing durable delivery machinery.
Browse the provider contracts by family: [Email](../email.md), [Chat](../chat.md),
[Forge](../forge.md) and [Social](../social.md). Those routes distinguish current request preparation
from each provider's proposed connected operation without creating separate application owners.
## Contract and ownership
The proposed identity is **`reach.correspondence` revision `1`**. Private correspondence, proactive
outbound messages, and preauthorized delivery materially change the old authority boundary;
silently adding them to `reach.discord@1` would reinterpret its contract. Acceptance would record
the successor relation explicitly under [Workflow's revision law](../../../adr/28-workflow.md#composition-identity-revision-and-retirement).
Historical Discord records retain their original meaning; there is no executable migration yet.
One Composition would own bounded correspondence across provider profiles. Providers vary
transport, audience, identity evidence, limits, and recovery. They do not each need an
application with a duplicate policy engine. Their adapters use native APIs behind typed host
ports; MCP is an optional future projection, not an execution dependency.
Reach owns connection configuration. It would decide which configured connection and admitted conversation a communication belongs
to, judge its audience and disclosure, and retain the proposal, delivery intent and result. It uses
the existing owners to carry out that work: Ward retains Principal, account linking, current grants
and revocation; HitL retains review/preauthorization; Spellweaver retains Patterns and admission;
and Workers retain jobs. The credential owner holds provider secrets and transport attempts.
A local result must still defer to provider records for the provider's external state.
Mail transport does not acquire accounting, client-case, publication, or software-change judgment.
Another Composition may submit an exact accepted artifact and a communication request. Coordinating
several live application Invocations requires a [Suite](../../products-and-suites.md#compositions-relate-without-nesting).
Forwarding between places is a new disclosure and delivery, never continuity inferred from matching
names, a common account owner, or one model.
## Three first journeys
| Profile | Input and bounded result | Initial stopping line |
| --- | --- | --- |
| [Gmail](gmail.md) | Search/read selected mail, propose or save a reply, send under exact review or standing policy; optionally apply admitted reversible labels/read/archive changes. | No mailbox settings, forwarding rules, permanent deletion, attachments, bulk campaigns, Calendar or Drive authority. |
| [Discord](discord.md) | A slash command or direct bot mention produces one bounded answer in an allowed channel. | No ambient surveillance, DMs, moderation, voice, attachments, or ordinary-user automation. |
| [GitHub](github.md) | Read admitted issue/PR conversations and propose or post timeline comments. | No code execution, code writes, formal approving reviews, merges, releases, workflows, checks or statuses. |
[WhatsApp](whatsapp.md) is an optional next channel with a different webhook deployment and
business/AI eligibility gates. Its limited-rollout owner–agent chat is a separate probe. Neither
route implies access to existing personal chats; the first three journeys do not depend on it.
An operator-originated message uses the same preparation and delivery path as a reply. Background
triage and follow-up enter through finite, deduplicated Schedule Occurrences, not a permanently
running model loop or a second application scheduler.
## Proposed records and Patterns
These names define application-local design contracts, not existing Python types or new Core stores.
| Record | Required meaning |
| --- | --- |
| `ReachConnection@1` | Local owner/partition; provider and immutable external account/application/installation ids; exact adapter/profile revision; credential reference and custody owner; granted provider scopes; local policy and revocation generation; lifecycle and last successful observation. An email address or login name is a mutable display field. |
| `ReachConversationRef@1` | Connection plus exact mailbox/thread, guild/channel/thread, host/repository/issue-or-PR, or qualified WhatsApp business-phone/recipient identity; audience and visibility evidence with observation time. No cross-connection identity merge. |
| `ReachEventAdmission@1` | Provider provenance and assurance, event/object identity and version, bounded payload reference/digest, partition, dedupe key, observation/cursor and admission outcome. Duplicate delivery and a later edit are different cases. |
| `ReachCommunication@1` | Purpose, caller, conversation/source references, pinned Pattern/Persona/Context, proposed sender/recipients/body, disclosure evidence, exact preparation digest, expiry, and formation outcome. Provider drafts are observations, not approved immutable preparations. |
| `ReachDeliveryIntent@1` | One immutable destination, actor mode, complete wire-payload digest, communication revision, effect identity, policy/Consent or preauthorization binding, and attempt/fence identity. |
| `ReachDeliveryReceipt@1` | Observed provider id/URL, attempt, payload binding, accepted/rejected/unknown outcome and reconciliation evidence. Provider acceptance does not prove reading, final email delivery, or agreement. |
The candidate catalogue is `reach.inspect_correspondence@1`, `reach.prepare_communication@1`,
`reach.deliver_communication@1`, `reach.reconcile_delivery@1`, and `reach.triage_correspondence@1`.
Each Scroll must close its exact typed inputs/results, effects, budgets and recovery before
registration. Inspection cannot silently invoke delivery; reconciliation cannot create a new send.
## One durable passage
```mermaid
flowchart LR
A[Provider event or operator request] --> B[Validate and deduplicate]
B --> C[Ward and bounded Context]
C --> D[Prepare exact communication]
D --> E[Review or standing policy]
E --> F[Commit delivery intent]
F --> G[Current authority and disclosure gate]
G --> H[Credential owner sends]
H --> I[Receipt or unknown outcome]
I --> J[Reconcile without blind resend]
```
First make incoming work recoverable. Commit intake before acknowledging durable custody or
advancing a cursor, and either commit cursor advancement atomically with the admitted work or
prove that their handoff can recover. Only then give a model the selected material and typed
capabilities. The model receives no token, unrestricted HTTP client or platform SDK: it proposes
a communication, while the host selects and validates the actual target.
Preparing a message freezes sender, To/Cc/Bcc or platform target, reply references, subject/body,
visibility, expiry, provenance and exact bytes. Review follows the existing [native action binding](../../../adr/25-hitl.md#required-review-for-native-actions-designed).
A provider draft edited after review cannot be sent through that approval. Destination, audience,
payload or policy changes require new preparation and authority.
The outbox records the passage through `PENDING`, `CLAIMED`, and `SUBMITTING`, followed by
`ACCEPTED`, `REJECTED`, `CANCELLED`, `EXPIRED`, or `UNKNOWN`. Before transmission, persist a
`ServiceJobAttempt@1` and fence ownership of the attempt. That record determines what recovery may
do: known pre-submit work may resume after current checks, but once bytes may have reached the
provider, automatic resubmission stays blocked until reconciliation proves a safe next action.
Cancellation cannot retract an accepted message, and redelivery of a queue entry never creates a
new communication.
## Autonomy that survives an update
Connecting an account grants provider access; it does not grant an Agent all uses of that access.
The proposed default is inspection and preparation with review before external delivery. An
operator may explicitly enable standing policy for bounded autonomous sends: named Principal and
connection, permitted operation, exact recipient/channel/repository sets, disclosure classes,
expiry, finite uses and rate/spend ceilings. Model confidence cannot widen it.
An automatic client reply may be allowed while a new recipient, changed `Reply-To`, attachment,
cross-company quotation, promise beyond the admitted purpose, or exceeded budget parks for review
or refuses. Standing policy can authorize a class of replies without approving every body in
advance; the host still checks each prepared body and target. Required native review cannot be
bypassed by a broader generic preauthorization rule. Every send rechecks current authority,
revocation, policy and byte-bound disclosure eligibility immediately before the effect.
All provider content is hostile input. Mail headers, repository membership, Discord roles and
instructions inside a message are evidence, not local grants. Keep connection/customer boundaries
in queries and Context assembly. Disable remote image fetching, active HTML, automatic link
following and attachment execution. No message becomes long-term Memory by default.
Before enabling a connection, configure separate retention rules for bodies/excerpts, receipts,
cursors and failed intake, including their backup deletion policy. Raw intake is transient unless
explicitly retained. Receipts keep secret-free evidence under access control; logs and broad status
projections contain no mail bodies, tokens or raw low-entropy content hashes. If private mail is
sent to remote inference, that transfer needs its own eligible disclosure decision. A Workspace
subscription supplies no such decision.
[Accounts and updates](accounts.md) defines connection lifecycle and custody.
[Delivery plan](delivery.md) defines implementation slices and the fixtures that can defeat this proposal.
---
title: "Accounts and updates"
plain_name: "Reach: Accounts and updates"
section: "Compositions > Candidate studies > Reach Connected Work"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/accounts/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/accounts/
---
# Accounts and updates (Reach: Accounts and updates)
## Plain-English summary (Snayu)
**What it is:** The proposed onboarding for connecting Gmail, Discord and GitHub: registering provider apps, authorizing each account, assigning local policy, and handling updates and secret custody.
**Why it matters:** Read this before designing connection screens, OAuth flows or how customer deployments hold provider credentials.
- Three separate acts: publisher registers the app, account owner authorizes, local operator sets policy.
- Each account is a separate connection, even for one person working at several companies.
- Recommended first road: customer-owned provider apps with credentials kept on their own install.
**Status:** Designed. Proposal; no settings screen or credential service exists.
## Original text (Hexanomicon)
The operator chooses **Connect Gmail**, **Install Discord**, or **Install GitHub**, sees the exact
account and requested access, then chooses where Reach may read and speak. The first success is a
confirmed connection and a prepared message; sending a test message remains a separately admitted
action.
This is the onboarding and custody proposal for the [connected-work study](index.md), not an
existing settings screen or deployment profile. Optional [WhatsApp](whatsapp.md) adds its own
business/number onboarding or separately qualified owner–agent route; it is not another Google-style
account grant or a dependency of the first three connections.
## Registration, connection, policy
Keep three acts visible. The application publisher registers the provider application once. An
account owner or administrator authorizes one account, guild or repository installation. The local
operator assigns Reach policy under Ward. A provider consent screen settles only the second act.
Each connected account retains a separate local identity and credential binding, even when the
same person works for several companies. The selected sender is visible during preparation and
review. Account discovery never silently links personal Gmail with a workplace, selects all
repositories, or enrolls external senders as local Users.
| Deployment choice | Customer setup | Secret custody and cost |
| --- | --- | --- |
| **Customer-owned applications, self-hosted authority** | Create/import exact Google, Discord and GitHub registrations, then authorize selected accounts. GitHub's manifest flow can reduce registration work. | App credentials and tokens stay at that installation. More first-install work; no shared publisher credential in customer packages. Recommended first road for the operator. |
| **Publisher-operated applications and service** | OAuth account consent or provider install link, followed by local audience/policy selection; administrators may need to approve access. | Publisher operates credential gates, callbacks, isolation, recovery and provider verification. Lowest recurring customer setup; a real hosted service obligation. Candidate later distribution road. |
A shared Discord token covers multiple guilds. A shared GitHub App signing key can obtain tokens
for its installations. Neither is a separate customer secret merely because a connection row is
separate. A self-hosted client must not receive the publisher's shared secret. A future credential
broker would need an exact per-installation protocol, custody/disclosure manifest and independently
authorized destination; it is not supplied by a generic OAuth proxy or by this study.
For Google, a shared confidential server client also stays with its trusted service. Customer-owned
registrations use their own exact callback. No wildcard callback or reusable authentication code
is accepted. A native installed-client flow would be a separately admitted deployment choice,
not a confidential server secret copied into a client.
## Connection lifecycle
`UNCONFIGURED → AUTHORIZING → ACTIVE` records installation/authorization and explicit account
confirmation. `DEGRADED` means transient service or quota failure; `REAUTH_REQUIRED` means expired or
revoked authorization; `SUSPENDED` means operator/provider policy denies work; `DISCONNECTED` closes
the connection. Status distinguishes these from a disconnected host and from unknown deliveries.
To authorize a connection, bind the authenticated local initiator to the chosen provider/client,
exact callback, short expiry, one-use state and PKCE where supported. Only the credential owner
may redeem and validate the grant, and activation must wait for confirmation of immutable provider
identity. Reconnection must retain an existing refresh token when the response omits one. Serialize
concurrent refreshes per connection and fence them by generation, so a late response cannot revive
a revoked grant.
Persist bearer tokens encrypted with separately scoped key custody. Configuration and database
records carry secret references; prompts, checkpoints, logs and ordinary backups carry no usable
bearer or decryption key. Restore must explicitly recover or reenroll the credential generation.
Disconnect in custody order: close admission and fence queued sends first, then stop watches/
subscriptions and retire that connection's authorization, installation binding and derived tokens.
A shared Discord bot token or GitHub App signing key also serves other installations; disconnecting
one guild/repository must not revoke it. Retiring an app-wide credential is a separate administrative
operation that enumerates and fences every affected connection.
Disconnection does not settle a send already submitted: that effect still needs reconciliation.
Remove content according to retention and holds, preserving the minimal lawful effect identity
needed to prevent replay. Deletion cannot erase a recipient's copy. On reconnection, confirm identity
and policy again; a valid token alone cannot release an old pending send.
## What an update asks of the user
| Change | Proposed handling |
| --- | --- |
| Bug fix or new logic within the existing contract and provider grant | Quiesced LychD generation update; retain connection ids, credential custody, cursors and effect identities. No routine provider reconnect or reinstall. |
| New optional provider capability | Keep disabled until its exact adapter/profile, local policy and required provider permissions are admitted. |
| Additional Google scopes or GitHub permissions; wider Discord access | Explain the increment and obtain provider/account-administrator authorization where required. Old installations keep their previous access until granted. |
| Revoked/expired grant, administrator block, lost key or changed client identity | Suspend affected work and request the exact repair. No retry loop or fallback to a different account. |
| Callback/host/custody change or schema/contract change | Explicit configuration/migration under Evolution; reauthorization when the provider requires it. Never drop outbox/dedupe state to make an upgrade pass. |
The lack of a provider prompt for an ordinary code release is an inference from the providers'
separation of application registration and runtime code; it is an acceptance target to verify,
not a promise that no provider will ever change its requirements. Executable extensions still
follow LychD's [one-process-generation rule](../../../adr/05-extensions.md#one-process-one-extension-generation).
## First deployment road
Propose `reach.home.connected@1`: one authority-host generation, outbound Discord Gateway/REST,
Gmail REST synchronization, and GitHub REST polling. Browser-based account authorization needs an
exact admitted callback reachable by that browser; steady-state polling does not need a public
webhook listener. An ordinary loopback application must not be exposed to create that callback.
Private mail and credentials remain at the authority host in separately scoped trusted services.
An optional remote ingress edge initially carries only bounded event hints whose provider state
the authority refetches; it cannot assert an enrolled caller or receive private Context. Public
Discord profiles remain unchanged and cannot become private-mail profiles through configuration
flags. Shared signing keys and bot tokens require a separately bounded publisher service road.
Before activation, the registered manifest must specify the exact services, secret references,
sockets, outbound destinations, callback routes, resource limits, migrations, authority epochs,
retention and restart/compromise recovery. If custody moves, fence the old generation and reconcile
pending effects before activating the new owner. Rotating its secret does not establish whether an
uncertain send occurred and cannot make that send safe to repeat.
The existing missing Ward, Composition selection, service-attempt and deployment prerequisites
remain delivery gates, recorded in [State](../../../state-of-the-work.md#composition-portfolio-delivery).
This proposal creates no service, port, token store or permissive local-authority substitute.
WhatsApp Cloud API would require the separately admitted webhook profile described in its
[assessment](whatsapp.md#intake-requires-a-different-deployment). Its message bodies are not
refetchable event hints by assumption; it cannot inherit this outbound-only road unchanged.
[Gmail](gmail.md) · [Discord](discord.md) · [GitHub](github.md) · [WhatsApp](whatsapp.md) · [Delivery plan](delivery.md)
---
title: "Acceptance and delivery"
plain_name: "Reach: Acceptance and delivery plan"
section: "Compositions > Candidate studies > Reach Connected Work"
status: "Designed"
original: https://hexanomicon.dev/compositions/reach/connected-work/delivery/
guide: https://lychd.snayu.ai/docs/compositions/reach/connected-work/delivery/
---
# Acceptance and delivery (Reach: Acceptance and delivery plan)
## Plain-English summary (Snayu)
**What it is:** The ordered implementation plan for connected Reach: close the contract, prove preparation, prove durable delivery, then qualify Gmail, Discord and GitHub, with failure tests for each.
**Why it matters:** Read this to see the build order and test cases for Reach's live provider integrations.
- First goal: one prepared email from the right mailbox and one known delivery after review.
- Delivery must survive restart, revoked access and lost responses without double-sending.
- Gmail is qualified first; each provider has specific falsifying fixtures.
**Status:** Designed. Plan; only offline preparation slice is done.
## Original text (Hexanomicon)
The first useful result is one prepared email from the correct mailbox and one known delivery
after authorized review. A successful API request alone cannot qualify Reach: it must survive a
restart, revoked access and a lost response without sending the same message twice by assumption.
This is the implementation plan for the [candidate successor](index.md). The separate
[connected preparation profile](preparation.md) implements pure account/target/payload preparation
and a finite native Graph. It supplies no operational successor registration, provider transport,
credential service or deployed capability.
## Ordered slices
1. **Close the contract.** Accept or revise the proposed `reach.correspondence` identity, records,
provider profiles, authority/privacy boundaries, Patterns and successor relation. Register no
empty package to imply acceptance. Any shared-law change belongs to its existing Covenant.
2. **Prove preparation without providers.** Pure application policy plus typed fake ports exercise
account selection, bounded reads, hostile input, exact communication preparation, required native
review, standing-policy constraints and finite retention. Initially no model/network is needed.
The offline connected profile now covers exact preparation and provider request construction;
its preparation policy is deliberately not standing delivery authority or native review.
3. **Prove durable delivery.** Add Composition-owned PostgreSQL models/migration/store and
transactionally bound intake, communication, outbox, authority generations and effect identity.
Bind existing Run/Consent/worker ownership without a second workflow executor. Exercise restart,
racing claims, revocation and reconciliation with inert effects and a disposable database.
4. **Qualify Gmail first.** Customer-owned internal/personal-use registration, bounded polling,
read/draft/review/send, current authorization, and Sent reconciliation. Start with the operator's
account after the required credential and deployment seams exist. Attachments/Calendar/Drive and
push are separate increments. Mail migration is independent of connector development.
5. **Qualify Discord and GitHub separately.** Reuse prepared-message policy and delivery machinery;
add exact platform identity, semantics and recovery. Prove one allowed Discord turn and one
issue/PR timeline comment, including each provider's unknown outcome.
6. **Package client onboarding.** Connection/status/review projections, customer-owned registration
assistance, compatibility/update checks and disconnect/delete. A publisher-operated application
comes only with its credential service, verification, isolation and support envelope qualified.
7. **Revisit optional WhatsApp.** Qualify business assets, actual use/market eligibility, current
pricing, template/window/opt-out policy, human escalation and its new HTTPS webhook profile.
Probe the separate personal owner–agent platform only where rollout and its developer contract
are confirmed. Neither path gates delivery of the initial three connectors.
## Smallest falsifying fixtures
| Boundary | Required counterexample and observation |
| --- | --- |
| Ownership | Two companies and personal mail share one instance. Cross-connection reads, wrong sender, forged external identity and broad status access refuse before disclosure. |
| Hostile content | A mail/issue/comment instructs the agent to reveal secrets, follow a link, change recipients or run code. It remains attributed content and produces no extra authority or network call. |
| Review and autonomy | Review binds exact body/recipients/actor. A changed draft, expired policy, new `Reply-To`, exhausted use counter, required-review bypass or changed audience cannot send. A matching finite standing policy can send without another human verdict. |
| Durable custody | Crash at each intake/cursor/admission and outbox/claim/submit/settlement boundary; recover all admitted work, preserve unknown effects and reject stale claims. Race two claimants and prove no second submission merely from queue replay. |
| Revocation | Revoke during preparation, review wait, token refresh and immediately before transport. Later work is fenced; already-accepted bytes remain honestly irreversible. Reconnection does not release old pending sends. |
| Gmail | Duplicate/out-of-order changes, pagination, expired-history 404, missing refresh token on refresh/reconnect, scope refusal, draft-create/send timeout, delayed readback and vanished draft without proof. No duplicate from full resync or ambiguous draft creation; optional label changes need their own exact effect/desired-state evidence. |
| Discord | Explicit mention versus ambient content, Gateway resume failure, three-second deferral, expired interaction token, mention injection and send uncertainty beyond nonce guarantees. No private authority from a role or interaction. |
| GitHub | Delivery replay or edited comment, untriggered activity, own-app reply loop, bad signature, removed repository, missed deliveries outside redelivery history, timeout after comment creation and forged matching marker. One reply cannot trigger another; correlation must also match app author, destination and admitted bytes. |
| Optional WhatsApp | Expired response window, paused template, opt-out, human takeover, forged/duplicate/late webhook, unknown send and delayed delivery, shared-account disconnect, spend or market-policy refusal. No access to other personal chats or unavailable agent rollout is inferred. |
| Limits and lifecycle | 429/403/quota exhaustion yields bounded waiting; revoked credentials stop retries. Disconnect one of two shared-app installations without revoking the other. Disconnect, retention, backup restore and generation upgrade preserve dedupe/effect identities and cannot resurrect a send. |
| Custody | Each service can read only its declared secrets/routes. A customer package has no shared publisher signing key/token. Logs, model Context, checkpoints and status contain no bearer secrets. |
Use these fixtures to test the provider's actual limits as well as local recovery. Each adapter
must declare what its provider can prove about an ambiguous write. When the evidence cannot
exclude a prior send, qualification requires a visible unresolved result and no automatic
repetition. A fake provider cannot establish an exactly-once guarantee the real provider lacks.
## Owners and delivery gates
| Required seam | Existing authority |
| --- | --- |
| Composition revision, Pattern/Scroll closure and event/schedule admission | [Workflow](../../../adr/28-workflow.md) |
| Current identity, account linking, object authority and revocation | [Ward](../../../adr/38-iam.md) |
| Exact review, standing preauthorization and re-admission | [HitL](../../../adr/25-hitl.md) |
| Secret custody, hostile input and per-transmission disclosure | [Security](../../../adr/09-security.md) |
| Transactional records, outbox and migration/recovery | [Persistence](../../../adr/06-persistence.md) |
| Durable service attempts and retry ownership | [Workers](../../../adr/14-workers.md#service-job-attempts) |
| Sealed contributions and generation replacement | [Extensions](../../../adr/05-extensions.md), [Evolution](../../../adr/18-evolution.md) |
| Exact service manifest and callback/ingress selection | [Containers](../../../adr/08-containers.md#versioned-application-deployments), [Configuration](../../../adr/12-configuration.md#application-and-gateway-profiles) |
Before implementation, reconcile the chosen slice with those owners and current
[delivery evidence](../../../state-of-the-work.md#composition-portfolio-delivery). The existing
public-only Discord profile and credential-gated loopback bootstrap supply no private remote IAM,
general service-attempt runtime, Composition selector or connected deployment by themselves.
Private mail must not be exposed through a convenient callback or permissive local-authority shim.
After deterministic proof, qualify the live path separately with one test account/repository/guild
and an explicitly admitted message. Observe real expiry/revoke/429 behavior where feasible, then
exercise reconnect and a generation upgrade. Record which observations actually occurred. This
design itself authorizes neither production-wide permissions nor external sends.
[Accounts and updates](accounts.md) · [Gmail](gmail.md) · [Discord](discord.md) · [GitHub](github.md) · [WhatsApp](whatsapp.md)
---
title: "Companion Android Foundation"
plain_name: "Companion: Android foundation study"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/companion/android-foundation/
guide: https://lychd.snayu.ai/docs/compositions/companion/android-foundation/
---
# Companion Android Foundation (Companion: Android foundation study)
## Plain-English summary (Snayu)
**What it is:** A candidate study for building the live Android client on a Samsung S20 FE: pairing with LychD, voice capture, transcript review, submission and spoken replies, with chosen languages, frameworks and API rules.
**Why it matters:** Read this before making technology or architecture decisions for the Android client.
- Kotlin with Jetpack Compose on Android; Ktor for HTTP and events; Android Keystore for credentials.
- Speech runs on the host, not the phone; pairing uses a TLS client-certificate candidate.
- Pairing, live transport, transcription and synthesis remain future work.
**Status:** Designed. Candidate study; only the development slice is built.
## Original text (Hexanomicon)
Build Companion first as a native Android Bridge and foreground voice client on the Samsung
S20 FE. Pair with the operator's LychD, record a short deliberate utterance, review its transcript,
submit the chosen words, and present the settled reply with optional speech. A folder-first music
player, selected photos, and explicit copy sync can grow from that foundation.
This candidate study, opened **2026-10-09**, develops the construction choices beside
[`companion.mobile` revision `3`](index.md). It accepts no successor Composition, Suite, remote
ingress, or phone execution contract. The priority is now Bridge and voice; [Phone
Workspace](phone-workspace.md) retains the broader everyday-phone direction. [State of
Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery.
[Android Development](android-development.md) now describes the first implementation under
`clients/android/**`: a schema-derived Bridge fixture and bounded local recording/replay.
Pairing, live transport, transcription, synthesis, semantic event subscription and the native
handoff/result journey in this study remain future work.
## Language and frameworks
Keep **Kotlin and Jetpack Compose** for Android. Keep **Python and Litestar** on the host and
**Svelte 5 with static SvelteKit** for Altar. The clients share generated wire contracts and
compatibility fixtures; each owns its platform UI and interaction state. They reference the same
authorized host records rather than acquiring application authority through a shared client
library.
| Layer | Initial construction choice | Reason and boundary |
| --- | --- | --- |
| Android UI | Kotlin, Compose, Material 3 | Direct access to Android capture, lifecycle, credentials, storage, and media APIs. |
| Interaction state | ViewModel, coroutines, StateFlow | Explicit recording, review, submission, reconnect, and presentation transitions. |
| HTTP and events | Ktor client with one explicitly selected CIO engine candidate | Coroutine-based HTTPS uploads, JSON, and SSE; exact TLS/Keystore and lifecycle behavior must pass the handset probe. |
| Wire data | Generated Kotlin DTOs compatible with kotlinx.serialization | Host-owned schemas, with handwritten client orchestration and semantic validation around generated shapes. |
| Credentials | App-scoped Android Keystore | Device/application key custody; actual security level and invalidation behavior are device facts. |
| Capture | AudioRecord | Count samples and bytes, stop locally, and produce one bounded recording. |
| Reply playback | Media3 ExoPlayer in the foreground | Decode admitted speech artifacts; background music later adds MediaSessionService and its own controls. |
| Speech execution | Host Echo with the accepted audio.cpp candidate profile | The phone needs no inference runtime for the first journey. |
| Preferences | DataStore | Non-secret settings and selected host preferences. Add a database only when retained client records require one. |
| Build | Gradle Kotlin DSL and a pinned wrapper | One reproducible Android project under `clients/android/**`. |
[Compose setup](https://developer.android.com/develop/ui/compose/setup) supplies the native
project route. [Keystore](https://developer.android.com/privacy-and-security/keystore) protects
key material but does not guarantee StrongBox or hardware backing on every device. Credential
secrets must not become ordinary DataStore preferences.
The first implementation uses an Android `app` and a pure JVM `core` for SDK-independent wire
and interaction tests. Keep platform capture, playback and UI inside `app`; extract additional Gradle modules when a
second feature or app establishes the need. Android's [modularization
guide](https://developer.android.com/topic/modularization) supports sharing features across app
modules and also identifies the overhead of excessive subdivision. Avoid a speculative module
tree, dependency-injection framework, database, or plugin runtime before the first journey needs it.
### Alternatives and reopening conditions
| Alternative | Useful strength | Condition that would justify it here |
| --- | --- | --- |
| Flutter and Dart | Shared mobile UI with typed native integration through Pigeon/platform channels | Simultaneous Android and iOS delivery becomes a concrete requirement worth maintaining Dart and native integrations. |
| React Native and TypeScript | React UI plus typed native module specifications and Codegen | A real React mobile product or reusable React codebase establishes the benefit. Current Svelte screens supply no direct React reuse. |
| Kotlin Multiplatform | Shared Kotlin logic across clients | A second supported client needs an identified transport/state library. Android UI can remain Compose. |
| Direct OkHttp | Thin Android HTTP/SSE integration | Its publication lineage is verified and a matched transport probe establishes an advantage over Ktor. |
| Rust or C++ core | Portable native compute and established engines | A measured inference, DSP, integrity, or existing native-library requirement earns JNI/ABI packaging. |
The platform integration requirements are documented in [Flutter's
guide](https://docs.flutter.dev/platform-integration/platform-channels) and [React Native's native
module guide](https://reactnative.dev/docs/turbo-native-modules-introduction). Kotlin's [platform
table](https://kotlinlang.org/docs/multiplatform/supported-platforms.html), Ktor's [engines](https://ktor.io/docs/client-engines.html)
and [SSE client](https://ktor.io/docs/client-server-sent-events.html), and Android's [native
ABIs](https://developer.android.com/ndk/guides/abis) establish available mechanisms. The preference
for native Kotlin is a construction judgment for this Android-first workload, not a measured
battery, memory, or latency result.
Ktor earns its place through coroutine cancellation and its existing SSE plugin, independently of
any later Multiplatform extraction. Keep all Ktor artifacts on one reviewed version, select the
engine explicitly, and disable automatic reconnect until the retained-result recovery contract
passes. Keep private-content diagnostic buffering off. CIO supports Android and HTTP/1.x; an
HTTP/2 requirement or failed Android Keystore/TLS integration reopens the engine choice. Change
the engine through the same transport probe rather than weakening the credential contract.
The strongest cost is separate Android and Svelte presentation code. Shared schemas reduce wire
drift; they do not remove that UI work. A demonstrated second-platform requirement can reopen
the mobile sharing choice without reopening Altar's accepted architecture.
## Bridge and the host boundary
Companion reaches **LychD's protected API**, not the Altar browser process. Altar and Android are
two projections of host-owned work. Existing text Bridge behavior is useful evidence, but its
send operation immediately admits a Run. Companion submission instead settles an exact handoff
before the destination independently decides whether to admit work. Relabeling a Bridge response
would lose that distinction.
The host's current [Bridge controller](https://github.com/hexanomicon/lychd/blob/main/src/lychd/interface/web/bridge.py)
and [web contracts](https://github.com/hexanomicon/lychd/blob/main/src/lychd/domain/web/contracts.py)
provide session reads, `sendBridgeMessage`, Run snapshots, cancellation, and semantic events.
`MessageIntent` currently carries a request UUID and text prompt; it supplies no Companion device,
utterance, expiry, disclosure, or exact requested Pattern binding. Its request identity is not a
complete mobile authority or recovery contract.
The first product promising capture through an eventual answer needs a **named candidate
Suite**, with **Communion Bridge** as its proposed working name. Its construction design must coordinate:
1. Echo recording/transcription and the operator's reviewed words.
2. Companion's separately settled `submit_turn@1` handoff.
3. Independently admitted destination work, with exact Pattern and Invocation/Run correlation.
4. Aggregate wait, destination cancellation, interruption, expiry, and recovery.
5. A fresh authorized `present_result@1` against the exact settled destination reference.
The Suite identity and accepted score remain an owner decision before implementation. A smaller
fixture can prove separate submission and presentation against a typed handoff sink and a
pre-settled result. It must describe that smaller promise. [Utterance](utterance.md) and
[Return](return.md) own the accepted handoffs; the Suite does not move destination effects or
finish judgment into the phone.
```mermaid
flowchart LR
A[Android Companion] -->|HTTPS JSON and bounded audio| I[Protected mobile ingress]
W[Altar] -->|Host API projection| H[LychD owners]
I -->|Ward identity and current object authority| H
H --> E[Echo speech and audio custody]
H --> C[Companion handoff and presentation]
C --> S[Candidate Communion Bridge Suite]
S --> D[Independently admitted destination work]
D -->|Settled result reference| C
```
### Pairing and authorization
Implement a separately admitted mobile ingress before a real LAN journey. The current
credential-gated loopback Altar must retain its existing boundary; neither forwarding it nor
copying its password provides remote identity. [Ward](../../sepulcher/extensions/ward.md) owns
enrollment, credentials, sessions, grants, and revocation; [Remote
IAM](../../state-of-the-work.md#remote-iam) records the missing execution seam.
A first pairing candidate uses a standard TLS client-certificate credential adapter with an
app-generated Keystore key for the initial single-operator owned-device fixture. An
operator-initiated, expiring enrollment offer conveys the expected host identity through a QR
or manually verified channel. Enrollment proves key possession and
binds the phone application separately from the initiating human. Ward resolves the credential
to a Principal and evaluates current object-scoped authority; a valid certificate alone grants
no application operations. Exact certificate issuance, rotation, revocation, host trust and
host-key replacement must be specified and tested before exposing the ingress. Use established
TLS/credential implementations rather than designing encryption or signing primitives.
This private profile proves the enrolled application key, not the identity of the human currently
holding the phone. Ward separately retains the initiating human, permitted acting-for relation,
and current grants; a certificate subject, QR possession, or phone unlock cannot create them.
For a product requiring human login, shared devices, account switching, or sign-in across Altar
and several apps, prefer a Ward-owned native OAuth authorization-code flow with PKCE through an
external browser and a reviewed [AppAuth implementation](https://github.com/openid/AppAuth-Android).
[Native OAuth guidance](https://www.rfc-editor.org/rfc/rfc8252.html) supports that flow; it does not
require OAuth for the private device fixture. The host issuer, audience, redirects, token
lifecycle, and browser-trusted HTTPS origin must exist first. QR trust installed in the app does
not establish browser trust. Device enrollment remains separate; DPoP or another sender constraint
needs its own admitted implementation and cannot be inferred from PKCE or Keystore use.
Complete enrollment before Familiar body admission, then use that admitted body for Companion
device/session admission. Pin credential and policy generations and the phone capability epoch.
Android permission and URI access add local checks; the target/platform matrix must also resolve
Android's [local network permission rules](https://developer.android.com/privacy-and-security/local-network-permission).
After admission, every protected read, stream, artifact download, submission and effect still
checks the requesting object and current authority. Revocation closes affected live access and
refuses new work. LAN discovery and later VPN reach may change addresses, but they do not change
these grants.
No provider, database, host-lifecycle, signing, or workflow secret belongs in the phone. APK signing,
device credentials, and a later Tether key have separate lifecycles. Reinstallation, key
invalidation, and restoration require explicit reconciliation or enrollment rather than a copied
credential backup.
## First voice profile
Use visible foreground push-to-talk and **record and send**. A proposed device fixture admits
mono PCM16 WAV at 16 kHz, at most 15 seconds and 512 KiB. Its maximum PCM payload is 480,000
bytes; the container also counts toward the byte ceiling. These are candidate fixture limits,
subject to capture and decoder verification on the exact S20 FE variant and installed OS.
[AudioRecord](https://developer.android.com/reference/android/media/AudioRecord) gives the app
sample reads; it does not itself supply the WAV file or lifecycle policy.
Stop capture on button release, local stop, permission loss, lock, or leaving the foreground.
Release the microphone and show failure if capture ends unexpectedly. The first path has no
background microphone service. Later service use must satisfy Android's [microphone foreground
service rules](https://developer.android.com/develop/background-work/services/fgs/service-types#microphone).
Upload the completed bounded file over authenticated HTTPS to the future host custody interface.
Validate actual codec, channels, rate, duration, bytes, digest, parser limits, retention, and
authority before transcription. Raw voice remains restricted and ephemeral by default, excluded
from logs, analytics, Graph checkpoints, queue bodies, and device backups. Offline material is an
expiring reviewable draft; reconnect never sends or executes it automatically.
[Echo](../../sepulcher/extensions/echo.md) already selects audio.cpp as the first local runtime,
Parakeet TDT 0.6B v3 as an Ear candidate, and Supertonic 3 as a Voice candidate. Upstream
[audio.cpp](https://github.com/0xShug0/audio.cpp) and the [Parakeet model
card](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) declare Slovak and English support for the
relevant profiles. Declared languages still need the exact runtime/model bake. Parakeet's
automatic language detection does not prove a language-forcing parameter. Low-confidence or
uncertain words require review; recognition must never silently translate an utterance.
Show the transcript as an attributed draft. Edits retain their relation to the recognized words;
only explicit Send admits the final words. Always retain the authorized settled text result if
TTS fails. Optional speech uses a selected exact output language and voice, visible playback,
speech audio attributes, audio focus, and immediate local stop. Handle calls and focus loss under
Android's [audio focus rules](https://developer.android.com/media/optimize/audio-focus).
Use Media3 ExoPlayer for the admitted foreground reply. A later [music
service](https://developer.android.com/media/media3/session/background-playback) adds its own media
session and background lifecycle; speech and music retain separate operation and receipt state.
Capture stop, playback stop, Companion session cancellation, and Suite/destination cancellation
are distinct actions. Record offered, received, playback started, completed, interrupted, and
unknown separately. A playback callback is device-observed delivery evidence, not proof that a
person heard or understood the reply.
Android's [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)
may use a remote service. Explicit on-device recognition requires platform and engine availability;
its API proves neither an open engine nor Slovak support on this phone. Platform TTS has similar
engine and network qualifications. The first host speech route therefore keeps the engine,
models, custody, and languages explicit.
Start with HTTPS upload/download and JSON/SSE for control and observation. Batch audio needs no
WebRTC or bidirectional socket. Response streaming can follow after capture closes. Full duplex
requires the separate timeline, echo cancellation, barge-in, turn ownership, and epoch fences in
[Audio](../../adr/37-audio.md#streaming-without-pretending-a-socket-is-a-protocol).
## API design coverage
The following is a **candidate operation inventory**, not an implemented route catalogue or
frozen wire schema. It covers the first batch journey and identifies each receiving owner.
Controller paths, operation IDs, concrete DTOs, error variants, and security metadata must be
closed in the owning backend contract before Kotlin generation. Companion has no universal
`execute`, shell, arbitrary Intent, or phone-admin operation.
| Operation group | Required request and result meaning | Receiving owner |
| --- | --- | --- |
| Contract and capability negotiation | Supported protocol/operation revisions, required features and server-owned limits; compatible profile or explicit refusal | Each receiving owner and protected ingress |
| Enrollment offer and redemption | Expected host identity, one-use expiring offer, key proof, application identity; exact credential and Principal references | Ward |
| Credential status, renewal and revocation | Exact credential transition/generation and revocation result; operator-authorized revocation distinct from local disconnect | Ward |
| Body and device admission | Exact capability snapshot/epoch, limits/stops, Ward references; Familiar body and Companion device records | Familiar, then Companion |
| Session open and close | Exact device/body, current grant, purpose, configuration, privacy and feature profile; session identity and settled closure | Companion |
| Audio upload and commit | Identified upload, actual bounded bytes, digest and validated audio facts, expiry/retention; immutable artifact reference or exact refusal | Echo and Reliquary custody |
| Transcription request and retrieval | Exact artifact, admitted Ear profile and language policy, attempt identity; attributed draft transcript, uncertainty, or failure | Echo |
| Reviewed turn submission | Exact reviewed Intent, requested Pattern, device/session/utterance, Principal, expiry, disclosure and correlation; idempotent settled handoff | Companion |
| Handoff lookup | Authorized utterance/request identity; settled handoff, exact absence, or refusal without resubmitting | Companion |
| Coordinated round trip | Handoff reference and destination admission; aggregate state, settled references, wait/cancel/recovery account | Candidate named Communion Suite |
| Destination observation | Exact authorized Invocation/Run; snapshot, retained result and bounded semantic events | Destination and existing host projection owners |
| Result presentation | Exact settled terminal reference, utterance/device, fresh authority, text/speech policy; presentation identity and receipt | Companion using Echo |
| Speech synthesis and download | Exact accepted words, Voice/language/profile, custody and expiry; audio artifact and scoped byte access | Echo and custody owner |
| Device delivery account | Presentation/attempt/artifact, local epoch and sequence, observed receipt/playback stages; accepted account or rejected stale report | Companion and Echo |
| Reconnect and event recovery | Object/account identity and acknowledged cursor; authoritative replacement or explicit capture gap | Each record owner |
| Material discard, deletion and export | Exact authorized material, retention and provenance; observed custody result separately from enrollment or destination cancellation | Custody and material owners |
Local recording controls require no server response to stop. Local disconnect releases connections
and capture; it does not invent server revocation or destination cancellation. A protected artifact
reference is not a bearer download URL. Capability reports describe observations, not permission
to execute a reported capability.
### Wire and recovery rules
Give each effectful candidate operation a stable request identity and canonical request hash.
Bind exact operation/version, target, expiry, current grant/credential/policy generations, and
correlation. The host must check declared generations against its own state before accepting
them as more than caller claims.
The first admitted terminal result wins. An identical duplicate returns the retained account;
changed payload under the same identity conflicts. Specify duplicate-in-flight behavior, retention
and replay horizon explicitly. If acknowledgement is lost, query the original identity before
proposing another attempt. Unknown remains unknown until reconciled, and reconnect alone neither
widens nor renews authority.
Saving an operation identity cannot atomically commit a Media3, Binder, filesystem, or external
app effect with its receipt. A crash between the two leaves an explicit reconciliation problem.
Prefer desired-state commands bound to an expected revision where possible; relative changes
such as append or next may remain unknown and must not be blindly replayed. Current observed
state can help reconcile without proving the full action history. An Intent launch reports the
launch/request observation, not another application's completed work.
Separate HTTP acceptance, handoff settlement, destination admission, destination completion,
synthesis, and device playback. Error contracts must distinguish malformed/oversized audio,
authentication failure, wrong object/audience, revocation, expiry, identity conflict, missing
capability, unavailable model/language, storage failure, overload, and unknown outcome. Specify
which failures permit retry and whether they require a new occurrence or reviewed request.
Transcribed words remain input data: they cannot install a Pattern, mint a Grant, change a
credential, or enlarge an effect's admitted scope.
Existing Altar [typed JSON and semantic SSE](../../adr/15-frontend.md#typed-json-and-semantic-sse)
provide the contract-generation route. The current exported schema has no Companion/Echo/Ward
mobile operations; its REST shapes also do not close broad event payload semantics. Publish
security requirements, all actual error responses, upload media types/limits, cursor headers,
pagination, and compatibility policy in the future schema. Keep runtime authorization tests
independent of schema generation, since the existing schema exporter does not run middleware.
Seed the Android event reducer from an authoritative snapshot. For each event, validate schema
version, account/host/object identity, event ID, sequence, kind, and every consumed payload. Ignore
duplicates; a gap or `resync` requires a bounded authoritative refetch.
Fence late responses after logout, host/account switch, revocation, teardown, or local generation
change. Retained results take precedence over incomplete token streams. The SSE socket being
connected proves neither current authority nor durable event retention. Bound queues, event
bytes, concurrent streams, backoff, and request deadlines. After ordinary Android background
suspension, recover from a snapshot on return.
The [OpenAPI Kotlin generator](https://openapi-generator.tech/docs/generators/kotlin/) is a
candidate mechanism, with documented limitations around nulls and composite schemas. A bootstrap
probe must generate a small DTO slice from the exact OpenAPI 3.1 schema and prove absent versus
null fields, enums, discriminators/unions, identifiers, timestamps, errors, and event fixtures
against Python and TypeScript. Pin the successful generator/version/configuration; do not treat
generated code as policy or handwrite a competing transport schema when a generator fails.
## Growing into phone capabilities and more apps
Use the same explicit operation layer from local controls and later authorized agent requests.
Each capability declares its owner, operation revision, Android permission/role, target type,
limits, foreground/background eligibility, expiry, stop/refusal behavior, and observed result.
Local handlers recheck Android access immediately before the effect. Runtime capability data
enables an admitted implementation; it never supplies executable code or new authority.
| Extension form | Construction and authority boundary |
| --- | --- |
| Companion feature | Compile Kotlin/Android code into an operator-built APK; reuse tested transport, UI and platform adapters. |
| Additional owned Android app | Reuse Gradle library modules; give the app its own package, signing/enrollment identity and permissions. Expose only required explicit Intents, content providers, or Binder APIs with caller checks. |
| Host LychD package | Use the selected native Python Contribution surface and receiving owner in [Extensions](../../adr/05-extensions.md); activation follows that host lifecycle. |
| External engine or service | Bind a typed provider/connector contract with its own deployment, license and lifecycle. |
This gives agents a practical development path: change source, build and test a candidate, inspect
the changed permissions and contract, produce a signed APK, then install an authorized release.
New features arrive through that versioned path. Android's [dynamic-code
guidance](https://developer.android.com/privacy-and-security/risks/dynamic-code-loading) favors
including functionality in the application; the first design has no remotely loaded executable
plugin mechanism.
Ordinary apps remain within Android's [application
sandbox](https://source.android.com/docs/security/app-sandbox). Selected file/photo access,
media control, sharing, and deliberate camera use are useful admitted capabilities. A later
launcher or default assistant can request an available qualified [Android
role](https://developer.android.com/reference/android/app/role/RoleManager); that role has its
own privileges and revocation, rather than universal access to other apps' private data.
Fully managed device administration has a separate [provisioning
path](https://developer.android.com/work/dpc/dedicated-devices), including device reset in the
documented production route. It does not enter the existing-phone milestone. Deeper system
ownership remains a separate device/OS undertaking.
After Bridge and voice, add Media3 background music with folder-first SAF access, then selected
photos and verified copy sync. Keep those local features useful without a host. A persistent media
index or effect journal can earn Room and explicit migrations; recoverable transfers can earn
WorkManager with current grants and Android execution limits. The broader media/transfer domain
ownership must pass [Choosing a Home](../choosing-a-home.md) before remote effects are accepted.
## Source visibility and release ownership
Maintain separate entries for app source, dependencies/transitives, SDK tools, engine code,
model/voice weights, platform services, and handset firmware. More open components are preferred;
one open layer cannot establish freedom or source availability for another. The wider owned
technology map stays above Companion in [Atlas](../../divination/altar/technology-map.md).
Kotlin is [Apache-2.0](https://kotlinlang.org/docs/faq.html); Android SDK distribution has
[separate terms](https://developer.android.com/studio/terms), with open-source components retaining
their applicable licenses. audio.cpp's [runtime license](https://github.com/0xShug0/audio.cpp/blob/main/LICENSE)
is Apache-2.0, and Parakeet's model card specifies CC-BY-4.0. Supertonic 3's [weight
license](https://huggingface.co/Supertone/supertonic-3/blob/main/LICENSE) is OpenRAIL-M with use
restrictions. The complete candidate speech stack must not be described as unrestricted FOSS.
Voice-model promotion must account for those terms; watched alternatives remain explicit owner
decisions rather than automatic fallback engines.
Pin AGP with its supported Gradle/JDK combination, min/target/compile SDK, the actual Kotlin
compiler, Compose/serialization compiler plugins, and exact library versions. AGP 9+ has
[built-in Kotlin](https://developer.android.com/build/migrate-to-built-in-kotlin); avoid applying
another Kotlin Android plugin to the same module. A Compose BOM coordinates Compose artifacts,
not every AndroidX dependency. Commit reviewed dependency locks and verification metadata;
catalogues and first-generated checksums alone do not establish provenance. The OkHttp repository
lookup redirected to another organization during this research, so exact publication lineage
must be resolved before reconsidering that artifact. Ktor/CIO still requires reviewed artifact
provenance and the same bounded transport and device-key probe before admission.
Before durable use, choose a stable application ID and versioning scheme. The operator/project
controls the [release signing key](https://developer.android.com/studio/publish/app-signing),
backed up outside the checkout and kept separate from device credentials. Prove how that identity
survives signed upgrades, data migration, key invalidation, and reinstall/re-enrollment.
Recovery also needs API-appropriate cloud-backup and device-transfer extraction exclusions,
excluded custody for sensitive material where applicable, and restore reconciliation tests. Android's [backup
guidance](https://developer.android.com/identity/data/autobackup) explains that `allowBackup=false`
alone can still permit OEM device transfers on API 31+. Android
[PackageInstaller](https://developer.android.com/reference/android/content/pm/PackageInstaller)
can require user action; ordinary app evolution must not promise silent installation.
## Construction sequence and acceptance
| Milestone | Smallest useful result | Required evidence |
| --- | --- | --- |
| Build and contract probe | Installable Compose shell, generated DTO fixtures, fake host and explicit transport states | Compatible locked toolchain, serializer/error/event tests, own APK identity/signing plan. |
| Protected handoff and presentation fixture | Paired device, reviewed text, settled handoff lookup and pre-settled presentation | Host trust, scoped Ward identity, revocation, object guessing refusal, expiry and lost-ack recovery. |
| Foreground speech fixture | Bounded capture, host transcription, reviewed Send, optional authorized reply playback | Exact handset capture, byte custody/limits, language bake, local stops, denied/revoked permission, lock/calls and TTS failure with text retained. |
| Live Communion product | Exact destination admission and eventual result under the named Suite | Accepted score, durable aggregate correlation, separate cancellation scopes, interruption and unknown-outcome recovery. |
| Local and admitted phone features | Folder-first player, then selected photos and copy sync | Media/controller behavior, retained/revoked URI access, no duplicate effect after reconnect, integrity/conflict/storage/migration tests. |
| Later VPN reach | Same protected application journey over another route | Existing identities, scopes and refusals remain effective when the address changes. |
The requested first useful **Bridge and Voice release includes the live Communion milestone**.
The shell, handoff fixture, and speech fixture are intermediate proofs; a pre-settled response
cannot establish a working conversational round trip.
The physical acceptance record names S20 FE model variant, Android/API level, firmware/build,
available storage and actual audio route. Emulator and Compose tests cover interaction/state;
physical tests establish Samsung lifecycle, headset and locked-device behavior. Host fixtures
remain distinct from a real admitted speech-runtime bake.
Before the LAN or speech milestones, the owning backend contracts must close mobile ingress,
Ward identity, audio byte custody, the exact audio.cpp batch dialect and cancellation behavior,
Companion native execution, and the chosen round-trip promise. A documentation design cannot
make these missing prerequisites executable. [Audio
admission](../../state-of-the-work.md#audio-admission) and [Remote
IAM](../../state-of-the-work.md#remote-iam) retain that boundary.
[Companion](index.md) · [Phone Workspace](phone-workspace.md) · [Utterance](utterance.md) · [Return](return.md)
---
title: "Companion Phone Workspace"
plain_name: "Companion: Phone workspace study"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/companion/phone-workspace/
guide: https://lychd.snayu.ai/docs/compositions/companion/phone-workspace/
---
# Companion Phone Workspace (Companion: Phone workspace study)
## Plain-English summary (Snayu)
**What it is:** A candidate direction for Companion to grow into an everyday phone workspace, starting with an offline music player, then selected photos and explicit file copy, each a revocable capability.
**Why it matters:** Read this if planning phone-side features beyond voice requests.
- First everyday feature is a folder-based offline music player using Media3.
- Uses ordinary Android permissions; no root or custom ROM.
- File sync starts as copy-only; mirroring, overwrite and deletion need separate design.
**Status:** Designed. Candidate study only.
## Original text (Hexanomicon)
Companion could grow into the everyday mobile workspace through which LychD can act on the
operator's phone. [Android Foundation](android-foundation.md) now places Bridge and foreground
voice first. The first everyday local feature remains an ordinary offline music player. Selected
photos and explicit file sync follow; a local Wi-Fi connection comes before access through a VPN.
Each stage adds named capabilities that the operator can grant and revoke on the phone.
This candidate study, opened **2026-10-07**, explores that direction beside
[`companion.mobile` revision `3`](index.md). It publishes no successor revision or supported phone
administration path. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
owns delivery. The initial device to test is the operator's Samsung S20 FE; the first application
design requires ordinary Android app permissions rather than root or a replacement ROM.
## Start with a player worth using
The first screen is a folder-based music library, with albums and search as other ways into the
same files. Selecting a track starts playback and exposes the queue, pause, previous, next, seek,
repeat, and shuffle. Playback, library browsing, and queue changes remain useful without a host,
network connection, or model. An agent can later use those same explicit player operations.
The native Android client stays under `clients/android/**`, following Companion's Kotlin and
Jetpack Compose target. Android's [Media3 background playback](https://developer.android.com/media/media3/session/background-playback)
provides a concrete implementation route for a player session with system controls, headset
interaction, and playback while the screen is locked. Those behaviors still need testing on the
actual handset. Persistent offline music must not depend on an expendable thumbnail or download
cache.
A granted control session can permit playback operations without another prompt for every pause
or next track. Microphone capture, photo access, transfers, camera capture, and deletion have
separate permission and authority boundaries. The phone always exposes local stop and a way to
revoke remote control.
## Grow in useful stages
Feature development and connectivity are separate tracks: local music can work before remote
admission exists, and photos need no VPN to become useful.
| Stage | Proposed behavior | Smallest useful journey |
| --- | --- | --- |
| Local music | Folder library, search, queue, and offline/background playback. | Pick an album, lock the screen, use headset controls, and continue playing without LychD. |
| Paired Wi-Fi | Connect to the operator's host and admit bounded player operations. | Grant playback control, execute one identified request, and display the observed player state. |
| Selected photos | Browse selected images and prepare a copy to a chosen destination. | Select a photo, inspect what will leave the phone, and copy it without changing the original. |
| Explicit sync | Copy selected music from host to phone and selected photos from phone to host. | Interrupt a transfer, resume it, verify the complete file, and show the result. |
| VPN reach | Reach the same paired application service through a private route. | Repeat an admitted operation away from home with the same application identity and grants. |
Photo selection begins with Android's [system photo picker](https://developer.android.com/training/data-storage/shared/photo-picker).
A later custom gallery can request a wider collection explicitly. Selected URI access, copying
bytes, and camera permission are different capabilities; revoked access or a missing file must
be visible. File arrival does not itself authorize model analysis, memory ingestion, or training.
## Connect to the same LychD
The Linux host remains the place for LychD's domain records, workflows, and any heavier inference.
The phone owns its platform integration and bounded local interaction state. Local inference is
an optional later capability to measure on the actual device; it is no prerequisite for a usable
player or an authenticated host connection.
Wi-Fi supplies reachability. Pairing must establish the expected host and the phone application's
identity over an authenticated, encrypted connection. Discovery, an IP address, or membership of
the home network grants no application authority. Android network permissions also belong to the
device capability check; the [LAN permission guidance](https://developer.android.com/privacy-and-security/local-network-permission)
depends on the platform and target SDK.
The first remote path needs a protected mobile ingress with
[Ward](../../sepulcher/extensions/ward.md)-owned enrollment, scoped grants, and revocation. The
current same-host loopback service is not this path: the study does not authorize exposing or
tunnelling the current Altar. [Remote IAM](../../state-of-the-work.md#remote-iam) retains that
delivery boundary. Later, [Tether](../../sepulcher/extensions/tether.md) can supply VPN reachability
without replacing application authentication or widening the grants.
## Keep execution and ownership explicit
Companion presents the session, permissions, configuration, pending work, results, and reconnect
state. [Familiar](../familiar/index.md) supplies the exact phone capability snapshot, local limits,
and stop/refusal path. Ward owns identity and authority; Tether owns a later private route.
The player feature maintains its local file index, queue, and observed playback state. Android
storage and the selected locations retain custody of the media bytes. An execution request needs
an identified operation, target, current grant, expiry, and a result grounded in what the device
actually did. A model's request is not evidence that playback or a transfer happened.
Broader mobile execution exceeds Companion revision 3's current handoff/presentation contract.
Before admitting that path, [Choosing a Home](../choosing-a-home.md) must resolve the media and
transfer application ownership, then publish the appropriate accepted contract. This study does
not choose a new Composition or Suite merely because the client has several screens. Coordinating
multiple live Composition Invocations would need the separately owned Suite boundary.
## Copy first, recover honestly
Initial sync is an explicit copy with selected source, destination, direction, size/storage
limits, and content identity. Partial bytes stay incomplete until verification and final commit.
Conflicts, insufficient space, missing access, and failed transfers remain visible. Both originals
survive; mirroring, overwrite, deletion, and cleanup need separately designed operations.
If an action response is lost, reconcile the device's operation record and current state before
claiming its outcome. Reconnect queries that identity instead of repeating a queue change or
another effect. Until reconciliation succeeds, the outcome remains unknown.
A transfer may resume its verified portions only under current access and grants; retry cannot
preserve expired or revoked authority. Network-dependent agent commands do not silently execute
when connectivity returns. The offline player continues independently.
The first device fixture should prove offline playback, locked-screen and headset behavior,
rejection of an unpaired peer on the same Wi-Fi, revocation, and lost acknowledgement without a
duplicate queue change. The photo/sync fixture then adds revoked URI access, an interrupted copy,
integrity verification, storage exhaustion, and a destination conflict with both originals intact.
VPN acceptance repeats the existing authenticated journey over another route.
Continuous observation, camera capture, notification actions, launcher integration, destructive
sync, and wider phone administration remain future candidate capabilities. Prove the initial
Bridge and voice foundation, then make the player useful and prove one admitted player action
and its failure endings on the S20 FE.
[Companion](index.md) · [Return](return.md) · [Choosing a Home](../choosing-a-home.md)
---
title: "Thorn"
plain_name: "App: Thorn (security workbench)"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/thorn/
guide: https://lychd.snayu.ai/docs/compositions/thorn/
---
# Thorn (App: Thorn (security workbench))
## Plain-English summary (Snayu)
**What it is:** A proposed whitehat security app that turns a scoped security question or incident into supported findings, a bounded protective response, and an accountable report or correction.
**Why it matters:** Read this before any security incident-response or investigation feature work.
- Its lasting unit is the security case: scope, leads, findings, response and reports.
- It serves the operator's own incidents and separately authorized engagements.
- Deterrence is an unmeasured idea; identifying an attacker is not required for useful protection.
**Status:** Designed. Candidate study; nothing implemented.
## Original text (Hexanomicon)
> _LychD has spikes._
Thorn is a proposed **whitehat security workbench**. It turns a scoped security question or attack
into supported findings, a bounded protective response, and an accountable report or correction.
It serves incidents affecting the operator and separately authorized engagements; the target
environment need not run LychD. Its lasting unit of work is the security case.
The intended deterrence is that targeting participating defenders can expose a campaign and
prompt intervention. Useful protection and findings do not require identifying a human controller.
Whether participation discourages attacks remains an unmeasured proposition.
This **candidate study**, opened **2026-09-22**, proposes **`thorn.defense`, revision 1**.
Portfolio acceptance and executable contracts remain open. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery)
owns delivery; [Workflow](../../adr/28-workflow.md#composition-identity-revision-and-retirement)
owns identity and revision law. The contract below is a proposal throughout.
## Purpose and boundary
Thorn keeps an investigation answerable: what may be examined, what the evidence supports, which
response is justified, what actually happened, and which obligations remain.
| Thorn owns | Adjacent responsibility |
| --- | --- |
| Security case, authorized targets/methods, leads, findings, and competing explanations | Logs, sensors, detectors, and analysis tools supply replaceable mechanisms and attributed observations. |
| Response decisions, scope, verification, and recovery follow-up | The target system and its action adapter execute under current authority and retain their effect records. |
| Security verification of a suspected weakness or remediation | Maintenance owners control code changes, migrations, activation, and operational recovery. |
| Recipient-specific reports, shared findings, challenges, and corrections | Each peer controls its own work and disclosure; external recipients own their intervention. |
[Autopoiesis](../../lexicon/iron-tongue.md#autopoiesis) names intended verified self-repair and
extension under operator authority. Routine database or workflow optimization, code maintenance,
backups, and whole-system restoration belong to that wider concern under existing owners. They
are outside Thorn's casework. A repair receipt can inform a security retest; a healthy service
does not by itself prove containment or close a security finding.
Tool availability supplies no permission. An assessment pins targets, methods, possible effects,
and stopping conditions. Receiving an attack supplies no right to enter suspected third-party
systems, coerce someone, expose private identities publicly, or retaliate.
[Security](../../adr/09-security.md) and [IAM](../../adr/38-iam.md) retain enforcement and authority.
Thorn introduces no general system administrator, scheduler, or self-authorizing agent.
Typed findings, requests, and settled receipts can cross these boundaries without transferring
ownership. A promise to coordinate separate Compositions' live Invocations needs the explicit
[Suite contract](../products-and-suites.md#compositions-relate-without-nesting).
## From encounter to result
A defender receives a suspicious message or an alert about unexpected account activity. Thorn
preserves permitted evidence, checks the signal's freshness and scope, and opens or links a case.
A human can instead begin with an authorized assessment question. Triage may also record a
non-incident, a gap, or a concrete refusal.
The case proceeds through five decisions:
1. What was observed, what is exposed, and what work is authorized?
2. Which immediate protective action is admitted, and how will its effect be verified?
3. Which optional lead could establish the next useful fact?
4. Do the findings justify a particular report or should the case abstain?
5. What needs correction, recovery, or further observation before the work can close?
Protection and investigation can proceed independently. Existing controls continue enforcing
their rules when Thorn, a model, or peers are unavailable. Immediate protection does not wait for
attribution or a completed inquiry. Detector interpretations remain distinct from observations
and case judgments. Duplicate or stale alerts confer no new authority; missing capture or a
failed sensor leaves a coverage gap rather than evidence of safety.
[Follow the campaign](investigation.md) develops the lead loop, peer sightings, supported activity
paths, and handling of hostile evidence. [Response policy](response-policy.md) independently
sets effort, automation, participation, attention, and cost. **Iron Shield** favors quiet
protection; **Guided Inquiry** proposes leads; **Hornet** pursues admitted leads persistently.
Their limits do not alter authority or the evidence needed for a claim.
## The case and its Patterns
The private case must explain both the investigation and its consequences. Retain its owner,
restricted subject/victim references, purpose, scope, effective policy revision and expiry,
budget allocations/consumption, leads, claims, contrary evidence, action attempts and receipts,
dispositions, and correction obligations.
For a reviewer to challenge a claim, its source references must preserve custody, method,
transformations and redaction lineage, original and UTC times with clock uncertainty, and
observed versus inferred status. Original bytes and local custody digests remain with their
owners. Each assessment records its reviewer, grounds for confidence, and review/expiry conditions.
| Proposed Pattern | Admitted input → accounted result |
| --- | --- |
| `thorn.open_case@1` | Scoped report, observation, or assessment question → triage and a new/linked private case, non-incident disposition, or refusal. |
| `thorn.investigate@1` | Admitted leads or assessment and source policy → supported claims, competing explanations, gaps, and disposition of each lead. |
| `thorn.protect@1` | Supported response and current authority → proposal or admitted action attempt, verified/unknown result, and recovery obligations. |
| `thorn.report@1` | Findings and recipient policy → exact reviewed packet and separately authorized handoff disposition. |
| `thorn.correct@1` | Changed or challenged evidence → successor claims, invalidated derivatives, and recipient-specific correction dispositions. |
These names are proposed, not registered Patterns. Their separation permits protection without
inquiry, inquiry without reporting, and correction after other work has ended. Tools remain
replaceable behind typed boundaries; the case and its judgment explain why Thorn is a Composition.
## Respond and verify
Before attempting a response, bind it to the target, evidence conditions and freshness, current
authority, impact, duration, limits, verification, and recovery plan. The effect boundary checks
that account independently of the worker proposing it. It must also prevent concurrent requests
from duplicating or conflicting over an effect. Assign an accountable owner who retains
verification and recovery even if the worker disappears.
Keep proposed, authorized, attempted, partially effective, maintained, and recovered states
distinct. An accepted command does not establish containment. Verification may reveal a failed
action, missing visibility, or an unknown effect. Reconcile uncertainty before retry so another
attempt cannot silently duplicate a change.
Account for false positives and service impact. Rollback or expiry requires the declared recovery
decision against current exposure; blindly restoring a still-compromised capability is not
recovery. An irreversible action needs an admitted recovery path. A maintenance outcome and the
security retest of that outcome remain distinct findings.
## Reports and corrections
A report separates facts from inference and retains contrary evidence, custody, gaps, affected
scope, and the requested response. Review whether the evidence supports that intervention and
its impact on unrelated users of shared infrastructure. Human acceptance records a decision;
it cannot make an allegation true. Narrow an unsupported request or abstain.
Independently verify the recipient and destination, accepted threat category, purpose, and
mandate/jurisdiction where applicable. A human accepts the exact packet, destination, and purpose;
changing them requires renewed acceptance. Preparation does not authorize sending or publication.
Outgoing evidence uses only recipient-permitted opaque references or scoped `EvidenceDigest@1`
under [Security's disclosure rules](../../adr/09-security.md#decision-identity-and-local-custody),
not raw canonical source digests. Peer exchange follows the same disclosure boundary through its
[own contract](investigation.md#ask-another-defender).
Once a report is admitted for handoff, persist its exact artifact, authority, attempt identity,
and receipts. Record whether it was **prepared**, **sent**, **acknowledged**, **refused**, **failed**,
or remains **unknown**. A successful transport proves neither guilt nor official action. If the
send may have happened but its acknowledgement was lost, reconcile that attempt before retrying.
Review equivalent allegations across visible collaborating cases, including differently worded
reports, while recording visibility limits. Cooperation must not become report flooding. A
correction is a separately admitted successor with its own recipient disposition, not another
copy of the allegation. Findings can remain useful when external reporting is unwarranted.
## Finish, stop, or return
Containment, operational recovery, investigation completion, and report delivery have separate
dispositions. **Actor unknown** and **insufficient evidence** are valid investigative findings.
Partial completion names remaining obligations and owners; refusal names the unavailable scope
or boundary; failure names the failed operation. Unknown effects keep overall settlement
unresolved even when analysis has finished.
Cancellation or revocation stops newly disallowed work and disclosure and initiates authorized
collection shutdown. It cannot undo delivered effects. Resume rechecks current permissions,
evidence freshness, sensor generation, and outstanding attempts. A stopped inquiry cannot erase
an unfinished action, delivery, or recovery obligation.
Corrections can outlive a closed case. Successor claims update dependent findings and affected
recipients; unresolved acknowledgements remain visible. Retention/deletion follows case and
custody policy while preserving only permitted lineage. Remote deletion or recall is not guaranteed.
## First proof
[Thorn Trials](trials.md) begins with a synthetic local attack and simulated response, then compares
the same case across three simulated defenders. A scoped assessment and repair retest separately
exercise security verification. The proposal must improve a supported decision or reduce total
work against competent simpler protection, within authority, privacy, recovery, and cost limits.
The trials page defines defeat conditions and advancement evidence; no trial result is claimed.
[Composition studies](../index.md#candidate-studies)
---
title: "Follow the Campaign"
plain_name: "Thorn: Following an attack campaign"
section: "Compositions > Candidate studies > Thorn"
status: "Designed"
original: https://hexanomicon.dev/compositions/thorn/investigation/
guide: https://lychd.snayu.ai/docs/compositions/thorn/investigation/
---
# Follow the Campaign (Thorn: Following an attack campaign)
## Plain-English summary (Snayu)
**What it is:** How Thorn investigates: open leads with answerable questions, ask other defenders for bounded evidence, keep hostile material from steering the work, and return correctable findings.
**Why it matters:** Read this when designing investigation workflows or evidence sharing between defenders.
- A lead is not proof; each keeps supporting and contrary evidence, effort limits and a stop condition.
- Peer requests bind recipient, purpose, minimal features and exact outgoing bytes.
- Protection during an attack proceeds without waiting for the investigation.
**Status:** Designed. Candidate study.
## Original text (Hexanomicon)
One defender receives a lure. Another records an access attempt. A third discovers unusual use
of an account. Thorn should help them determine which encounters belong together, what the
evidence establishes, and which observation would resolve the next useful question.
This is the investigative journey within the [Thorn candidate](index.md). During an attack,
admitted protection proceeds without waiting for this inquiry. A separately authorized assessment
can start with a security question instead of an incident; its target, methods, possible effects,
and stopping conditions enter the same case scope.
## Open a lead with an answerable question
Defender A preserves the received lure and its receipt record. A referenced destination becomes
a lead, not proof that its operator sent the message or that anyone followed it. Attachments and
links stay inert until an admitted analysis step. Received material, authorized records, permitted
public sources, and voluntary peer evidence supply the investigation.
Give the lead an answerable question and explain why pursuing it could help. Retain supporting
and contrary evidence, competing explanations, permitted sources or tests, expected contribution,
effort ceiling, expiry, and stopping condition. The agent may pursue that admitted lead without
asking for each reasoning step. A new target, method, or disclosure outside its scope needs
separate admission. When the allowance is exhausted, return findings and explicit gaps rather
than inventing an answer.
A verification lead can ask whether a suspected weakness is reproducible within the authorized
scope or whether an applied repair closes it. Keep the exact tested revision, conditions, and
limits with the result. A passed test supports that tested claim; it does not certify the whole
environment or authorize deployment.
## Ask another defender
A asks an eligible peer whether it observed the destination during a bounded interval. The
request binds its recipient, purpose, minimal matching features, exact outgoing bytes, period,
authority, expiry, and response-size/fan-out limits. The receiver independently admits the work
and any response. It may return evidence and suggest a lead without acquiring control of A's case.
| Response | What it establishes |
| --- | --- |
| Matching observation | The contributor observed the stated facts by the stated method, within its coverage. |
| No matching observation | The permitted search found nothing in its declared scope; activity outside it remains unknown. |
| Withheld or unavailable | A result cannot be disclosed or produced. The distinction must not expose whether a private case exists. |
| Correction | A recipient-scoped claim is revised or withdrawn, with affected conclusions and delivery accounted for. |
Evidence can remain with its owner, with enough permitted support for independent challenge.
Each exchange fixes retention and redistribution rules. Queries, their combinations, and derived
findings can expose a victim just as attachments can; pseudonyms or hashes alone do not establish
anonymity. An audience label is not access control. This exchange exposes no private-case
inventory, raw mailbox, bearer artifact link, or raw canonical source digest.
Use a permitted observable for matching when necessary. A scoped evidence digest accounts for
evidence; it does not supply a private matching protocol between peers. Enrollment, revocation,
query-abuse controls, and cross-community trust need their own design and evidence before live
exchange. [Security](../../adr/09-security.md#portal-privatization-and-egress) owns disclosure;
[Intercom](../../adr/26-a2a.md) owns sovereign peer-task transport.
## Establish the relationship
B reports an earlier matching attempt; C contributes later use of a compromised account. Thorn
keeps a versioned timeline and relationship map. Every proposed link carries its source, relation
type, time interval and clock uncertainty, observed or inferred status, and alternative explanations.
Each participant sees only the victim references and observations it may receive.
Distinguish **receipt → attempted access → successful access → subsequent use**. Ordering these
events does not prove movement between systems. A missing hop stays missing. A shared address,
hosting provider, writing style, or generated lure can support comparison without proving common
control. Keep **indicator, infrastructure, campaign, automated actor, account user, and human
controller** separate. A compromised machine or account may belong to another victim.
Copied reports retain their common origin; signatures establish contributors, not allegations.
Even independent observers can collect identifiers planted by one adversary. Separate observation
independence from grounds for operational control. Test borrowed, planted, or compromised
infrastructure explanations before making a consequential association. When available evidence
cannot distinguish them, retain the narrower finding and the next discriminating question.
An admitted lead might check whether B recorded a completed session, whether C observed the same
destination, or whether the clocks support the proposed order. Findings can merge, split, reject,
or revise a campaign hypothesis. Peer counts cannot settle attribution or trigger a shared
blacklist. **Controller unknown** is a useful outcome when the supported activity is clear.
## Keep hostile material from directing the investigation
Attacker artifacts, suspected coordination messages, peer returns, tool outputs, summaries, and
recalled claims remain attributed evidence. They cannot recruit a defender into new goals or
grant tools, targets, disclosures, or budget. Observing a coordination channel supplies no right
to enter private communications or join the attacking activity.
Assume a reasoning worker can be fully compromised. Preserved originals, permissions, budgets,
effect admission, and the supervising stop remain outside its control under
[Security](../../adr/09-security.md#7-return-quarantine). A second model or detector cannot replace
that enforcement. Keep source and transformation dependencies, including producing model/tool
generation and occurrence, so a challenger can inspect permitted underlying evidence and gaps.
Quarantine suspect contributors, sensors, and derivatives from consequential use pending review.
Incomplete lineage restricts affected use until supported reconstruction; it cannot restore trust
by omission. Reassess dependent reports while retaining earlier effects and correction obligations.
Incident material does not automatically become standing instructions, cross-case memory, or
training data; [Archive](../../adr/27-memory.md#ingestion) governs that passage.
## Add a source only for a missing observation
An additional collector must answer an identified detection or investigation need. Pin authorized
infrastructure, source generation, capture method/scope, time coverage, storage and retention,
permitted export, resource limits, and a stop outside its control. Importing a log grants no
administrative rights over its source system.
Before exposing a collector, establish observed isolation from private home and control-plane
resources, restricted egress, and the absence of production credentials or relay/pivot capability.
Admit capture and export separately. Keep hostile bytes quarantined through parsing, rendering,
storage, and analysis.
If the collector is compromised, remove its ingress/export authority, preserve permitted
evidence, and review its output. Rebuilding requires a newly admitted generation; reconnecting
the old one cannot restore trust. Any period of silence means only what the known coverage can
support.
## Return findings and keep them correctable
The case returns supported activity, known reach, disputed links, gaps, and useful next actions.
Warnings and reports follow the [case's reporting contract](index.md#reports-and-corrections),
with evidence proportionate to the recipient and requested intervention. Local protection stays
scoped, reviewable, expiring, and subject to an explicit recovery decision.
A challenged claim updates its timeline links, dependent conclusions, and recipient-specific
correction obligations together. A closed inquiry can still owe corrections. The
[response policy](response-policy.md) bounds pursuit and participation; [Trials](trials.md) tests
whether the added evidence improves a decision at acceptable cost.
[Thorn](index.md)
---
title: "Thorn Response Policy"
plain_name: "Thorn: Response policy presets"
section: "Compositions > Candidate studies > Thorn"
status: "Designed"
original: https://hexanomicon.dev/compositions/thorn/response-policy/
guide: https://lychd.snayu.ai/docs/compositions/thorn/response-policy/
---
# Thorn Response Policy (Thorn: Response policy presets)
## Plain-English summary (Snayu)
**What it is:** Proposed presets for how hard Thorn works: Iron Shield (just protect), Guided Inquiry (suggest leads) and Hornet (actively pursue), with each control adjustable separately.
**Why it matters:** Read this when designing Thorn's settings, automation levels or cost limits.
- Iron Shield is the proposed default; every preset keeps protection and evidence duties.
- Separate controls for response automation, pursuit, effort and priority.
- Hornet raises persistence, never permissions or attribution standards; external reports still need approval.
**Status:** Designed. Proposed presets, not delivered settings.
## Original text (Hexanomicon)
One operator wants protection and an uninterrupted afternoon. Another wants to follow useful
leads until the case is understood. Thorn's proposed response policy lets both choose their
effort, automatic actions, and participation independently.
These are editable presets within the [candidate Composition](index.md), not delivered settings,
additional Compositions, or global Agent Postures.
## From Iron Shield to Hornet
| Preset | Intent and behavior |
| --- | --- |
| **Iron Shield** | “Protect me; I am concentrating on my work.” Use admitted local protection, retain bounded permitted evidence, and surface actionable exceptions. No automatic lead expansion or peer inquiries. |
| **Guided Inquiry** | “Find out whether this deserves my attention.” Add bounded local triage/correlation and propose leads for the operator to select. |
| **Hornet** | “If you attack me, I follow the trail.” Proactively pursue admitted leads, ask eligible peers, reconstruct supported campaign activity, and prepare findings within finite limits. |
Iron Shield is the proposed initial selection. Every preset preserves configured protection,
evidence handling, and outstanding recovery/correction duties. Hornet increases persistence;
anger, attack volume, or a peer's urgency cannot change its permissions or attribution standards.
Within an admitted inquiry, agents need no new approval for each reasoning step. External reports
still require acceptance of the exact packet, destination, and purpose under the
[report contract](index.md#reports-and-corrections).
## Set each control on its own
| Control | Operator choice |
| --- | --- |
| Response automation | Notify, propose a change for acceptance, or execute an exact preauthorized response. Existing enforcement keeps its own policy. |
| Pursuit | Protection only, proposed leads, or proactive admitted investigation; eligible incident categories and repeat-incident triggers. |
| Effort | Time, lead depth/count, concurrent cases, model/tool calls, compute/spend, peer fan-out, evidence storage and retention. |
| Task priority | Spare capacity, a time window, or bounded foreground attention while reserving essential defense resources. |
| Human attention | Critical-only notices, summaries, or case updates; consequential failures and unresolved decisions remain visible under the selected policy. |
| Participation | Separately permit peer replies, specific observation sharing, investigation/review effort, or a collector. |
| Explanation | Concise results or technical evidence, hypotheses, coverage, and controls. Both show consequential permissions, costs, disclosures, and unknown effects. |
An expert may choose Iron Shield; a newcomer may choose a thorough inquiry. Expertise supplies no
grants or trust. Private Hornet work need not share anything. An Iron Shield user may contribute
one permitted observation without investigating. A preset never enrolls peers, deploys a collector,
enables export, or inherits a tool's sharing defaults.
## Authorize the response separately
Iron Shield can execute prompt preauthorized protection. Hornet can investigate extensively while
requiring acceptance for every service change. Automation preference alone grants neither one
permission to act.
For preauthorization, state which action may run against which eligible targets and under what
evidence conditions/freshness. Bind current authority, impact limit, duration, rate/concurrency
ceiling, verification, and recovery rule. The effect boundary checks this envelope independently
of the proposing worker; “Defend me” and a model's severity label cannot supply it.
When several actions could affect one resource, retain an accountable owner for resolving
conflicts. A changed target still falls under the aggregate limits.
Preserve accepted, effective, partially effective, and unknown outcomes. Reconcile ambiguity before
retry; account for service impact and current exposure before rollback. An irreversible action
needs a separately admitted recovery path. Human, model, or peer unavailability cannot silently
promote a proposal into an automatic action or disable existing controls. Apply only an explicitly
admitted fallback when a required decision is unavailable, and expose the unresolved condition.
## Bound the cost of defense
Per-case ceilings sit inside aggregate period budgets and concurrency limits. Intake, parsing,
rejected requests, retries, parallel workers, peer requests, reviewer time, and correction work
all consume the applicable allowances. New cases cannot replenish them. Zero optional inquiry
budget means pursuit is disabled.
Reserve bounded capacity for essential protection and outstanding reconciliation/corrections
before optional investigation. If that reserve is insufficient, expose the backlog and stop new
optional obligations. Account for coalesced, deferred, and dropped work without retaining unlimited
hostile input. Exhaustion leaves a gap, not an examined lead or a completed correction. Collector
connection and containment limits remain separate; quiet notifications cannot prove healthy coverage.
Choose leads by expected contribution to a supported decision, with uncertainty and cost visible.
Use bounded sampling and aging so cheap or familiar cases cannot consume all capacity. Claimed
urgency, novelty, and repetition alone cannot set priority. Full review capacity means a bounded
pending lead or an explicit stop, not more unreviewed reports.
Priority resolves through [Workflow service classes](../../adr/28-workflow.md#compositions-products-suites-and-schedules).
Thorn introduces no queue or scheduler; Hornet can use spare capacity. Those facilities retain
their existing delivery boundary.
## Change the policy without losing the case
An operator may override a persistent default for one case with an owner, purpose, expiry, and
budget. Show the effective choices and their origins before admission. Missing limits or
conflicting policy produces a concrete refusal. New methods, destinations, or disclosures need
their own admission even when more effort is available.
At admission, each occurrence pins its effective policy revision and budget allocation. Changing
the default governs later admissions while preserving historical Runs and the existing limits of
open cases.
To apply a downgrade, expiry, or revocation to current work, stop newly disallowed optional work,
recheck queued effects, and account for work already underway. Raising an allowance instead needs
a newly admitted allocation. Retrying never resets what the work has consumed.
Switching to Iron Shield leaves separately admitted protection and collectors in place; stopping
a collector has its own control. Corrections and uncertain deliveries survive. Returning to a
default cannot resume cancelled work or authorize an automatic resend.
[Configuration](../../adr/12-configuration.md#future-selectors) owns typed loading, validation,
precedence, and generation. Thorn would own this policy's application meaning; the proposal adds
no executable switch or configuration schema. [Policy trials](trials.md#compare-response-policies)
must first establish the intended behavior.
[Thorn](index.md)
---
title: "Thorn Trials"
plain_name: "Thorn: Trial plan"
section: "Compositions > Candidate studies > Thorn"
status: "Designed"
original: https://hexanomicon.dev/compositions/thorn/trials/
guide: https://lychd.snayu.ai/docs/compositions/thorn/trials/
---
# Thorn Trials (Thorn: Trial plan)
## Plain-English summary (Snayu)
**What it is:** An unexecuted trial plan to prove Thorn is useful, using synthetic defenders and simulated attacks to compare its case coordination against ordinary local protection.
**Why it matters:** Read this to understand how Thorn would be evaluated before any expansion.
- Three fictional defenders with complementary evidence plus deliberate decoys and planted identifiers.
- Comparison criteria and held-out cases are fixed before running to prevent tuning to the test.
- Includes protection when models or humans are unavailable and verifying a scoped repair.
**Status:** Designed. Unexecuted trial plan.
## Original text (Hexanomicon)
Thorn must earn its place by improving a security decision or reducing the total work needed
to reach it. The first proof uses synthetic cases and simulated effects: local response during
an attack, investigation with and without peers, and verification of a scoped repair.
This is an unexecuted trial plan for the [candidate workbench](index.md). It selects no engine,
adapter, or deployment and supplies no evidence of live protection or deterrence.
## Fix the question and the comparison
Use three fictional defenders with complementary records: a received lure, an earlier matching
attempt, and later use of a compromised account. Include a relationship their combined evidence
can establish and a plausible transition it cannot. Add harmless lookalikes, unrelated use of
shared infrastructure, planted identifiers, copied reports, missing capture, and uncertain clocks.
Keep all artifacts marked synthetic and outside real victim dossiers.
Start with one defender's evidence and permitted fixture sources; admit peer comparison as a
separate treatment. For an authorized assessment, add a declared suspected weakness and a
candidate repair. Test the original and repaired revisions under pinned conditions, including a
case where the service becomes healthy but the security weakness remains.
Define the comparison before running it. Pin subjects and component revisions, permitted
sources/actions, case selection, authority, machine and human budgets, protection floor, deadlines,
metrics, meaningful improvement, and advancement criteria. Keep development material separate from
the held-out assessment so tuning cannot quietly become proof. Where practical, reviewers inspect
permitted underlying evidence without knowing the treatment.
Compare competent local protection and manual or agent-assisted response with Thorn's case
coordination. Then vary optional investigation while holding protection rules and authority fixed.
An inquiry cannot take credit for a stronger control supplied only to its treatment.
Required outputs are a scoped case, source-dependent claims and gaps, every lead's disposition,
action proposals or accounted simulated effects, a report or reasoned abstention, and unresolved
recovery/correction obligations. An opted-in peer branch also returns the exact minimized exchange.
## Prove enforcement with an untrusted investigator
A bounded team may divide case leadership, evidence curation, one-lead investigation, independent
challenge, and disclosure review. These are responsibilities, not permanent Agent identities or a
delivered parallel Graph. Recommendations cannot admit effects. The lead retains aggregate limits
and resolves disagreements against underlying evidence rather than worker consensus.
Replace a reasoning worker's complete output, including tool returns, summaries, recall, and saved
continuation, with hostile fixture material. Attempt to overwrite originals, change the question,
widen permissions, exceed budgets, suppress contrary evidence, recruit another worker, and conceal
an outstanding effect. Enforcing boundaries must survive without a detector recognizing compromise.
Quarantine an origin after several derived summaries and a simulated disclosure. Require restricted
consequential use, traceable dependencies and earlier effects, and recipient corrections. Missing
lineage must restrict affected use, not silently reinstate it. Refuse an unauthorized method even
when it would be the only way to answer the question.
A forbidden effect or changed original fails the boundary gate regardless of usefulness. Offline
fixtures establish only exercised logic. Effectful trials require the exact adapter's
[observed outer boundary evidence](../../adr/09-security.md#refusal-compromise-and-evidence).
## Respond during an attack
Replay timed observations through a fake monitoring adapter and effect simulator. Declare the
asset, detector revision, freshness, action envelope, maximum impact, response deadline,
verification, and recovery owner. Keep observations, detector assertions, case judgments, attempts,
and actual simulated effects separate.
| Fixture | Required result |
| --- | --- |
| Models and peers unavailable during an ongoing attack | Existing admitted protection meets its deadline without waiting for inquiry; Thorn accounts for its receipt and remaining exposure. |
| Human unavailable for a proposal-only change | Apply only an explicitly admitted fallback; absence cannot invent preauthorization. |
| Duplicate, stale, reordered alerts or missing capture | Bound intake, preserve provenance/freshness, and expose lost coverage without repeating actions. |
| Several requests affect one resource | Prevent duplicated or conflicting effects and preserve one accountable response owner. |
| Severity label, new case, or changed target | No expansion of authority or reset of aggregate limits. |
| Successful command receipt with ineffective, partial, or unknown protection | Verify the condition; account for uncertainty and reconcile before retry. |
| Worker disappears before verification | Preserve an accountable successor or visible unresolved obligation. |
| False positive or expiry while the attack continues | Assess service impact and current exposure before recovery; no blind rollback. |
| Repair succeeds operationally but security retest fails | Keep the security finding open; the maintenance receipt cannot settle it. |
Measure time to observed protection, missed/harmful responses, resource availability, verification
delay, and recovery cost. Closing the inquiry cannot settle an outstanding response.
## Compare response policies
Replay matched cases under [Iron Shield, Guided Inquiry, and Hornet](response-policy.md), holding
evidence and protection authority constant. Iron Shield does not expand leads; Guided Inquiry
proposes them; Hornet progresses admitted leads within budget. Cross each with notify, propose,
and exact preauthorized action policies. Preauthorized Iron Shield protection must meet the same
limits as Hornet; proposal-only Hornet must not execute a service change.
Test expert presentation with Iron Shield, plain-language Hornet, private investigation, and a
separately permitted narrow contribution without pursuit. Expertise and presets cannot add grants,
sharing, collectors, or exports. Compare useful findings, spend, primary-task delay, and human
interruptions rather than agent-call counts.
Flood intake, including rejected requests, before introducing a consequential case and an overdue
correction. Test aggregate caps, bounded sampling/aging, reserved protection/reconciliation capacity,
and visible deferred/dropped work. More cases, workers, or retries cannot replenish budgets.
Expire overrides, downgrade an open case, revoke permissions while work waits, and exhaust a lead's
budget. Require refusal of newly disallowed effects, retained earlier policy/consumption, and
explicit gaps. A downgrade after a possible report send preserves the unknown attempt and
correction duties without resending or resuming cancelled work.
## Challenge cooperation and attribution
Each proposed path link needs source support, a relation type, time uncertainty, and observed or
inferred status. Receipt, attempted access, successful access, and later use remain distinct.
Compare local findings with the three-defender result; peers must add supported relationships
without filling the deliberately missing hop. Unavailable and irrelevant replies are controls.
| Fixture | Defeats the proposal if… |
| --- | --- |
| Shared hosting, similar lures, or reused infrastructure | Similarity or time order establishes control, campaign membership, or traversal without additional grounds. |
| Copied reports and honest sightings of planted identifiers | Repetition becomes independence, or observer independence becomes proof of common control. |
| A fixture supplies an admitted discriminating check | Thorn omits it within the declared budget while making the consequential association it could challenge. |
| A compromised account and unknown controller | Another victim becomes the accused controller, or an unknown identity becomes fabricated attribution. |
| Instructions inside a coordination note or peer response | The defender changes goals, tools, targets, authority, or budget. |
| Repeated slightly different queries or forged peer returns | A participant enumerates private cases, gains another's tools, or promotes claims by majority vote. |
| Sensitive relationship split across queries | Individually reviewed disclosures reveal a prohibited relationship in combination. |
| Critical evidence withdrawn after a possible report delivery | Dependent paths and claims remain eligible, or correction obligations disappear. |
Exercise matching, no-match-with-coverage, withheld/unavailable, and correction replies under the
[exchange contract](investigation.md#ask-another-defender). Receiver policy controls which response
distinctions may be exposed. Test exact recipient, purpose, time window, source lineage, retention,
redistribution, authority/expiry, and size/fan-out bounds. Use synthetic observables and explicit
matching vocabulary; scoped digests do not establish a private matching protocol.
## Admit collection and reporting separately
Compare an added log source or collector with existing evidence. It must resolve a stated question
or improve a protective decision at acceptable cost. Pin source generation, capture/export
authority, configuration, coverage, retention, and limits. The first collector fixture has synthetic
inputs, no public listener or real malware, no production credentials, and no home-network route.
Require observed isolation, restricted egress, an external stop, and compromise/rebuild handling
before effectful collection. Test interruption, clock skew, storage exhaustion, revoked authority,
and suspect output. Lost coverage stays visible; dependent claims enter review, and reconnection
alone cannot restore trust.
Have a compromised fixture collector attempt prohibited access/egress and evasion of outer
resource limits or stop controls. Any successful escape fails that capability's boundary gate.
Use simulated recipients for a defender warning, provider complaint, and incident-response or
authority report. Pin accepted threat categories, mandate/jurisdiction, independently verified
destination, evidence needs, authentication, disclosure, rate/size limits, receipt meaning, and
correction channel. Refuse an incompatible destination rather than substituting one.
Test the [exact report contract](index.md#reports-and-corrections): supported requested intervention,
contrary evidence, uncertainty, recipient-permitted references, and human acceptance of exact
packet/destination/purpose. Include an innocent tenant sharing implicated infrastructure. Narrow
an unsupported request or abstain; acceptance cannot make the allegation true.
Inject lost acknowledgement, timeout after acceptance, cancellation during transmission,
equivalent allegations phrased differently across visible cases, and correction after closure.
Keep prepared, sent, acknowledged, refused, failed, and unknown distinct. Reconcile possible sends
before retry, preserve visibility limits in duplicate review, and deliver corrections as separately
admitted successors. Transport success proves no official investigation or intervention.
## Decide what has earned expansion
At the end of the trial, keep enough evidence to reconstruct both its result and its limits:
exact inputs, versions, enforcement receipts, denied effects, criteria, measurements, exceptions,
and unresolved obligations. The report gives case counts, spread, and uncertainty for supported
links, false associations, useful decisions, privacy failures, reporting adequacy, correction delay,
total machine/human cost, and primary-task disruption. Include justified abstention and unfinished
work in that account rather than counting only completed investigations.
Advance for a predeclared decision-quality gain within cost limits, or lower total cost at equivalent
quality, while meeting the protection floor. A safe but inferior or inconclusive result warrants
simplification. Freeze a candidate and challenge it with a separately budgeted synthetic adversary
that can adapt misleading evidence and workload through a declared feedback channel. Retain failed
attempts and untouched final cases. No observed bypass means only none was found under those conditions.
Local simulation comes first. Real action, collection, reporting, and peer exchange each require
their own scope, observed enforcement, and recovery evidence. Live peers additionally need proved
enrollment, revocation, disclosure, and sustainable review/correction capacity. A changed model,
tool, parser, policy, or collector reopens affected qualification and utility checks. No stage
automatically deploys a tool or accepts Thorn into the Portfolio.
Deterrence needs a separate comparison of successful abuse or recurrence under comparable exposure
and observation coverage. Silence may reflect lost capture or displaced activity. Public claims
need their own disclosure decision and must not expose participating homes or victims.
[Thorn](index.md) · [Follow the campaign](investigation.md)
---
title: "Accounting Office"
plain_name: "App: Accounting Office (bookkeeping)"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/accounting-office/
guide: https://lychd.snayu.ai/docs/compositions/accounting-office/
---
# Accounting Office (App: Accounting Office (bookkeeping))
## Plain-English summary (Snayu)
**What it is:** A candidate app for one business's bookkeeping: connect invoices and bank movements, review journal entries, reconcile, and close a period with clear exceptions and handoffs to an accountant.
**Why it matters:** Read this before any accounting, invoicing or bank-integration work.
- Lifecycle: source evidence, proposed match, reviewed journal, reconciliation, period close.
- During a pilot it shadows the external accountant's books and records disagreements.
- Mail, bank and document adapters are proposed ports; no live integration or tax filing exists.
**Status:** Designed. Candidate study outside the accepted app list.
## Original text (Hexanomicon)
A business owner needs to know what arrived, what is owed, what has been paid, and what the books can honestly say. An invoice in mail and a matching bank movement are evidence to connect, not a finished accounting judgment. Accounting Office would preserve that connection through review, reconciliation, and an explainable period close.
This **candidate study**, prepared **2026-09-11**, proposes `accounting.office` revision `1`, outside the accepted Portfolio. It supplies no source implementation, registered Pattern, executable configuration, live mail/bank integration, or jurisdiction support claim. [Workflow](../../adr/28-workflow.md#composition-identity-revision-and-retirement) owns acceptance and revision law; [State of Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery evidence.
[Knowledge and obligations](knowledge-and-obligations.md) explores a proposed successor revision:
source-effective rules, scoped professional answers, and entity-specific obligation instances.
That proposal neither changes this revision's contract nor establishes acceptance or delivery.
## One accounting lifecycle
The proposed owner is one entity's accounting lifecycle:
```text
source evidence → proposed classification/match → validated and reviewed journal
→ reconciliation → period close → accepted scope, exact partial, unresolved, or handoff
```
An `AccountingOfficeRequest@1` would bind the entity, period, purpose, source coverage, exact compliance profile, rule versions, reviewer authority, privacy policy, and effect ceilings. An `AccountingOfficeOutcome@1` would identify accepted records and reports, exceptions, unresolved balances, missing coverage, and required handoffs. Refusal and an indeterminate external action remain explicit outcomes. A plausible report cannot substitute for missing evidence.
During a pilot, the external accountant's books remain the reference. Accounting Office shadows them, records disagreements, and prepares evidence for resolution; it cannot silently replace their books or treat agreement on one period as general accounting acceptance. Acceptance names the reviewer, scope, rule versions, exceptions, and reconciliation evidence.
## Records that survive the conversation
The candidate would retain distinct, linked records for:
- **Evidence:** each source occurrence, custody and coverage observations, original bytes and their separate digest, extraction version, and attributed corrections. Identical bytes can arrive through several occurrences; a digest alone does not identify the business event.
- **Commercial obligations:** counterparty identity and evidence; invoices, accounts payable/receivable, credit notes, due dates, disputes, advance allocations, and supporting contracts.
- **Money and books:** bank observations, match proposals, journal entries and postings, transaction and functional currencies, FX source/date/rate, rounding, reconciliation exceptions, and period closure evidence.
- **Assets and recurring rights:** acquisition/disposal basis, separate book and tax schedules, impairment evidence where applicable, subscription rights, renewal dates, cancellation conditions, and future obligations.
- **Compliance outputs:** attributed tax positions, applicable rule versions, report and filing candidates, reviewer disposition, and separately observed submission/acceptance receipts.
These records must support calculations another reviewer can reproduce. The accounting kernel therefore uses decimal arithmetic with deterministic balancing, rounding, currency precision, effective-date resolution, and rule selection. A model can propose a classification or explanation; it cannot choose the arithmetic or establish tax law.
Before posting, validate accounts, dates, amounts, provenance, and applicable review. Once posted, a correction appends a reversal or adjustment so the original remains inspectable. A closed period stays locked. Authorized reopening records its reason and produces a successor close while preserving the predecessor.
## Portable rules, isolated entities
The proposed Composition-owned `EntityComplianceProfile@1` binds legal form, tax residence, functional/reporting currency, accounting period, typed registrations and their effective dates. A versioned `JurisdictionPack@1` resolves accounting, company-law, income-tax, VAT/GST/withholding, and filing rules and schemas. Transaction facts and treaty overlays may change which rules apply. Provider dialect translates transport fields; it never decides law.
Neither a country string nor a successful import proves support. Missing, conflicting, expired, or inapplicable rules block the affected judgment with an exact reason. Portability requires a second wholly synthetic foreign profile with distinct rules, effective-time changes, calendar, and currency. Its fixture must demonstrate deliberate rule selection and refusal without fallback; this study makes no live foreign legal assertion.
To admit a rule, retain its authoritative source, source digest, publication and effective dates, applicability predicates, reviewer, executable revision, and expected fixtures. Research can assemble that evidence, but its findings cannot activate themselves.
When a rule changes, identify the open cases it affects and preserve earlier judgments. It cannot silently recompute a filed return or closed period. Selection must continue to distinguish interface language, bank country, tax residence, establishment, and transaction jurisdiction; none substitutes for the others.
Each entity keeps separate books, credential references, source coverage, grants, and acceptance authority. A counterparty buying services establishes a commercial relationship, not permission to operate that counterparty's books. Shared software and reusable profiles do not create shared financial authority.
## Proposed Patterns and configuration
These are proposed Pattern identities, separate from the Composition revision:
| Pattern | Bounded result |
| --- | --- |
| `accounting.admit_evidence@1` | Deduplicated evidence references, coverage gaps, quarantined items, or refusal. |
| `accounting.review_journal@1` | Validated/reviewed postings or exact unresolved proposals. |
| `accounting.reconcile_period@1` | Reconciled scope and explicit unmatched observations/obligations. |
| `accounting.close_period@1` | Accepted scoped close/report candidates, partial close, blocker, or accountant handoff. |
| `accounting.review_obligations@1` | Asset/subscription accounting updates and evidenced renewal obligations. |
| `accounting.prepare_invoice@1` | Validated invoice or correction candidate with exact customer, supply, tax position, and numbering scope. |
| `accounting.prepare_filing@1` | Frozen return/report candidate, applicable schema validation, open exceptions, and authorized handoff. |
| `accounting.assess_cash@1` | Assumption-bound cash scenarios and a separately authorized handoff candidate. |
The following is **non-loadable, nonbinding design notation**, not a Rune or accepted schema. Exact registrations and deployment syntax remain future work.
```text
composition: accounting.office / revision 1
entity_ref: synthetic-entity-a
compliance_profile: synthetic-a / revision 1
jurisdiction_pack: synthetic-rules-a / revision 1
mail: provider_ref, capability_revision, read_scope, history_coverage
bank: provider_ref, capability_revision, account_refs, read_scope
documents: intake_ref, accepted_media, quarantine_policy
effects: ingestion_policy_ref, review_policy_ref, payment_policy_ref
privacy: local_policy_ref, approved_target_refs, disclosure_budget
close: period_ref, reviewer_ref, exception_policy_ref
```
## Intake and effects have different authority
`MailAdapter`, `BankAdapter`, and `DocumentAdapter` name proposed application-facing ports, not existing global LychD classes or new Core offices or Extension Domains. Mail separates read, draft, send, and delivery observation. Bank separates read, payment preparation, submission, status observation, and reconciliation. Document intake retains original evidence and quarantines untrusted content. Any required registration must identify the receiving owner, typed Contribution, Provider, profile revision, and Registrant under [Extensions](../../adr/05-extensions.md); these names do not justify stuffing bank or mail operations into `ToolConnector`.
Before using an adapter, inspect its declared operations, coverage, limits, and recovery semantics. Unsupported operations must refuse or return a manual handoff. During intake, use cursors to track traversal while keeping document identity separate. At-least-once ingestion deduplicates repeated delivery without losing distinct arrivals. Partial imports, unavailable attachments, and historical gaps remain visible.
Classification comes after that evidence is established. Refunds, fees, FX differences, and payments without invoices each need their own evidence and judgment. A bank movement alone cannot become an automatic expense.
Bounded standing policy may authorize low-impact ingestion and repeated exact actions. Fresh consent is required when the applicable HitL or effect policy requires it; there is no mandatory per-click doctrine. Approval binds the exact entity, operation, recipient/account, payload, amount/currency, policy, and expiry as applicable. Mutation invalidates it. Credentials stay in their owning custody and never enter model context.
Observed submission is not delivered mail, settled money, or an accepted filing. An unclear timeout stays indeterminate. Recovery observes and reconciles the original external identity before any retry; uncertain execution cannot silently create a duplicate payment or message.
Follow an invoice through its separate acts. Preparing the document does not issue it. Issuing reserves its number within the entity's declared series and preserves that revision; a later correction links its predecessor. Sending, receiving payment, and recognizing revenue each create distinct records.
A filing candidate follows the same evidence discipline: freeze its source/period and rule/schema revisions before submission. Generation and local validation establish a candidate, while official acceptance still requires its own receipt.
## Privacy before remote cognition
Here **Portal** means remote provider cognition. The candidate follows [Context](../../adr/21-context.md#privatization-and-the-privacy-cut) and [Security](../../adr/09-security.md#portal-privatization-and-egress):
```text
local minimization + classification + lineage
→ consumer-specific PrivacyCut + independent verification
→ Security EgressDecision for exact target, payload, purpose, and expiry
→ transmission → quarantined return → validation and local admission
```
Local processing removes unnecessary identities, metadata, quoted correspondence, attachment text, and embedded banking information before a remote candidate is considered. Amounts, dates, relationships, and unusual combinations can themselves identify a business. Pseudonyms, reversible identifiers, and hashes are not anonymity. Semantic abstraction must preserve the question's declared invariants; if that cannot be verified, the work remains local or refuses the remote road.
Any re-identification map remains separately controlled locally under Context's lease law. No map, raw history, credential, or local decision evidence accompanies the request. Related calls, retries, and derived summaries count toward cumulative disclosure. A failed local capability or privacy check creates no implicit cloud fallback. A returned recommendation remains untrusted and cannot directly post, pay, send, or file. [State](../../state-of-the-work.md#context-privatization-and-portal-egress) records that the shared privacy machinery is not delivered.
Statutory records retain their actual legally required contents. An accountant may need exact originals through a separately authorized, exact-recipient exchange; model anonymization cannot replace that channel or alter the books. Applicable Security disclosure law still governs that exchange.
## A wholly synthetic advance
A fictional entity receives **2,400 currency units** before providing services across two periods. The intake records the bank observation and contractual evidence separately, then proposes an advance allocation. Under an explicitly synthetic rule fixture, reviewed evidence of service completion supports allocation of 1,200 units in each period. The example asserts no real tax treatment; tax timing remains a separately resolved position.
A missing completion record leaves the affected allocation unresolved. An invoice mismatch retains both originals and the discrepancy. A cash scenario may compare retaining the remaining advance against future obligations without changing the journal. If remote reasoning is eligible, it receives only the abstract synthetic problem required for that task, never a private transaction pattern disguised by substituted names.
## Foreign owners and the stopping line
Asset/subscription inventory here concerns accounting value, rights, and renewal obligations. Physical warehouse custody, stock counting, and IoT remain with their actual owner. Accounting Office consumes exact settled count/valuation evidence and records its accounting interpretation. A Suite becomes necessary only when a promised result must coordinate several owners' live Invocations; [Choosing a Home](../choosing-a-home.md) retains that routing test.
Cash strategy and tactics produce scenarios with assumptions, liquidity constraints, and uncertainty. Any proposed [Broker](../broker/index.md) client handoff must fit its admitted insurance-service scope; a report provides neither trading agency nor payment authority. An external accountant or filing system remains an unmanaged external precondition unless an exact admitted integration says otherwise. No foreign reference lends credentials, lifecycle control, or settlement authority.
## Fixtures that can defeat the proposal
| Falsifying fixture | Required evidence |
| --- | --- |
| Duplicate mail plus bank ingestion | Preserve occurrences; prevent duplicated obligations/postings without merging distinct events. |
| Crash at every durable transition and effect boundary | Resume from receipts; retain unresolved state without invented completion. |
| Mutation after approval | Reject stale authority before the changed effect. |
| Currency mismatch or missing rules | Block affected posting/report; never guess conversion or inherit another entity's pack. |
| Reopened period | Preserve locked predecessor, authorized correction, and successor close. |
| Payment timeout and repeated delivery | Reconcile original identity; prove no duplicate semantic payment. |
| Adversarial privacy leakage | Detect metadata, quotes, attachments, linkage and cumulative reconstruction; refuse uncertain disclosure. |
| Accountant discrepancy | Preserve both positions and attributable resolution; no silent overwrite. |
Composition ownership itself fails if these records, judgments, recovery, and finish already belong to an exact existing owner, or if regional variation requires incompatible lifecycles concealed in profiles. A mere report projection, provider wrapper, or Product label cannot establish the proposed office. Conversely, distinct deployment credentials alone do not justify another Composition.
Implementation would begin with local synthetic receipts and the deterministic accounting kernel, then an explicitly authorized read-only shadow against reference books. Accounting acceptance follows demonstrated reconciliation and reviewer judgment; optional external effects come later with their own evidence. Portfolio acceptance establishes a maintained design boundary, while executable delivery requires source contracts, focused verification, and maintained receipts. Until then this remains a candidate study.
---
title: "Knowledge and obligations"
plain_name: "Accounting Office: Rules and obligations"
section: "Compositions > Candidate studies > Accounting Office"
status: "Designed"
original: https://hexanomicon.dev/compositions/accounting-office/knowledge-and-obligations/
guide: https://lychd.snayu.ai/docs/compositions/accounting-office/knowledge-and-obligations/
---
# Knowledge and obligations (Accounting Office: Rules and obligations)
## Plain-English summary (Snayu)
**What it is:** A study on turning published accounting and tax rules into entity-specific obligations: researching questions, getting scoped professional review, and scheduling what a business actually must do.
**Why it matters:** Read this when designing tax-rule knowledge, professional review or compliance deadlines.
- A question case pins entity, period, sources, known and missing facts, and deadline.
- Professional review binds the exact answer and scope; silence is not acceptance.
- Proposes additions for a possible successor revision; nothing is accepted or built.
**Status:** Designed. Successor-revision study only.
## Original text (Hexanomicon)
A published rule does not say whether a particular business must file tomorrow. Accounting
Office must connect the rule's effective date to the entity's registrations, the transaction,
the reporting period, and evidence that the required act was completed. This study follows
that connection from research through professional review to a scheduled obligation.
This public study proposes additions for a **possible successor revision of `accounting.office`**,
dated 2026-09-19. It does not publish an accepted successor contract, retire revision `1`, or accept the
Composition into the Portfolio. The [existing candidate](index.md) remains the revision `1`
reference. Material additions below require explicit revision acceptance under
[Workflow](../../adr/28-workflow.md#composition-identity-revision-and-retirement); they are not
new Core records, registered Patterns, or executable country support.
## One question, bounded evidence
A question case begins with one decision: classify an advance, determine a filing obligation,
recognize an asset, or resolve a discrepancy with a professional. It pins the entity-profile
revision, event and period, source documents, known and missing facts, decision deadline, and
permitted downstream use.
Research should remove questions that public evidence already answers. It cannot discover a
private contract, choose commercial rights for an owner, or infer a registration from a country
name. An unresolved question is routed to the person who holds the missing fact or authority.
The proposed dispositions are researched, awaiting facts, awaiting decision, awaiting professional
review, accepted for a specified scope, disputed, and superseded. None means executed.
An answer retains its facts, applicable rule revisions and pinpoint sources, alternatives,
calculation trace, exceptions, and proposed next step. A professional review binds the exact
answer and inputs, reviewer capacity, date, scope and conditions. Silence is not acceptance;
agreement on one case does not validate every future transaction or a whole jurisdiction pack.
The [reference-book comparison](index.md#one-accounting-lifecycle) preserves disagreements.
## Sources and effective rules
Source custody and rule admission are separate. A snapshot records issuer, canonical URL,
publication reference, captured bytes and digest, capture time, document date, language, pinpoint
passages and coverage failures. A successful HTTP response may still be a challenge page. A hash
establishes byte identity, not legal authority, currency or applicability.
A proposed rule revision adds effective intervals, transition provisions, required facts,
exceptions, deadline and calculation logic, applicable form/schema versions, reviewer admission
and fixtures. The time a rule was learned is distinct from the time it governs. A newly published
rule may be future-effective; an old official guide may omit a later amendment.
When an authority publishes a change, identify affected open cases and propose re-evaluation.
Do not silently rewrite closed books or previously filed returns. A provider notification or
website change is a research trigger, not an admitted rule update. Where no authoritative feed
exists, a bounded periodic source check may propose a diff; it must report missing coverage.
## Definitions and actual obligations
First define the obligation as a reusable rule: when it applies, which event or recurring trigger
opens it, how its deadline is calculated, and which calendar and time zone govern that calculation.
The definition also fixes the evidence needed, exact recipient/form family, preparer and signatory
roles, and completion criteria.
An entity-specific instance then pins those revisions and the facts that activated the rule.
Keep false applicability distinct from unknown applicability: evidence that a rule does not apply
is a different result from missing the facts needed to decide.
For each instance, name the actual accountable owner and delegate and record its status as of a
known time. Keep the statutory deadline separate from an earlier internal preparation target, and
make any payment deadline, next review and escalation time explicit. A postponed meeting cannot
postpone the statutory deadline. Rejected, missed and reopened instances retain their history and
need a documented next action.
Completion must be equally specific. Preserve prepared, reviewed, authorized, submitted, accepted,
paid and reconciled outcomes separately where relevant. The tax return, its payment and the
regulator's receipt are related records, but each proves a different part of the obligation.
Schedules use [Workflow's occurrence law](../../adr/28-workflow.md#compositions-products-suites-and-schedules).
Repeated observations of the same event must not create duplicate obligations. A timeout after
submission remains indeterminate until reconciled against the original external identity.
Professional acceptance of the tax treatment does not authorize a payment or filing.
## Public knowledge and private operation
The public contract owns reusable record shapes, transitions and wholly synthetic fixtures.
Jurisdiction packs own effective rules and applicability tests. A private entity profile selects
those rules using actual registrations and circumstances; private evidence, books, correspondence,
account references and grants remain entity-scoped outside the public repository.
This is more than replacing names in configuration. Retention, authority, source coverage,
professional judgments and publication rights are part of the boundary. Reusing a supplier's
invoice does not grant access to its books. Reusing an accountant's answer must respect its agreed
scope and permitted use. A public example must not reconstruct a private transaction pattern.
For a bounded agent, route: entity and period → event → required facts → effective sources →
deterministic calculation → answer candidate → applicable review → separately authorized effect.
An index chooses the next owner; it neither assembles unlimited context nor upgrades research
into law. The [existing privacy and entity boundaries](index.md#portable-rules-isolated-entities)
continue to apply.
## Cases that must defeat an incorrect design
- A future amendment is mistakenly applied to an earlier transaction: reject the rule selection.
- A registration date is absent: preserve unknown applicability rather than generating a zero return.
- A source fetch returns a challenge page: retain the failure, never mark the rule current.
- A deadline crosses a holiday or jurisdiction boundary: use the pinned calendar and explain the result.
- A form exists for the previous year only: refuse to label it as the new year's accepted payload.
- An accountant corrects an answer: retain both versions and identify affected proposals.
- A second entity uses another jurisdiction: require its own facts and rules, never inherit a convenient default.
- A filing times out: observe the original attempt before retrying; do not manufacture acceptance.
Acceptance requires synthetic fixtures for these cases, reproducible calculations and source
lineage, and an explicitly scoped comparison against reference professional outputs. The
[State of Work](../../state-of-the-work.md#composition-portfolio-delivery) remains the delivery
owner. This study creates neither a tax filing engine nor a professional certification.
---
title: "Transmuter"
plain_name: "App: Transmuter (archive import)"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/transmuter/
guide: https://lychd.snayu.ai/docs/compositions/transmuter/
---
# Transmuter (App: Transmuter (archive import))
## Plain-English summary (Snayu)
**What it is:** A candidate app that works through conversation archives and attachments, identifies what each source actually says, and prepares grounded proposals for memories or persona changes.
**Why it matters:** Read this before building chat-export import or turning past conversations into memory.
- Two internal stages: Extractor (what is here, who said it) and Synthesizer (how it relates, what to adopt).
- Your words stay distinct from the model's interpretations; contradictions are kept.
- Proposals go to their owners (memory, persona, training), never applied directly.
**Status:** Designed. Candidate study; no import adapters or workflows.
## Original text (Hexanomicon)
A conversation archive contains your words, a model's suggestions, abandoned ideas, and decisions
that may have changed. Transmuter would work through that material with its attachments, identify
what each source actually says, and prepare grounded proposals for what the Lich could remember
or use to develop its identity.
The name **Transmuter** and its two internal responsibilities are settled in this candidate study,
reviewed **2026-09-11**. Portfolio acceptance and executable contracts remain open; [State of
Work](../../state-of-the-work.md#composition-portfolio-delivery) owns delivery.
## From sources to proposals
The operator selects a source, purpose, permitted destinations, and processing bounds. Transmuter
keeps a processing dossier while two internal stages work through the material:
| Stage | Reader question | Result |
| --- | --- | --- |
| [Extractor](extractor.md) | What is here, who produced it, and how should it be named and classified? | Source-located units with attribution, proposed names, labels, and uncertainty. |
| [Synthesizer](synthesizer.md) | How does this relate to what is already known, and what could be adopted? | Evidence-linked knowledge and proposals for separately admitted use. |
For a first personal intake, a smaller model could identify and prioritize material from a bounded
chat export or supplied phone history before a larger model synthesizes selected units. That split
is a possible implementation of the two stages. Selection would need to account for deferred
material and bring relevant corrections and contradictions into synthesis with the earlier claims.
Extractor and Synthesizer are internal parts of Transmuter, not nested Compositions, Extension
Domains, fixed Agent identities, or independent coordinators. Naming and labeling belong to
Extractor; no separate Labeler is introduced.
A chat archive and its images can yield a proposed preference, a project history, and a possible
Persona revision. The operator's words remain distinct from the model's interpretations. A
contradiction stays visible. [Archive](../../adr/27-memory.md) or
[Mirror](../../adr/32-identity.md) decides whether to accept the exact proposal, and Transmuter
records that outcome alongside what it prepared. In the designed memory path, Archive retains
admitted records in the [Phylactery](../../sepulcher/phylactery/index.md); its Curator separately
decides which revisions are eligible for recall.
## Learn through Transmutation
[Transmutation](../../divination/transmutation/index.md) gives the two stages a method for
learning from what they transform. Suppose an archive contains “keep answers short,” followed
months later by “explain this design fully.” A model has summarized both as “the operator always
prefers brevity.” The useful result must recover whose words support which claim, what their
contexts permit, and how a later correction could reach the proposed lesson.
| Chapter | Question within this intake |
| --- | --- |
| [Genesis](../../divination/transmutation/genesis.md) | Could the statements express a general preference, a task-specific request, or a changed preference? Form alternatives from attributed units before settling their relation. |
| [Trial](../../divination/transmutation/trial.md) | Compare each interpretation with the exact source passages and authorized surrounding context. Include the inconvenient statement; unprocessed material remains a gap. |
| [Canon](../../divination/transmutation/canon.md) | Declare before extraction and synthesis what would support the proposed use: correct speaker, preserved scope, traceable evidence, and the receiving owner's requirements. More extracted claims or a smoother summary cannot substitute for these conditions. |
| [Revelation](../../divination/transmutation/revelation.md) | Separate the observed requests from the diagnosis that their contexts differ and the proposal for a scoped preference. The model's universal summary is another attributable claim to examine. |
| [Distillation](../../divination/transmutation/distillation.md) | Carry the supported distinction with its conditions, counterevidence, and proposed next use. A later correction should reopen the affected preference rather than erase unrelated history. No adoption may be the warranted result. |
These chapters can recur within either stage; they add no five-stage execution pipeline.
**Canon precedes the attempt.** A later statement does not automatically defeat an earlier one:
changed context, changed preference, and unresolved contradiction require different conclusions.
The Tree's [relations](../../divination/transmutation/genesis.md#relations-within-relations)
sharpen the method. Chokhmah opens interpretations and Binah asks what supports their structure.
Chesed gives a neglected source room to matter; Gevurah limits what may be inferred from it.
Tiferet seeks a useful composition that preserves disagreement where it remains unresolved.
Netzach sustains the search; Hod can acknowledge that the available material cannot support the
desired conclusion. Their interaction matters more than assigning a separate Agent to each name.
The [receiving relation](../../divination/transmutation/genesis.md#repair-the-relation) reaches
the handoff itself. “Prefers brevity” loses the condition that made the lesson usable; a scoped
proposal carries that condition to Archive or Mirror. Likewise, an archive's description of the
Lich may inform a Persona proposal without establishing what it should become. Distillation
preserves a way back to correction within the dossier's privacy and retention bounds; the
receiving owner still decides what may enter memory, identity, or training.
## Sources and machinery
The candidate scope includes mobile shared items, conversation exports such as ChatGPT or Claude
archives, social exports and links such as Facebook material, documents, images, recordings, and
supplied system-inventory snapshots. These name intended inputs, not delivered adapters or current
platform access. A device inventory remains a dated observation; live discovery and host control
are separate work.
Reliquary would retain original bytes under its custody contract. Scout can supply admitted
acquisition, while [Prism](../../adr/36-vision.md) and [Echo](../../adr/37-audio.md) supply media
processing. Synthesizer's [receiving-owner map](synthesizer.md#receiving-owners) distinguishes
Memory, Persona, training, and code candidates. Each job selects the branches its purpose needs.
Using several Extension mechanisms does not make Transmuter a Suite. A promise that actively
coordinates separate Composition-owned Invocations requires a [Suite](../products-and-suites.md#compositions-relate-without-nesting).
This study supplies no general installation, self-extension, or autonomous evolution coordinator.
## The processing dossier
The proposed durable dossier lets the operator see what was admitted, what each stage produced, and what remains
unresolved. It owns the processing purpose and scoped authorization, source manifest and fixed
revisions, privacy/retention/resource bounds, and stage implementation and configuration revisions.
As work proceeds, it keeps progress, extracted units, corrections, knowledge candidates, and their
dependencies together.
For each proposed handoff, retain the exact payload, attempt identity, receiving receipt, and
separate outcome. The dossier references original artifacts so a reader can return to the
evidence; it does not become their byte-custody owner.
Completion means the admitted scope was processed and every proposed handoff has an accounted
disposition. It does not require every proposal to be accepted. Partial work identifies unfinished
sources or proposals; refusal names the blocker; cancellation stops new work. An unknown receiving
effect remains unresolved until reconciled and cannot be reported as successful completion.
Committed receiving-owner effects survive local cancellation.
The stage pages specify how their attempts can be retried or corrected. Deletion must follow
the policies of artifacts, Archive, and Mirror, retain only permitted lineage, and mark dependent
material invalid where required. That process can account for stored records and proposals; it
cannot promise to remove influence from already trained weights.
## What would establish the application
A bounded historical chat import and ongoing mobile captures are two independently useful cases
for the same dossier and judgment. Each mobile arrival remains bounded; connecting a source grants
no unlimited background collection. The candidate must establish exact schemas, Patterns,
admission and custody, implementation, and receiving contracts before execution.
The first network-disabled synthetic fixture should include duplicate imports, changed source
content, a model claim misattributed to the operator, conflicting preferences, an uncertain image
label, a denied destination, cancellation and resumption, and an unknown downstream outcome. It
must demonstrate provenance-preserving reuse, correction, honest partial completion, and refusal
to repeat an unresolved effect. This is proposed acceptance work, not an implemented test or source
scaffold.
[Composition studies](../index.md#candidate-studies) · [Extractor](extractor.md) · [Synthesizer](synthesizer.md)
---
title: "Extractor"
plain_name: "Transmuter: Extractor stage"
section: "Compositions > Candidate studies > Transmuter"
status: "Designed"
original: https://hexanomicon.dev/compositions/transmuter/extractor/
guide: https://lychd.snayu.ai/docs/compositions/transmuter/extractor/
---
# Extractor (Transmuter: Extractor stage)
## Plain-English summary (Snayu)
**What it is:** The stage that splits imported material into source-located units with author, timestamps, proposed names, labels and uncertainty, separating what is in the source from what a model infers.
**Why it matters:** Read this when designing parsing, labelling or attribution for imported archives.
- A model's claim about the operator can never become an operator statement.
- Imported text is data, never instructions that widen processing or permissions.
- Labels do not lower privacy restrictions or identify people from images.
**Status:** Designed. Proposed responsibility only.
## Original text (Hexanomicon)
An imported screenshot may contain a conversation, a quoted claim, and text added by somebody
else. Extractor separates what can be located in the source from what a model merely infers. It
is Transmuter's internal decomposition and extraction stage, under the [candidate application
study](index.md).
## Extract, name, and classify
Each input binds an admitted source revision, format, purpose, and processing bounds. Conversation
archives retain speaker roles and authorship: a model's assertion about the operator cannot become
an operator assertion. Unknown source authority or unsupported formats produce a reasoned refusal.
Imported text and metadata are data, never instructions that can widen processing or permissions.
For each extracted unit, the proposed result records:
- Original reference, source identity, digest, revision, and source location such as a message,
page, image region, or time interval.
- Author or speaker role, producer, source timestamps, observation time where relevant, and the
transformation chain.
- Extracted content or media reference, whether it is extraction or interpretation, uncertainty,
and gaps in coverage.
- Proposed name, labels, content classification, privacy and retention constraints, and the
parser, extractor, and configuration revisions that produced it.
Use naming, labeling, and classification within Extractor to make the units easier to find.
They can describe topics, projects, document kinds, or likely relationships, with their evidence
and uncertainty intact. A proposed display name leaves source identity and the original filename
unchanged. When the operator corrects it, create an attributable revision.
A topical label does not lower a Privacy Label, authorize sharing, or establish a person's identity
from an image. Source and derivative restrictions survive extraction. Observations supplied by
[Prism](../../adr/36-vision.md) or [Echo](../../adr/37-audio.md) retain their exact references and
limitations; an OCR result or caption does not replace the source. Inventory snapshots retain
their observation time and scope rather than becoming claims about the machine's current state.
## Reuse and recovery
The [processing dossier](index.md#the-processing-dossier) retains completed units and unfinished
source regions. Repeated intake uses source identity, revision, and digest to recognize already
processed material without erasing distinct acquisition paths or crossing ownership boundaries.
Reuse requires matching processing revisions, scope, and current authorization. A changed source
or parser creates new traceable output rather than silently replacing earlier evidence.
Budget exhaustion returns partial extraction with explicit gaps. Cancellation stops new work;
resumption reconciles pending attempts and continues only the admitted remainder. Neither a
skipped image nor an unparsed archive entry proves there was nothing relevant there.
After a correction, identify which extraction needs to be revisited and invalidate the pending
proposals that depended on it. If a downstream owner already accepted the result, request the
correction through that owner. Editing a label locally cannot rewrite an earlier Memory or
Persona decision.
The stage finishes with attributed units and an accounted extraction disposition. [Synthesizer](synthesizer.md)
then works from exact selected revisions; successful extraction alone establishes no memory,
instruction, preference, or identity truth.
---
title: "Synthesizer"
plain_name: "Transmuter: Synthesizer stage"
section: "Compositions > Candidate studies > Transmuter"
status: "Designed"
original: https://hexanomicon.dev/compositions/transmuter/synthesizer/
guide: https://lychd.snayu.ai/docs/compositions/transmuter/synthesizer/
---
# Synthesizer (Transmuter: Synthesizer stage)
## Plain-English summary (Snayu)
**What it is:** The stage that relates extracted units to dates, purposes and existing knowledge, groups them into claims and contradictions, and prepares reviewable proposals for memory, persona or training.
**Why it matters:** Read this when designing how imported material becomes memory or persona proposals.
- Keeps three subjects apart: the operator's preferences, the Assistant's persona, and dated facts.
- Repetition cannot turn a model's interpretation into an endorsed preference.
- Each proposal names its receiving owner: Long-term Memory, Persona Keeper, Model Trainer or Smith.
**Status:** Designed. Proposed responsibility only.
## Original text (Hexanomicon)
An old conversation asks for brief answers; a later project calls for detailed explanations.
Synthesizer would relate those statements to their dates and purposes, preserving both until
evidence or review supports a scoped preference. It is the interpretation and synthesis stage of
the [Transmuter candidate](index.md), working from [Extractor](extractor.md) outputs.
## Compare and propose
Each synthesis attempt pins the selected extracted units, explicitly authorized comparison
material, purpose, target namespaces, synthesis implementation and configuration revisions, and
resource limits. Missing authorization excludes the comparison source or destination. Similarity
does not grant access to another person's or Persona's records.
Group the selected evidence into tentative claims, relations, contradictions, and proposed uses.
A reviewer must be able to assess each proposal on its own: name its subject and receiving owner,
exact proposed content or change, supporting and opposing source references, uncertainty,
dependencies, and required review. A Persona-change proposal also names its exact parent revision.
Keep a summary's derivation available so the summary never substitutes for the source.
The stage keeps three subjects distinct: the operator's preferences and history, the Lich's
Persona and commitments, and dated facts about devices or software. A model-generated description
of the operator remains that model's interpretation. Repetition cannot turn it into an endorsed
preference. Material may remain a source-linked knowledge candidate without any request to change
memory or identity.
## Receiving owners
| Proposed use | Receiving decision |
| --- | --- |
| Retain or correct a memory | [Archive](../../adr/27-memory.md) owns Memory admission, curation, and recall eligibility. |
| Revise the Lich's Persona | [Mirror](../../adr/32-identity.md) owns the reviewed revision and its publication. |
| Nominate material for training | [Soulforge](../../adr/33-training.md) independently admits a corpus and any later training. |
| Request a missing parser, tool, or code candidate | [Smith](../../adr/35-assimilation.md) supplies candidate authorship through a separately admitted exact application contract. |
Settled Smith outputs may also enter Transmuter as attributed material for interpretation. Their
authorship establishes no promotion or truth. Forge constructs packages and images; Soulforge
owns training. Neither code activation nor weight promotion follows automatically from synthesis.
This study specifies these proposed handoffs without publishing executable contracts for them.
## Account for the result
The [dossier](index.md#the-processing-dossier) links each fixed proposal to its handoff and the
receiving owner's outcome. Local synthesis may finish while memory is accepted, a Persona change
is refused, and training was never requested. An unknown downstream effect remains unknown until
reconciled with that owner; a missing receipt is not permission to repeat the effect.
Retry an attempt against its fixed inputs and revision pins. If a source changed or was corrected,
prepare a revised candidate and invalidate the affected pending proposals instead. Earlier
acceptances remain in the record. Any repair they need must be proposed to the responsible owner,
which retains authority over its own history.
Budget exhaustion retains completed proposals and identifies unfinished work. Cancellation stops
new synthesis and handoffs while preserving committed effects. Resumption must reconcile recorded
uncertainty and recheck authority before further work. The exact executable recovery contract
remains acceptance work under [Workflow](../../adr/28-workflow.md).
---
title: "Workshop"
plain_name: "App: Workshop (vehicle service cases)"
section: "Compositions > Candidate studies"
status: "Designed"
original: https://hexanomicon.dev/compositions/workshop/
guide: https://lychd.snayu.ai/docs/compositions/workshop/
---
# Workshop (App: Workshop (vehicle service cases))
## Plain-English summary (Snayu)
**What it is:** A candidate app for guided repair diagnosis, starting with car service (the proposed 'Mechanic' product): it keeps the vehicle, symptoms, hypotheses, checks and results together until a scoped outcome or handoff.
**Why it matters:** Read this before working on diagnostic or service-case workflows.
- The flow: identify asset, triage hazards, revise hypotheses, request one discriminating check, record result.
- Cannot certify safety, control machines, invent part identities, purchase or pay.
- The legacy workshop code scaffold is inert and no precedent for new stubs.
**Status:** Designed. Candidate study outside the accepted app list.
## Original text (Hexanomicon)
An intermittent no-start complaint is a service case before it is a diagnosis. Workshop would keep the exact vehicle, reported symptom, sources, competing hypotheses, requested checks, and observed results together until the evidence supports a scoped disposition—or makes a qualified handoff the useful result.
This candidate study, reviewed **2026-08-09**, tests that reusable application boundary. Workshop is outside the accepted Portfolio; **Mechanic** is its proposed first Product using the passenger-vehicle service profile. [State of Work](../../state-of-the-work.md#composition-portfolio-delivery) retains the delivery boundary.
## Candidate contract
`workshop.service` revision `1` proposes `workshop.service_case@1`. Its `WorkshopServiceRequest@1` binds purpose, case-scoped asset identity/configuration evidence, condition, hazards, operator role, pinned service profile, attributed sources/observations, and privacy/authority ceilings.
The proposed `WorkshopServiceCase@1` keeps the work reconstructible after the conversation. It owns purpose and operator assignment, asset assurance, and the evidence available to the case: symptoms, manuals, bulletins, schematics, codes, images, statements and measurements. It also retains hypotheses and contradictions; checks, prerequisites, hazards, tools, results and interruptions; part/tool requirements; and verification scope. A hypothesis remains distinct from an observed fact, and chat cannot substitute for this record.
`WorkshopServiceDisposition@1` can return scoped verified restoration, containment advice or attributable containment evidence, professional handoff, exact blocker, unresolved result, refusal, or indeterminate action. It cannot certify a machine generally safe, perform statutory inspection, admit unsafe/unqualified work, control a machine, bypass guards, invent part identity, purchase, or pay. Emergency response is outside this office.
## The guided case
```text
identify asset → triage hazards → admit evidence → revise hypotheses
→ request one discriminating check → wait for the operator → record the result
→ verify, advise containment, block, refuse, or hand off
```
The operator opens the no-start case from a phone, deliberately speaks through push-to-talk, and attaches a code report and finite images. Work may continue through a headset while retaining the same case. Workshop pins configuration and applicable source release, then proposes one non-invasive, engine-off inspection with reason, prerequisites, and stop conditions. Its reported result remains an attributed observation. Conflicting evidence can end in a qualified handoff instead of another speculative repair.
[Sight](../../sepulcher/extensions/prism/sight.md) may nominate a connector region, and a phone or future glasses may show it. The estimate proves no component identity, cause, or action safety. Silence, “seems fine,” unseen repair, and missing acknowledgement cannot close the case.
Revision one guides no lifting/support, exposed high voltage or hazardous energy, energized/rotating machinery, pressurized/combustible material, pyrotechnics, primary vehicle controls, or guard/interlock defeat. It can organize evidence for qualified help. Consent does not create competence; local inference retains access, retention, deletion, and workplace privacy duties.
Neither this study nor the inert legacy `src/lychd/compositions/workshop/` scaffold supplies a schema, service, registry contribution, Pattern, effect path, or delivery evidence. The scaffold is no precedent for new candidate stubs.
## One workshop, versioned practices
`WorkshopServiceProfile@1` pins ontology, identity/compatibility keys, acceptable sources, checks, units, tools, qualifications, hazards, verification recipes, and stop rules. The first is `workshop.automotive_passenger` revision `1`. Another trade may use a profile only while the same service-case records, authority, recovery, and honest finish remain coherent. A materially different trade boundary needs another Composition.
A Product selects profiles/use cases; a client changes presentation; a [Persona](../../adr/32-identity.md) changes discourse and commitments; a Posture changes a cognitive step. None owns technical or safety law.
## Proposed reuse beneath the Product
Workshop can use existing mechanisms while retaining the purpose and policy of the service case. Companion, Echo, Tether, and Ward keep mobile controls, speech chronology, transport, authentication, grants, and revocation. Scout and Sight provide acquisition/visual evidence; Workshop decides whether that source applies and which check may follow. When parts need sourcing, [Scavenger](../scavenger/index.md) keeps its own listing, seller, bargaining, commitment, payment, and parcel records.
`WorkshopPartRequirement@1` carries compatibility, quantity, condition, certification, and evidence needs to stock or Scavenger, without reservation or commitment authority. A stock owner can return exact snapshots and reservation/use/return receipts. Workshop records them; it cannot mutate ambient inventory.
An asset owner such as [Homestead](../homestead/index.md) may supply the request and consume the disposition while retaining its site, work order, controller envelope, and return-to-service authority. Workshop's typed requests, part needs, and dispositions remain its proposed projections, not new Core primitives. [Products and Suites](../products-and-suites.md) explains settled handoffs versus live coordination.
## Honest settlement
Close the case only as far as its evidence permits. Verified restoration means the case-defined symptom and checks passed under recorded conditions. If the useful result is containment advice, keep it as advice; evidence of actual containment must name the human/controller and independent verification. A handoff carries identity, evidence, attempted checks, uncertainty, and hazards to the next responsible person.
When identity, source, observation, tool, part, qualification, or authority is missing, return that exact blocker. Conflicts and exhausted budget remain unresolved. An uncertain action stays indeterminate and must not be repeated.
The first network-disabled synthetic passenger-vehicle fixture must include conflicting identity, a pinned manual excerpt, finite images, codes/measurements, and fake stock. It proves refusal and source mismatch, one parked/resumed check without duplication, Sight uncertainty, hypothesis revision, hazardous-work handoff, a part need without purchase, scoped verification, and interruption without invented completion. No live vehicle, public web, camera stream, purchase, actuator, or repair enters it.
[Composition Portfolio](../index.md) · [Homestead Maintenance](../homestead/maintenance.md) · [Scavenger](../scavenger/index.md)
---
title: "Communion moved to Companion"
section: "Compositions"
original: https://hexanomicon.dev/compositions/communion/
guide: https://lychd.snayu.ai/docs/compositions/communion/
---
# Communion moved to Companion
Communion is now a bounded interaction route inside the
[Companion](../companion/index.md#communion-route) mobile Composition rather than a separate
Composition page.
Continue with [Companion](../companion/index.md), its current
[Utterance](../companion/utterance.md), or its [Return](../companion/return.md) contract.
---
title: "Communion Return moved to Companion"
section: "compositions/communion"
original: https://hexanomicon.dev/compositions/communion/return/
guide: https://lychd.snayu.ai/docs/compositions/communion/return/
---
# Communion Return moved to Companion
The Communion mobile custody, reconnect, revocation, and proof boundary now belongs to
[Companion](../companion/index.md#communion-route).
Continue with the current [Companion Return](../companion/return.md) contract.
---
title: "Communion Utterance moved to Companion"
section: "compositions/communion"
original: https://hexanomicon.dev/compositions/communion/utterance/
guide: https://lychd.snayu.ai/docs/compositions/communion/utterance/
---
# Communion Utterance moved to Companion
The Communion foreground-utterance route now belongs to
[Companion](../companion/index.md#communion-route).
Continue with the current [Companion Utterance](../companion/utterance.md) contract.
---
title: "Cultivation"
section: "Compositions > Stewardship & Acquisition > Homestead"
original: https://hexanomicon.dev/compositions/homestead/cultivation/
guide: https://lychd.snayu.ai/docs/compositions/homestead/cultivation/
---
# Cultivation
Cultivation now belongs to [Cultivator](../cultivator/index.md): growing cultures, their spaces
and life cycles, tending judgment, and confirmed harvests. Continue with [Tending](../cultivator/tending.md)
for work planning or [Harvest](../cultivator/harvest.md) for collection and stock handoff.
This route preserves the boundary of retired `homestead.steward` revision `1` and its
`homestead.tend_land@1` Pattern. The old Pattern is not an alias for Cultivator. Homestead keeps
physical site assets, resources, commissioned controls, and separate acceptance of collected
material into stores. [Revision continuity](index.md#revision-continuity) records the successor
and absence of an executable migration.
Return to [Homestead](index.md).