Resonance System
Resonance is Musewoods' audience-relationship and circulation system. It begins where canonical publishing and semantic navigation have established what the Explorer is being invited into. Stories, Journals, Viewgraphs, and Groves remain the places where canonical editorial work is authored and owned. Trailhead v2 authors journeys and Trailmap v9 authors innovation fields in the Navigation System. Resonance then decides how selected work can travel outward, how a reader can explicitly Follow an inquiry, and how a later Return can be recognized without turning Musewoods into an account-centric application.
That placement is an architectural boundary, not a naming preference. Resonance is not a fifth publishing field, and it is not the semantic owner of Venture Trailmaps or current v2 Trailheads. It does not acquire a field manifest comparable to Journals, Viewgraphs, or Groves and does not become a new home for canonical essays, frames, research, or graph topology. content/resonance/ contains circulation sources and the supported v1 Trailhead edition. Canonical work continues to live in the four publishing fields, while v2 Trailhead and v9 Trailmap sources are validated through the Navigation System.
The normative editorial reference is the unlisted Musewoods Resonance Grove at content/groves/musewoods-resonance/. When implementation work changes a frozen Resonance responsibility, the implementation and that normative Grove move together. This Field Manual explains the code and operational boundaries; the Resonance Grove explains the product doctrine.
Where Resonance Sits
canonical-work
Stories, Journals, Viewgraphs, and Groves continue to own their content, routes, previews, visibility, and editorial identity. Resonance references those objects instead of copying their titles, excerpts, or bodies into a parallel content store.
circulation
Resonance asks what is alive now and which canonical work or authored journey should be brought back into attention. Where the established v1 email/web edition is used, the four-role Path remains the circulation grammar. Where a v2 Trailhead already exists, Resonance may point toward or distribute that journey without redefining its eleven semantic roles.
relationship
A Follow is explicit and revocable. Version 1 supports only the whole Musewoods scope and a Grove-specific scope. Verification and suppression belong to the relationship plane; they are not inferred from anonymous reading behavior.
signals
Resonance records a bounded event grammar using opaque actor identifiers. The event plane exists to understand movement through the inquiry, not to become a generic analytics collector or an alternate identity database.
The Resonance Loop
01 Select What Is Alive
Musewoods begins with canonical work, semantic journeys, and explorable fields. Resonance adds an editorial circulation question: what is alive now, and what should be brought back into relationship with an audience? That choice should not alter the underlying Story, Grove, Trailhead, or Trailmap.
02 Project The Circulation Edition
The established v1 Trailhead edition remains one versioned circulation source that can project to web and email without creating two competing editions of the same act. This is a compatibility responsibility of Resonance, not the definition of the current Trailhead concept. New semantic journeys are authored with
musewoods.trailhead/v2.03 Carry The v1 Path
Where v1 circulation is used, the Path carries the reader through canonical objects using the closed roles
entry,deepen,see, andfollow. Each step points to the source of record; Resonance may supply a hook for the circulation journey, but it does not duplicate the underlying object or invent Trailmap topology.04 Follow
After the editorial question, a reader may choose Follow this inquiry. That action creates an explicit relationship, verified by email and revocable without an account or password. The content role named
followand the reader relationship named Follow are deliberately separate concepts.05 Return
A later re-entry closes the loop. Return is interpreted through a versioned window policy while raw timestamps remain available, so the meaning of "returned" can evolve without rewriting the historical record.
Figure 1
Rendering diagram…
Three Operational Planes
| Plane | Owns | Primary implementation territory |
|---|---|---|
| Circulation content | v1 edition, Path, typed content references, web/email projections | lib/resonance/content-ref*, path*, v1 trailhead/*, web/*, email/* |
| Relationship | Follower, Follow, consent, verification, suppression, delivery eligibility | lib/resonance/follow/*, relationship stores |
| Signal | Bounded journey events, engagement/return policy, rollups | lib/resonance/signals/*, rollups/*, event/rollup stores |
The planes are separated because they answer different questions. Circulation content asks what should be brought outward and in what v1 Path order. Relationship asks what the reader has explicitly asked Musewoods to remember. Signal asks what happened in the journey. Keeping those responsibilities apart prevents transport, analytics, and identity concerns from quietly collapsing into one database or one provider-specific abstraction.
Identity And Behaviour Stay Separate
Event payloads do not carry email addresses
The signal plane uses opaque actor identifiers.
validateEventrejects an email address in an event payload, preserving a hard boundary between journey measurement and relationship identity rather than relying on convention or review discipline.The mapping point is deliberately narrow
The only actor-to-follower mapping point is the entry boundary. After that boundary, journey events can remain pseudonymous while Follow state remains in the relationship plane. This gives the implementation a small place to reason about identity rather than allowing identity to leak into every event and projection.
Trailhead links carry no personal data
Attribution is first-party, but the link itself does not encode an email address or other personal identity. The
/r/<token>entry route resolves attribution and then redirects to the clean canonical URL, keeping the canonical content route independent of circulation mechanics.
The Bounded Event Grammar
| Event | Meaning in the journey |
|---|---|
trailhead.delivered | A Trailhead edition was delivered through the circulation boundary |
path.entered | A reader entered the curated Path |
content.engaged | Engagement satisfied the current versioned engagement policy |
path.deepened | The reader moved into a deeper Path step |
field.crossed | The journey crossed from one publishing field to another |
grove.reached | The journey reached a Grove destination |
follow.created | A verified Follow relationship was created |
inquiry.returned | A later entry satisfied the current versioned return policy |
The event names are registered in lib/resonance/signals/events.mjs; an unregistered event is rejected. Two meanings are intentionally policy-driven: content.engaged is decided by the versioned engagement policy and inquiry.returned by the versioned return policy. Code should therefore ask the policy modules what those events mean rather than re-creating thresholds in routes, components, or analytics queries.
Persistence And Transport
Musewoods owns the records
Store interfaces in the Resonance store contract isolate Followers, Follows, sends, raw events, and rollups from the physical persistence adapter. Tests can use memory, development can use the on-disk .musewoods/resonance/ store, and production or an explicit object configuration can use @vercel/blob through the object adapter.
Production persistence must fail visibly when it is not configured. An object store without BLOB_READ_WRITE_TOKEN raises STORE_UNCONFIGURED; the runtime must never pretend a relationship, send, or signal was persisted when it was not. Raw events are sharded by UTC day because the current object store is a whole-document store rather than a true append log.
Providers move messages; they do not own Resonance
Musewoods owns Navigation semantics outside the provider boundary, while Resonance owns circulation editions, followers, consent, Follow state, attribution, suppression, and delivery eligibility. A mail provider owns only transport operations such as send, sendTest, delivery-event normalization, and its provider message identifier.
Version 1 ships with a development outbox provider that writes rendered artifacts to .musewoods/resonance/outbox/ and does not touch the network. A real transport is registered behind registerMailProvider() and selected with RESONANCE_MAIL_PROVIDER; changing transport should not require a second Trailhead model, a Trailmap model, or a provider-owned subscriber model.
Environment And Persistence Controls
| Variable | Purpose |
|---|---|
RESONANCE_STORE | memory or object; otherwise development uses the file adapter |
RESONANCE_MAIL_PROVIDER | Selects a registered transport; otherwise the development outbox is used |
RESONANCE_ADMIN_SECRET | Bearer secret for explicit production send |
RESONANCE_DELIVERY_SECRET | Bearer secret for provider delivery feedback |
RESONANCE_LINK_SECRET | HMAC secret for /r/<token> entry links |
RESONANCE_PUBLIC_URL | Absolute public base used when rendering email links |
Runtime Boundaries
| Route | Kind | Responsibility |
|---|---|---|
/trailheads, /trailheads/<slug> | static | Trailhead web experience; remains available when relationship/signal runtime services are unavailable, with v1/v2 semantics owned by their respective source generations |
/r/<token> | dynamic | First-party attribution, then 302 to a clean canonical content URL |
/api/resonance/follow, /follow/verify, /follow/revoke | dynamic | Explicit Follow, email verification, and one-click revocation |
/api/resonance/events, /journey, /engaged | dynamic | Bounded first-party journey events with server-side semantics |
/api/resonance/send, /delivery | dynamic | Bearer-guarded production send and provider feedback |
/resonance-lab | development-only | Trailhead stress specimens and geometry validation |
Static Trailheads, static Trailmaps, and runtime relationship services are intentionally not one availability domain. A failure in the event store, mail provider, or Follow API must not make an authored Trailhead or Venture Trailmap disappear. That static-first boundary is part of the product contract, not merely a deployment optimization.
Operational Invariants
Building or deploying never sends email
The static Trailhead and Trailmap route graphs do not import the production send path. Publishing an edition, running a build, or marking an edition Ready cannot cause a production delivery as a side effect.
Ready is not Send
The authoring lifecycle stops at a Ready state until an explicit, bearer-guarded call reaches
POST /api/resonance/send. Production send is idempotent byproductionKey, defaulting to the edition id, so a repeated call returns the existing immutable send record rather than delivering twice.Runtime failure does not rewrite editorial truth
Canonical content remains in its field, while Trailhead and Trailmap projections remain independent of relationship persistence. Runtime systems may add attribution, relationship state, delivery, and signals, but they cannot become prerequisites for resolving the underlying editorial object.
Fieldwork, Not V1
Deferred Resonance surface
fieldwork
Personalized Trailheads or Trailmaps, autonomous circulation selection, A/B testing, send-time optimization, drip campaigns, lead scoring, member accounts, a composite Resonance score, tracking pixels, generic analytics collection, and newsletter card grids are intentionally outside the v1 contract. Their absence is a boundary to preserve, not a backlog invitation to add them opportunistically.