picopilot 0.0.0 → 0.1.0

package/dist/commands/verify.js

@@ -0,0 +1,213 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { z } from 'incur';
+import { Cart, CartParseError } from '../engine/cart/index.js';
+import { ShrinkoParseError, ShellShrinkoAdapter, } from '../engine/shrinko/index.js';
+import { TOKEN_BUDGET } from './tokens.js';
+/**
+ * The one-line self-scoping the `picopilot verify` envelope always carries, so
+ * the connotation of "verify" never misleads an agent into treating a green
+ * static gate as terminal (ADR-0003). It states BOTH facts: verify is static,
+ * and passing does NOT mean the cart runs.
+ */
+export const VERIFY_SCOPE = 'static gate: tokens + integrity; passing does NOT mean the cart runs';
+/**
+ * The exit code for the DISTINCT `gate-incapable` outcome (shrinko absent).
+ * Chosen as 2 to be categorically separate from `fail` (exit 1, a cart that
+ * flunked a check) and from `pass` (exit 0): an absent capability is neither a
+ * green gate nor a failed check but a gate that could not run its most
+ * important check, so it gets its own nonzero code an agent can branch on.
+ */
+export const GATE_INCAPABLE_EXIT = 2;
+const defaultAdapterFactory = (env) => new ShellShrinkoAdapter({ env });
+/**
+ * Runs the STATIC cart-integrity check against `text`: the cart must parse into
+ * the cart model and round-trip cleanly (`Cart.parse(text).serialize() ===
+ * text`). This is a purely static, well-formedness check — it never runs the
+ * cart. A {@link CartParseError} (malformed header/version/section) or a
+ * round-trip mismatch is a fail with a human-readable detail.
+ */
+function checkIntegrity(text) {
+    let cart;
+    try {
+        cart = Cart.parse(text);
+    }
+    catch (e) {
+        if (e instanceof CartParseError) {
+            return {
+                ok: false,
+                detail: `cart does not parse (${e.code}): ${e.message}`,
+            };
+        }
+        throw e;
+    }
+    if (cart.serialize() !== text) {
+        return {
+            ok: false,
+            detail: 'cart does not round-trip cleanly through the cart model (malformed sections)',
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Registers `picopilot verify` (US #15, #18), the STATIC cart-acceptance gate an
+ * agent drives each iteration toward.
+ *
+ * It runs two static checks and returns ONE structured envelope:
+ *
+ * - **integrity** — the cart parses and round-trips cleanly through the cart
+ *   model (well-formed sections). No run.
+ * - **tokens** — the cart is within the 8,192-token budget (via the shrinko
+ *   adapter `--count`).
+ *
+ * (Lint folds in when the lint task lands; in v1-core verify = tokens +
+ * integrity.)
+ *
+ * Three categorical outcomes (ADR-0003):
+ *
+ * - **pass** (exit 0) — both checks green. The envelope SELF-SCOPES (states it
+ *   is static and that passing does not mean the cart runs) and CTAs to
+ *   `picopilot run` ("static checks pass, now confirm it boots"), so the agent
+ *   is led from well-formed to actually-runs.
+ * - **fail** (exit 1) — a check flunked (over budget, or a malformed/non-parsing
+ *   cart). A structured `verify-failed` error listing which checks failed.
+ * - **gate-incapable** (exit {@link GATE_INCAPABLE_EXIT}) — shrinko is ABSENT,
+ *   so the token check (the #1 failure mode, token bloat) cannot run. verify
+ *   returns a DISTINCT `gate-incapable` result, NEVER green, categorically
+ *   separate from pass and fail. This is the gate-as-theatre regression guard:
+ *   verify must never report green by skipping its most important check.
+ *
+ * verify is STATIC and never runs the cart, so it has NO PICO-8 dependency (US
+ * #19). It reaches shrinko entirely through the {@link ShrinkoAdapter} seam, so
+ * a native-TS shrinko would satisfy it unchanged.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present / absent / over-budget without the real
+ *   binary.
+ */
+export function registerVerify(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('verify', {
+        description: 'Static acceptance gate: run tokens + cart-integrity and return one pass/fail envelope. Does NOT run the cart. Requires shrinko.',
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to verify. Defaults to main.p8 in the current folder.'),
+        }),
+        // Declared so incur resolves it from the (test-overridable) env source and
+        // hands it to the shrinko child; verify itself never runs the cart, so it
+        // needs no PICO-8 env.
+        env: z.object({
+            PATH: z
+                .string()
+                .optional()
+                .describe('Used to locate shrinko8 in the child process.'),
+        }),
+        output: z.object({
+            status: z
+                .literal('pass')
+                .describe('The overall gate result. Only a green gate reaches ok.'),
+            scope: z
+                .string()
+                .describe('The self-scoping note: verify is static and passing does NOT mean the cart runs.'),
+            checks: z
+                .object({
+                integrity: z
+                    .boolean()
+                    .describe('True when the cart parses and round-trips cleanly.'),
+                tokens: z
+                    .boolean()
+                    .describe('True when the cart is within the 8,192-token budget.'),
+            })
+                .describe('Per-check pass/fail, so the agent sees WHAT was checked.'),
+            tokens: z.number().describe('The token count shrinko reported.'),
+            budget: z.number().describe('The token budget checked against (8192).'),
+        }),
+        examples: [
+            { description: 'Verify main.p8' },
+            { description: 'Verify a specific cart', args: { cart: 'game.p8' } },
+        ],
+        async run({ args, env, error, ok }) {
+            const cartPath = isAbsolute(args.cart)
+                ? args.cart
+                : resolve(process.cwd(), args.cart);
+            // A missing cart is a picopilot-side error, distinct from a fail: there is
+            // nothing to gate. Surface it clearly rather than reporting a hollow fail.
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            const text = readFileSync(cartPath, 'utf8');
+            // Integrity is a static, shrinko-free check: the cart parses + round-trips.
+            const integrity = checkIntegrity(text);
+            // Tokens goes through the shrinko seam. Absent shrinko is the gate-incapable
+            // trigger (below); a parse failure of shrinko's own output is shrinko-failed.
+            const adapter = adapterFactory(env);
+            let count;
+            try {
+                count = await adapter.count(cartPath);
+            }
+            catch (e) {
+                if (e instanceof ShrinkoParseError) {
+                    return error({
+                        code: 'shrinko-failed',
+                        message: `shrinko ran but its --count output could not be parsed: ${e.message}`,
+                        exitCode: 1,
+                    });
+                }
+                throw e;
+            }
+            // GATE-INCAPABLE (ADR-0003): shrinko absent → verify CANNOT check the #1
+            // failure mode (token bloat). It returns a DISTINCT outcome, NEVER green,
+            // never a silent skip. This is the load-bearing regression guard: verify
+            // must not report pass by omitting its most important check.
+            if (!count.ok) {
+                return error({
+                    code: 'gate-incapable',
+                    message: `${VERIFY_SCOPE}. gate-incapable: cannot check tokens without shrinko, so verify will not report green. ${count.remedy} (needs: ${count.needs.join(', ')})`,
+                    exitCode: GATE_INCAPABLE_EXIT,
+                });
+            }
+            const tokens = count.value.tokens;
+            const tokensOk = tokens <= TOKEN_BUDGET;
+            // FAIL (exit 1): a static check flunked. List every failing check so the
+            // agent knows what to fix, not just that something did.
+            if (!integrity.ok || !tokensOk) {
+                const failed = [];
+                if (!integrity.ok)
+                    failed.push(`integrity: ${integrity.detail}`);
+                if (!tokensOk) {
+                    failed.push(`tokens: ${tokens} exceeds the ${TOKEN_BUDGET}-token budget`);
+                }
+                return error({
+                    code: 'verify-failed',
+                    message: `${VERIFY_SCOPE}. verify FAILED: ${failed.join('; ')}`,
+                    exitCode: 1,
+                });
+            }
+            // PASS (exit 0): both static checks green. Self-scope, then CTA to `run` so
+            // the agent is led from well-formed to actually-boots (ADR-0003 CTA).
+            return ok({
+                status: 'pass',
+                scope: VERIFY_SCOPE,
+                checks: { integrity: true, tokens: true },
+                tokens,
+                budget: TOKEN_BUDGET,
+            }, {
+                cta: {
+                    description: 'Static checks pass. Now confirm the cart actually boots:',
+                    commands: [
+                        {
+                            command: 'run',
+                            description: 'Launch the cart headless to confirm it boots (verify does not run it).',
+                        },
+                    ],
+                },
+            });
+        },
+    });
+}
+//# sourceMappingURL=verify.js.map

package/dist/commands/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"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"}

package/dist/commands/version.d.ts

@@ -0,0 +1,12 @@
+import { type Cli } from 'incur';
+/**
+ * Registers the trivial `version` command onto the given CLI (or command group).
+ *
+ * This is the skeleton's proof-of-life command: it exercises the full incur
+ * pipeline (output schema, the structured envelope, TOON-by-default and `--json`
+ * formatting) with no engine dependencies, so the `verify` gate has something
+ * real to build and test. Later command groups mount alongside it via their own
+ * `register*` helpers, called from `createCli`.
+ */
+export declare function registerVersion(cli: Cli.Cli): void;
+//# sourceMappingURL=version.d.ts.map

package/dist/commands/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAGlC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAWlD"}

package/dist/commands/version.js

@@ -0,0 +1,24 @@
+import { z } from 'incur';
+import { VERSION } from '../version.js';
+/**
+ * Registers the trivial `version` command onto the given CLI (or command group).
+ *
+ * This is the skeleton's proof-of-life command: it exercises the full incur
+ * pipeline (output schema, the structured envelope, TOON-by-default and `--json`
+ * formatting) with no engine dependencies, so the `verify` gate has something
+ * real to build and test. Later command groups mount alongside it via their own
+ * `register*` helpers, called from `createCli`.
+ */
+export function registerVersion(cli) {
+    cli.command('version', {
+        description: 'Print the picopilot version.',
+        output: z.object({
+            name: z.string().describe('The tool name.'),
+            version: z.string().describe('The installed picopilot version.'),
+        }),
+        run() {
+            return { name: 'picopilot', version: VERSION };
+        },
+    });
+}
+//# sourceMappingURL=version.js.map

package/dist/commands/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,CAAC,EAAC,MAAM,OAAO,CAAC;AAClC,OAAO,EAAC,OAAO,EAAC,MAAM,eAAe,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC3C,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE;QACtB,WAAW,EAAE,8BAA8B;QAC3C,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;YAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAC3C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;SAChE,CAAC;QACF,GAAG;YACF,OAAO,EAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAC,CAAC;QAC9C,CAAC;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/engine/audio/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `engine/audio` — the shrinko-free, PICO-8-free audio codec. Two halves:
+ * the picopilot-MML to `__sfx__` transpiler (finding Part A/B, ADR-0005 +
+ * ADR-0008) and the structural pattern-list to `__music__` codec (finding A.5 /
+ * B.6, ADR-0005).
+ *
+ * Mirrors the `engine/gfx` shape: a pure module + this index re-export, no
+ * adapter. The `sfx from-mml` command is thin wiring over {@link mmlToSfxRow};
+ * the `music from-patterns` command over {@link patternsToMusic}.
+ */
+export { mergeSfxRow, setMusicSection, SFX_SLOT_COUNT } from './section.js';
+export { AudioMmlError, type AudioMmlErrorCode, DEFAULT_LENGTH, DEFAULT_OCTAVE, DEFAULT_SPEED, FILTER_BUZZ, FILTER_DAMPEN_LEVEL, FILTER_DETUNE_1, FILTER_DETUNE_2, FILTER_MAX_LEVEL, FILTER_NOIZ, FILTER_REVERB, mmlToSfxRow, PITCH_MAX, PITCH_MIN, type RowRoundingWarning, SFX_MAX_ROWS, SFX_ROW_LENGTH, type SfxTranspileResult, } from './sfx.js';
+export { CHANNEL_OFF_BIT, type ChannelRef, FLAG_LOOP_BACK, FLAG_LOOP_START, FLAG_STOP, MUSIC_PATTERN_MAX, MusicError, type MusicErrorCode, type MusicTranspileResult, type MusicWarning, type Pattern, patternsToMusic, SFX_INDEX_MAX, } from './music.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/audio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,WAAW,EAAE,eAAe,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAC1E,OAAO,EACN,aAAa,EACb,KAAK,iBAAiB,EACtB,cAAc,EACd,cAAc,EACd,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,SAAS,EACT,SAAS,EACT,KAAK,kBAAkB,EACvB,YAAY,EACZ,cAAc,EACd,KAAK,kBAAkB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,eAAe,EACf,KAAK,UAAU,EACf,cAAc,EACd,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC"}

package/dist/engine/audio/index.js

@@ -0,0 +1,14 @@
+/**
+ * `engine/audio` — the shrinko-free, PICO-8-free audio codec. Two halves:
+ * the picopilot-MML to `__sfx__` transpiler (finding Part A/B, ADR-0005 +
+ * ADR-0008) and the structural pattern-list to `__music__` codec (finding A.5 /
+ * B.6, ADR-0005).
+ *
+ * Mirrors the `engine/gfx` shape: a pure module + this index re-export, no
+ * adapter. The `sfx from-mml` command is thin wiring over {@link mmlToSfxRow};
+ * the `music from-patterns` command over {@link patternsToMusic}.
+ */
+export { mergeSfxRow, setMusicSection, SFX_SLOT_COUNT } from './section.js';
+export { AudioMmlError, DEFAULT_LENGTH, DEFAULT_OCTAVE, DEFAULT_SPEED, FILTER_BUZZ, FILTER_DAMPEN_LEVEL, FILTER_DETUNE_1, FILTER_DETUNE_2, FILTER_MAX_LEVEL, FILTER_NOIZ, FILTER_REVERB, mmlToSfxRow, PITCH_MAX, PITCH_MIN, SFX_MAX_ROWS, SFX_ROW_LENGTH, } from './sfx.js';
+export { CHANNEL_OFF_BIT, FLAG_LOOP_BACK, FLAG_LOOP_START, FLAG_STOP, MUSIC_PATTERN_MAX, MusicError, patternsToMusic, SFX_INDEX_MAX, } from './music.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/audio/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/audio/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,WAAW,EAAE,eAAe,EAAE,cAAc,EAAC,MAAM,cAAc,CAAC;AAC1E,OAAO,EACN,aAAa,EAEb,cAAc,EACd,cAAc,EACd,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,SAAS,EACT,SAAS,EAET,YAAY,EACZ,cAAc,GAEd,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,eAAe,EAEf,cAAc,EACd,eAAe,EACf,SAAS,EACT,iBAAiB,EACjB,UAAU,EAKV,eAAe,EACf,aAAa,GACb,MAAM,YAAY,CAAC"}

package/dist/engine/audio/music.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `engine/audio`: the shrinko-free structural pattern-list to `__music__` codec.
+ *
+ * `__music__` carries NO melodic content (that lives entirely in the referenced
+ * SFX built by `sfx from-mml`). A song is authored STRUCTURALLY: an ordered list
+ * of patterns, each naming up to 4 SFX-channel references plus the 3 pattern-flow
+ * flags. This module OWNS that pattern-list -> `__music__` text emission; the
+ * `music from-patterns` command is thin wiring over {@link patternsToMusic}.
+ *
+ * The layout is the CLOSED spec from the ADR-0005 spike, verified byte-for-byte
+ * against PICO-8 v0.2.7:
+ * `work/notes/findings/pico8-audio-sfx-music-layout-and-mml-subset.md` Part A.5
+ * (the `__music__` text row) + Part B.6 (the structural authoring model). Each
+ * pattern serializes to `<flagbyte> <4 channel bytes>` = `FF CCCCCCCC` (a 2-hex
+ * flag byte + space + 8 hex = 4 channel bytes). Patterns are listed top to
+ * bottom = song order.
+ *
+ * The load-bearing subtlety (finding B.6 / B.7 #9): "channel off" is NOT "sfx 0".
+ * An off channel sets bit6 (`0x40`) on its channel byte and is silent this
+ * pattern; sfx 0 is a real, playing SFX. The model keeps them DISTINCT: a channel
+ * entry is an SFX index 0..63 OR `null` (off).
+ *
+ * Pattern LENGTH is not stored here: PICO-8 ends a pattern when the LEFT-MOST
+ * non-looping channel's SFX finishes (finding B.6), so timing is INHERITED from
+ * the referenced SFX (its speed + LEN, set via `sfx from-mml`). The music model
+ * carries no per-pattern length by design.
+ */
+/** The flag bit set on the leading flag byte for a loop-start pattern (finding A.5). */
+export declare const FLAG_LOOP_START = 1;
+/** The flag bit for a loop-back pattern (jump back to loop-start at its end). */
+export declare const FLAG_LOOP_BACK = 2;
+/** The flag bit for a stop pattern (music stops after it). */
+export declare const FLAG_STOP = 4;
+/** The bit6 marker that makes a channel byte "off" (silent this pattern; finding A.5). */
+export declare const CHANNEL_OFF_BIT = 64;
+/** The highest valid SFX index a channel may reference (0..63; finding A.5). */
+export declare const SFX_INDEX_MAX = 63;
+/** The most patterns `__music__` holds (song positions 0..63; finding: 64 slots). */
+export declare const MUSIC_PATTERN_MAX = 64;
+/**
+ * One channel reference in a pattern: an SFX index 0..63, or `null` = "off"
+ * (bit6 set; the channel is silent this pattern). `null` and `0` are DISTINCT
+ * (finding B.6): 0 is a real, playing SFX; `null` is silence.
+ */
+export type ChannelRef = number | null;
+/**
+ * One song pattern (finding B.6). `channels` is EXACTLY 4 entries (ch0..ch3);
+ * each is an SFX index 0..63 or `null` (off). The 3 flow flags are optional and
+ * default to false. Pattern order in the list = song order.
+ */
+export interface Pattern {
+    /** The 4 channel references (ch0..ch3): each an SFX index 0..63 or `null` (off). */
+    channels: [ChannelRef, ChannelRef, ChannelRef, ChannelRef];
+    /** Flag 0x01: a `music` loop-back searches back to the nearest of these (or pattern 0). */
+    loopStart?: boolean;
+    /** Flag 0x02: at the end of this pattern, jump back to the loop-start pattern. */
+    loopBack?: boolean;
+    /** Flag 0x04: music stops after this pattern. */
+    stop?: boolean;
+}
+/** Machine-readable reason a pattern list could not be transpiled. */
+export type MusicErrorCode = 
+/** A channel referenced an SFX index outside 0..63 (finding A.5). */
+'audio-music-sfx-out-of-range'
+/** A pattern did not carry exactly 4 channel entries (finding A.5). */
+ | 'audio-music-bad-channel-count'
+/** More than 64 patterns were supplied (the `__music__` slot count). */
+ | 'audio-music-too-many-patterns'
+/** The pattern list was empty (nothing to emit). */
+ | 'audio-music-empty';
+/**
+ * A structured pattern-list transpile failure. Mirrors {@link AudioMmlError}'s
+ * shape (a machine-readable `code` + an actionable `message`), surfaced by the
+ * `music from-patterns` command as incur's `error({code,...})` envelope with a
+ * nonzero exit. Never thrown for a case the spec allows (e.g. a loop-back with
+ * no loop-start, which WARNS, not errors).
+ */
+export declare class MusicError extends Error {
+    readonly code: MusicErrorCode;
+    constructor(code: MusicErrorCode, message: string);
+}
+/** A non-fatal advisory surfaced to the caller (finding B.6: loop-back w/o loop-start). */
+export interface MusicWarning {
+    /** A machine handle for the advisory. */
+    code: 'loop-back-without-loop-start';
+    /** A human-readable, actionable explanation. */
+    message: string;
+}
+/** The successful result of transpiling a pattern list to `__music__`. */
+export interface MusicTranspileResult {
+    /** The `__music__` section body: one `FF CCCCCCCC` row per pattern, `\n`-terminated. */
+    section: string;
+    /** The number of patterns emitted (= song length). */
+    patterns: number;
+    /** Any non-fatal advisories (e.g. a loop-back with no loop-start anywhere). */
+    warnings: MusicWarning[];
+}
+/**
+ * Transpiles an ordered pattern list into a `__music__` section body (finding
+ * Part A.5 + B.6). Emits the friendly text rows directly (flow flags hoisted
+ * into the leading flag byte; bit6 set on off channels).
+ *
+ * Pattern order = song order. The result body is one `FF CCCCCCCC` row per
+ * pattern, `\n`-joined with a terminating newline (what PICO-8 writes).
+ *
+ * A `loopBack` flag anywhere with NO `loopStart` flag anywhere is ALLOWED (PICO-8
+ * falls back to pattern 0; finding B.6) but surfaces a {@link MusicWarning}, not
+ * an error. Pattern LENGTH is inherited from the referenced SFX and is not stored
+ * here (finding B.6).
+ *
+ * @throws {MusicError} `audio-music-empty` (no patterns),
+ *   `audio-music-too-many-patterns` (>64), `audio-music-bad-channel-count` or
+ *   `audio-music-sfx-out-of-range` (a malformed / out-of-range channel).
+ */
+export declare function patternsToMusic(patterns: Pattern[]): MusicTranspileResult;
+//# sourceMappingURL=music.d.ts.map

package/dist/engine/audio/music.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/music.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,wFAAwF;AACxF,eAAO,MAAM,eAAe,IAAO,CAAC;AAEpC,iFAAiF;AACjF,eAAO,MAAM,cAAc,IAAO,CAAC;AAEnC,8DAA8D;AAC9D,eAAO,MAAM,SAAS,IAAO,CAAC;AAE9B,0FAA0F;AAC1F,eAAO,MAAM,eAAe,KAAO,CAAC;AAEpC,gFAAgF;AAChF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACvB,oFAAoF;IACpF,QAAQ,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC3D,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,sEAAsE;AACtE,MAAM,MAAM,cAAc;AACzB,qEAAqE;AACnE,8BAA8B;AAChC,uEAAuE;GACrE,+BAA+B;AACjC,wEAAwE;GACtE,+BAA+B;AACjC,oDAAoD;GAClD,mBAAmB,CAAC;AAEvB;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM;CAKjD;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC5B,yCAAyC;IACzC,IAAI,EAAE,8BAA8B,CAAC;IACrC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACpC,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAuDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,oBAAoB,CAgCzE"}

package/dist/engine/audio/music.js

@@ -0,0 +1,138 @@
+/**
+ * `engine/audio`: the shrinko-free structural pattern-list to `__music__` codec.
+ *
+ * `__music__` carries NO melodic content (that lives entirely in the referenced
+ * SFX built by `sfx from-mml`). A song is authored STRUCTURALLY: an ordered list
+ * of patterns, each naming up to 4 SFX-channel references plus the 3 pattern-flow
+ * flags. This module OWNS that pattern-list -> `__music__` text emission; the
+ * `music from-patterns` command is thin wiring over {@link patternsToMusic}.
+ *
+ * The layout is the CLOSED spec from the ADR-0005 spike, verified byte-for-byte
+ * against PICO-8 v0.2.7:
+ * `work/notes/findings/pico8-audio-sfx-music-layout-and-mml-subset.md` Part A.5
+ * (the `__music__` text row) + Part B.6 (the structural authoring model). Each
+ * pattern serializes to `<flagbyte> <4 channel bytes>` = `FF CCCCCCCC` (a 2-hex
+ * flag byte + space + 8 hex = 4 channel bytes). Patterns are listed top to
+ * bottom = song order.
+ *
+ * The load-bearing subtlety (finding B.6 / B.7 #9): "channel off" is NOT "sfx 0".
+ * An off channel sets bit6 (`0x40`) on its channel byte and is silent this
+ * pattern; sfx 0 is a real, playing SFX. The model keeps them DISTINCT: a channel
+ * entry is an SFX index 0..63 OR `null` (off).
+ *
+ * Pattern LENGTH is not stored here: PICO-8 ends a pattern when the LEFT-MOST
+ * non-looping channel's SFX finishes (finding B.6), so timing is INHERITED from
+ * the referenced SFX (its speed + LEN, set via `sfx from-mml`). The music model
+ * carries no per-pattern length by design.
+ */
+/** The flag bit set on the leading flag byte for a loop-start pattern (finding A.5). */
+export const FLAG_LOOP_START = 0x01;
+/** The flag bit for a loop-back pattern (jump back to loop-start at its end). */
+export const FLAG_LOOP_BACK = 0x02;
+/** The flag bit for a stop pattern (music stops after it). */
+export const FLAG_STOP = 0x04;
+/** The bit6 marker that makes a channel byte "off" (silent this pattern; finding A.5). */
+export const CHANNEL_OFF_BIT = 0x40;
+/** The highest valid SFX index a channel may reference (0..63; finding A.5). */
+export const SFX_INDEX_MAX = 63;
+/** The most patterns `__music__` holds (song positions 0..63; finding: 64 slots). */
+export const MUSIC_PATTERN_MAX = 64;
+/**
+ * A structured pattern-list transpile failure. Mirrors {@link AudioMmlError}'s
+ * shape (a machine-readable `code` + an actionable `message`), surfaced by the
+ * `music from-patterns` command as incur's `error({code,...})` envelope with a
+ * nonzero exit. Never thrown for a case the spec allows (e.g. a loop-back with
+ * no loop-start, which WARNS, not errors).
+ */
+export class MusicError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'MusicError';
+        this.code = code;
+    }
+}
+/** A byte as two lowercase hex chars. */
+function byte(n) {
+    return n.toString(16).padStart(2, '0');
+}
+/**
+ * Encodes one pattern into its `FF CCCCCCCC` text row (finding A.5): the 3 flow
+ * flags are hoisted into the leading flag byte; each channel byte is the SFX
+ * index (0..63), OR the index with bit6 (`0x40`) set for an "off" channel. A
+ * `null` channel is off (bit6, index bits 0 -> byte `0x40`); the finding notes
+ * an off byte keeps its low 6 bits (`0x41` = off + sfx 1), so a `null` becomes a
+ * bare `0x40` (there is no underlying sfx index to preserve).
+ *
+ * @throws {MusicError} `audio-music-bad-channel-count` (not exactly 4 channels),
+ *   `audio-music-sfx-out-of-range` (a channel index outside 0..63).
+ */
+function encodePattern(pattern, index) {
+    const { channels } = pattern;
+    if (!Array.isArray(channels) || channels.length !== 4) {
+        throw new MusicError('audio-music-bad-channel-count', `pattern ${index} must have exactly 4 channels (ch0..ch3), got ${Array.isArray(channels) ? channels.length : typeof channels}. Each channel is an SFX index 0..${SFX_INDEX_MAX} or null (off).`);
+    }
+    let flags = 0;
+    if (pattern.loopStart)
+        flags |= FLAG_LOOP_START;
+    if (pattern.loopBack)
+        flags |= FLAG_LOOP_BACK;
+    if (pattern.stop)
+        flags |= FLAG_STOP;
+    let channelBytes = '';
+    for (let c = 0; c < 4; c++) {
+        const ref = channels[c];
+        if (ref === null) {
+            // "Off" is bit6 with no sfx index: a bare 0x40 (finding A.5). Distinct
+            // from sfx 0 (byte 0x00), which is a real, playing SFX.
+            channelBytes += byte(CHANNEL_OFF_BIT);
+            continue;
+        }
+        if (!Number.isInteger(ref) || ref < 0 || ref > SFX_INDEX_MAX) {
+            throw new MusicError('audio-music-sfx-out-of-range', `pattern ${index} channel ${c} references SFX ${ref}, outside 0..${SFX_INDEX_MAX}. A channel is an SFX index 0..${SFX_INDEX_MAX} or null (off); use null to silence a channel, not an out-of-range index.`);
+        }
+        channelBytes += byte(ref);
+    }
+    return `${byte(flags)} ${channelBytes}`;
+}
+/**
+ * Transpiles an ordered pattern list into a `__music__` section body (finding
+ * Part A.5 + B.6). Emits the friendly text rows directly (flow flags hoisted
+ * into the leading flag byte; bit6 set on off channels).
+ *
+ * Pattern order = song order. The result body is one `FF CCCCCCCC` row per
+ * pattern, `\n`-joined with a terminating newline (what PICO-8 writes).
+ *
+ * A `loopBack` flag anywhere with NO `loopStart` flag anywhere is ALLOWED (PICO-8
+ * falls back to pattern 0; finding B.6) but surfaces a {@link MusicWarning}, not
+ * an error. Pattern LENGTH is inherited from the referenced SFX and is not stored
+ * here (finding B.6).
+ *
+ * @throws {MusicError} `audio-music-empty` (no patterns),
+ *   `audio-music-too-many-patterns` (>64), `audio-music-bad-channel-count` or
+ *   `audio-music-sfx-out-of-range` (a malformed / out-of-range channel).
+ */
+export function patternsToMusic(patterns) {
+    if (!Array.isArray(patterns) || patterns.length === 0) {
+        throw new MusicError('audio-music-empty', 'no patterns to assemble: supply at least one pattern (each: 4 channel refs + optional loopStart/loopBack/stop flags).');
+    }
+    if (patterns.length > MUSIC_PATTERN_MAX) {
+        throw new MusicError('audio-music-too-many-patterns', `${patterns.length} patterns exceeds the ${MUSIC_PATTERN_MAX}-pattern __music__ limit (song positions 0..${MUSIC_PATTERN_MAX - 1}).`);
+    }
+    const rows = patterns.map((p, i) => encodePattern(p, i));
+    const warnings = [];
+    const anyLoopStart = patterns.some((p) => p.loopStart === true);
+    const anyLoopBack = patterns.some((p) => p.loopBack === true);
+    if (anyLoopBack && !anyLoopStart) {
+        warnings.push({
+            code: 'loop-back-without-loop-start',
+            message: 'a pattern has loopBack but no pattern has loopStart: PICO-8 loops back to pattern 0. Add loopStart to the pattern you want the loop to return to, or accept the fall-back to pattern 0.',
+        });
+    }
+    return {
+        section: rows.join('\n') + '\n',
+        patterns: rows.length,
+        warnings,
+    };
+}
+//# sourceMappingURL=music.js.map

package/dist/engine/audio/music.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.js","sourceRoot":"","sources":["../../../src/engine/audio/music.ts"],"names":[],"mappings":"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"}

package/dist/engine/audio/section.d.ts

@@ -0,0 +1,34 @@
+import type { Cart } from '../cart/index.js';
+/**
+ * The number of SFX slots a cart holds (finding: 64 SFX, indices 0..63).
+ */
+export declare const SFX_SLOT_COUNT = 64;
+/**
+ * Merges one transpiled `__sfx__` row into slot `slot` (0..63) of a cart's
+ * `__sfx__` section, leaving every other slot BYTE-IDENTICAL, and commits it
+ * back through the cart model (so all other sections stay untouched).
+ *
+ * PICO-8 trims trailing all-zero SFX rows on save, so a cart's `__sfx__` body
+ * may have FEWER than 64 lines (or be absent). This pads with empty rows up to
+ * the target slot as needed, replaces the target, and drops trailing empty rows
+ * again so the result matches what PICO-8 would write (a stable round-trip).
+ *
+ * The `__sfx__` body's newline style + trailing-newline are preserved from the
+ * existing section (defaulting to `\n` with a terminating newline, matching what
+ * PICO-8 writes).
+ */
+export declare function mergeSfxRow(cart: Cart, slot: number, row: string): void;
+/**
+ * Replaces a cart's `__music__` section with a transpiled body, leaving every
+ * OTHER section (including `__sfx__`) BYTE-IDENTICAL, and commits it back through
+ * the cart model.
+ *
+ * Unlike `__sfx__` (where {@link mergeSfxRow} writes ONE slot), a `music
+ * from-patterns` call authors the WHOLE song at once (an ordered pattern list is
+ * the whole `__music__`), so this REPLACES the section wholesale rather than
+ * merging a single row. The body is the codec's output (one `FF CCCCCCCC` row per
+ * pattern); this only normalises its newline style to match the cart's existing
+ * `__music__`/dominant newline so the round-trip stays stable.
+ */
+export declare function setMusicSection(cart: Cart, body: string): void;
+//# sourceMappingURL=section.d.ts.map

package/dist/engine/audio/section.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/section.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AAG3C;;GAEG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAKjC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAgCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO9D"}