Reference
Architecture & anatomy
The map of the system, the anatomy of a .trl file, and the nomenclature —
the words we use to talk about the language. (For the words you write in it, see the
vocabulary glossary.)
The two halves
TropeLang is a descriptive language and a live recognition engine. One half describes a story at compile time; the other observes facts at runtime and reports the tropes they satisfy. The thing emitting events stays "blind" — TropeLang is the omniscient observer on top. (Why TropeLang.)
DESCRIBE — compile time
flowchart TB s1["trl source<br/>corpus + story"] --> s2["compiler<br/>lex, parse, validate"] --> s3["rule network"]
OBSERVE — runtime
flowchart TB o1["events"] --> o2["harness<br/>events to facts"] --> o3["graph store"] --> o4["evaluation engine<br/>recognize, drams"] --> o5["confirmed, possible,<br/>in-flight, gap"]
The boundary
The engine and the log form a closed boundary. The engine is a pure reader over the log: it consumes facts and emits analysis — recognition, coverage, state at a point. It performs no I/O, has no effect outside the log, and does no arithmetic over story values.
A harness is any component outside the boundary. It is the sole writer of facts into the
log, owns all arithmetic over story values, and consumes the engine's analysis; the engine is agnostic to
it. Hence a stat is assigned, not mutated in place — the engine evaluates the threshold
predicate, the harness computes the value.
Harnesses are typed by role: an application harness integrates the engine into a live system — the editor is one, with a human in the loop (a writer emits facts by typing; analysis returns as diagnostics and recognition), and a game is another. A test harness drives it from fixtures and asserts invariants (round-trip fidelity, corpus coverage).
Anatomy of a .trl
Every file has two phases: declarations & setup up top, then the temporal event log. The whole thing is an accretive log — facts are laid down and never deleted, only reinterpreted. (Style guide.)
flowchart TB f["file.trl"] f --> p["preamble<br/>+ imports"] f --> d["DECLARATIONS<br/>setup · static"] f --> l["TEMPORAL LOG<br/>play · timeline"] d --> dd["nodes · tags · edges · seeds"] l --> ll["arc ▸ act ▸ scene ▸ beat"]
AST → structural meaning
What you write, and what it is in the graph:
| You write | AST node | Structural meaning |
|---|---|---|
char · set · obj · evt · arc | entity decl | a node — a vertex in the graph (actor, place, object, event, thread) |
concept grief | concept decl | a foundational node a story can be about (lowercase, declared once) |
[+Grifter] [#Wounded] | tag | a facet attached to a node — what it is / how it is |
a -- b · > · -> · @ · >< | edge | a typed relationship between two nodes |
scene · beat · act · arc {} | scope | a temporal container; reading order is time (beat = finest) |
<<world>> · <<a|b>> | level / crossing | a plane directive, or a loud crossing into another plane |
chron a ~> b · @@ m · x ~~ y | story-time | the second clock — story-time (fabula) vs work-time; the @@ anchor, ~> precedence, ~~ co-presence |
!S! · *S* · ?S? | epistemic wrapper | the truth-tier of a fact (absolute / contingent / latent) |
"""…""" | prose node | raw prose — inert, parses & round-trips, not evaluated |
rule · when · then | rule | a recognition pattern over the graph's shape |
imply · alias | ontology | relations between tags — one expands into many; two names are one |
Nomenclature
Boundary
- boundary
- The closed engine + log. The engine reads facts and emits analysis; no I/O, no external effects, no arithmetic over story values.
- harness
- Any component outside the boundary: the sole writer of facts, owner of arithmetic, and consumer of the engine's analysis. The engine is agnostic to it.
- application harness
- A harness integrating the engine into a live system — an authoring tool, a game.
- test harness
- A harness driving the engine from fixtures and asserting invariants — round-trip fidelity, corpus coverage.
Structure
- node / entity
- A thing in the graph —
char, set, obj, evt, arc, or a concept. The vertices. (graph) - edge
- A typed relationship between two nodes. The operator names the tie:
-- associates, > holds, -> causes, @ located-at, >< mutual conflict. - tag
- A component attached to a node, naming one facet of it:
[+Grifter]. Composition over inheritance — a node has tags. (tags) - facet
- Which dimension a tag denotes:
= Body · # Mind · % Essence · @ Rel · & Verb. A name has exactly one canonical facet. - sigil
- The single leading character on a tag — either a domain facet (above) or a dynamic (below).
- dynamic
- How a trope is deployed, chosen per use:
+ straight · - subverted · ~ deconstructed / intent · ? averted · ! invoked. - buffer
- The file under analysis. Names resolve buffer-first — a snippet's own declarations win over the corpus.
Grounding
- declaration
- Introducing a node (
char vale) or vocabulary (concept, prop, rule, imply). A name with a declaration resolves. - founded
- An edge or reference whose endpoints ground in a declared node or a corpus concept.
- unfounded
- A reference that grounds in nothing — a typo or a missing
import. The build still tolerates a short fragment that names an entity it didn't declare; in a real file it's a defect. (style §founding) - broken (red)
- In the editor, a tag name with no canonical declaration anywhere (buffer, base, or corpus) — the honest mark that it isn't shared vocabulary yet.
Vocabulary tiers
- corpus
- The standard, layered library: prelude → concepts → modules → tropes. Loaded at runtime; can be layered. (corpus)
- prelude
- The always-in-scope base vocabulary and its implications.
- concept
- A lowercase abstract node (
grief, power) — referenced by identity, never derived. - module
- A reusable system of
imply / rule (the hero's journey, power dynamics). - trope
- A recognition pattern — a rule over the graph's shape, packaged with a worked vignette. (tropes)
- vignette
- A concrete example that triggers a trope's rule (show the cause; let the engine prove the effect).
Time
- beat ▸ scene ▸ act ▸ arc
- Nested temporal containers; the beat is the finest unit (the engine ticks per beat).
- temporal log
- The timeline half of a file. Reading order is time. (graph)
- accretive log
- The governing model: facts accumulate and are never deleted, only reinterpreted (soft-state, never-delete).
Planes (diegetic)
- level / plane
- The narrative plane a fact lives on (
<<…>>): the world, a tale within it, the table. (diegetic levels) - work-time / story-time
- Two clocks: work-time is presentation order (what's shown, top-down); story-time is in-world chronology (
chron · @@), which a flashback or time-loop permutes. (the two clocks) - home plane
- Where a node is declared and lives.
- crossing
- Reaching from one plane into another,
<<home|name>> — always loud, never silent. - non_canon
- A plane marked as not ground truth — a perception or a told tale. It can't mint an
!absolute! fact. - pov_<char>
- Convention: a character's point-of-view plane, typically
non_canon, surfaced by perspective(char).
Knowledge (epistemic)
- epistemic
- Pertaining to knowledge — the truth-tier of a fact and who knows it. (epistemic levels)
- the four tiers
!S! absolute · S asserted · *S* contingent · ?S? latent.- perspective
- A lens that re-wraps every fact by what an observer knows — yielding their (possibly false) world-model.
- dramatic irony
- The gap between two perspectives at one moment.
- reveal
- A fact changing tier over time (latent → asserted).
Recognition & coverage
- recognition
- Matching tropes by shape, not keyword. Reports confirmed, possible, or in-flight (matched/total, with what's missing). (tropes)
- drams
- The paired coverage metric, density over coverage. (drams)
- coverage
- The fraction of a story's facts that at least one trope explains (0–100%).
- density
- The average number of tropes reading each fact (unbounded — richer readings climb past 1×).
- gap
- The facts no trope yet explains — a prioritized worklist.