entangled-worlds-orbiters-shared 2.13.0 → 2.15.0

package/README.md

@@ -93,6 +93,12 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - `createStatusChannel` - Status-line seam ("Saving…", "Saved")
 - `isTrustedHostOrigin`, `isEmbedded`, `postToHost` - Host-frame transport
 
+### Note head programs (`entangled-worlds-orbiters-shared/faust`)
+- `buildVoiceProgram`, `buildHeadPrograms` - Compose a rack's note head into FAUST source, keyed by shape
+- `exportHead` - Compose, compile, shrink, size and stamp a head's programs; the compiler and the shrink tool are handed in
+- `recipesFingerprint`, `readRecipes`, `readHeadShape`, `programsNamespace` - The recipes file a build publishes, and the checks a release step makes on it
+- `largestFunction`, `shrinkWasm` - The size check and the shrink step
+
 ### Uploads (`entangled-worlds-orbiters-shared/uploads`)
 - `uploadViaSignedUrl` - The API's signed-URL upload: `/spaces/upload-init` → PUT → `/spaces/upload-complete`, over the app's own authenticated JSON caller
 - `putToSignedUrl` - The storage PUT alone, with progress and abort

package/dist/faust/headExport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A head made ready for play mode: its programs composed, compiled, shrunk, sized and stamped.
+ *
+ * Play mode downloads finished programs: no compiler in the page, no first-build wait on a phone.
+ * This is the step that makes them, once, when an Orbiter is released. It runs where a compiler and
+ * the shrink step exist (a server, a build, a test), never in a listener's browser, so both arrive
+ * as tools rather than imports: this file stays pure.
+ *
+ * For one head (`voiceProgram.ts`, `buildHeadPrograms`):
+ *
+ * 1. **Compose** its programs: the note modules as one, the instrument as another; the instrument
+ *    alone when nothing sits in front of it.
+ * 2. **Compile** each with the app's own options.
+ * 3. **Shrink** each (the same step the module build uses: the same program, a quarter smaller).
+ * 4. **Size** each: past the heavy line its largest function is one Safari may never optimise. The
+ *    export still goes through; the author is told.
+ * 5. **Stamp** the export with what it was built from and the runtime it expects.
+ *
+ * A released Orbiter keeps its sound: an export stays valid when a module's source changes later
+ * (the stamp says what it was built from). Play mode refuses it only when the runtime it expects is
+ * no longer the app's, and then plays as it would have without one.
+ */
+import { type VoiceSlot } from './voiceProgram.js';
+/** One item of Faust's UI tree: a group (with `items`) or a control. */
+export interface FaustUiItem {
+    type: string;
+    label: string;
+    address?: string;
+    init?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    items?: FaustUiItem[];
+    [field: string]: unknown;
+}
+/** Faust's metadata for a compiled DSP (its JSON): the UI tree, inputs, outputs, declares. */
+export interface FaustDspMeta {
+    name: string;
+    inputs: number;
+    outputs: number;
+    compile_options: string;
+    ui: FaustUiItem[];
+    meta?: Array<Record<string, string>>;
+    [field: string]: unknown;
+}
+/** A compiled program as it is stored and downloaded: its wasm and the description of its controls. */
+export interface CompiledProgram {
+    /** Faust's sha key; the `registerProcessor` name. */
+    processorName: string;
+    dspName: string;
+    dspMeta: FaustDspMeta;
+    /** Fully-qualified control addresses, in Faust's order. */
+    paramAddresses: string[];
+    wasmBase64: string;
+    /** 4 for a single-precision build, 8 for -double. */
+    sampleSize: 4 | 8;
+}
+/** Every control address in the DSP's UI tree, in Faust's own order. */
+export declare function collectParamAddresses(ui: FaustUiItem[] | null | undefined): string[];
+/** What an export was built from, and what it needs to play. */
+export interface HeadExportStamp {
+    /** The runtime contract the programs were built for: the app's, as its recipes file names it. */
+    runtime: number;
+    /** The FAUST compiler's version, and its options. */
+    faust: string;
+    options: string;
+    /** The shrink step's version. */
+    shrink: string;
+    /** The fingerprint of the recipes file: every `.dsp` source and library the compiler could read. */
+    sources: string;
+}
+/** The compiler and the shrink step, handed in by whoever runs the export. */
+export interface HeadExportTools {
+    /** Compile `source` under `name` with the sources and libraries mounted: FAUST's factory. */
+    compile(name: string, source: string): Promise<{
+        code: Uint8Array;
+        json: string;
+        shaKey: string;
+    }>;
+    /** The same program, smaller. */
+    shrink(wasm: Uint8Array): Uint8Array;
+    /**
+     * A program already filed under this key, if there is one: it is taken as it is, never compiled
+     * again (an instrument's program is the same file for every Orbiter that plays it).
+     */
+    find?(key: string): Promise<CompiledProgram | null>;
+    stamp: HeadExportStamp;
+}
+/** One finished program of a head. */
+export interface ExportedProgram {
+    /** What it is filed under: its shape. */
+    key: string;
+    artifact: CompiledProgram;
+    /** Its largest function, in bytes, and whether that is past the heavy line. */
+    largestFunction: number;
+    heavy: boolean;
+}
+export interface HeadExport {
+    /** Null when nothing sits in front of the instrument. */
+    notes: ExportedProgram | null;
+    instrument: ExportedProgram;
+    stamp: HeadExportStamp;
+}
+/**
+ * `slots`: the head's note modules in rack order, then its instrument, each with what it does with
+ * notes. Throws when a program does not compile: the caller saves the release without programs, and
+ * play mode plays as it does without them.
+ */
+export declare function exportHead(slots: readonly VoiceSlot[], tools: HeadExportTools): Promise<HeadExport>;

package/dist/faust/headExport.js

@@ -0,0 +1,89 @@
+/**
+ * A head made ready for play mode: its programs composed, compiled, shrunk, sized and stamped.
+ *
+ * Play mode downloads finished programs: no compiler in the page, no first-build wait on a phone.
+ * This is the step that makes them, once, when an Orbiter is released. It runs where a compiler and
+ * the shrink step exist (a server, a build, a test), never in a listener's browser, so both arrive
+ * as tools rather than imports: this file stays pure.
+ *
+ * For one head (`voiceProgram.ts`, `buildHeadPrograms`):
+ *
+ * 1. **Compose** its programs: the note modules as one, the instrument as another; the instrument
+ *    alone when nothing sits in front of it.
+ * 2. **Compile** each with the app's own options.
+ * 3. **Shrink** each (the same step the module build uses: the same program, a quarter smaller).
+ * 4. **Size** each: past the heavy line its largest function is one Safari may never optimise. The
+ *    export still goes through; the author is told.
+ * 5. **Stamp** the export with what it was built from and the runtime it expects.
+ *
+ * A released Orbiter keeps its sound: an export stays valid when a module's source changes later
+ * (the stamp says what it was built from). Play mode refuses it only when the runtime it expects is
+ * no longer the app's, and then plays as it would have without one.
+ */
+import { buildHeadPrograms, HEAD_PROGRAM_NAME } from './voiceProgram.js';
+import { HEAVY_FUNCTION_BYTES, largestFunction } from './wasmSize.js';
+/** Every control address in the DSP's UI tree, in Faust's own order. */
+export function collectParamAddresses(ui) {
+    const out = [];
+    const walk = (items) => items.forEach((item) => {
+        if (item.items)
+            walk(item.items);
+        else if (item.address)
+            out.push(item.address);
+    });
+    walk(ui ?? []);
+    return out;
+}
+function base64(bytes) {
+    let binary = '';
+    // In pieces: one call with every byte as an argument overflows the stack on a large program.
+    for (let at = 0; at < bytes.length; at += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000));
+    return btoa(binary);
+}
+function bytes(text) {
+    const binary = atob(text);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+async function exportProgram(key, source, tools) {
+    const filed = await tools.find?.(key);
+    if (filed) {
+        const size = largestFunction(bytes(filed.wasmBase64));
+        return { key, artifact: filed, largestFunction: size, heavy: size > HEAVY_FUNCTION_BYTES };
+    }
+    const factory = await tools.compile(HEAD_PROGRAM_NAME, source);
+    const wasm = tools.shrink(factory.code);
+    const dspMeta = JSON.parse(factory.json);
+    const size = largestFunction(wasm);
+    return {
+        key,
+        artifact: {
+            processorName: factory.shaKey,
+            dspName: HEAD_PROGRAM_NAME,
+            dspMeta,
+            paramAddresses: collectParamAddresses(dspMeta.ui),
+            wasmBase64: base64(wasm),
+            sampleSize: dspMeta.compile_options.includes('-double') ? 8 : 4,
+        },
+        largestFunction: size,
+        heavy: size > HEAVY_FUNCTION_BYTES,
+    };
+}
+/**
+ * `slots`: the head's note modules in rack order, then its instrument, each with what it does with
+ * notes. Throws when a program does not compile: the caller saves the release without programs, and
+ * play mode plays as it does without them.
+ */
+export async function exportHead(slots, tools) {
+    const programs = buildHeadPrograms(slots);
+    // One after the other: one libfaust compiles one program at a time.
+    const notes = programs.notes ? await exportProgram(programs.notes.key, programs.notes.source, tools) : null;
+    const instrument = await exportProgram(programs.instrument.key, programs.instrument.source, tools);
+    if (notes && notes.artifact.dspMeta.outputs !== instrument.artifact.dspMeta.inputs) {
+        throw new Error(`[headExport] the note modules put out ${notes.artifact.dspMeta.outputs} signals; the instrument takes ${instrument.artifact.dspMeta.inputs}`);
+    }
+    return { notes, instrument, stamp: tools.stamp };
+}

package/dist/faust/index.d.ts

@@ -0,0 +1,4 @@
+export * from './voiceProgram.js';
+export * from './wasmSize.js';
+export * from './headExport.js';
+export * from './recipes.js';

package/dist/faust/index.js

@@ -0,0 +1,7 @@
+// Composing a rack's note head into FAUST programs, and making them ready for play mode: shared by
+// the app that plays them and the server step that compiles them at release, so the source, its key
+// and its file name are the same on both sides. Pure: the compiler and the shrink tool are handed in.
+export * from './voiceProgram.js';
+export * from './wasmSize.js';
+export * from './headExport.js';
+export * from './recipes.js';

package/dist/faust/recipes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The recipes file: everything one build of the app compiles its programs from, in one file named by
+ * a fingerprint of its content.
+ *
+ * The app publishes it beside its compiler; the release step fetches it by the fingerprint the author's
+ * page sends, checks the content against the name, and compiles from exactly that. The sources stay
+ * where they are authored: nothing else has to hold a copy of them in step.
+ *
+ * The fingerprint covers all of it (the sources, the libraries, the compiler's version and options,
+ * the runtime contract), so two builds that would compile a different program never share a name.
+ */
+import { type VoiceSlot } from './voiceProgram.js';
+export interface Recipes {
+    /** `.dsp` file name → FAUST source. */
+    sources: Readonly<Record<string, string>>;
+    /** Library file name → FAUST source, mounted beside the standard ones. */
+    libraries: Readonly<Record<string, string>>;
+    /** The compiler: the version of the package that carries libfaust. */
+    faust: string;
+    /** The compiler's options. */
+    options: string;
+    /** The runtime contract a program compiled from these plays under. */
+    runtime: number;
+}
+export declare const isRecipesFingerprint: (value: unknown) => value is string;
+/** The file a fingerprint names, as the app publishes it. */
+export declare const recipesFileName: (fingerprint: string) => string;
+/** A hash of everything a compile reads and is told (SHA-256, its first 16 hex digits). */
+export declare function recipesFingerprint(recipes: Recipes): Promise<string>;
+/** A downloaded recipes file, if it reads as one; anything else is null. */
+export declare function readRecipes(value: unknown): Recipes | null;
+/**
+ * How this package composes a program from a shape. Raise it when the same shape would compose to
+ * different text: a test keeps a fingerprint of the composed text beside it and fails until then.
+ */
+export declare const COMPOSER_VERSION = 2;
+/**
+ * Where a build's compiled programs are filed: the recipes, the shrink step and the composer
+ * together. A file under it is never replaced, so a release keeps the programs it was given.
+ */
+export declare function programsNamespace(fingerprint: string, shrink: string): Promise<string>;
+/** The most World dimensions an Orbiter has: a head each. */
+export declare const MAX_HEADS = 3;
+/** The most note modules in front of an instrument: a generator and the MIDI effects. */
+export declare const MAX_HEAD_NOTE_MODULES = 12;
+/**
+ * A head's shape as a client sent it, checked before anything is composed from it: the note modules
+ * in rack order, then the instrument. Every file must be one of the recipes', every count a whole
+ * number inside the rack's limits. Returns the shape with nothing else on it; throws with the reason.
+ */
+export declare function readHeadShape(value: unknown, sources: Readonly<Record<string, string>>): VoiceSlot[];
+/** One head's programs on a release: their keys, and whether the author was told it is heavy. */
+export interface ReleasedHead {
+    /** Null when nothing sits in front of the instrument. */
+    notes: string | null;
+    instrument: string;
+    heavy?: boolean;
+}
+/** What a release carries of its programs: written by the server at release, never by a client. */
+export interface ReleasedPrograms {
+    /** The runtime contract the programs were built for. */
+    runtime: number;
+    /** Where they are filed (`programsNamespace`): what they were built from and with. */
+    sources: string;
+    /** By World dimension id. */
+    heads: Record<string, ReleasedHead>;
+}
+/** A release's programs, if what it carries reads as them; anything else is no programs. */
+export declare function readReleasedPrograms(value: unknown): ReleasedPrograms | null;

package/dist/faust/recipes.js

@@ -0,0 +1,102 @@
+/**
+ * The recipes file: everything one build of the app compiles its programs from, in one file named by
+ * a fingerprint of its content.
+ *
+ * The app publishes it beside its compiler; the release step fetches it by the fingerprint the author's
+ * page sends, checks the content against the name, and compiles from exactly that. The sources stay
+ * where they are authored: nothing else has to hold a copy of them in step.
+ *
+ * The fingerprint covers all of it (the sources, the libraries, the compiler's version and options,
+ * the runtime contract), so two builds that would compile a different program never share a name.
+ */
+import { MAX_NOTE_LANES } from './voiceProgram.js';
+const FINGERPRINT = /^[0-9a-f]{16}$/;
+export const isRecipesFingerprint = (value) => typeof value === 'string' && FINGERPRINT.test(value);
+/** The file a fingerprint names, as the app publishes it. */
+export const recipesFileName = (fingerprint) => `sources-${fingerprint}.json`;
+async function shortHash(parts) {
+    const text = new TextEncoder().encode(JSON.stringify(parts));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', text));
+    return Array.from(digest.subarray(0, 8), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** A hash of everything a compile reads and is told (SHA-256, its first 16 hex digits). */
+export function recipesFingerprint(recipes) {
+    const sorted = (files) => Object.keys(files).sort().map((file) => [file, files[file]]);
+    return shortHash([sorted(recipes.sources), sorted(recipes.libraries), recipes.faust, recipes.options, recipes.runtime]);
+}
+const isTextMap = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value).every((text) => typeof text === 'string');
+/** A downloaded recipes file, if it reads as one; anything else is null. */
+export function readRecipes(value) {
+    const recipes = value;
+    if (!recipes || typeof recipes !== 'object')
+        return null;
+    if (!isTextMap(recipes.sources) || !isTextMap(recipes.libraries) || !Object.keys(recipes.sources).length)
+        return null;
+    if (typeof recipes.faust !== 'string' || typeof recipes.options !== 'string' || !Number.isInteger(recipes.runtime))
+        return null;
+    return { sources: recipes.sources, libraries: recipes.libraries, faust: recipes.faust, options: recipes.options, runtime: recipes.runtime };
+}
+/**
+ * How this package composes a program from a shape. Raise it when the same shape would compose to
+ * different text: a test keeps a fingerprint of the composed text beside it and fails until then.
+ */
+export const COMPOSER_VERSION = 2;
+/**
+ * Where a build's compiled programs are filed: the recipes, the shrink step and the composer
+ * together. A file under it is never replaced, so a release keeps the programs it was given.
+ */
+export function programsNamespace(fingerprint, shrink) {
+    return shortHash([fingerprint, shrink, COMPOSER_VERSION]);
+}
+/** The most World dimensions an Orbiter has: a head each. */
+export const MAX_HEADS = 3;
+/** The most note modules in front of an instrument: a generator and the MIDI effects. */
+export const MAX_HEAD_NOTE_MODULES = 12;
+/** The largest program constant an instrument takes. */
+const MAX_CONSTANT = 64;
+const whole = (value, most) => Number.isInteger(value) && value >= 1 && value <= most;
+/**
+ * A head's shape as a client sent it, checked before anything is composed from it: the note modules
+ * in rack order, then the instrument. Every file must be one of the recipes', every count a whole
+ * number inside the rack's limits. Returns the shape with nothing else on it; throws with the reason.
+ */
+export function readHeadShape(value, sources) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > MAX_HEAD_NOTE_MODULES + 1)
+        throw new Error('a head is 1 to 13 modules');
+    return value.map((slot, index) => {
+        const file = slot?.dspFileName;
+        const notes = slot?.notes;
+        if (typeof file !== 'string' || !Object.hasOwn(sources, file))
+            throw new Error(`module ${index}: no such source`);
+        const last = index === value.length - 1;
+        if (last) {
+            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
+                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+            const constants = notes.constants ?? {};
+            if (typeof constants !== 'object' || Array.isArray(constants))
+                throw new Error(`module ${index}: constants`);
+            const entries = Object.entries(constants);
+            if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT)))
+                throw new Error(`module ${index}: constants`);
+            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+        }
+        if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES))
+            throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
+        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+    });
+}
+const isHead = (head) => {
+    const h = head;
+    return Boolean(h && typeof h === 'object' && typeof h.instrument === 'string' && (h.notes === null || typeof h.notes === 'string'));
+};
+/** A release's programs, if what it carries reads as them; anything else is no programs. */
+export function readReleasedPrograms(value) {
+    const programs = value;
+    if (!programs || typeof programs !== 'object' || !Number.isInteger(programs.runtime) || typeof programs.sources !== 'string')
+        return null;
+    if (!/^[a-z0-9]+$/i.test(programs.sources) || !programs.heads || typeof programs.heads !== 'object')
+        return null;
+    const heads = Object.fromEntries(Object.entries(programs.heads).filter(([, head]) => isHead(head)));
+    return Object.keys(heads).length ? { runtime: programs.runtime, sources: programs.sources, heads } : null;
+}

package/dist/faust/voiceProgram.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Composing a rack description into one FAUST program.
+ *
+ * This is the play runtime's source: the same per-module `.dsp` files the edit
+ * runtime compiles standalone, stitched together with `component()` so both
+ * runtimes are built from one authored source. Parity is structural, and
+ * measured — a two-module chain renders bit-identically either way.
+ *
+ * ## The slot group is not optional
+ *
+ * Two instances of the same module in one program **silently collapse into a
+ * single control**:
+ *
+ *     process = component("psGain.dsp") : component("psGain.dsp");
+ *     -> one address: /psVoice/gain
+ *
+ * Both multiplies still happen, so the audio is right, but the two slots share
+ * one parameter and move together — and Faust does not warn. Wrapping each slot
+ * in its own group fixes it and costs nothing:
+ *
+ *     process = hgroup("s0", component(...)) : hgroup("s1", component(...));
+ *     -> /psVoice/s0/gain, /psVoice/s1/gain
+ *
+ * That group name is also the **per-slot identity** a single compiled program
+ * was said to lack. It has one — as long as the composer never forgets, which
+ * is why it is emitted here rather than left to each `.dsp`, and why
+ * `slotGroupId` is derived from the slot index and cannot be omitted.
+ *
+ * ## A note chain
+ *
+ * A head rack that plays notes composes as lanes (`lib/ps_notes.lib`):
+ *
+ *     process = nt.chainEntry(8)                                       // the lanes the allocator writes
+ *       : hgroup("s0", nt.bypass(8, 1, library("pitch.dsp")[SLOT=0;].notes(8)))
+ *       : hgroup("tap0", nt.tap(8))                                    // the notes leaving s0
+ *       : nt.toPlay(8)                                                 // the beats stay behind
+ *       : hgroup("s1", library("synth.dsp")[SLOT=1;].play(8))          // a note voice per lane
+ *       : hgroup("s2", component("filter.dsp"));
+ *
+ * One entry at the head, sized by the instrument's polyphony; each generator or MIDI effect takes the
+ * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
+ * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
+ * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * since `notes(n)` is told only n.
+ *
+ * Between the note modules a lane carries a fourth signal, the beat its note started on (what Random
+ * and Velocity draw from): `nt.chainEntry` writes it, `nt.toPlay` drops it, so an instrument takes
+ * three signals a lane whether or not anything sits in front of it. An instrument alone keeps the
+ * plain `nt.entry`.
+ */
+/** The most note lanes one head plays: what reaches the instrument after every note module has multiplied them. */
+export declare const MAX_NOTE_LANES = 16;
+/**
+ * What a slot does with notes: a notes instrument's polyphony (and its program constants, when it has
+ * any), or a generator's or MIDI effect's lanes out per lane in.
+ */
+export type SlotNotes = {
+    kind: 'instrument';
+    polyphony: number;
+    constants?: Readonly<Record<string, number>>;
+    copies?: number;
+} | {
+    kind: 'generator' | 'midi';
+    lanesPerLane: number;
+};
+/** One slot of a composed voice: the module's `.dsp`, by file name. */
+export interface VoiceSlot {
+    dspFileName: string;
+    /**
+     * A note module, with what it does with notes at its stored values (the registry's `resolveNotes`):
+     * a generator or MIDI effect's lanes out per lane in, or a notes instrument's polyphony. Both are
+     * structural: they shape the program.
+     */
+    notes?: SlotNotes;
+}
+/**
+ * The group name for a slot. Index-based, so it is stable across renames and
+ * unique by construction — the two properties the collision above needs.
+ */
+export declare function slotGroupId(index: number): string;
+/** The address a slot's control has once composed: `/<voice>/<group>/<control>`. */
+export declare function composedParamAddress(voiceName: string, index: number, controlName: string): string;
+/**
+ * Build the `.dsp` source for one voice. `voiceName` is the program name and the address root;
+ * `slots` the ordered rack chain.
+ */
+export declare function buildVoiceProgram({ voiceName, slots }?: {
+    voiceName?: string;
+    slots?: readonly VoiceSlot[];
+}): string;
+/** The group of the tap after a note module (its slot index): the notes leaving it. */
+export declare function tapGroupId(index: number): string;
+/**
+ * A stable key for a composed voice.
+ *
+ * The compiled program is a pure function of the ordered slot list, so this is
+ * what makes "compile once, then every listener fetches a finished artifact"
+ * possible. It deliberately covers *only* what changes the program: the modules
+ * and their order. Parameter **values** are written into the running unit and
+ * must not invalidate the cache — a knob turn is not a recompile
+ * (`reactivity: 'live'` versus `'structural'`).
+ *
+ */
+export declare function voiceCacheKey(slots: readonly VoiceSlot[] | null | undefined): string;
+/**
+ * The name every program of a released head declares. A control's address starts with it, so with one
+ * name the two programs of a head read as one (`/psHead/s0/rate`, `/psHead/s1/cutoff`), and an
+ * instrument's program is the same file whichever Orbiter plays it.
+ */
+export declare const HEAD_PROGRAM_NAME = "psHead";
+/** One program of a released head: what it is filed under, and its source. */
+export interface HeadProgram {
+    key: string;
+    source: string;
+}
+/**
+ * A released head, as the programs play mode downloads: the note modules as one (the entry, each
+ * module in its bypass, a tap after each; its outputs are the lanes), and the instrument as another
+ * (its inputs are those lanes), played one after the other in one audio processor.
+ */
+export interface HeadPrograms {
+    /** Null when nothing sits in front of the instrument: its program then carries the entry itself. */
+    notes: HeadProgram | null;
+    instrument: HeadProgram;
+    /** The lanes between the two (three signals a lane). */
+    lanes: number;
+}
+/**
+ * A head composed for release: always two programs when a note module sits in front of the
+ * instrument, so neither grows past the size a phone still optimises, and the instrument's (the
+ * large one) depends only on the instrument, its lanes, its constants and its place: every Orbiter
+ * with that instrument there shares one file.
+ *
+ * `slots`: the note modules in rack order, then the instrument (the audio effects after it stay
+ * units of their own). The addresses are the ones `buildVoiceProgram` gives the same chain.
+ */
+export declare function buildHeadPrograms(slots: readonly VoiceSlot[]): HeadPrograms;