Introduction

AURA is a plain-text language for describing media content. Authors write .aura files that capture the timing, credits, rights, vocabulary, and availability of a work — whether that work is a music track, a film, a podcast episode, or an audiobook chapter.

The aura tool reads those files and compiles them into binary formats the Hami engine loads at runtime.

What gets compiled

These three files are always published together for a given work. The engine memory-maps all three and holds them in RAM for the duration of a playback session.

How to use this documentation

• Language Reference — start here if you are authoring .aura files. Syntax and Sigils covers the AURA language in full. Keyword Reference is the complete key vocabulary table. Conventions covers the ID system, reference grammar, and folder layout rules for every supported media type.

• Compiler — read this if you are working on the aura tool itself. Architecture explains the lexer, parser, and emitter pipeline. Crate Structure documents the module layout and data type definitions.

• Project Management — covers the aura init scaffolding command and the built-in history system (takes, marks, streams, rewind).

Current status

This is the 0.3.2-beta.2 release. The toolchain now features a standardized, high-contrast logging system and strict grammatical enforcement for multi-ID domain references. End-to-end compilation is stable.

Installation

macOS — Homebrew

brew install hamiorg/aura/aura

The Homebrew formula is updated automatically on each release. Run brew upgrade aura to get a newer version.

Linux — one-line installer

curl -fsSL https://hami.aduki.org/install.sh | bash

Detects your architecture (x86_64 or arm64), downloads the appropriate static binary from the latest GitHub release, and installs it to /usr/local/bin/aura. The binary has no system library dependencies.

To install a specific version:

AURA_VERSION=v0.3.2-beta.2 curl -fsSL https://hami.aduki.org/install.sh | bash

Linux — Package Managers (APT / YUM / DNF)

The recommended way to install and stay updated on Linux is via our official Cloudsmith repository.

Debian, Ubuntu (APT)

curl -1sLf 'https://dl.cloudsmith.io/public/aduki-inc/aura/setup.deb.sh' | sudo bash
sudo apt install aura

Fedora, RHEL, AlmaLinux (DNF/YUM)

curl -1sLf 'https://dl.cloudsmith.io/public/aduki-inc/aura/setup.rpm.sh' | sudo bash
sudo dnf install aura

Manual installation

If you prefer to install the packages manually without adding a repository:

Debian, Ubuntu:

sudo dpkg -i aura-<version>-linux-x86_64.deb

Fedora, RHEL, AlmaLinux:

sudo rpm -i aura-<version>-linux-x86_64.rpm

Build from source

Requires Rust 1.75 or later.

git clone https://github.com/hamiorg/aura.git
cd aura
cargo build --release -p compiler
# binary at: target/release/aura

Supported platforms

Linux binaries are statically linked against musl libc. They run on any Linux distribution without installing additional libraries.

Project Initialization (aura init)

Bootstrapping new AURA projects with correct structures and identifiers.

The aura init command scaffolds a new AURA project. It generates the folder structure, creates the base .aura manifests, sets up toolchain configuration, and generates the initial root identities.

Because AURA relies heavily on generated hex IDs, initializing a project manually is tedious. aura init automates this process while enforcing the layout rules defined in conventions.md.

Basic Usage

aura init <kind> [options]

Where <kind> is the media kind of the project, corresponding to the kind field in the root schema block.

Common Kinds

• Audio: audio::music, audio::album, audio::ep, audio::podcast, audio::audiobook, audio::speech
• Video: video::movie, video::series, video::music, video::animation
• Text: text::book, text::article

Example:

aura init audio::album --name "Signal Loss" --lang en-US

Generated Identifiers

When you run aura init audio::album:

1. It generates a collection ID (e.g., c8xab3d).
2. It generates a generic project directory based on the kind (album/, track/, film/, etc.). Detail identities like names, metadata, and the ID stay inside the .aura node manifest files, ensuring root project folder names remain clean and standardized.
3. It generates an annotator ID for the current user and populates info/annotators.aura.

Output Structures by Kind

The folder structure generated depends strictly on the kind argument.

1. audio::album (or audio::ep)

Creates a hierarchical collection for multiple tracks.

album/                           <- Project root folder
  namespace.aura                 <- Project entry point
  c8xab3d.aura                   <- Collection manifest
  info/
    namespace.aura
    metadata.aura                <- Initialized with the album name
    people.aura                  <- Empty people registry
    annotators.aura              <- Initialized with the current user
    credits.aura                 <- Empty global credits
    arts.aura                    <- Ready for artwork URLs
  meta/
    namespace.aura               <- Empty local vocabulary registry
  tracks/
    namespace.aura               <- Export block for tracks
  variants/
    namespace.aura
  artwork/                       <- Default local asset folders
  motion/
  trailers/
  stems/
  configs/
    llm.aura                     <- Toolchain integrations
    stores.aura                  <- Cloud origin definition
    account.aura                 <- Local deployment credentials
    ignore.aura                  <- History exclusion list

2. audio::music (Single Track)

A much flatter structure when releasing a single track.

track/
  namespace.aura
  t7xab3c.aura                   <- Track manifest (serves as root document)
  info/
    namespace.aura
    metadata.aura
    people.aura
    annotators.aura
  artwork/
  stems/
  configs/
    llm.aura
    stores.aura
    account.aura
    ignore.aura

3. audio::podcast

Bootstraps a podcast series with a season-oriented layout.

podcast/
  namespace.aura
  pc5xk4m.aura                   <- Series manifest
  info/
    namespace.aura
    metadata.aura
    people.aura
    annotators.aura
  seasons/
    namespace.aura               <- Add seasons here using `aura add season`
  artwork/
  configs/

4. video::music

Creates a companion video project, prioritizing scenes and shots.

music-video/
  namespace.aura
  mv6xp3l.aura                   <- Video manifest
  info/
    namespace.aura
    metadata.aura
    people.aura
    annotators.aura
    credits.aura
  scenes/
    namespace.aura               <- Initialized empty, ready for scenes
  shots/
  artwork/
  configs/

5. video::movie (Film)

Bootstraps a long-form video output with acts and scenes.

film/
  namespace.aura
  f6np2qr.aura                   <- Film manifest
  info/
    namespace.aura
    metadata.aura
    people.aura
    annotators.aura
    credits.aura
    rights.aura
  acts/
    namespace.aura
  scenes/
    namespace.aura
  configs/

6. audio::speech

Bootstraps a short or long-form address, lecture, or panel.

speech/
  namespace.aura
  sp2xr7n.aura                   <- Speech manifest
  info/
    namespace.aura
    metadata.aura
    people.aura
    annotators.aura
  segments/
    namespace.aura               <- Standard division unit for speeches
  artwork/
  configs/

Default File Contents (Example: audio::album)

namespace.aura

The compiler entry point automatically routes to the generated collection manifest.

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::album
  namespace  -> signal-loss
  lang       -> en-US

exports::
  info       -> @info/metadata
  people     -> @info/people
  tracks     -> @tracks/*
  collection -> c8xab3d.aura

info/metadata.aura

The central identity metadata for the release.

schema::
  root    -> https://hami.aduki.org/aura/1.0
  kind    -> metadata
  lang    -> en-US

manifest::
  name      ! -> "Signal Loss"
  creator   ! -> @person/PLACEHOLDER
  version     -> 1.0.0
  released    -> 0000-00-00

info/annotators.aura

AURA automatically populates the first annotator using the local system’s toolchain configuration. This ID tracks who made the file changes.

annotators::

  p9xb3mn::
    name     -> "Local System User"
    roles    -> annotator | editor

Modifiers and Commands Post-Init

Once aura init establishes the base directory, authors use the toolchain to scaffold files within the active project.

# Generate a new track inside an album project
aura add track "Fold"
> Created tracks/t4mn2rp.aura

# Create a scene inside a film project
aura add scene "Cold Open"
> Created scenes/f2xb7np.aura

# Generate a new person ID in the annotators or people file
aura generate person
> p5xz2kr

AURA Compiler Reference — v0.3.2-beta.2
init.md maps directly to the constraints laid out in conventions.md and flux.md.

AURA History System (history)

Source-of-truth, AST-node-based version control for the AURA ecosystem.

1. Core Philosophy

The AURA history system provides permanent, append-only provenance for media metadata.

• Source of Truth: It tracks changes only to the human-authored .aura text files. It never stores compiled .atom or .hami binaries in the ledger.
• Node-Level Diffs: Because AURA relies on slash-identifiers (e.g., verse/one/line/two), the diffing algorithm tracks changes at the AST node level, not raw text lines.
• Append-Only Immutability: Once a take is recorded, it cannot be modified or deleted. History grows forward. The ledger is a permanent record.

What History Tracks

Art, motion, and trailer URLs stored in info/arts.aura are tracked (they are text values in .aura files), but the remote media assets they point to are not.

2. The Isolated Store

Version control data is isolated from the working directory, under .history/ at project root. History objects are serialized natively as .hami files.

project-root/
├── .history/
│   ├── objects/               <- Immutable take objects (AST SourceDeltas)
│   │   ├── tx3ab7k.hami
│   │   └── tx9zz1p.hami
│   ├── marks/
│   │   ├── v1.0               <- plain text: take ID "tx3ab8m"
│   │   └── premiere           <- plain text: take ID "tx3ab7k"
│   ├── streams/               <- Pointers to latest takes per stream
│   │   ├── main               <- head of the main stream (plain text: take ID)
│   │   └── translation-fr     <- head of a parallel stream
│   └── HEAD                   <- Active stream pointer (plain text: stream name)
├── info/
├── meta/
├── tracks/
├── configs/                   <- NOT tracked by history
└── dist/

The .history/ folder is never compiled and never published to the cloud store. When using aura release, the published artifact is the compiled .atom / .hami — not the history store.

Note: aura dub creates an independent full-history copy of the project, including the entire .history/ folder. This is the mechanism for creating forks with full provenance.

3. Data Structures (core)

TakeObject

#![allow(unused)]
fn main() {
pub struct TakeObject {
    pub id: String,                  // e.g., "tx3ab7k" — tx prefix, 6 alphanumeric chars
    pub parent: Option<String>,   // previous take (None for origin take)
    pub stream: String,              // stream name this take belongs to (default: "main")
    pub message: Option<String>,     // optional human-readable description
    pub timestamp: u64,              // Unix timestamp of the take
    pub deltas: Vec<SourceDelta>,    // AST node text diffs relative to parent
}
}

SourceDelta

#![allow(unused)]
fn main() {
pub enum SourceDelta {
    /// Upsert a node (add if new, replace if existing)
    UpsertNode {
        path: String,       // slash-identifier path, e.g., "verse/one/line/two"
        aura: String,  // full AURA text block for this node
    },
    /// Remove a node entirely
    DropNode {
        path: String,       // slash-identifier path of the removed node
    },
}
}

StreamPointer

#![allow(unused)]
fn main() {
pub struct StreamPointer {
    pub stream: String,  // e.g., "main", "translation-fr"
    pub head: String, // ID of the most recent take on this stream
}
}

MarkEntry

#![allow(unused)]
fn main() {
pub struct MarkEntry {
    pub name: String,    // e.g., "v1.0", "premiere", "final-mix"
    pub take: String, // the take this mark labels
}
}

4. The Delta Chain

Each take stores only the difference from its parent take. To reconstruct the full source state at any take, the engine replays the chain from the origin take to the target:

origin (tx3ab7k)
  └── delta: UpsertNode { verse/one/line/one, "The signal..." }

tx3ab8m (parent: tx3ab7k)
  └── delta: UpsertNode { verse/one/line/two, "She said..." }

tx3ab9n (parent: tx3ab8m)
  └── delta: UpsertNode { chorus/one/line/one, "Find me..." }
           + DropNode   { bridge/one }

Reconstructing tx3ab9n replays all three deltas in sequence — producing a virtual in-memory .aura document that matches that take state without writing a file to disk.

5. Compilation Workflows

6. Toolchain Reference

Taking Snapshots

Navigating History

Streams

Working State

7. History Constraints

• Tracks only .aura source files. Compiled artifacts are always reproduced deterministically.
• The configs/ folder is excluded by design. Credentials are never versioned.
• The .history/ folder itself is excluded from compiled output except in --embed-history.
• History resolution is always read-only. The working state changes only via take, rewind, or mix.

AURA History System (history) — v0.3.2-beta.2 Append-only, AST-node-based version control for .aura source files. No compiled artifacts. No credentials. No binary assets.

AURA (Adaptive Universal Relational Annotations)

The Human-Readable Authoring Layer for ATOM/HAMI

AURA is not JSON. Not YAML. Not TOML. Not XML. It is a language built for people who think in nodes, not files. Write it like prose. Compile it like a machine.

Part I — Philosophy

Why a New Language?

Every existing serialization format was designed for machines first. JSON forces quotes around every key. YAML collapses on indentation ambiguity. TOML becomes unreadable past two levels. XML is ceremony without substance.

AURA starts from the opposite direction: design for the author, compile for the machine.

A music producer, a documentary editor, a podcast archivist — none of them should think in angle brackets. They should think in tracks, nodes, contributors, scenes, chapters, moments. AURA should feel like writing about their work, not configuring it.

The compiled output — .atom and .hami — is where the machine takes over. AURA is the bridge.

Three Governing Rules

1. One sigil, one job. Every symbol in AURA has one purpose and one purpose only. No symbol does double duty. If you see ::, it is always a namespace jump. If you see @, it is always a reference. If you see ##, it is always an annotation. No context-dependent overloading.

2. Nodes are the atomic unit. Everything in AURA is a node. A track is a node. A scene is a node. An author is a node. A syllable is a node. A chord change is a node. A rights boundary is a node. Nodes nest inside nodes. Nodes reference other nodes. The hierarchy is not organizational — it is relational. Depth is meaning.

3. People are first-class. Contributors are not strings inside a field. They are defined entities with their own namespace. They are referenced by identity, not by name. In any text, at any depth, you can point to a person. The engine remembers who they are.

Part II — The Sigil System

AURA uses a small, unambiguous set of sigils. Each is chosen to be visually distinct, keyboard-accessible, and semantically memorable.

This is the complete sigil vocabulary.

Multi-ID Reference Syntax

When a field references multiple entities within the same domain, AURA uses the list bracket directly after the domain path.

## Single reference — scalar, no brackets
annotator  -> @annotator/p9xb3mn
creator    -> @person/p4xt9k2

## Multi-ID reference — plural domains with bracketed lists
annotators -> @annotators/[p9xb3mn, p3xr7kn]
speakers   -> @people/[cc9xpq, lp2wnr]
cast       -> @people/[mt4qbz, vr8kfw, xp3bnr]

The single form (@domain/id) compiles to a scalar :: arc. The bracketed plural form (@domains/[id1, id2]) compiles directly to a HAMI array of :: arcs.

The Union Pipe | is used when values span different domains or are non-reference values (genres, tags, roles, territories).

## Pipe for non-ID and cross-domain unions
genre    -> Electronic | Afro-Soul | Experimental
roles    -> main-artist | vocalist | composer
territory -> worldwide | KE | NG

Part III — Document Structure

The Namespace Block

The top-level structure of an AURA document is a sequence of namespace blocks. A namespace block opens with a name followed by :: and a newline, and contains indented key-value pairs or sub-nodes.

manifest::
  name       -> "Project ATOM EP"
  version    -> 1.0.0
  language   -> en-US

Namespace blocks are order-independent. The AURA engine resolves all dependencies before writing to ATOM/HAMI. You can declare persons after tracks. It works.

Key-Value Assignment

The -> arrow assigns a literal value to a key.

name       -> "Song Title"
released   -> 2024-11-01
rating     -> explicit

Keys are unquoted. Values are quoted when they contain spaces or special characters, and bare otherwise.

Sub-Nodes

Nesting is done with indentation. There is no closing bracket. Every indented block under a key is a sub-node of that key.

credits::
  main       -> @person/p4xt9k2
  vocals     -> @person/p4xt9k2 | @author/j8mn2rk
  producer   -> @author/j8mn2rk
  writers::
    primary  -> @person/k7wrt2
    co       -> @person/h8dv5x

Each level of indentation becomes a HAMI sub-namespace.

Lists

Multiple values on a single key use the union pipe |. Alternatively, a list block spreads values across lines under the key.

## Inline list (union)
genres -> Electronic | Afro-Soul | Experimental

## Block list
formats::
  - flac
  - aac
  - opus
  - mp3

Both compile identically to a HAMI GS-delimited list.

Optional and Required Markers

## Field must be present — engine halts if missing
title !       -> "Untitled"

## Field may be absent — engine skips gracefully
isrc  ?       -> "UNKNOWN"

## Optional with no default
artwork ?

The Custom Mark (%)

The AURA compiler enforces a strict dictionary of standard keys to catch typos and enforce ecosystem consistency (the W006 Unknown Key lint). When a project requires a domain-specific or non-standard key that is not in the global dictionary, it must be explicitly marked with the % sigil.

## This will trigger a W006 error if 'engine-version' is not a standard key
engine-version -> "4.2"

## This bypasses the lint and compiles successfully
engine-version % -> "4.2"

The % mark signals intent: “I know this key is custom, let it through.” The mark is separated by spaces (key % -> value) and is stripped before compiling to ATOM/HAMI.

Part IV — Time Notation

The [start, end, duration] Triple

Every temporal object in AURA compiles to a three-value time triple stored in ATOM. All three values — start, end, and duration — are always stored. The engine validates that start + duration = end.

If any two values are provided and the third is absent, the engine derives and writes the third before compiling. If all three violate the invariant, the engine raises a compile-time error.

AURA provides three authoring syntaxes for the time triple. All three compile to the same [start, end, duration] triple in ATOM.

Syntax 1 — Range (start~end)

The author provides start and end. Duration is derived.

## Short form — seconds and minutes
time -> 0s~30s
time -> 22s~1m10s
time -> 1m50s~3m00s

## Long form — HH:MM:SS for film and long-form video
time -> 00:04:32~00:07:18
time -> 01:22:05~01:38:47

This syntax is unchanged from the original specification and remains the most common form for authored content.

Syntax 2 — Start and Duration (start+duration)

The author provides start and a forward duration. End is derived.

## Verse begins at 22 seconds and runs for 48 seconds
time -> 22s+48s

## Scene begins at 4 minutes 32 seconds and runs for 2 minutes 46 seconds
time -> 00:04:32+2m46s

This syntax is preferred when an editor knows section length before final timeline alignment is complete. The engine stores end as unresolved until the master timeline is finalized.

Syntax 3 — Explicit Triple ([start, end, duration])

The author provides all three values explicitly. The engine validates the invariant.

time -> [22s, 1m10s, 48s]
time -> [00:04:32, 00:07:18, 2m46s]

This syntax is used when importing from external systems that provide all three values, or when duration must be explicitly verified in the source record for rights and billing purposes.

Point Anchors

A point anchor is a single instant in time with no duration. It compiles to a triple where start = end and duration = 0.

sync-point -> @time/1m32s
sample     -> @track/02 @time/2m44s

Mixed Notation Within a Document

All three time syntaxes may be used within the same AURA document. The engine normalizes all of them to [start, end, duration] triples before writing ATOM/HAMI. Authors should choose the syntax that most naturally matches their editorial workflow for each section.

Part IV-B — Scalar Values and the Boolean System

Why Not true and false

AURA deliberately avoids true and false. They are machine concepts pasted into a domain that deserves its own vocabulary. A lyric line is not enabled: true. A rights clearance is not cleared: false.

Instead, AURA uses two media-native boolean literals:

These are the only two boolean literals in AURA. Every boolean field accepts exactly one of them.

Boolean in Practice

## A rights node
rights/doc::
  cleared -> live            ## rights confirmed
  blocked -> dark            ## not blocked in any territory

## A manifest field
manifest::
  explicit  -> dark          ## not explicit
  featured  -> live          ## is currently featured
  published -> live          ## is published

## A track annotation
tracks/t7xab3c.aura::
  karaoke   -> live          ## karaoke data present
  richsync  -> dark          ## word-level timing absent

## A sample node
sample/one::
  cleared   -> live

## An ad slot
slot/mid::
  required  -> live

The engine compiles live to 1 and dark to 0 in HAMI. Both are reachable via ATOM node queries filtered on their field value. true and false are accepted as synonyms for toolchain interoperability.

The @access Domain

@access is the singular reference domain for content visibility and permission levels. Unlike boolean fields (which express binary flag states), @access expresses a content governance decision with multiple named levels.

## Declaring access on a node
schema::
  root   -> https://hami.aduki.org/aura/1.0
  kind   -> audio::music
  lang   -> en-US
  access -> @access/open

## Overriding access on a specific track
tracks/t7xab3c.aura::
  access -> @access/gated

## A pre-release track under embargo
tracks/t4mn2rp.aura::
  access  -> @access/embargoed
  embargo -> 2025-06-01        ## date when it transitions to @access/open

Access Levels

Access levels form an ordered hierarchy for cascade resolution:

open < archived < restricted < gated < embargoed < locked

A parent collection’s access level applies to all members unless explicitly overridden on the member. A member may only restrict further, never relax, without an explicit override.

Access in a Collection

## FILE: collections/c8xab3d.aura

manifest::
  name   ! -> "Signal Loss"
  access -> @access/open        ## whole album: public

collection::
  members::

    track/one::
      aura-ref -> tracks/t7xab3c.aura
      access   -> @access/open

    track/two::
      aura-ref -> tracks/t4mn2rp.aura
      access   -> @access/gated     ## subscriber-only
      note     -> "Bonus track for subscribers"

    track/three::
      aura-ref -> tracks/t9vkx7q.aura
      access   -> @access/embargoed
      embargo  -> 2025-09-01        ## future release

@access in the Engine

Access nodes compile to ATOM AccessNode objects (node class 0x13). The engine evaluates the access bitmask at query time before returning any node payload. Gated and embargoed statuses are re-evaluated on every request — they are never baked into the compiled artifact.

Part V — The People System

@people Is the Base

In AURA every human entity — artist, director, narrator, transcriber, editor, translator — is a person. The @people namespace is the single base from which all human references resolve. Authors, annotators, speakers, cast members: all are people first.

The plural/singular distinction in reference syntax is intentional and applies across all reference domains in AURA, not just people:

This applies to @person/@people, @genre/@genres, @role/@roles, @mood/@moods, @track/@tracks, @annotator/@annotators, @event/@events, and every other domain.

Singular vs Plural References

## One person — singular domain
speaker    -> @person/p4xt9k2

## Multiple people — plural domain with bracket list
cast       -> @people/[mt4qbz, vr8kfw, p4xt9k2]
speakers   -> @people/[cc9xpq, lp2wnr]
authors    -> @people/[p4xt9k2, j8mn2rk]

## One author (author is an alias for person)
author     -> @person/j8mn2rk
## Multiple authors
authors    -> @people/[p4xt9k2, j8mn2rk]

## One annotator — singular domain
annotator  -> @annotator/p9xb3mn
## Multiple annotators — plural domain
annotators -> @annotators/[p9xb3mn, p3xr7kn]

The @author/ and @authors/ domains are fully interchangeable with @person/ and @people/. All four resolve against info/people.aura and the same global cloud path.

Defining People

People are defined in info/people.aura. The namespace may be declared as people::, persons::, or authors:: — all are valid and compile identically.

## FILE: info/people.aura

people::

  p4xt9k2::
    name    -> "Mario Aleka"
    legal   -> "Mario A. Mwangi"
    born    -> 1993-04-11
    country -> KE
    city    -> "Nairobi"
    roles   -> @roles/[main-artist, vocalist, composer, producer]
    genre   -> @genres/[electronic, afro-soul, experimental]
    links::
      spotify -> spotify::artist/mario-aleka
      website -> https://marioaleka.com
    bio     -> "Nairobi-based producer and vocalist. Known for blending
                electronic architecture with Afro-Soul textures."

  j8mn2rk::
    name    -> "Jay Femar"
    legal   -> "James Femar Ogutu"
    country -> KE
    roles   -> @roles/[producer, mixer, engineer]

  k7wrt2::
    name    -> "Janet Doe"
    country -> KE
    roles   -> @roles/[writer, lyricist]

IDs are generated by the toolchain — never hand-authored:

aura generate person    -> p4xt9k2

Referencing People

## Credits block
credits::
  vocals   -> @person/p4xt9k2
  producer -> @person/j8mn2rk       ## @author/ also valid
  writers  -> @people/[k7wrt2, p4xt9k2]

## Inside text
description -> "Mixed by @person/j8mn2rk, written by @people/[k7wrt2]."

## Inside a lyric line
line/four::
  text    -> "She said my name @person/p4xt9k2 in a voice like static"
  speaker -> @person/p4xt9k2

## Cast and speakers
scene/cold-open::
  cast     -> @people/[mt4qbz, vr8kfw]

chapter/interview::
  speakers -> @people/[cc9xpq, lp2wnr]

Global Forms

All of the following resolve to the same node for p4xt9k2:

@person/p4xt9k2
@author/p4xt9k2
@aduki.org/person/p4xt9k2
@aduki.org/author/p4xt9k2
@aduki.org/people/p4xt9k2

Reference Domain Table

Complete singular/plural reference domain listing for all entity types.

People, Authors, Annotators

Vocabulary

Content Files

Time and Sync

Music-Specific

Annotation and Context

Events

Info and Meta

In-file Nodes

Cloud

Reserved (Future)

Part VI — The Annotator System

What an Annotator Is

An annotator is the actual human who writes, transcribes, and maintains a AURA file. Annotators are distinct from persons. A person is someone whose work appears in the media — an artist, a director, a narrator. An annotator is someone who documents and encodes that work in AURA.

Annotators include lyric transcribers, subtitle writers, metadata editors, translators working in AURA, and any contributor who authors or maintains a .aura file. They are accountable for the accuracy and completeness of the data.

Defining an Annotator

Annotators are defined in info/annotators.aura, separate from the persons file. They use the same generated ID format and the same p prefix, because they are also people. Keeping them in a separate file ensures the persons list remains clean as a list of content contributors only.

## FILE: info/annotators.aura

annotators::

  p9xb3mn::
    name     -> "Amina Weru"
    roles    -> transcriber | editor
    country  -> KE
    contact  -> amina@aduki.org

  p3xr7kn::
    name     -> "Diego Ferraz"
    roles    -> translator | annotator
    country  -> BR
    locale   -> pt-BR
    contact  -> diego@aduki.org

Declaring the Annotator in a File

Every AURA content file declares its annotator in the schema block.

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::music
  lang       -> en-US
  annotator  -> @annotator/p9xb3mn

When more than one annotator contributed to a single file:

schema::
  root        -> https://hami.aduki.org/aura/1.0
  kind        -> audio::music
  lang        -> en-US
  annotators  -> @annotator/[p9xb3mn, p3xr7kn]

Annotation attribution may also appear at the node level when different annotators wrote different sections of the same file:

verse/two::
  annotator -> @annotator/p3xr7kn
  lines::
    line/one::
      text -> "She said my name like static"

Global Annotator References

Annotator IDs follow the same global URI convention as all other IDs.

@annotator/p9xb3mn              <- local shorthand
@aduki.org/annotators/p9xb3mn   <- global cloud reference

An annotator who contributes to multiple catalogs has one global ID that appears in the annotators file of each project. Their global record is maintained at @aduki.org/annotators/{id} and is shared across all catalogs.

Part VII — The Meta Vocabulary System

Why Vocabulary Nodes?

Genre, role, and mood values in AURA have always been written as free strings:

genre -> Electronic | Afro-Soul | Experimental
roles -> main-artist | vocalist | composer

Strings work but they carry no semantic weight. They cannot be queried by type. They cannot carry additional metadata (parent genre, region, color for UI). They cannot be shared and resolved across catalogs. And they are fragile — a typo in one file silently diverges from the canonical term.

Vocabulary nodes make genre, role, and mood terms first-class typed entities, defined once and referenced everywhere — exactly like persons.

The meta/ Folder

Vocabulary files live in a folder called meta/ alongside info/. Unlike info/, which holds project-specific data, meta/ holds vocabulary definitions that may be local overrides of global platform vocabulary or entirely custom terms for the project.

meta/
  genres.aura     <- genre nodes
  roles.aura      <- role nodes
  moods.aura      <- mood vocabulary nodes

The meta/ folder is optional. If absent, the project uses only the global vocabulary available at @aduki.org/genre/, @aduki.org/role/, @aduki.org/mood/.

Vocabulary Node IDs

Vocabulary nodes use slug IDs — lowercase words with hyphens for compounds. This is the one exception to the generated hex ID rule. Vocabulary slugs are stable, human-readable, and platform-canonical.

electronic        <- genre slug
afro-soul         <- genre slug (hyphen for compound)
main-artist       <- role slug
lead-vocal        <- role slug
ethereal          <- mood slug

Slugs must be unique within their namespace. The platform registry prevents collisions across all catalogs.

genres.aura

## FILE: meta/genres.aura

genres::

  electronic::
    name    -> "Electronic"
    parent  -> @genre/instrumental
    tags    -> synthesizer | beat-driven | digital

  afro-soul::
    name    -> "Afro-Soul"
    parent  -> @genre/soul
    region  -> Africa
    note    -> "Soul music with African rhythmic and melodic elements"

  experimental::
    name    -> "Experimental"
    note    -> "Non-genre marker; denotes boundary-pushing or avant-garde work"

  instrumental::
    name    -> "Instrumental"

  soul::
    name    -> "Soul"
    parent  -> @genre/rnb

Each genre can declare a parent genre, building a simple genre hierarchy. The platform maintains the canonical genre tree at @aduki.org/genre/.

roles.aura

## FILE: meta/roles.aura

roles::

  main-artist::
    name  -> "Main Artist"
    kind  -> performer

  vocalist::
    name  -> "Vocalist"
    kind  -> performer
    note  -> "Any singing role; use lead-vocal or backing-vocal for specificity"

  lead-vocal::
    name  -> "Lead Vocalist"
    kind  -> performer
    parent -> @role/vocalist

  backing-vocal::
    name  -> "Backing Vocalist"
    kind  -> performer
    parent -> @role/vocalist

  composer::
    name  -> "Composer"
    kind  -> creator

  producer::
    name  -> "Producer"
    kind  -> creator

  mixer::
    name  -> "Mixing Engineer"
    kind  -> technical

  master::
    name  -> "Mastering Engineer"
    kind  -> technical

  director::
    name  -> "Director"
    kind  -> creator

  narrator::
    name  -> "Narrator"
    kind  -> performer

moods.aura

## FILE: meta/moods.aura

moods::

  ethereal::
    name      -> "Ethereal"
    energy    -> 0.2
    valence   -> positive

  reflective::
    name      -> "Reflective"
    energy    -> 0.3
    valence   -> neutral

  euphoric::
    name      -> "Euphoric"
    energy    -> 0.9
    valence   -> positive

  melancholic::
    name      -> "Melancholic"
    energy    -> 0.3
    valence   -> negative

  tense::
    name      -> "Tense"
    energy    -> 0.7
    valence   -> negative

  ominous::
    name      -> "Ominous"
    energy    -> 0.5
    valence   -> negative
    context   -> film | video | drama

The mood-vocabulary directive in schema:: declares which mood vocab file applies to the document. The engine validates mood descriptor values against this vocabulary at compile time.

schema::
  root            -> https://hami.aduki.org/aura/1.0
  kind            -> audio::music
  mood-vocabulary -> @meta/moods

Referencing Vocabulary Nodes

Vocabulary nodes are referenced via their domain prefix exactly like persons.

## Single genre reference
genre -> @genre/electronic

## Multi-genre reference — bracket form
genre -> @genre/[electronic, afro-soul, experimental]

## Single role reference
roles -> @role/main-artist

## Multi-role reference
roles -> @role/[main-artist, vocalist, composer]

## Mood reference in support node
descriptors -> @mood/[ethereal, reflective]

Reference Domains for Vocabulary

Global cloud forms:

@aduki.org/genre/electronic
@aduki.org/genre/[electronic, afro-soul]
@aduki.org/role/main-artist
@aduki.org/role/[main-artist, vocalist]
@aduki.org/mood/ethereal

Resolution Cascade

When the engine encounters a vocabulary reference, it resolves in this order:

1. The local meta/ folder for this project
2. The parent catalog’s meta/ folder (if inside a catalog)
3. The global platform vocabulary at @aduki.org/genre/, @aduki.org/role/, @aduki.org/mood/
4. If not found anywhere: compile warning, stored as unresolved string

Backward Compatibility — String Literals

The bare string form is still valid. The compiler tries to resolve each string against the vocabulary automatically.

## These two produce identical ATOM output when "electronic" exists in vocab
genre -> Electronic | Afro-Soul | Experimental
genre -> @genre/[electronic, afro-soul, experimental]

The compiler lowercases and slugifies the string, looks it up in the vocab, and if found, replaces it with a typed reference arc. If not found, it stores the string literal and issues a compile warning in strict mode. This means existing AURA files continue to compile without modification.

Part VIII — Media Kinds

Kind Declaration

Every AURA document declares its media kind upfront. The schema block also declares the annotator responsible for this file.

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::music
  lang       -> en-US
  annotator  -> @annotator/p9xb3mn

Supported Kinds

## Audio
kind -> audio::music          ## album, EP, single
kind -> audio::podcast        ## podcast show or episode
kind -> audio::audiobook      ## spoken word with chapters
kind -> audio::live           ## live recording

## Video
kind -> video::movie          ## feature or short film
kind -> video::series         ## episodic series
kind -> video::podcast        ## video podcast episode
kind -> video::documentary    ## documentary
kind -> video::music          ## music video
kind -> video::live           ## live performance or concert
kind -> video::short          ## short-form under 10 minutes

## Mixed
kind -> mixed::album          ## visual album — audio and video tied
kind -> mixed::interactive    ## interactive or branching media

The kind is not cosmetic. It tells the AURA engine which namespaces are required, which are optional, and how to map the structure to ATOM.

Part IX — Content Node Architecture

The Granularity Stack

AURA maps to ATOM’s content node hierarchy. The engine walks this stack:

[Macro-Node]  Act / Scene / Shot / Verse       MANDATORY container
    [Meso-Node]  Line / Dialogue               MANDATORY temporal anchor
        [Micro-Node]  Word / Token             optional richsync
            [Nano-Node]  Syllable / Phoneme    optional karaoke
                [Pico-Node]  Letter / Character   optional 60fps animation

You do not have to go all the way down. Define as much granularity as your use case needs. The engine degrades gracefully. If syllables are absent, it falls back to words. If words are absent, it falls back to lines.

Macro and Meso are mandatory in every AURA document that contains content nodes. Micro, Nano, and Pico are optional.

Node Identifier Convention

Every named node uses the slash identifier convention. The type comes before the slash. The label after the slash is an ordinal in English words or a unique meaningful name in lowercase with hyphens if compound.

verse/one::        chorus/one::      bridge/one::
verse/two::        chorus/two::      scene/cold-open::
line/one::         word/one::        syllable/one::
chapter/intro::    act/one::         shot/one::

Content Nodes for Music

## FILE: tracks/t7xab3c.aura
>> @info/metadata

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::music
  lang       -> en-US
  annotator  -> @annotator/p9xb3mn

manifest::
  name   ! -> "Signal Loss"
  creator  -> @person/p4xt9k2

## Content node hierarchy (Macro > Meso > Micro > Nano)
verse/one::
  time -> 22s~1m10s
  lines::
    line/one::
      text    -> "The signal drops at the edge of the grid"
      time    -> 22s~25.4s
      speaker -> @person/p4xt9k2
      words::
        word/one::
          text -> "The"
          time -> 22s~22.3s
          syllables::
            syllable/one::
              text -> "The"
              time -> 22s~22.3s
        word/two::
          text -> "signal"
          time -> 22.3s~22.9s
    line/two::
      text    -> "She said my name like static"
      time    -> 25.4s~28.8s
      speaker -> @person/p4xt9k2

chorus/one::
  time -> 1m10s~1m50s
  lines::
    line/one::
      text -> "Find me where the frequency breaks"
      time -> 1m10s~1m16s
    line/two::
      text -> "Find me at the edge of everything"
      time -> 1m16s~1m22s

credits::
  vocals   -> @person/p4xt9k2
  producer -> @author/j8mn2rk
  writer   -> @person/k7wrt2

Content Nodes for Podcasts

## FILE: episodes/ep7xb3n.aura
>> @info/metadata

schema::
  root      -> https://hami.aduki.org/aura/1.0
  kind      -> audio::podcast
  lang      -> en-US
  annotator -> @annotator/p9xb3mn

manifest::
  name    ! -> "Recursive"
  show      -> "The Mesh"
  season    -> one
  episode   -> three
  host      -> @person/cc9xpq

chapter/cold-open::
  name     -> "Cold Open"
  time     -> 0s~3m15s
  speakers -> @person/[cc9xpq]
  lines::
    line/one::
      text    -> "Welcome back to The Mesh."
      speaker -> @person/cc9xpq
      time    -> 0s~2s
    line/two::
      text    -> "Today we go deep into something that terrifies
                  engineers and excites theorists in equal measure."
      speaker -> @person/cc9xpq
      time    -> 2s~9s

chapter/interview::
  name     -> "Interview Begins"
  time     -> 3m15s~18m40s
  speakers -> @person/[cc9xpq, lp2wnr]

Content Nodes for Films

## FILE: f6np2qr.aura   (or split into per-scene files under scenes/)
>> @info/metadata

schema::
  root      -> https://hami.aduki.org/aura/1.0
  kind      -> video::movie
  lang      -> en-US
  annotator -> @annotator/p9xb3mn

scene/cold-open::
  name     -> "Cold Open: Sector 7"
  time     -> 00:00:00~00:03:15
  location -> "Sector 7 Grid Hub"
  cast     -> @person/[mt4qbz]

scene/the-diagnostic::
  name     -> "The Diagnostic"
  time     -> 00:03:15~00:11:40
  cast     -> @person/[mt4qbz, vr8kfw]
  dialogue::
    line/one::
      speaker -> @person/mt4qbz
      text    -> "The mesh isn't failing — it's been redirected."
      time    -> 00:04:12~00:04:18

scene/root-node::
  name -> "The Root Node"
  time -> 00:38:20~00:44:10
  cast -> @person/[mt4qbz]
  note -> "Callback to @scene/cold-open visual motif"

Part X — Support Node Architecture

Why Support Nodes Exist

Content nodes carry text payloads — the lyrics, dialogue, words, syllables, and characters that are rendered to the audience. Support nodes carry structured metadata that supports, contextualizes, and governs those content nodes without carrying renderable text.

Support nodes are time-anchored relational objects compiled to the ATOM mesh as first-class place nodes in the OCPN graph. They are registered in the interval tree alongside content nodes. A stabbing query at any time t returns both the active content nodes and all support nodes whose intervals overlap t.

Support nodes are authored in the support:: namespace within any content file. They can be declared at document level for nodes that span the entire work.

Segment Support Nodes

A segment node marks a named musical or structural section. It has temporal extent but no lyric payload. Segment support nodes use the slash identifier convention matching their content node counterparts.

support::
  segments::

    intro/one::
      kind    -> intro
      time    -> 0s~22s
      energy  -> 0.3

    verse/one::
      kind    -> verse
      time    -> 22s~1m10s
      energy  -> 0.6
      instruments -> @instrument/[keys, bass]

    chorus/one::
      kind    -> chorus
      time    -> 1m10s~1m50s
      energy  -> 0.9

    bridge/one::
      kind    -> bridge
      time    -> 2m30s+28s
      energy  -> 0.5
      note    -> "Key modulation — Ab major to F# minor"

The kind field accepts: intro, verse, pre-chorus, chorus, post-chorus, bridge, drop, breakdown, outro, interlude, instrumental, transition, ad-lib, hook, or any custom value.

Instrument Support Nodes

An instrument node tracks the presence and activity of a specific instrument across one or more time windows within a track.

support::
  instruments::

    keys::
      name      -> "Rhodes Piano"
      family    -> keys
      performer -> @author/j8mn2rk
      active::
        - 0s~22s
        - 22s~1m10s
        - 2m30s~3m47s

    bass::
      name    -> "Electric Bass"
      family  -> bass
      active::
        - 22s~3m47s

    drums::
      name   -> "Electronic Drum Kit"
      family -> percussion
      active::
        - 22s~2m30s
        - 2m58s~3m47s
      stem   -> @track/t7xab3c::stems/drums

Chapter Support Nodes

A chapter node marks a navigable division. It is the primary navigation unit for podcast chapters, audiobook chapters, film act breaks, and album sides.

support::
  chapters::

    side/one::
      kind   -> side
      title  -> "Side A"
      index  -> one
      time   -> 0s~22m00s
      cover  -> @art/cover-a

    side/two::
      kind   -> side
      title  -> "Side B"
      index  -> two
      time   -> 22m00s~44m30s
      cover  -> @art/cover-b

Credit Window Support Nodes

A credit window node anchors a contributor credit to a specific time window. It answers when in the playback timeline a given person’s contribution occurs.

support::
  credits::

    credit/one::
      person  -> @person/p4xt9k2
      role    -> lead-vocal
      time    -> 22s~1m10s
      via     -> @verse/one

    credit/two::
      person  -> @author/j8mn2rk
      role    -> keys
      time    -> 0s~22s

Translation Support Nodes

A translation node shadows a content node in a different language or script. It carries a text payload that is always derivative — a translation or transliteration of the canonical content node it shadows.

Translation nodes are structured within the support:: namespace and grouped by locale. A single content node can have translations in multiple locales simultaneously.

support::
  translations::

    fr-FR::
      line/one::
        source  -> @verse/one/line/one
        locale  -> fr-FR
        text    -> "Le signal tombe au bord de la grille"
        time    -> 22s~25.4s
        via     -> @annotator/p3xr7kn

      line/two::
        source  -> @verse/one/line/two
        locale  -> fr-FR
        text    -> "Elle a dit mon nom comme de la statique"
        time    -> 25.4s~28.8s

    sw-KE::
      line/one::
        source  -> @verse/one/line/one
        locale  -> sw-KE
        script  -> Latn
        text    -> "Ishara inashuka ukingoni mwa gridi"
        time    -> 22s~26.1s

Mood Support Nodes

A mood node attaches emotional, tonal, or affective metadata to a time window.

support::
  moods::

    mood/one::
      time        -> 0s~22s
      descriptors -> ethereal | reflective
      confidence  -> 0.82
      source      -> authored

    mood/two::
      time        -> 1m10s~1m50s
      descriptors -> euphoric
      confidence  -> 0.91
      source      -> hybrid
      note        -> "High-energy chorus — confirmed by analysis engine"

The mood vocabulary is declared in the directives:: namespace for this file. The mood-vocabulary directive specifies which descriptor values are valid.

Rights Support Nodes

A rights node marks a segment with licensing or rights boundary metadata.

support::
  rights::

    rights/doc::
      scope   -> document
      territory -> worldwide
      license -> "ISRC:KE-A00-24-00001"
      holder  -> @person/p4xt9k2
      expires -> 2034-11-01

    rights/sample::
      scope     -> window
      time      -> 2m44s~2m58s
      territory -> worldwide
      license   -> proprietary
      holder    -> "Unnamed Session Records"
      blocked   -> US | CA
      note      -> "Sample clearance pending in North American territories"

Ad Slot Support Nodes

An ad slot node defines a pre-declared advertising insertion point.

support::
  slots::

    slot/pre::
      kind     -> pre-roll
      time     -> 0s~0s
      max      -> 30s
      fill-policy -> optional

    slot/mid::
      kind     -> mid-roll
      time     -> 1m50s~1m50s
      max      -> 60s
      fill-policy -> required

    slot/post::
      kind     -> post-roll
      time     -> 3m47s~3m47s
      max      -> 30s
      fill-policy -> house

Sync Anchor Support Nodes

A sync anchor node declares an explicit, authored hard recovery point.

support::
  anchors::

    anchor/verse-one::
      kind -> hard
      time -> @time/22s
      note -> "Start of verse one — verified spectral anchor"

    anchor/chorus-one::
      kind -> verified
      time -> @time/1m10s

    anchor/chorus-two::
      kind -> hard
      time -> @time/2m00s

Tempo Support Nodes

A tempo node declares the rhythmic tempo at a time window. Tempo changes affect lyric sync directly — the engine uses tempo nodes to validate and adjust word- and syllable-level timing when the beat grid shifts. This is critical for tracks with tempo automation, live recordings, or freestyle sections.

support::
  tempo::

    tempo/one::
      time    -> 0s~1m10s
      bpm     -> 112
      type    -> steady
      grid    -> 4/4

    tempo/two::
      time    -> 1m10s~1m50s
      bpm     -> 116
      type    -> increasing
      note    -> "Slight tempo push into chorus"

    tempo/three::
      time    -> 2m30s~2m58s
      bpm     -> 92
      type    -> variable
      note    -> "Bridge — rubato feel, no strict grid"

Fields:

• time — the interval during which this tempo applies
• bpm — beats per minute at the start of the interval
• type — one of: steady, increasing, decreasing, variable, free
• grid — time signature (4/4, 3/4, 6/8, etc.)
• note — optional annotation

References:

## A lyric line may declare the tempo it falls under
line/one::
  text  -> "The signal drops at the edge of the grid"
  time  -> 22s~25.4s
  tempo -> @tempo/one

Sample Support Nodes

A sample node attributes a sampled element to its original source: which track, which segment, what kind of sample, and clearance status. Samples differ from interpolations — a sample uses the actual audio recording; an interpolation re-records the same melody or progression.

support::
  samples::

    sample/one::
      source  -> @track/t9vkx7q        ## original track sampled
      time    -> [1m20s, 1m24s, 4s]    ## portion of source used
      used-at -> 2m44s                  ## where this appears in the work
      kind    -> loop                   ## loop | stab | chop | vocal | melodic | rhythmic
      cleared -> live
      note    -> "Four-bar drum loop from bridge section"

    sample/two::
      source  -> @aduki.org/track/mx4nq7b
      time    -> [0s, 3s, 3s]
      used-at -> 0s
      kind    -> vocal
      cleared -> dark
      note    -> "Vocal stab — clearance pending"

Fields:

• source — @track/id or global @aduki.org/track/id of the sampled work
• time — [start, end, duration] of the portion taken from the source
• used-at — time point in this work where the sample appears
• kind — loop | stab | chop | vocal | melodic | rhythmic | atmospheric | custom
• cleared — boolean: true if rights are confirmed, false if pending
• note — optional annotation

Explainer Support Nodes

An explainer node attaches a detailed explanation to any content node — a line, a word, a scene, an act. Explainers may be cultural glosses, historical context, lyrical interpretation, technical notes, or detailed per-node documentation.

support::
  explainers::

    explainer/line-four::
      target  -> @line/four
      kind    -> cultural
      lang    -> en-US
      text    -> "\"She said my name like static\" — references the protagonist's
                   experience of dissociation during radio interference outages
                   documented in urban Nairobi circa 2019."

    explainer/chorus-concept::
      target  -> @chorus/one
      kind    -> lyrical
      lang    -> en-US
      text    -> "The chorus collapses the metaphor: \"frequency\" = emotional bandwidth.
                   The grid is both the power grid and the social one."

    explainer/bridge-chord::
      target  -> @bridge/one
      kind    -> technical
      lang    -> en-US
      text    -> "Key modulation from Ab major to F# minor via enharmonic pivot
                   (G# = Ab). Creates tension before final chorus resolution."

Fields:

• target — @node/id of the content or support node being explained
• kind — cultural | lyrical | historical | technical | translation | annotation | custom
• lang — IETF BCP 47 locale of this explanation
• text — the explanation content
• via — optional @person/id of the author of this explanation
• note — optional further annotation

Interpolation Support Nodes

An interpolation node attributes a melodic, harmonic, or lyrical element that is re-recorded from an existing composition — distinct from a sample, which uses the original audio. Interpolations require a separate mechanical license, not a master license.

support::
  interpolations::

    interpolation/one::
      source   -> @aduki.org/track/mx4nq7b
      element  -> melody
      time     -> [32s, 1m10s, 38s]    ## interval in this work
      cleared  -> true
      writers  -> @people/[p4xt9k2, k7wrt2]
      note     -> "Chorus melody re-records main hook from source. Separate
                   mechanical clearance filed 2024-09."

Fields:

• source — @track/id or global URI of the original composition
• element — melody | chord-progression | lyric | rhythm | hook | bassline | custom
• time — [start, end, duration] interval in this work where it appears
• cleared — whether mechanical license is confirmed
• writers — @people/[…] who wrote the interpolated element in this work
• note — optional annotation

Instruction Support Nodes

An instruction node carries a processing instruction — a directive to the engine, player, or downstream system. Instructions are not rendered to the audience. They control playback behavior, encoding choices, looping logic, or editorial flags.

support::
  instructions::

    instruction/intro-loop::
      kind      -> loop
      target    -> @segment/intro-one
      condition -> @event/first-play
      count     -> 2
      note      -> "Loop intro twice before verse on first play"

    instruction/fade-out::
      kind      -> fade
      target    -> @segment/outro-one
      duration  -> 8s
      type      -> linear
      note      -> "Fade to silence over last 8 seconds"

    instruction/skip-ad::
      kind      -> skip
      target    -> @slot/mid
      condition -> @event/subscriber
      note      -> "Skip mid-roll for authenticated subscribers"

Fields:

• kind — loop | skip | jump | repeat | fade | crossfade | trim | mute | custom
• target — @segment/id, @slot/id, or @chapter/id this instruction applies to
• condition — optional @event/id that triggers this instruction
• count — for loop: number of repetitions
• duration — for fade: fade length
• type — for fade: linear | exponential | logarithmic
• note — optional annotation

Event Support Nodes

An event node defines a condition-triggered signal. When the engine detects the triggering condition at playback time, it fires the configured signal to all registered listeners. Events bridge AURA media data with real-world reactive systems — smart lighting, AR effects, haptic feedback, IoT stage control, accessibility adapters, and interactive overlays.

support::
  events::

    event/lights-dim::
      trigger   -> @moods/[ominous, tense]
      at        -> @time/1m32s
      signal    -> lights::dim(0.1)
      kind      -> ambient
      note      -> "Dim all stage lights to 10% when tense mood begins"

    event/strobe-drop::
      trigger   -> @segment/drop-one
      at        -> onset                   ## fires at the start of the segment
      signal    -> lights::strobe | haptic::pulse(80ms)
      kind      -> reactive
      note      -> "Strobe + haptic pulse on bass drop"

    event/scene-colour::
      trigger   -> @scene/cold-open
      at        -> onset
      signal    -> lights::colour(#0a1628) | ar::overlay(frost)
      kind      -> ambient
      note      -> "Cold-open: deep navy, AR frost overlay on screens"

    event/credits-roll::
      trigger   -> @segment/outro-one
      at        -> onset
      signal    -> display::credits | lights::fade(white, 30s)
      kind      -> editorial
      note      -> "Begin credits display and fade to white on outro"

    event/subscriber-only::
      trigger   -> condition::subscriber == false
      at        -> @slot/mid
      signal    -> player::insert-ad
      kind      -> interactive

Fields:

• trigger — what fires this event: a mood reference (@mood/slug or @moods/[…]), a segment reference (@segment/id), a scene (@scene/id), a time point (@time/value), or a boolean condition string
• at — when within the trigger’s interval to fire: onset | offset | peak | @time/value
• signal — what to emit. Free-form dotted path: system::action(params). Multiple signals separated by |
• kind — ambient | reactive | interactive | editorial | broadcast | custom
• note — optional

Signal path convention:

lights::dim(0.1)              <- lights subsystem, dim to 10%
lights::colour(#0a1628)      <- set colour
lights::strobe                <- strobe
haptic::pulse(80ms)          <- haptic motor, 80ms burst
ar::overlay(frost)            <- AR layer
display::credits              <- show credits overlay
player::insert-ad             <- trigger ad insertion
player::pause                 <- pause playback
iot::gpio(17, HIGH)          <- raw GPIO signal for custom hardware

Events compile to ATOM EventNode objects (node class 0x0D) registered in the interval tree. The engine evaluates their trigger conditions during the stabbing query loop and emits signals via the registered EventBus.

Part XI — The History System

Why History Is First-Class

Every change to an AURA document is permanent by design. No take is ever overwritten or deleted. The entire history of a file — every edit, every annotator’s contribution, every version of every line — is preserved in the ledger and accessible via the @history reference domain.

This is not backup. This is provenance. In music, film, and spoken word, the origin of every lyric, every subtitle edit, every credit change is a legal and creative matter. AURA treats history as data, not metadata.

Media-Native Vocabulary

AURA uses its own versioning vocabulary derived from the recording studio, the film production floor, and the broadcast booth. Git verbs are not used.

Taking a Snapshot

A take captures the current state of one or more AURA files. It receives a generated ID and an optional message. Takes are immutable once recorded.

## Toolchain commands
aura take                                -> cx3ab7k
aura take "Finalized verse two timing"   -> cx3ab8m
aura take "Released to Spotify"          -> cx3ab9n

The take ID follows the standard format with the tx prefix reserved for take objects:

tx3ab7k    <- a take

Takes are ordered, append-only, and permanent. Every node state at every take is resolvable via @history.

Marking a Take

A mark is a human-readable name attached to a specific take. Marks are how you identify releases, versions, significant milestones, and named checkpoints.

## Toolchain commands
aura mark v1.0        -> marks current take as "v1.0"
aura mark premiere    -> marks current take as "premiere"
aura mark final-mix   -> named checkpoint

Marks resolve via @history just like take IDs:

@history/v1.0
@history/premiere
@history/final-mix

The @history Reference Domain

@history is the AURA reference domain for versioned access. It accepts take IDs, mark names, ordinal positions, and node paths.

Referencing a Take

## A specific take by generated ID
@history/tx3ab7k

## A named mark
@history/v1.0
@history/premiere

## Relative position (ordinal from current, past-tense)
@history/~1       <- one take before current
@history/~5       <- five takes before current
@history/~0       <- current take (same as @history/current)

## The first take ever recorded
@history/origin

## The current take (latest)
@history/current

Referencing a Node at a Specific Take

Any node path follows the take reference via ::

## What did verse/one look like at take v1.0?
@history/v1.0::verse/one

## What was line/four at five takes ago?
@history/~5::verse/one/line/four

## The original first take's chorus
@history/origin::chorus/one

## Compare node at two specific marks
@history/v1.0::verse/one/line/two
@history/premiere::verse/one/line/two

This is how editors verify what a specific line said at a specific version, what a credit said at release, or what a subtitle read at broadcast.

In-Document History Declarations

An AURA document may declare history references inline as metadata, linking back to the take at which a piece of content was first authored or last changed.

## In a line node
line/four::
  text     -> "She said my name like static"
  time     -> 25.4s~28.8s
  speaker  -> @person/p4xt9k2
  authored -> @history/tx3ab7k      ## take when this line was first recorded
  revised  -> @history/v1.0         ## take when last revised

## In a translation node
fr-FR/line/one::
  source   -> @verse/one/line/one
  text     -> "Le signal tombe au bord de la grille"
  via      -> @annotator/p3xr7kn
  authored -> @history/tx3ab8m

Streams — Parallel Development

A stream is a named parallel line of development within a project. Streams allow simultaneous work on translations, regional variants, alternative edits, and pre-release drafts — all without affecting the main line.

## Toolchain commands
aura stream open translation-fr      ## open a new stream
aura stream open deluxe-edition      ## another parallel stream
aura stream list                     ## show all active streams
aura stream close translation-fr     ## close and archive a stream

Streams are referenced in @history paths:

@history/stream/translation-fr
@history/stream/translation-fr::verse/one

Referencing the main line:

@history/main                        ## the primary line of development
@history/main::chorus/one

Rewinding

Rewind restores the working draft to the state of a previous take. The rewind itself is non-destructive — a rewind creates a new take, pointing the draft to the older state. The history ledger always grows forward.

## Toolchain commands
aura rewind tx3ab7k                  ## rewind to a specific take
aura rewind v1.0                     ## rewind to a named mark
aura rewind ~3                       ## rewind three takes

After rewinding, a fresh take records the restored state:

aura rewind v1.0
aura take "Restored to premiere version"   -> cx3ac0p

The history now shows the chain:

tx3ab7k  "original"
tx3ab8m  "Finalized verse two"
cx3ab9n  "Released to Spotify"       <- forward history preserved
cx3ac0p  "Restored to premiere"      <- rewind take — ledger entry

Viewing the Ledger

## Show full history of this file
aura ledger

## Show history of a specific node
aura ledger verse/one/line/four

## Show delta between two takes
aura delta tx3ab7k tx3ab8m

## Show delta between a mark and current
aura delta v1.0 current

The ledger output shows:

take      mark       when                  message
cx3ac0p              2025-04-13T18:00Z     "Restored to premiere version"
cx3ab9n   release    2025-03-01T09:00Z     "Released to Spotify"
cx3ab8m   v1.0       2025-02-14T12:30Z     "Finalized verse two timing"
tx3ab7k   origin     2025-01-10T10:00Z     "First take"

Mixing Streams

When work on a stream is complete, it is mixed back into the main line (or another stream).

aura mix translation-fr              ## mix translation-fr into current stream
aura take "Mixed French translation" -> cx3ac1q

The mix creates a delta between the stream’s head and the target, applies it, and records a new take. Both streams’ full histories remain intact and independently resolvable.

Sync and Release

release publishes the current take to the cloud distribution. sync pulls the latest released state from the cloud into the local working state.

aura release                         ## publish current take to @aduki.org store
aura sync                            ## pull latest from @aduki.org store

After release, the take is also accessible from the global cloud path:

@aduki.org/track/t7xab3c/history/current
@aduki.org/track/t7xab3c/history/premiere
@aduki.org/track/t7xab3c/history/~1::verse/one/line/four

Holding Work

hold parkss the current working draft without taking a snapshot. Useful when switching to a different stream mid-session.

aura hold                            ## park current draft
aura stream open urgent-fix          ## switch context
## ... make changes ...
aura take "Emergency credit fix"
aura stream close urgent-fix
aura hold restore                    ## restore parked draft

History in the Engine

The history system compiles to HAMI HistoryNode objects (node class 0x14). The engine stores the full delta chain, not full copies. Each take records only what changed from the previous take. The ATOM stabbing query can be directed at any historical take state via the @history domain.

A node query at @history/v1.0::verse/one causes the engine to reconstruct the verse/one node from the delta chain up to the v1.0 take and return it as if it were the current state — without altering the active document.

History resolution is always read-only. The working state can only change via take, rewind, or mix.

Part XII — The Manifest and Meta Namespaces

What Each Namespace Does

manifest:: — The identity of this work. What is it? Who made it? What is it called? These fields are permanent and do not change across releases.

meta:: — The context of this work. When was it released? What genre? What are its relationships to other works? What credits apply globally? These fields may be updated.

For projects with multiple files, both manifest:: and meta:: live in info/metadata.aura and are inherited by all member files via >>.

Manifest

manifest::
  name      ! -> "Signal Loss"
  creator   ! -> @person/p4xt9k2
  version     -> 1.0.0
  language    -> en-US
  released    -> 2024-11-01
  label       -> "Self-Released"
  territory   -> worldwide

For a series or podcast with episodes, manifest:: describes the show, while each track or episode file carries its own identity.

Meta

meta::
  genre      -> Electronic | Afro-Soul | Experimental
  tags       -> Nairobi | Instrumental | Ambient
  isrc       -> "KE-A00-24-00001"
  bpm        -> 112
  key        -> "F# minor"

  credits::
    main       -> @person/ao9txa
    vocals     -> @person/ao9txa
    producer   -> @person/j3fmr9
    writer     -> @person/k7wrt2 | @person/h8dv5x
    mixer      -> @person/j3fmr9
    mastering  -> @person/j3fmr9

  description -> "Five tracks built from field recordings across Nairobi.
                  Composed by @person/ao9txa over eighteen months.
                  Mixed and mastered by @person/j3fmr9."

  related::
    previous   -> @collection/c4xvp2k          ## prior release
    next       ?
    sampled    -> @track/t9vkx7q @time/2m44s  ## sampled segment

Part XII — Collections and Variations

Why Collections Are First-Class in AURA

A single AURA document describes one work: one track, one episode, one film. But media is almost never singular. An album is a collection of tracks. A series is a collection of episodes. A label’s catalog is a collection of albums.

AURA handles this through the collection:: namespace, which authors the CollectionManifest that the engine compiles to a HAMI index document. A collection file is authored separately from its member files.

Collection File Structure

A collection file carries the schema, manifest, meta, and collection:: namespaces. It does not carry tracks::, scenes::, or chapters:: — those belong to the member files.

## FILE: collections/c8xab3d.aura

schema::
  root    -> https://hami.aduki.org/aura/1.0
  kind    -> audio::music
  lang    -> en-US

--

manifest::
  name       ! -> "Signal Loss"
  creator    ! -> @person/ao9txa
  version      -> 1.0.0
  released     -> 2024-11-01
  territory    -> worldwide
  label        -> "Self-Released"

--

meta::
  genre      -> Electronic | Afro-Soul | Experimental
  total-duration -> 22m41s
  track-count    -> 5

--

collection::
  kind        -> album
  persons-ref -> @info/people

  members::

    track.01::
      index    -> 1
      name     -> "Signal Loss"
      aura-ref -> tracks/t7xab3c.aura
      duration -> 3m47s

    track.02::
      index    -> 2
      name     -> "Fold"
      aura-ref -> tracks/t4mn2rp.aura
      duration -> 4m12s

    track.03::
      index    -> 3
      name     -> "Recursive"
      aura-ref -> tracks/t9vkx7q.aura
      duration -> 5m08s

    track.04::
      index    -> 4
      name     -> "Meridian"
      aura-ref -> tracks/t2nq5wb.aura
      duration -> 4m55s

    track.05::
      index    -> 5
      name     -> "Origin Point"
      aura-ref -> tracks/t6rj8vc.aura
      duration -> 4m39s

Declaring Variations

Variations are declared within the collection:: namespace. Each variation references the canonical member it diverges from.

collection::
  ## ... members as above

  variations::

    track.01.acoustic::
      canonical-ref   -> track.01
      variant-kind    -> acoustic
      name            -> "Signal Loss (Acoustic)"
      aura-ref        -> variants/t7xab3c-acoustic.aura
      duration-delta  -> +0m34s

    track.01.radio-edit::
      canonical-ref   -> track.01
      variant-kind    -> radio-edit
      name            -> "Signal Loss (Radio Edit)"
      aura-ref        -> variants/t7xab3c-radio.aura
      duration-delta  -> -0m47s

    track.01.sw-KE::
      canonical-ref   -> track.01
      variant-kind    -> dubbed
      locale          -> sw-KE
      name            -> "Signal Loss (Kiswahili)"
      aura-ref        -> variants/t7xab3c-swahili.aura
      duration-delta  -> +0m04s

Series and Season Nesting

A series is authored as a collection of seasons. A season is authored as a collection of episodes. The structure mirrors the content hierarchy.

## FILE: collections/c3xn7rp.aura

schema::
  root -> https://hami.aduki.org/aura/1.0
  kind -> audio::podcast
  lang -> en-US

manifest::
  name       ! -> "The Mesh"
  creator    ! -> @person/cc9xpq
  version      -> 1.0.0

collection::
  kind        -> series
  persons-ref -> @info/people

  members::

    season.01::
      kind     -> season
      index    -> 1
      name     -> "Season One"
      aura-ref -> seasons/s1xp4fm.aura

    season.02::
      kind     -> season
      index    -> 2
      name     -> "Season Two"
      aura-ref -> seasons/s2xq8nt.aura

A season collection file follows the same pattern, listing episode member files in its members:: block.

Shared Person Index

When a collection:: block declares a persons-ref, the engine uses that file as the primary person index for all members of the collection. Individual member files may still declare a local persons:: block for members not present in the shared index. The engine resolves @person/slug references against the shared index first, then the local block.

## FILE: info/people.aura

people::

  ao9txa::
    name    -> "Mario Aleka"
    roles   -> main-artist | vocalist | composer
    country -> KE

  j3fmr9::
    name    -> "Jay Femar"
    roles   -> producer | mixer
    country -> KE

  k7wrt2::
    name    -> "Janet Doe"
    roles   -> writer

Cross-Member References

Within any member file, you can reference other members in the same collection using the @member/ domain.

## In track 03, reference a moment in track 01
note -> "Melodic theme introduced at @member/track.01 @time/1m10s"

## Reference a specific line in another episode
## (from an episode AURA file within a series)
related-to -> @member/ep7xb3n::scene/cold-open

Part XII — Source Data Store Directives

Declaring the Store

The directives:: namespace is extended to support source data store declaration. This tells the engine where to find and write compiled artifacts for this file and its collection.

directives::
  store           -> aura://store.hami.aduki.org/catalogs/cx0ab3de
  collection-ref  -> @collection/c8xab3d
  variation-default -> canonical
  rights-verify   -> true
  granularity     -> word
  dtw-enabled     -> true
  mood-vocabulary -> joyful | melancholic | tense | euphoric |
                     reflective | aggressive | ethereal | romantic

Store URI Formats

## Cloud object store (production)
store -> aura://store.hami.aduki.org/catalogs/{catalog-id}

## Cloudflare R2 or equivalent
store -> r2://bucket-name/catalogs/{catalog-id}

## Self-hosted
store -> https://media.example.com/atom/{catalog-id}

## Local filesystem (development)
store -> file:///home/user/projects/signals/dist

Directives Quick Reference

Part XIII — Media Assets, Industry Entities, and Availability

@art — Cover Art Assets

An art node declares a static image asset for a work: album covers, single art, movie posters, episode art, and show banners. Art assets are uploaded separately to the Triverse store to obtain their cloud URL. The local project stores the URL as literal text — no image files live in the project. Art nodes live in info/arts.aura and compile to HAMI manifests. They are not interval-tree indexed.

## FILE: info/arts.aura

arts::

  cover-main::
    kind  -> square
    url   -> https://store.hami.aduki.org/art/ar4xab3c?ratio=square
    note  -> "Primary album cover — 3000x3000px"

  cover-wide::
    kind  -> 16:9
    url   -> https://store.hami.aduki.org/art/ar4xab3c?ratio=16x9
    note  -> "Streaming platform header"

  poster-tall::
    kind  -> 2:3
    url   -> https://store.hami.aduki.org/art/ar7mn9rk?ratio=2x3
    note  -> "Tall movie poster"

Aspect ratio kinds: square, landscape, portrait, 16:9, 4:3, 9:16, 21:9, 2:3, custom. For custom, declare width and height in pixels as additional fields.

Reference syntax:

cover  -> @art/cover-main
covers -> @arts/[cover-main, cover-wide, poster-tall]

## In a manifest
manifest::
  name  -> "Signal Loss"
  cover -> @art/cover-main

## Global cloud reference
@aduki.org/art/{id}

Art nodes compile to ATOM ArtNode objects (node class 0x15).

@motion — Motion Cover Assets

A motion node declares a short looping video or animated art asset: Apple Music-style animated album covers, ambient show backgrounds. Motion assets are uploaded separately to the Triverse store. The local project stores the cloud URL as literal text — no video files live in the project. Motions are authored in the motions:: block of info/arts.aura.

motions::

  motion-main::
    kind      -> album-motion
    url       -> https://store.hami.aduki.org/motion/mo7xk9p2
    duration  -> 8s
    loop      -> live
    ratio     -> square
    note      -> "Apple Music-style looping cover — 1080x1080px"

  motion-wide::
    kind      -> album-motion
    url       -> https://store.hami.aduki.org/motion/mo3xb5qr
    duration  -> 6s
    loop      -> live
    ratio     -> 16:9

Motion kinds: album-motion, episode-motion, movie-motion, show-motion, background.

Reference syntax:

motion  -> @motion/motion-main
motions -> @motions/[motion-main, motion-wide]

Motion nodes compile to ATOM MotionNode objects (node class 0x16).

@trailer — Trailer and Preview Assets

A trailer inherits from @motion — it is a purposeful motion clip with deliberate editorial structure. Trailer assets are uploaded separately to the Triverse store. The local project stores the cloud URL as literal text. Trailers are declared in the trailers:: block of info/arts.aura.

trailers::

  main-trailer::
    kind      -> movie-trailer
    url       -> https://store.hami.aduki.org/trailer/tr6xp3lm
    duration  -> 2m30s
    loop      -> dark
    ratio     -> 16:9
    released  -> 2024-09-01
    note      -> "Official theatrical trailer"

  ep-preview::
    kind      -> episode-trailer
    url       -> https://store.hami.aduki.org/trailer/tr2mn8xk
    duration  -> 45s
    ratio     -> 16:9
    loop      -> dark

Trailer kinds: movie-trailer, episode-trailer, podcast-trailer, series-trailer, teaser, announcement, behind-the-scenes.

Reference syntax:

trailer  -> @trailer/main-trailer
trailers -> @trailers/[main-trailer, ep-preview]

Trailer nodes compile to ATOM TrailerNode objects (node class 0x17).

@studio — Production Studio Entities

A studio node declares a production studio, production company, or broadcast network. Studios support ownership hierarchy via the parent field. They are defined in info/studios.aura.

## FILE: info/studios.aura

studios::

  st4xab3c::
    name    -> "Warner Bros. Pictures"
    kind    -> film
    country -> US
    founded -> 1923-04-04
    logo    -> @art/wb-logo

  st8mn2rk::
    name    -> "DC Films"
    kind    -> film
    parent  -> @studio/st4xab3c     ## owned by Warner Bros.
    country -> US
    note    -> "DC Comics adaptation studio"

Studio kinds: film, television, animation, documentary, music, game, custom.

The engine traverses the parent arc chain to resolve rights and credit inheritance.

Reference syntax:

studio  -> @studio/st4xab3c
studios -> @studios/[st4xab3c, st8mn2rk]

## In a manifest
manifest::
  studio  -> @studio/st4xab3c

Studio nodes compile to ATOM StudioNode objects (node class 0x18).

@label — Record Label Entities

A label node declares a music record label or publishing imprint. Labels support ownership hierarchy via the parent field. They are defined in info/labels.aura.

## FILE: info/labels.aura

labels::

  lb3xab7c::
    name    -> "Universal Music Group"
    kind    -> major
    country -> US
    founded -> 1934-01-01

  lb7mn4rp::
    name    -> "Def Jam Recordings"
    kind    -> imprint
    parent  -> @label/lb3xab7c    ## owned by UMG
    country -> US
    founded -> 1983-01-01
    note    -> "Hip-hop imprint under UMG"

  lb2xq9bk::
    name    -> "Self-Released"
    kind    -> independent
    country -> KE

Label kinds: major, independent, imprint, publisher, distributor, custom.

Reference syntax:

label  -> @label/lb7mn4rp
labels -> @labels/[lb7mn4rp, lb2xq9bk]

Label nodes compile to ATOM LabelNode objects (node class 0x19).

@watch, @buy, @rent, @download — Content Availability

Availability nodes declare where and how content can be accessed externally. They are defined in info/availability.aura and compiled to HAMI manifests.

## FILE: info/availability.aura

watch::

  netflix::
    platform  -> "Netflix"
    url       -> https://netflix.com/title/12345678
    territory -> worldwide
    quality   -> 4k | hd | sd
    access    -> @access/gated

  youtube::
    platform  -> "YouTube"
    url       -> https://youtube.com/watch?v=abc123
    territory -> worldwide
    quality   -> hd
    access    -> @access/open

buy::

  itunes::
    platform  -> "Apple TV / iTunes"
    url       -> https://tv.apple.com/movie/buy/12345678
    price     -> "14.99 USD"
    currency  -> USD
    territory -> US
    quality   -> 4k

rent::

  itunes-rent::
    platform  -> "Apple TV / iTunes"
    url       -> https://tv.apple.com/movie/rent/12345678
    price     -> "3.99 USD"
    currency  -> USD
    territory -> US
    window    -> 30d

download::

  bandcamp-dl::
    platform  -> "Bandcamp"
    url       -> https://artist.bandcamp.com/album/signal-loss
    territory -> worldwide
    quality   -> lossless
    format    -> flac | mp3 | aac
    drm       -> dark
    access    -> @access/gated

Declared in manifest:: via the availability:: block:

manifest::
  name   -> "Signal Loss"
  cover  -> @art/cover-main
  studio -> @studio/st4xab3c
  label  -> @label/lb7mn4rp

  availability::
    watch    -> @watch/[netflix, youtube]
    buy      -> @buy/itunes
    rent     -> @rent/itunes-rent
    download -> @download/bandcamp-dl

Availability node classes: watch 0x1A, buy 0x1B, rent 0x1C, download 0x1D.

Person Name Fields and Screen Attribution

Person nodes carry structured name fields so the SDK can show the right name in the right context — a short on-screen label for dialogue captions, or a full name in credits.

people::

p4xt9k2::
  first   -> "Mario"
  last    -> "Aleka"
  screen  -> "Mario"
  legal   -> "Mario A. Mwangi"
  kind    -> artist            ## what kind of creative person
  born    -> 1993-04-11
  country -> KE
  roles   -> @roles/[main-artist, vocalist, composer, producer]
  bio     -> "Nairobi-based producer and vocalist."

mt4qbz::
  first   -> "Amara"
  middle  -> "Chukwuemeka"
  last    -> "Okafor"
  screen  -> "Amara"          ## short name for on-screen captions
  kind    -> actor
  country -> NG
  roles   -> @roles/[lead-actor, voice-actor]

Name field rules:

Valid kind values for a person node: actor, artist, musician, director, producer, writer, narrator, host, journalist, comedian, athlete, presenter, voice-artist, dj, character, custom.

Comments That Survive Compilation

In AURA, ## annotations are not discarded. They compile to HAMI metadata under a reserved aura::annotations namespace. They are queryable.

## This is an annotation — it compiles into the HAMI file.
## Use it to document intent, decisions, or editorial notes.

track.01::
  ## Intro was recorded in one take — do not re-sequence
  name -> "Signal Loss"

Part XIV — Template Inheritance

The >> Operator

AURA documents can extend base templates using >>. This allows you to define shared schema structure once and reuse it across many files.

## FILE: templates/music_album.aura
schema::
  root  -> https://hami.aduki.org/aura/1.0
  kind  -> audio::music

## FILE: my_album.aura
>> templates/music_album

manifest::
  name -> "My New Album"

The child file inherits all namespace structure from the parent and can override or extend any field. Inheritance compiles to an ATOM inheritance arc.

Part XV — AURA to ATOM/HAMI Compilation Map

Part XVI — File Naming and Organization

## Track and episode source files — named by generated ID
namespace.aura                     <- project entry point
tracks/namespace.aura              <- folder namespace manifest
tracks/t7xab3c.aura
tracks/t4mn2rp.aura
episodes/namespace.aura
episodes/ep7xb3n.aura

## Collection manifests — named by generated ID
collections/c8xab3d.aura   <- album
collections/c3xn7rp.aura   <- series
seasons/s1xp4fm.aura       <- season within a series

## Info folder — shared project metadata (descriptive names only here)
info/namespace.aura
info/people.aura
info/annotators.aura
info/metadata.aura
info/credits.aura
info/rights.aura
info/labels.aura           <- record label and imprint entities
info/studios.aura          <- production studio entities
info/arts.aura             <- cover art, motion covers, trailers
info/availability.aura     <- watch/buy/rent/download entries

## Meta folder — vocabulary (descriptive names only here)
meta/namespace.aura
meta/genres.aura
meta/roles.aura
meta/moods.aura

## Configs folder — NEVER compiled, NEVER tracked by history
configs/llm.aura
configs/stores.aura
configs/account.aura
configs/ignore.aura

## Reusable templates
templates/music_album.aura
templates/podcast_episode.aura
templates/film.aura
templates/series.aura

## Compiled output — single file
dist/t7xab3c.atom
dist/t7xab3c.hami

## Compiled output — collection (folder named by collection ID)
dist/c8xab3d/
  manifest.hami
  people.hami
  annotators.hami
  t7xab3c.atom
  t7xab3c.hami
  t7xab3c-acoustic.atom
  t7xab3c-acoustic.hami
  t7xab3c-acoustic.atlas
  ## ...

Part XVII — Sigil Quick Reference

AURA Language Reference — v0.4 Human-readable authoring layer for the Triverse Protocol (ATOM + HAMI) Incorporates: support node layer, [start, end, duration] time triples, collection and variation authoring, cloud source data store directives, @art / @motion / @trailer, @studio / @label, @watch / @buy / @rent / @download, person kind+role, project namespace.aura convention, configs/ folder. Write it like prose. Compile it like a machine.

AURA — Keyword Reference

Single-page lookup for every keyword, sigil, domain, enumerated value, standard key, and toolchain command in the AURA language. For full explanations, see flux.md, structure.md, and chages.md.

Sigils

Every sigil in AURA has exactly one meaning. No context-dependent overloading.

Boolean Literals

AURA uses media-native boolean values instead of true and false. true and false are accepted as synonyms for toolchain interoperability.

explicit  -> dark      ## not explicit
cleared   -> live      ## rights confirmed
featured  -> live      ## currently featured
published -> dark      ## still a draft

Reference Domains

All domains use the @domain/id or @domain/[id1, id2] pattern. Singular domain = one entity. Plural domain = multiple entities (compiles to array).

People

Vocabulary

Content Files

Time, Sync, and Tempo

Music Attribution

Annotation and Context

Events

Access

Access cascade (least → most restrictive):

open < archived < restricted < gated < embargoed < locked

History

Info and Meta Files

Media Assets

Industry Entities

Content Availability

Cloud

Reserved (Future)

Namespace Blocks

Namespace blocks open with :: and contain key-value pairs or sub-nodes.

Core Namespaces

People and Annotators

Vocabulary - meta/ and info/ files

Media Assets and Industry Entities

Configs (Non-Compiled)

Support Node Namespaces

Declared inside support:: blocks within content files.

Content Node Types

Content nodes carry renderable text payloads.

Support Node Types

Support nodes carry metadata without a renderable text payload.

Standard Keys

Approved Hyphenated Keys

Hyphens are permitted only when no single word cleanly carries the full meaning.

Media Kinds

Every AURA document declares its kind in the schema:: block.

Audio

Video

Mixed

Enumerated Values

Segment Kinds

Used in segments:: support nodes under the kind key.

intro | verse | pre-chorus | chorus | post-chorus | bridge |
drop | breakdown | outro | interlude | instrumental | transition |
ad-lib | hook | custom

Sample Kinds

Used in samples:: support nodes under the kind key.

loop | stab | chop | vocal | melodic | rhythmic | atmospheric | custom

Interpolation Elements

Used in interpolations:: support nodes under the element key.

melody | chord-progression | lyric | rhythm | hook | bassline | custom

Explainer Kinds

Used in explainers:: support nodes under the kind key.

cultural | lyrical | historical | technical | translation | annotation | custom

Tempo Types

Used in tempo:: support nodes under the type key.

steady | increasing | decreasing | variable | free

Instruction Kinds

Used in instructions:: support nodes under the kind key.

loop | skip | jump | repeat | fade | crossfade | trim | mute | custom

Instruction Fade Types

Used under type in fade instructions.

linear | exponential | logarithmic

Event Kinds

Used in events:: support nodes under the kind key.

ambient | reactive | interactive | editorial | broadcast | custom

Event Trigger at Values

When within a trigger’s interval the event fires.

onset | offset | peak | @time/value

Anchor Kinds

Used in anchors:: support nodes under the kind key.

hard | verified | soft

Rights Scope

Used in rights:: support nodes under the scope key.

document | window

Ad Slot Fill Policy

Used in slots:: support nodes under the fill-policy key.

optional | required | house

Ad Slot Kinds

Used in slots:: support nodes under the kind key.

pre-roll | mid-roll | post-roll

Inference Source

Used in moods:: support nodes under the source key.

authored | hybrid | inferred

History Vocabulary

AURA-native versioning terms. Git verbs (commit, branch, tag, push, etc.) are not used.

ID Prefix Reference

Every AURA ID begins with a type prefix. Prefixes are one or two characters.

ID format: {prefix}{6 alphanumeric chars} using charset a-z0-9.

t7xab3c    <- track
p4xt9k2    <- person
ep7xb3n    <- episode
c8xab3d    <- collection
tx3ab7k    <- take

ATOM Node Class Reference

The node_class byte in ATOM’s interval tree entry allows stabbing queries to filter by node type at SIMD evaluation time.

Toolchain Commands

All commands are issued via the aura CLI.

ID Generation

History(.history)

Compilation

Info and Meta Files : (Base)

info/ Folder — Project-Specific Data

namespace.aura Files — Project and Folder Manifests

configs/ Folder — Non-Compiled Toolchain Config

Never compiled to .atom / .hami. Never tracked by .history/.

meta/ Folder — Vocabulary Definitions

Vocabulary nodes use slug IDs (e.g. electronic, main-artist), not generated hex IDs.

Vocabulary Resolution Cascade

When the engine encounters a @genre/, @role/, or @mood/ reference:

1. Local meta/ folder for this project
2. Parent catalog’s meta/ folder (if inside a catalog)
3. Global platform vocabulary at @aduki.org/genre/, @aduki.org/role/, @aduki.org/mood/
4. Not found → stored as string literal, compile warning in strict mode

Signal Path Convention

Used in event:: nodes under the signal key. Multiple signals separated by |.

lights::dim(0.1)               <- dim lights to 10%
lights::colour(#0a1628)        <- set light colour
lights::strobe                 <- strobe
lights::fade(white, 30s)       <- fade to white over 30 seconds
haptic::pulse(80ms)            <- haptic motor burst
ar::overlay(frost)             <- AR frost overlay
display::credits               <- show credits display
player::insert-ad              <- trigger ad insertion
player::pause                  <- pause playback
player::skip                   <- skip current segment
iot::gpio(17, HIGH)            <- raw GPIO for custom hardware

Format: subsystem::action(params) where params are optional.

Time Notation Quick Reference

## Full triple — explicit
time -> [22s, 1m10s, 48s]

## Range — start ~ end (engine derives duration)
time -> 22s~1m10s

## Duration offset — start + duration (engine derives end)
time -> 2m30s+28s

## Point anchor (no duration)
sync-point -> @time/1m32s

## Cross-file time reference
sampled -> @track/t9vkx7q @time/2m44s

Time units: s (seconds), m (minutes), h (hours), ms (milliseconds). Full timestamps for film/video: HH:MM:SS, HH:MM:SS.mmm.

@history Reference Quick Reference

@history/current                  <- latest take
@history/origin                   <- first take ever
@history/premiere                 <- named mark
@history/v1.0                     <- another named mark
@history/~1                       <- one take back
@history/~3                       <- three takes back
@history/tx3ab7k                  <- specific take by ID
@history/stream/translation-fr    <- head of a stream
@history/main                     <- head of main stream

## Node state at a specific take
@history/v1.0::verse/one
@history/~3::chorus/one/line/two
@history/premiere::credits

## Global cloud form
@aduki.org/track/t7xab3c/history/premiere
@aduki.org/track/t7xab3c/history/~1::verse/one

AURA Keyword Reference — Engine Documentation See flux.md for syntax, structure.md for structure, changes.md for engine internals.

AURA (Adaptive Universal Relational Annotations) — Structure Reference

ID System, Key Conventions, File References, and Folder Layouts

This document defines the structural conventions of AURA before any content is authored. It covers how identifiers are generated and used, how keys are written, how files reference each other locally and globally, how the info folder system works, and how the folder tree is organized for every supported media type. File names carry no human-readable meaning. Names live inside the files. File names are IDs.

Part I — The Identifier System

Why IDs, Not Names

File names in an AURA project carry no human-readable information. The name of a track, the title of an episode, the full name of a contributor — all of that lives inside the .aura file, inside the manifest or persons block. The file system sees only IDs.

This design serves three purposes.

First, it eliminates naming collisions globally. Two different artists may both have a track called “Fade Out” or a scene called “Cold Open.” When files are named by generated IDs, those titles coexist without conflict in any shared store.

Second, it makes renaming a non-event. Changing a title is editing one line inside a .aura file. No file is renamed. No reference breaks. No downstream link is invalidated.

Third, it makes cloud references unambiguous and permanent. Once an ID is issued, it is the stable address of that object forever. Any reference to it — local or global — resolves to exactly one thing.

ID Format

An AURA ID is a short alphanumeric string composed of a one or two character type prefix followed by six lowercase alphanumeric characters.

Format:   {prefix}{6 chars}
Charset:  a-z, 0-9 (36 possible values per character position)
Length:   7 to 8 characters total depending on prefix length

The 6-character body gives 36^6 = 2,176,782,336 unique values per prefix. Collisions within a prefix space are statistically negligible and are additionally prevented by the ID generator which registers each issued ID against the active store before returning it.

Examples of well-formed IDs:

t7xab3c     track
t4mn2rp     track
c8xab3d     collection (album, ep, single, compilation)
p4xt9k2     person
v3qr7st     variant
ep7xb3n     episode
sn2kr9l     season
tv4x7ab     TV series manifest
f6np2qr     film
dc3wr8x     documentary
pc5xk4m     podcast series
an9vl3b     animation or anime series
sp2xr7n     speech
b8mt4kx     audiobook
mv6xp3l     music video
sg4xr9t     single release
cy3wp8n     interview
r1xb7kp     rights declaration
i0xmt3q     info document (metadata, credits, labels)

Prefix Reference

Every ID begins with its type prefix. The prefix encodes what the object is. A system reading any ID can determine the object class from the prefix alone, without any additional context.

ID Generation

IDs are generated by the AURA toolchain. No ID is hand-authored. The generator produces IDs on demand, checks each against the active store’s ID registry, and retries on the rare collision before returning the ID to the caller.

In local development, the generator uses a local registry file at the project root. In cloud deployments, the store’s ID registry is the authoritative source. The generator is always invoked — IDs are never typed manually.

The generation command follows this pattern (exact toolchain syntax is defined in the Engine Reference):

aura generate track         -> t7xab3c
aura generate person        -> p4xt9k2
aura generate episode       -> ep7xb3n
aura generate collection    -> c8xab3d

The generator returns the ID. The ID becomes the file name and the canonical reference for that object everywhere.

A Note on Scene and Act Files

Scene and act files inside film, music-video, and documentary projects use generated IDs whose prefix is drawn from the parent content kind. For example, a scene file in a film project may carry an f-prefixed ID because it belongs to that film’s namespace. There is no separate sc or ac prefix — scene and act files are sub-objects of their parent manifest and share its prefix space.

The folder they reside in (scenes/, acts/) defines their content role; the ID prefix encodes their parent kind. This is intentional: it keeps the prefix table small and makes parent ownership legible from the ID alone.

Part II — The Reference System

Local References

Within a project, any AURA file references another file or node using the @ sigil followed by the type domain and the ID.

## Reference a track file from a collection manifest
aura -> @track/t7xab3c

## Reference an episode file
aura -> @episode/ep7xb3n

## Reference a variant file
aura -> @variant/v3qr7st

## Reference a person defined in info/people.aura
producer -> @person/p4xt9k2

## Multiple people — plural domain
cast     -> @people/[mt4qbz, vr8kfw]

## Reference the info folder's people file
>> @info/people

## Reference the info folder's metadata file
>> @info/metadata

The engine resolves local references relative to the project root. The type domain — track, episode, variant, person — matches the subfolder where files of that type reside. The engine knows where to look from the domain alone.

Global Cloud References

When a reference must be globally unambiguous — crossing catalog boundaries, cited from an external system, embedded in a published record — it uses the full global URI form with the aduki.org domain.

## Global reference to a specific track
@aduki.org/track/t7xab3c

## Global reference to a specific person
@aduki.org/person/p4xt9k2

## Global reference to a person via the info path
@aduki.org/people/p4xt9k2

## Global reference to an episode
@aduki.org/episode/ep7xb3n

## Global reference to a collection manifest
@aduki.org/collection/c8xab3d

## Global reference to a season within a series
@aduki.org/series/tv4x7ab/season/sn2kr9l

## Global reference to an episode within a season
@aduki.org/series/tv4x7ab/season/sn2kr9l/episode/ep7xb3n

## Global reference to an info document
@aduki.org/people/p4xt9k2
@aduki.org/info/metadata/c8xab3d

The global URI is the same ID — only the prefix domain changes. A track referenced locally as @track/t7xab3c is referenced globally as @aduki.org/track/t7xab3c. The ID body never changes.

Short Global Form

Because the type prefix is embedded in the ID itself, a short global form is also valid when the calling system can resolve the prefix to the type:

@aduki.org/t7xab3c       -> resolves to track t7xab3c
@aduki.org/p4xt9k2       -> resolves to person p4xt9k2
@aduki.org/ep7xb3n       -> resolves to episode ep7xb3n
@aduki.org/c8xab3d       -> resolves to collection c8xab3d

The short form is used in tight contexts like credit fields, relation declarations, and sampling references. The full path form is used in collection manifests, rights instruments, and any context where an auditor or external system must resolve the reference without engine assistance.

Node Path References

Within a file, specific nodes are addressed by following the slash path from the node type down to the target node. These are in-file references: they do not cross file boundaries.

@verse/one
@chorus/two
@scene/cold-open
@act/one
@chapter/interview-begins
@line/one
@word/three
@syllable/one
@anchor/chorus-one

Nested nodes are addressed by extending the path:

@verse/one/line/three
@verse/two/line/one/word/four
@act/two/scene/cold-open

Cross-file node references combine the file ID with the in-file node path:

@track/t7xab3c::verse/two/line/one
@episode/ep7xb3n::scene/cold-open
@aduki.org/track/t7xab3c::verse/two/line/one

The :: leap signals a cross-boundary reference — either into a different file or into a different memory region in the compiled ATOM mesh.

The Full Reference Grammar

## Local: type domain + file ID
@track/t7xab3c
@episode/ep7xb3n
@person/p4xt9k2
@variant/v3qr7st

## Local: info folder document
@info/people
@info/metadata
@info/credits
@info/rights

## Local: in-file node
@verse/one
@chorus/two/line/three

## Local: cross-file node
@track/t7xab3c::verse/two
@episode/ep7xb3n::scene/cold-open

## Global: full path form
@aduki.org/track/t7xab3c
@aduki.org/person/p4xt9k2
@aduki.org/people/p4xt9k2
@aduki.org/series/tv4x7ab/season/sn2kr9l/episode/ep7xb3n

## Global: short form (prefix-resolved)
@aduki.org/t7xab3c
@aduki.org/p4xt9k2

## Global: cross-file node
@aduki.org/track/t7xab3c::verse/two/line/one

## Temporal anchor
@time/1m32s

## Singular people forms
@person/p4xt9k2
@author/p4xt9k2

## Plural people forms
@people/[p4xt9k2, j8mn2rk]
@authors/[p4xt9k2, j8mn2rk]

## Sampling reference (file + time point)
@track/t7xab3c @time/2m44s

Reference Domain Index

All domains follow the singular/plural convention: @entity/id for one, @entities/[a, b] for many.

People

Vocabulary

Content Files

Time, Sync, and Tempo

Music Attribution

Annotation and Context

Events

Info and Meta Files

Media Assets

Industry Entities

Content Availability

Cloud

Access

History

Reserved (Future)

When referencing in-file node types (verse, chorus, line, word, etc.) the domain is the node type itself, not a folder. These resolve within the current file unless combined with a file ID via the :: leap.

Part III — Node Identifier Convention

The Slash Identifier

Every named node in an AURA document uses the slash convention. The name before the slash is the node type. The name after the slash is the ordinal or a unique meaningful label.

Ordinals are written as full English words. No numerals, dots, or underscores in node identifiers.

verse/one::
verse/two::
chorus/one::
chorus/two::
bridge/one::
act/one::
act/two::
scene/one::
scene/cold-open::
chapter/one::
chapter/interview-begins::
line/one::
line/two::
word/one::
syllable/one::
letter/one::

When a node has a unique meaningful name rather than an ordinal position, the label after the slash is that name, lowercase with hyphens if compound.

scene/cold-open::
scene/the-diagnostic::
scene/root-node::
chapter/interview-begins::
bridge/breakdown::
anchor/chorus-one::

Ordinal Word Reference

Beyond twenty: twenty-one, twenty-two, and so on as full hyphenated words. Season/one, episode/twenty-two, line/thirty-five — the pattern extends without any change in convention.

Node Type Vocabulary

Content node types and their levels:

Support node types:

Part IV — Key Naming Convention

The Single-Word Rule

Keys in AURA are written as single lowercase words wherever the language allows it. Hyphens are used only when there is genuinely no single word that carries the same meaning without ambiguity.

The goal is readability. An AURA file should read as close to natural prose as the structure permits.

Standard Keys

| access | Content access level — @access/open, locked, gated, embargoed, archived, restricted | | embargo | Date after which an embargoed item transitions to @access/open | | live | Boolean true literal (broadcast: “going live”) | | dark | Boolean false literal (stage: “going dark”) | | published | Boolean publish flag (live = published, dark = draft) | | featured | Boolean flag for editorial featuring | | explicit | Boolean explicit content flag | | authored | @history/take-id — the take when this node was first recorded | | revised | @history/take-id or mark — the take when this node was last changed |

Approved Hyphenated Keys

Hyphens are permitted only when no single word cleanly carries the full meaning. This list is closed.

Part V — The Info Folder System

What Info Is

Every project has an info folder and an optional meta folder. Both live at the project root alongside the content folders.

• info/ holds project-specific data: persons, annotators, credits, rights, labels. All entries are unique to this project.
• meta/ holds vocabulary definitions: genres, roles, moods. These may be local specializations of or additions to the global platform vocabulary at @aduki.org. The meta/ folder is optional — if absent, the project uses only the global vocabulary.

Person nodes in info/people.aura each carry their own generated hex ID. Vocabulary nodes in meta/ use slug IDs instead.

Info Folder Contents

Meta Folder Contents

Vocabulary nodes in meta/ use slug IDs, not generated hex IDs. The slug IS the canonical identifier — e.g. electronic, main-artist, ethereal. Slugs must be unique within their namespace and are registered in the platform registry to prevent collisions.

People, Authors, and Annotators — The @people Base

All human entities in AURA — artists, directors, narrators, annotators, transcribers — resolve from the @people base namespace. The @person/ and @author/ domains are singular aliases; @people/ and @authors/ are their plural counterparts. All four resolve against info/people.aura.

## Singular — one person
creator  -> @person/p4xt9k2
creator  -> @author/p4xt9k2    ## same thing

## Plural — multiple people
cast     -> @people/[mt4qbz, vr8kfw]
writers  -> @people/[p4xt9k2, k7wrt2]
authors  -> @authors/[p4xt9k2, j8mn2rk]

## Both local and global forms
@person/p4xt9k2
@people/[p4xt9k2, j8mn2rk]
@aduki.org/person/p4xt9k2
@aduki.org/people/p4xt9k2

The namespace in info/people.aura may be declared as people::, persons::, or authors:: — all compile identically.

## FILE: info/people.aura

people::

  p4xt9k2::
    first   -> "Mario"
    last    -> "Aleka"
    screen  -> "Mario"
    legal   -> "Mario A. Mwangi"
    kind    -> artist
    born    -> 1993-04-11
    country -> KE
    city    -> "Nairobi"
    roles   -> @roles/[main-artist, vocalist, composer, producer]
    genre   -> @genres/[electronic, afro-soul, experimental]
    links::
      spotify -> spotify::artist/mario-aleka
      website -> https://marioaleka.com
    bio     -> "Nairobi-based producer and vocalist."

  j8mn2rk::
    first   -> "Jay"
    last    -> "Femar"
    screen  -> "Jay"
    legal   -> "James Femar Ogutu"
    kind    -> producer
    country -> KE
    roles   -> @roles/[producer, mixer, engineer]

All equivalent global forms for p4xt9k2:

@aduki.org/people/p4xt9k2
@aduki.org/person/p4xt9k2
@aduki.org/author/p4xt9k2
@person/p4xt9k2       <- local shorthand
@author/p4xt9k2       <- local shorthand, identical resolution

Annotators File Structure

Annotators are the actual humans who write, transcribe, and maintain AURA files. They are distinct from persons (the content contributors — artists, actors, directors, musicians). A person is someone whose work appears in the media. An annotator is someone who documents and encodes that work in AURA.

Annotators include lyric transcribers, subtitle writers, metadata editors, translators working in AURA, and any editor who authors or maintains a .aura file. They are accountable for the accuracy and completeness of the data.

Annotators are stored in info/annotators.aura. They use the same p prefix for their IDs as persons because they are also people — but they are indexed separately to keep the persons list clean (persons are content contributors, not documentation contributors).

Every .aura file declares its annotator in the schema block.

## FILE: info/annotators.aura

annotators::

  p9xb3mn::
    name     -> "Amina Weru"
    roles    -> transcriber | editor
    country  -> KE
    contact  -> amina@aduki.org

  p3xr7kn::
    name     -> "Diego Ferraz"
    roles    -> translator | annotator
    country  -> BR
    locale   -> pt-BR
    contact  -> diego@aduki.org

In every AURA content file, the annotator is declared in the schema block:

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::music
  lang       -> en-US
  annotator  -> @annotator/p9xb3mn

When a file has been edited by more than one annotator:

schema::
  root        -> https://hami.aduki.org/aura/1.0
  kind        -> audio::music
  lang        -> en-US
  annotators  -> @annotator/[p9xb3mn, p3xr7kn]

Annotation attribution may also appear at the node level for granular accountability — useful when different annotators contributed different sections of the same file:

verse/two::
  annotator -> @annotator/p3xr7kn
  lines::
    line/one::
      text -> "She said my name like static"

The global cloud references for annotators follow the same pattern as persons but use the annotators path:

@aduki.org/annotators/p9xb3mn
@aduki.org/annotators/p3xr7kn
@annotator/p9xb3mn              <- local shorthand

Annotator IDs are generated by the same toolchain as all other IDs:

aura generate annotator         -> p9xb3mn

The cloud store path for annotators is flat across all catalogs. An annotator who contributes to multiple catalogs on the platform has a single global ID that appears in the annotators file of each project they worked on. Their global record is maintained at:

@aduki.org/annotators/p9xb3mn

Metadata File Structure

## FILE: info/metadata.aura

schema::
  root    -> https://hami.aduki.org/aura/1.0
  kind    -> audio::music
  lang    -> en-US

manifest::
  name      ! -> "Signal Loss"
  creator   ! -> @person/p4xt9k2
  version     -> 1.0.0
  released    -> 2024-11-01
  territory   -> worldwide
  label       -> "Self-Released"

meta::
  genre    -> Electronic | Afro-Soul | Experimental
  tags     -> Nairobi | Instrumental | Ambient

Part VI — Folder Structures by Media Type

Universal Conventions

• Every project folder is named in lowercase with no spaces and no special characters other than hyphens. It is the human-readable name of the project, not a generated ID.
• Every project folder must have a namespace.aura at its root. This is the project entry point — the equivalent of main.rs or mod.rs in Rust.
• Every sub-folder (info/, meta/, tracks/, episodes/, scenes/, etc.) has its own namespace.aura file listing the files it contains.
• Every content file is named by its generated object ID plus .aura.
• The info folder uses descriptive file names (people, annotators, metadata, credits, rights, labels, studios, arts, availability) because these are structural roles.
• The meta folder uses descriptive file names (genres, roles, moods). Vocabulary nodes inside use slug IDs.
• The dist folder receives all compiled .atom, .hami, and .atlas files.
• No descriptive words appear in folder or file names outside of info, meta, and dist.
• Artwork, stems, and binary assets live in named folders: artwork/, stems/.
• Stems are organized under subdirectories named by the track ID they belong to.
• The configs/ folder is never compiled and never tracked by .history/. It holds toolchain configuration: LLM providers, store origins, credentials, and ignore lists.
• The .history/ folder is an append-only object store maintained by the toolchain. It is private to the local project and is never published to the cloud store.

The namespace.aura File

Every project and every project sub-folder has a namespace.aura.

Root namespace.aura

This is the project entry point. It declares the project’s namespace identity, kind, and language, and re-exports its sub-namespaces. The compiler reads this file first.

## FILE: namespace.aura

schema::
  root       -> https://hami.aduki.org/aura/1.0
  kind       -> audio::music
  namespace  -> signal-loss-album
  lang       -> en-US

exports::
  info       -> @info/metadata
  people     -> @info/people
  tracks     -> @tracks/*
  collection -> c8xab3d.aura

Sub-folder namespace.aura

Every sub-folder’s namespace.aura lists its contained files.

## FILE: info/namespace.aura

namespace::
  folder    -> info
  contains::
    - people.aura
    - annotators.aura
    - metadata.aura
    - credits.aura
    - arts.aura
    - studios.aura
    - labels.aura
    - availability.aura

## FILE: tracks/namespace.aura

namespace::
  folder    -> tracks
  contains::
    t7xab3c -> "Signal Loss"
    t4mn2rp -> "Fold"
    t9vkx7q -> "Recursive"
    t2nq5wb -> "Meridian"
    t6rj8vc -> "Origin Point"

The configs/ Folder

The configs/ folder is always at the project root. It is excluded from compilation and from .history/ tracking. It holds toolchain configuration.

configs/
  llm.aura        <- LLM provider definitions (editor integration)
  stores.aura     <- Remote store origins and authentication refs
  account.aura    <- Cloud identity — reads from .env or env variables
  ignore.aura     <- Extra paths excluded from .history/ tracking

Credential values are never stored in configs/account.aura. That file declares environment variable names. Actual secrets come from .env at project root or process environment.

Album

album/                          <- project directory
  namespace.aura                <- project entry point
  info/
    namespace.aura              <- folder namespace manifest
    people.aura
    annotators.aura
    metadata.aura
    credits.aura
    rights.aura
    labels.aura                 <- record label entities
    studios.aura                <- production studio entities (if needed)
    arts.aura                   <- cover art, motion covers, trailers
    availability.aura           <- watch/buy/rent/download entries
  meta/
    namespace.aura
    genres.aura                 <- optional: local genre vocab
    roles.aura                  <- optional: local role vocab
  tracks/
    namespace.aura
    t7xab3c.aura
    t4mn2rp.aura
    t9op5lw.aura
    t2kr8xn.aura
    t6bx4qm.aura
  variants/
    namespace.aura
    v3qr7st.aura                <- acoustic variant of t7xab3c
    v5nm9xb.aura                <- radio edit of t4mn2rp
    v8xp2kl.aura                <- dubbed track
  artwork/
    cover.jpg
    back.jpg
    booklet.pdf
  motion/
    cover-loop.mp4              <- Apple Music-style motion cover
  trailers/
    main-trailer.mp4
  stems/
    t7xab3c/
      drums.flac
      bass.flac
      keys.flac
      vocals.flac
  c8xab3d.aura                  <- collection manifest
  configs/                      <- Never compiled. Not tracked by history.
    llm.aura
    stores.aura
    account.aura
    ignore.aura
  .history/                     <- History object store (toolchain only)
    objects/
    marks/
    streams/
    HEAD
  dist/
    c8xab3d.hami                <- compiled collection manifest
    people.hami                 <- compiled people index
    t7xab3c.atom
    t7xab3c.hami
    v3qr7st.atom
    v3qr7st.atlas               <- DTW alignment atlas for this variant

Each variant file declares which canonical track it diverges from using its canonical field pointing at the track ID.

EP

ep/                             <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
  tracks/
    t2ab8xk.aura
    t7xr3mn.aura
    t5nq4bp.aura
  artwork/
    cover.jpg
  c3xn7rp.aura
  dist/

Single

single/                         <- project directory
  info/
    people.aura
    metadata.aura
  tracks/
    t7xab3c.aura                <- A-side
    t3mn8rk.aura                <- B-side or instrumental
  artwork/
    cover.jpg
  sg4xr9t.aura
  dist/

If the single has no B-side, the collection manifest is optional and the single track file may serve as the root document.

Compilation

compilation/                    <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
    rights.aura
    labels.aura
  tracks/
    t7xab3c.aura                <- licensed track, local copy
    t4mn2rp.aura
  links/
    links.aura                  <- external track references for licensed
  artwork/                       content that lives in other catalogs
    cover.jpg
  c5xr2nm.aura
  dist/

Licensed tracks that originate from other catalogs are declared as linked members in the collection manifest, referencing them via their global ID. They are not copied into the local tracks folder.

Music Video

music-video/                    <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
  scenes/
    f2xb7np.aura
    f8nm3kr.aura
    f4xp9rt.aura
    f6bq2xm.aura
  shots/
    f2xb7np/                    <- shots organized by parent scene ID
      sh1.aura
      sh2.aura
  artwork/
    thumbnail.jpg
    poster.jpg
  mv6xp3l.aura
  dist/

When a music video is companion content inside an album folder:

album/
  ...
  video/
    mv6xp3l/
      info/
        credits.aura
      scenes/
        f2xb7np.aura
      mv6xp3l.aura
      dist/

Podcast

podcast/                        <- project directory
  info/
    people.aura
    metadata.aura
  seasons/
    sn2kr9l/                    <- season ID
      info/
        people.aura
        metadata.aura
      episodes/
        ep7xb3n.aura
        ep3mn8rk.aura
        ep9xp4lw.aura
      sn2kr9l.aura              <- season manifest
      dist/
    sn8pq3xv/
      info/
        people.aura
        metadata.aura
      episodes/
        ep2xb8mn.aura
      sn8pq3xv.aura
      dist/
  pc5xk4m.aura                  <- series manifest
  dist/

TV Series

tv-series/                      <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
  seasons/
    sn2kr9l/                    <- season ID
      info/
        people.aura
        metadata.aura
        credits.aura
      episodes/
        ep7xb3n.aura
        ep3mn8rk.aura
        ep4xp9rt.aura
        ep6bq2xm.aura
      variants/
        v5nm9xb.aura            <- dubbed version of ep7xb3n
      sn2kr9l.aura
      dist/
    sn8pq3xv/
      info/
        people.aura
        metadata.aura
      episodes/
        ep2xb8mn.aura
      sn8pq3xv.aura
      dist/
  tv4x7ab.aura                  <- series manifest
  dist/

Anime and Animation

animation/                      <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
  seasons/
    sn2kr9l/
      info/
        people.aura
        metadata.aura
      episodes/
        ep7xb3n.aura
        ep3mn8rk.aura
      variants/
        v2xb8kp.aura            <- English dub of ep7xb3n
        v7nm3xr.aura            <- French dub of ep7xb3n
      sn2kr9l.aura
      dist/
  an9vl3b.aura
  dist/

Film

film/                           <- project directory
  info/
    people.aura
    metadata.aura
    credits.aura
    rights.aura
  acts/
    fa2xb7n.aura                <- act file
    fa8mn3k.aura
    fa4xp9r.aura
  scenes/
    fs1xb4n.aura                <- scene files
    fs3mn9x.aura
    fs7xr2kp.aura
    fs5bq8nm.aura
  variants/
    v3qr7st.aura                <- director's cut
    v8xp2kl.aura                <- dubbed version
    v2nm4xb.aura                <- commentary track
  artwork/
    poster.jpg
    thumbnail.jpg
  f6np2qr.aura                  <- film manifest
  dist/

For short films where scenes are not broken into separate files, a single f6np2qr.aura document carries all scenes inline and the acts and scenes folders are absent.

Documentary

dc3wr8x/                        <- documentary ID
  info/
    people.aura
    metadata.aura
    credits.aura
  segments/
    sg8xb2mn.aura
    sg4xr9t.aura
    sg6np3kx.aura
    sg2xb7nm.aura
  interviews/
    cy9xb3mn.aura               <- interview ID files
    cy4xr7kp.aura
  artwork/
    poster.jpg
    thumbnail.jpg
  dc3wr8x.aura
  dist/

Interview files are linked from segment files via @interview/ references using the interview file’s ID.

Audiobook

b8mt4kx/                        <- audiobook ID
  info/
    people.aura
    metadata.aura
    rights.aura
  chapters/
    part-one/                   <- parts use descriptive folder names
      ch3xb7mn.aura
      ch8xr4np.aura
      ch2xb9kl.aura
    part-two/
      ch7xp3rn.aura
      ch5xb8mk.aura
  artwork/
    cover.jpg
  b8mt4kx.aura
  dist/

Part folders use descriptive names (part-one, part-two) because they are grouping containers, not addressable content objects with IDs. Chapter files inside them are addressed by their generated IDs.

Speech

speech/                         <- project directory
  info/
    people.aura
    metadata.aura
  segments/
    sg8xb2mn.aura
    sg4xr9t.aura
    sg6np3kx.aura
  artwork/
    thumbnail.jpg
  sp2xr7n.aura
  dist/

For a short speech that fits in a single file, the segments folder is absent and sp2xr7n.aura is the complete document.

Music (Standalone — No Release Context)

For standalone music files not part of a formal release — demos, session recordings, library music, stem packages:

track/                          <- project directory
  info/
    people.aura
    metadata.aura
  stems/
    drums.flac
    bass.flac
    keys.flac
  t7xab3c.aura
  dist/
    t7xab3c.atom
    t7xab3c.hami

Part VII — Catalog Structure

The Catalog Root

A catalog groups all collections belonging to one label, publisher, or creator. The catalog root folder is named by the catalog’s own ID.

catalog/                        <- catalog root directory
  info/
    people.aura                 <- global people index for all projects
    annotators.aura             <- global annotators index
    metadata.aura               <- catalog-level identity
    labels.aura
  meta/
    genres.aura                 <- catalog-level genre vocabulary
    roles.aura                  <- catalog-level role vocabulary
    moods.aura                  <- catalog-level mood vocabulary
  collections/
    c8xab3d/                    <- album
    c3xn7rp/                    <- EP
    tv4x7ab/                    <- TV series
    f6np2qr/                    <- film
    pc5xk4m/                    <- podcast
  catalog.aura                  <- catalog root manifest
  dist/

The catalog-level people.aura is the global index. Individual collection-level persons files carry only persons specific to that collection who are not already in the catalog index. Resolution cascades: collection info first, catalog info second.

Multi-Catalog Global Store

At the global store level, catalogs are organized by their IDs under the store root. The store has no folder hierarchy beyond the top-level catalog folders. All nesting lives inside each catalog.

store-root/
  cx0ab3de/                     <- catalog A
  cx9mn4rp/                     <- catalog B
  cx3xr7bk/                     <- catalog C

The global URI for any object in the store is:

@aduki.org/{type}/{id}
@aduki.org/people/{person-id}
@aduki.org/series/{series-id}/season/{season-id}/episode/{episode-id}

The store ID registry maps every issued ID to its type and the catalog that owns it. Cross-catalog references are resolved via this registry. Rights validation runs before any cross-catalog :: arc is resolved.

AURA Structure Reference — v0.2 Covers: ID system, prefix vocabulary, ID generation, reference grammar, local and global cloud references, key naming, info folder, and folder layouts for all supported media types. File names are IDs. Names live inside files.

AURA Compiler (compiler)

The Zero-Copy Pipeline: From Human-Readable AURA to Machine-Executable Triverse Meshes.

The compiler reads human-authored .aura text files and emits zero-copy .hami (configuration) and .atom (temporal media) binary files. It is one of three Rust crates in the Triverse system — see engine.md for the runtime and history.md for the version store.

1. System Topology: The Three-Crate Model

Crate boundary rule: core is a zero-dependency library. compiler and engine both depend on core but never on each other. The compiler cannot accidentally call engine code and vice versa.

2. The Zero-Copy Lexer

The lexer scans the raw UTF-8 buffer and emits a stream of tokens. It strictly adheres to the rule that character escaping is prohibited. It never allocates heap memory (String); it only yields string slices (&'a str) tied to the source buffer’s lifetime.

The lexer’s hot path is a single-branch condition:

if byte < 0x20 → structural token (control code)
else           → content byte (part of a key or value)

This enables AVX-2 SIMD vectorization: 32 bytes are evaluated per CPU clock cycle. The lexer never allocates; it classifies and slices in-place.

Critical invariant: The lexer does not interpret AURA sigils (::, ->, @, etc.). It emits them as raw byte sequences. The parser is responsible for semantic meaning.

3. The Parser & Time Resolution

The parser consumes tokens from the lexer, tracks indentation depth for nested :: blocks, and builds the Abstract Syntax Tree (AST). The AST node structure mirrors the AURA document hierarchy: namespaces contain nodes, nodes contain fields or sub-nodes.

Time Normalization

Before emitting .atom files, the compiler normalizes all flexible time syntaxes into explicit float triples:

The compiler enforces the mathematical invariant: start + duration = end. If all three are provided and violate the invariant, the compiler raises a hard error. If only two are provided, the third is derived.

Reference Resolution

The parser collects all @domain/id references and resolves them in a two-phase pass:

1. First pass: Build the local symbol table — all defined nodes and IDs in this file and its info/ and meta/ dependencies.
2. Second pass: Resolve all @ references against the local table, then the catalog table, then the global cloud registry. Unresolved references are stored as forward arcs and flagged as warnings unless the strict directive is set, in which case they are compile errors.

4. The Emitter

The emitter transforms the resolved AST into binary output.

.hami Emitter

1. Replaces AURA sigils (::, ->, @, |) with ASCII control codes (US 0x1F, RS 0x1E, GS 0x1D, FS 0x1C).
2. Writes all key-value pairs as the contiguous Lexical Data Region.
3. Calculates byte offsets for every namespace and field.
4. Appends the fixed-width B-Tree Positional Index to the end of the file.

The B-Tree index is written last so the emitter can calculate all offsets in a single forward pass over the Lexical Data Region without backpatching.

.atom Emitter

1. Flattens the hierarchical AST into a contiguous array of interval structs.
2. Each struct has six 32-bit floats: [low, high, duration, max, data_ptr, node_class].
3. Structs are ordered by interval low value for BST layout.
4. The max field is calculated in a second pass over the array (augmented interval tree property).

The flat-array layout is optimized for AVX-2 SIMD: one 256-bit register loads 8 × 32-bit floats, covering the low, high, and duration fields of two adjacent nodes in a single cycle.

5. Compilation Workflows

A. Default (Working Draft)

aura compile

Ignores .history/ entirely. Parses only the current working .aura files and emits lightweight .atom / .hami artifacts. No historical overhead.

B. On-Demand Historical Target

aura compile --take tx3ab7k

Reconstructs the virtual source for take tx3ab7k in memory by replaying the delta chain from origin. Parses the reconstruction and emits compiled binaries — without writing a new .aura file to disk. The working draft is untouched.

C. Embedded History (For Runtime Querying)

aura compile --embed-history

Translates SourceDelta objects from .history/ into HistoryNode objects (class 0x14) and embeds them into the .atom interval tree. The engine can then resolve @history/v1.0 queries at runtime. This mode produces larger .atom files and is intended for archival tools, not the lightweight client SDK.

6. Compilation Exclusions

The compiler respects the exclusion list in configs/ignore.aura. Files and folders listed there are skipped entirely. The .history/ tracker also observes this list.

The configs/ folder itself is never compiled. Its files (llm.aura, stores.aura, account.aura, ignore.aura) are toolchain configuration — read only by the CLI, never passed to the AURA-to-ATOM compiler pipeline.

7. Standardized Logging System

As of v0.3.2-beta.2, the AURA toolchain uses a centralized Logger system (in src/logs/) that enforces a sleek, timestamp-free, high-contrast terminal output.

• Phase-Based Output: Every command clearly demarcates its phases (LEX, PARSE, EMIT, etc.) with consistent color coding.
• Diagnostic Parity: Errors and warnings from the linter use the same reporting interface as the compiler, ensuring uniform CLI experiences.
• Machine Readable: Stripping timestamps makes the output easier to parse by CI/CD logs and wrapping scripts while remaining visually premium for human authors.

AURA Compiler (compiler) — v0.3.2-beta.2 Zero-copy lexer → parser → emitter pipeline Outputs: .atom interval trees and .hami B-Tree indices

Compiler Structure Reference

Crate layout, module tree, shared data types, pipeline stages, and output conventions.

This document covers the physical structure of the AURA compiler system — how the three crates are laid out on disk, what each module owns, how data flows between pipeline stages, and what the emitted binary files look like internally.

Part I — Workspace Layout

The AURA toolchain is a Cargo workspace. All three crates live under a single workspace root.

aura/                               <- workspace root
  Cargo.toml                        <- workspace manifest (members = [core, compiler, engine])
  Cargo.lock

  core/                             <- shared data types and ID generator
    Cargo.toml
    src/
      lib.rs
      id.rs                         <- ID generation and prefix registry
      node.rs                       <- AtomNode, HamiNode, AtlasNode structs (#[repr(C)])
      interval.rs                   <- Allen interval triple: [low, high, duration]
      delta.rs                      <- SourceDelta, TakeObject, MarkEntry, StreamPointer
      vocab.rs                      <- VocabNode (genre, role, mood slugs)
      person.rs                     <- PersonNode, AnnotatorNode structs
      asset.rs                      <- ArtNode, MotionNode, TrailerNode structs
      entity.rs                     <- StudioNode, LabelNode structs
      availability.rs               <- WatchNode, BuyNode, RentNode, DownloadNode structs
      access.rs                     <- AccessLevel enum (open, locked, gated, embargoed, etc.)
      history.rs                    <- HistoryNode, delta chain types

  compiler/                         <- AURA source → binary emitter (aura compile)
    Cargo.toml
    src/
      main.rs                       <- CLI entry point
      lib.rs
      lexer/
        mod.rs
        token.rs                    <- Token enum: Sigil, Key, Value, Indent, Newline
        scanner.rs                  <- zero-copy byte scanner; yields &'a str slices
      parser/
        mod.rs
        ast.rs                      <- ASTNode tree: Namespace, Field, Reference, Literal
        resolver.rs                 <- two-phase @domain/id reference resolution
        time.rs                     <- time expression normalizer → [low, high, duration]
        inherit.rs                  <- >> (inherits) arc expander
      emitter/
        mod.rs
        hami.rs                     <- HAMI B-Tree emitter (manifests, people, vocab)
        atom.rs                     <- ATOM flat-array interval tree emitter
        atlas.rs                    <- ATLAS DTW alignment file emitter
      namespace/
        mod.rs
        loader.rs                   <- namespace.aura reader; builds project symbol table
        export.rs                   <- exports:: block resolver
      history/
        mod.rs
        store.rs                    <- .history/ object store reader/writer
        delta.rs                    <- SourceDelta diff engine (AST node-level diffs)
        replay.rs                   <- delta chain replayer → virtual source reconstruction
      config/
        mod.rs
        loader.rs                   <- configs/ folder reader (never compiled)
        ignore.rs                   <- ignore.aura exclusion list
      error.rs                      <- CompileError, DiagnosticLevel, Span
      directives.rs                 <- schema:: and directives:: block processor
      logs/
        mod.rs
        logger.rs                   <- Centralized AURA Logger (timestamp-free)
        formatter.rs                <- ANSI color and layout formatting
        colors.rs                   <- Standard palette definitions

  engine/                           <- execution daemon (aura serve / aura query)
    Cargo.toml
    src/
      main.rs
      lib.rs
      mount.rs                      <- mmap mount for .atom and .hami files
      query.rs                      <- stabbing query: SIMD interval tree traversal
      ocpn.rs                       <- OCPN marking vector M and support sub-vector S
      filter.rs                     <- node_class bitmask filter applied during SIMD loop
      arc.rs                        <- :: relational arc resolution
      verb.rs                       <- DML verbs: Fetch, Spawn, Purge, Mutate, Link, etc.
      history.rs                    <- in-engine @history/take-id resolution (read-only)
      cache.rs                      <- L1 in-process mmap cache management
      eventbus.rs                   <- support signal dispatcher (mood, rights, ad cue)

Part II — Core Crate Data Types

The core crate defines every shared struct with #[repr(C)] so the compiler and engine see identical memory layouts. No business logic lives here — only data.

AtomNode

The fundamental unit of the .atom flat array. Six contiguous 32-bit fields.

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct AtomNode {
    pub low:        f32,   // interval start (seconds)
    pub high:       f32,   // interval end (seconds)
    pub duration:   f32,   // high - low (pre-computed for SIMD)
    pub max:        f32,   // max high in subtree (augmented interval tree property)
    pub data_ptr:   u32,   // byte offset into the .hami companion file
    pub node_class: u32,   // class byte: 0x01 content, 0x02 segment, ... 0x1D download
}
}

Size: 24 bytes. One AVX-2 register (256-bit) holds 10.67 AtomNodes — in practice the SIMD loop processes 8-node blocks, covering low, high, and duration of two nodes per cycle.

Interval Triple

The canonical time representation everywhere in the system.

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct Interval {
    pub low:      f32,   // start offset in seconds
    pub high:     f32,   // end offset in seconds
    pub duration: f32,   // high - low  (invariant: low + duration == high)
}
}

All time expressions in AURA source normalize to this triple before emission:

PersonNode

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct PersonNode {
    pub id:      [u8; 7],          // e.g., "p4xt9k2"
    pub first:   StringRef,        // given name → .hami string pool
    pub middle:  Option<StringRef>,
    pub last:    Option<StringRef>,
    pub screen:  Option<StringRef>, // short on-screen label
    pub legal:   Option<StringRef>,
    pub kind:    PersonKind,       // artist, actor, director, host, etc.
}

pub enum PersonKind {
    Artist,
    Actor,
    Director,
    Host,
    Narrator,
    Composer,
    Producer,
    Other,
}
}

AnnotatorNode

Annotators are the humans who write and maintain AURA files. They share the p prefix with person IDs but are stored in a separate index.

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct AnnotatorNode {
    pub id:      [u8; 7],          // e.g., "p9xb3mn" (same p prefix as person)
    pub name:    StringRef,        // display name → .hami string pool
    pub roles:   AnnotatorRoles,   // bitfield: transcriber | editor | translator
    pub country: [u8; 2],          // ISO 3166-1 alpha-2
    pub contact: Option<StringRef>,// email or contact URI
}

pub struct AnnotatorRoles(u8);     // bitfield flags
impl AnnotatorRoles {
    pub const TRANSCRIBER: u8 = 0x01;
    pub const EDITOR:      u8 = 0x02;
    pub const TRANSLATOR:  u8 = 0x04;
    pub const ANNOTATOR:   u8 = 0x08;
}
}

ArtNode / MotionNode / TrailerNode

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct ArtNode {
    pub id:    [u8; 8],    // e.g., "ar4xab3c"
    pub kind:  ArtKind,    // square, landscape, 16:9, 4:3, 9:16, 2:3, custom, etc.
    pub url:   StringRef,  // cloud URL — no local file path
    pub note:  Option<StringRef>,
}

#[repr(C)]
pub struct MotionNode {
    pub id:       [u8; 8],
    pub kind:     MotionKind,  // album-motion, episode-motion, movie-motion, etc.
    pub url:      StringRef,   // cloud URL
    pub duration: f32,         // seconds
    pub loop_:    bool,        // live = loops, dark = plays once
    pub ratio:    ArtKind,     // reuses aspect ratio enum
}

#[repr(C)]
pub struct TrailerNode {
    // Inherits all MotionNode fields; kind uses TrailerKind enum
    pub id:       [u8; 8],
    pub kind:     TrailerKind, // movie-trailer, episode-trailer, podcast-trailer, etc.
    pub url:      StringRef,
    pub duration: f32,
    pub loop_:    bool,
    pub ratio:    ArtKind,
    pub released: Option<u32>, // Unix date of release
}
}

StudioNode / LabelNode

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct StudioNode {
    pub id:      [u8; 8],          // "st" prefix
    pub name:    StringRef,
    pub kind:    StudioKind,       // film, television, animation, music, etc.
    pub country: [u8; 2],          // ISO 3166-1 alpha-2
    pub parent:  Option<[u8; 8]>,  // parent studio ID (ownership hierarchy arc)
    pub logo:    Option<[u8; 8]>,  // @art/id reference
}

#[repr(C)]
pub struct LabelNode {
    pub id:      [u8; 8],          // "lb" prefix
    pub name:    StringRef,
    pub kind:    LabelKind,        // major, independent, imprint, publisher, distributor
    pub country: [u8; 2],
    pub parent:  Option<[u8; 8]>,  // parent label ID (ownership hierarchy arc)
}
}

Availability Nodes

#![allow(unused)]
fn main() {
#[repr(C)]
pub struct WatchNode {
    pub id:        [u8; 8],
    pub platform:  StringRef,
    pub url:       StringRef,
    pub territory: StringRef,
    pub quality:   QualityFlags,  // bitfield: 4k | hd | sd
    pub access:    AccessLevel,
}

// BuyNode and RentNode share WatchNode fields plus:
pub struct BuyNode {
    // ... WatchNode fields ...
    pub price:    StringRef,  // "14.99 USD"
    pub currency: [u8; 3],   // ISO 4217
}

pub struct RentNode {
    // ... BuyNode fields ...
    pub window: StringRef,   // "30d", "48h"
}

pub struct DownloadNode {
    // ... WatchNode fields plus:
    pub quality: StringRef,   // lossless, hd, sd
    pub format:  StringRef,   // flac | mp3 | aac
    pub drm:     bool,        // live = DRM, dark = DRM-free
}
}

Part III — Compiler Pipeline Stages

.aura source file
        │
        ▼
  ┌─────────────┐
  │   Lexer     │  Scans raw UTF-8 bytes.
  │  (scanner)  │  Emits zero-copy &str token stream.
  └─────────────┘  No heap allocation. No string escaping.
        │
        ▼
  ┌─────────────┐
  │   Parser    │  Consumes token stream.
  │   (ast.rs)  │  Tracks indentation depth for :: blocks.
  └─────────────┘  Builds typed AST (Namespace → Field → Value).
        │
        ▼
  ┌─────────────┐
  │  Namespace  │  Reads namespace.aura at project root.
  │   Loader    │  Builds project symbol table for reference resolution.
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │  Resolver   │  Two-phase @domain/id reference pass.
  │ (resolver)  │  Local → catalog → global cloud. Forward arc warnings.
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │   Time      │  Normalizes all AURA time syntax to [low, high, duration].
  │ Normalizer  │  Enforces low + duration == high invariant.
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │  >> Expander│  Resolves inheritance arcs.
  │ (inherit)   │  Merges parent node fields into child AST nodes.
  └─────────────┘
        │
        ▼
  ┌─────────────────────────────────┐
  │            Emitter              │
  │                                 │
  │  hami.rs  → .hami (manifest)    │  HAMI: B-Tree positional index over key-value regions
  │  atom.rs  → .atom (sync mesh)   │  ATOM: augmented interval tree flat-array
  │  atlas.rs → .atlas (alignment)  │  ATLAS: DTW warp path for variant alignment
  └─────────────────────────────────┘

Part IV — Output File Formats

.hami — HAMI Manifest

HAMI replaces human-readable AURA sigils with ASCII control codes:

File layout:

┌─────────────────────────────────────────────────────┐
│  HAMI Magic: "HAMI" (4 bytes)                       │
│  Version: u16                                       │
│  Root namespace offset: u32                         │
├─────────────────────────────────────────────────────┤
│  Lexical Data Region                                │
│  (contiguous key RS value US key RS value US ...)   │
├─────────────────────────────────────────────────────┤
│  B-Tree Positional Index                            │
│  (key → byte offset pairs, sorted, fixed-width)     │
└─────────────────────────────────────────────────────┘

The B-Tree index is appended last so the emitter calculates all offsets in a single forward pass without backpatching.

.atom — ATOM Interval Tree

ATOM is a contiguous flat array of AtomNode structs ordered by low:

┌────────────────────────────────────────────────────────┐
│  ATOM Magic: "ATOM" (4 bytes)                          │
│  Version: u16                                          │
│  Node count: u32                                       │
├────────────────────────────────────────────────────────┤
│  AtomNode[0]  { low, high, duration, max, ptr, class } │
│  AtomNode[1]  { ... }                                  │
│  AtomNode[N]  { ... }                                  │
├────────────────────────────────────────────────────────┤
│  String Pool                                           │
│  (null-terminated UTF-8 strings; data_ptr indexes here)│
└────────────────────────────────────────────────────────┘

max values are filled by a second pass after initial flat-array construction:

for i = N-1 downto 0:
    nodes[i].max = max(nodes[i].high, nodes[left(i)].max, nodes[right(i)].max)

.atlas — ATLAS Alignment File

Stores a DTW (dynamic time warping) warp path mapping source timestamps to target timestamps for a variant (e.g., an extended cut or alternate language dub).

┌────────────────────────────────────────────────────────┐
│  ATLAS Magic: "ATLS" (4 bytes)                         │
│  Source ID: [u8; 8]   (e.g., track ID)                 │
│  Target ID: [u8; 8]   (e.g., variant ID)               │
│  Point count: u32                                      │
├────────────────────────────────────────────────────────┤
│  WarpPoint[0]  { source_t: f32, target_t: f32 }        │
│  WarpPoint[1]  { ... }                                 │
│  WarpPoint[N]  { ... }                                 │
└────────────────────────────────────────────────────────┘

Part V — Compilation Exclusions

Files and folders the compiler always skips:

Art, motion, and trailer assets are uploaded separately to the cloud store to obtain their URL. That URL is stored as literal text in info/arts.aura. No binary media files are compiled or bundled into .atom or .hami outputs.

Part VI — ID Prefix Registry (core/src/id.rs)

Every generated ID has a type prefix. The prefix encodes the object class.

ID format: {prefix}{6 alphanumeric chars} — charset a-z0-9, 36^6 = 2,176,782,336 values per prefix. The generator checks each candidate against the active project registry before returning it. IDs are never hand-authored.

Part VII — Namespace Resolution Order

When the compiler encounters an @domain/id reference it resolves it in this order:

1. In-file symbol table
   (nodes defined in the current .aura file)

2. Project-local info/ and meta/ symbol tables
   (info/people.aura, info/arts.aura, info/studios.aura, etc.)

3. Project-local tracks/, episodes/, scenes/ registry
   (from namespace.aura files in each sub-folder)

4. Project-level catalog registry
   (the root namespace.aura exports:: block)

5. Global cloud registry
   (via @aduki.org/domain/id lookup — requires network)

6. Unresolved → forward arc
   (stored as a dangling reference; warning unless directives::strict -> live)

Local resolution always wins. The compiler never makes a network call unless all local tables have been exhausted.

Compiler Structure Reference — v0.3.2-beta.2 Workspace layout: core / compiler / engine Pipeline: lexer → parser → namespace loader → resolver → time normalizer → emitter Output formats: .atom (interval tree) · .hami (B-Tree manifest) · .atlas (DTW alignment)