@miadi/composition

Read a gmtermux composition folder and weave it into a miadi-chronicle episode.

A composition is where a recording lands: a folder on an Android device holding voice clips, Whisper transcripts, images, MIDI takes, and the songwriting layer of a piece — key, capo, tempo, sections, chords. It is a musician's artifact. This package reads that artifact and authors its provenance into the chronicle, so a film or musical production and an episode ledger can hold the same work without either one rewriting the other.

The ownership split

| Concern | Owner | | --- | --- | | Creating and narrating episodes | passages | | Relating and syncing artefacts to episodes | @miadi/inquiry-weave | | Reading compositions, authoring their provenance | @miadi/composition | | Observing heterogeneous sources without judging them | @miadi/episodic-memory-schema |

The dependency runs one way. This package imports inquiry-weave and the schema; neither may ever import it. There is exactly one episode scaffold algorithm in this repository and it lives in inquiry-weave — every filesystem primitive on the episode side is delegated there.

What it will not do

• Rewrite a composition. Reading is the only operation performed on a composition folder. No repair, no normalization, no schema-version stamping.
• Invent an episode number. A slug reading ep250- is evidence about a recording, not authorization to claim episode 250. The number is offered as a candidate; a caller must confirm it.
• Bump the weave version. weave: 1 is what every existing reader parses. Composition provenance travels in episode.yaml, never by versioning up.
• Claim to be canonical. Everything projected is marked canonical: false. A machine-derived projection is a proposal to the chronicle, not a ruling.
• Project to authored EpisodicMemory. That schema requires a session id, an opened-at, a charter purpose, and consent decisions. A composition supplies none of them, and inventing them would be authoring disguised as reading.

Classification, not validation

The composition corpus is deliberately heterogeneous — hand-authored folders sit beside editor-written ones and both are legitimate. A boolean valid/invalid would declare half the corpus broken, so compositions are classified:

| Classification | Meaning | | --- | --- | | current-ui-ready | Carries every collection the current editor writes | | compatible-legacy | Readable and whole, predating some of those collections | | repairable | Readable, with defects a human could resolve | | unsafe-or-ambiguous | Cannot be read, or its identity cannot be trusted |

A folder with no composition.json is compatible-legacy, not an error — the directory is the identity and the manifest materializes on the first edit.

Usage

composition observe  <dir>              # read a composition, print its observation
composition classify <dir>              # classify it without touching it
composition project  <dir>              # print the episode.yaml overlay it would write
composition weave    <dir> --number 250 # create the vessel and relate both sides
composition weave    <dir> --episode 250 --dry-run

import { readComposition, classifyComposition, weaveComposition } from "@miadi/composition"

const source = await readComposition("/path/to/compositions-nyro/ep250-routing")
const assessment = classifyComposition(source)

const result = await weaveComposition({
  compositionDir: source.dir,
  number: 250,
  issue: "miadisabelle/gmtermux#31",
})

Environment

Inherited from @miadi/inquiry-weave, unchanged:

| Variable | Meaning | | --- | --- | | MIADI_CHRONICLE_ROOT | Episode vessel root | | MIADI_INQUIRY_ROOT | Where artefact folders are resolved from | | MIADI_INQUIRY_REPO | Fallback repo for issue references |

A composition folder anywhere on disk registers as an artefact by absolute path; it never has to be moved under the inquiry root.

What gets written

Weaving writes three files, none of them inside the composition's manifest:

<composition>/.weave.yaml                     durable relation (weave: 1)
<composition>/AGENTS.md                       back-link appended
<episode>/inquiry/weave.yaml                  sync state (weave: 1)
<episode>/episode.yaml                        source_composition, projection, lineage

In episode.yaml, only source_composition, projection, and composition_musical are ever replaced. lineage is written only when absent — a hand-authored lineage always wins. Every other key is left exactly as found.

Requires

@miadi/episodic-memory-schema@^0.3.0 — 0.2.0 swept the songwriting layer into unmappedFields and labelled .mid and .mp4 clips as audio.