nubos-pilot 0.1.0

package/lib/metrics-aggregate.test.cjs

@@ -0,0 +1,192 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const agg = require('./metrics-aggregate.cjs');
+const { aggregatePhase, aggregateSession, _readJsonlLines } = agg;
+
+const _sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-metrics-agg-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'metrics'), { recursive: true });
+  _sandboxes.push(root);
+  return root;
+}
+
+function writeJsonl(root, name, records) {
+  const p = path.join(root, '.nubos-pilot', 'metrics', name);
+  const lines = records.map((r) => (typeof r === 'string' ? r : JSON.stringify(r))).join('\n') + '\n';
+  fs.writeFileSync(p, lines);
+  return p;
+}
+
+test.afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {  }
+  }
+});
+
+function claudeRec(overrides) {
+  return Object.assign({
+    agent: 'np-executor', tier: 'sonnet', resolved_model: 'claude-sonnet-4-6',
+    phase: '10', plan: '10-01', task: '10-01-T01',
+    started_at: '2026-04-17T10:00:00Z',
+    ended_at: '2026-04-17T10:00:01Z',
+    duration_ms: 1000,
+    tokens_in: 100, tokens_out: 50,
+    retry_count: 0, status: 'ok', runtime: 'claude', error: null,
+  }, overrides || {});
+}
+
+function codexRec(overrides) {
+  return Object.assign({
+    agent: 'np-executor', tier: 'sonnet', resolved_model: 'claude-sonnet-4-6',
+    phase: '10', plan: '10-01', task: '10-01-T02',
+    started_at: '2026-04-17T10:00:00Z',
+    ended_at: '2026-04-17T10:00:01Z',
+    duration_ms: 1000,
+    tokens_in: null, tokens_out: null,
+    retry_count: 0, status: 'ok', runtime: 'codex', error: null,
+  }, overrides || {});
+}
+
+test('AGG-1: aggregatePhase on empty dir returns zero-shape', async () => {
+  const sb = makeSandbox();
+  const out = await aggregatePhase('10', { cwd: sb });
+  assert.equal(out.phase, '10');
+  assert.equal(out.record_count, 0);
+  assert.equal(out.total_tokens_in, null);
+  assert.equal(out.total_tokens_out, null);
+  assert.deepEqual(out.avg_duration_ms_by_tier, {});
+  assert.deepEqual(out.avg_duration_ms_by_agent, {});
+  assert.equal(out.retry_count_sum, 0);
+  assert.equal(out.error_count, 0);
+  assert.equal(out.error_rate, 0);
+  assert.deepEqual(out.agents_seen, []);
+  assert.equal(out.first_record_at, null);
+  assert.equal(out.last_record_at, null);
+});
+
+test('AGG-2: mixed claude + codex records → partial_tokens true; sum only claude tokens', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-10.jsonl', [
+    claudeRec({ tokens_in: 100, tokens_out: 50 }),
+    claudeRec({ tokens_in: 200, tokens_out: 75 }),
+    codexRec(),
+    codexRec(),
+    codexRec(),
+  ]);
+  const out = await aggregatePhase('10', { cwd: sb });
+  assert.equal(out.record_count, 5);
+  assert.equal(out.total_tokens_in, 300);
+  assert.equal(out.total_tokens_out, 125);
+  assert.equal(out.partial_tokens, true);
+});
+
+test('AGG-3: all-codex records → total_tokens_in null, partial_tokens false', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-10.jsonl', [codexRec(), codexRec(), codexRec(), codexRec(), codexRec()]);
+  const out = await aggregatePhase('10', { cwd: sb });
+  assert.equal(out.record_count, 5);
+  assert.equal(out.total_tokens_in, null);
+  assert.equal(out.total_tokens_out, null);
+  assert.equal(out.partial_tokens, false);
+});
+
+test('AGG-4: error_rate = error_count / record_count', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-10.jsonl', [
+    claudeRec({ status: 'ok' }),
+    claudeRec({ status: 'error' }),
+    claudeRec({ status: 'ok' }),
+    claudeRec({ status: 'timeout' }),
+  ]);
+  const out = await aggregatePhase('10', { cwd: sb });
+  assert.equal(out.record_count, 4);
+  assert.equal(out.error_count, 2);
+  assert.equal(out.error_rate, 0.5);
+});
+
+test('AGG-5: avg_duration_ms buckets by tier and agent', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-10.jsonl', [
+    claudeRec({ tier: 'opus', agent: 'alpha', duration_ms: 100 }),
+    claudeRec({ tier: 'opus', agent: 'alpha', duration_ms: 200 }),
+    claudeRec({ tier: 'opus', agent: 'alpha', duration_ms: 300 }),
+    claudeRec({ tier: 'haiku', agent: 'beta', duration_ms: 500 }),
+  ]);
+  const out = await aggregatePhase('10', { cwd: sb });
+  assert.equal(out.avg_duration_ms_by_tier.opus, 200);
+  assert.equal(out.avg_duration_ms_by_tier.haiku, 500);
+  assert.equal(out.avg_duration_ms_by_agent.alpha, 200);
+  assert.equal(out.avg_duration_ms_by_agent.beta, 500);
+  assert.deepEqual(out.agents_seen, ['alpha', 'beta']);
+});
+
+test('AGG-6: aggregateSession filters records below sinceIso', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-10.jsonl', [
+    claudeRec({ started_at: '2026-04-17T08:00:00Z' }),
+    claudeRec({ started_at: '2026-04-17T11:00:00Z' }),
+    claudeRec({ started_at: '2026-04-17T12:00:00Z' }),
+  ]);
+  const out = await aggregateSession('2026-04-17T10:00:00Z', { cwd: sb });
+  assert.equal(out.record_count, 2);
+  assert.equal(out.since_iso, '2026-04-17T10:00:00Z');
+});
+
+test('AGG-7: aggregateSession reads all phase-*.jsonl + meta.jsonl', async () => {
+  const sb = makeSandbox();
+  writeJsonl(sb, 'phase-09.jsonl', [claudeRec({ phase: '09' })]);
+  writeJsonl(sb, 'phase-10.jsonl', [claudeRec({ phase: '10' }), claudeRec({ phase: '10' })]);
+  writeJsonl(sb, 'meta.jsonl', [claudeRec({ phase: null })]);
+  const out = await aggregateSession(null, { cwd: sb });
+  assert.ok(out.by_phase['09']);
+  assert.ok(out.by_phase['10']);
+  assert.ok(out.by_phase['meta']);
+  assert.equal(out.by_phase['10'].record_count, 2);
+  assert.equal(out.record_count, 4);
+  assert.deepEqual(out.phases_touched.sort(), ['09', '10', 'meta']);
+});
+
+test('AGG-8: malformed line logs warning to stderr and skips, valid lines parse', async () => {
+  const sb = makeSandbox();
+  const p = path.join(sb, '.nubos-pilot', 'metrics', 'phase-10.jsonl');
+  const lines = [
+    JSON.stringify(claudeRec()),
+    '{not valid json',
+    JSON.stringify(claudeRec()),
+    JSON.stringify(claudeRec()),
+  ].join('\n') + '\n';
+  fs.writeFileSync(p, lines);
+  const orig = process.stderr.write.bind(process.stderr);
+  let captured = '';
+  process.stderr.write = (chunk) => { captured += chunk; return true; };
+  let out;
+  try {
+    out = await aggregatePhase('10', { cwd: sb });
+  } finally {
+    process.stderr.write = orig;
+  }
+  assert.equal(out.record_count, 3);
+  assert.match(captured, /skipping malformed JSONL/);
+});
+
+test('AGG-9: path-traversal phase rejected with metrics-invalid-phase', async () => {
+  const sb = makeSandbox();
+  await assert.rejects(
+    () => aggregatePhase('../etc/passwd', { cwd: sb }),
+    (err) => err && err.name === 'NubosPilotError' && err.code === 'metrics-invalid-phase',
+  );
+});
+
+test('READJL-1: _readJsonlLines on missing file resolves without error', async () => {
+  const sb = makeSandbox();
+  const missing = path.join(sb, '.nubos-pilot', 'metrics', 'absent.jsonl');
+  let records = [];
+  await _readJsonlLines(missing, (r) => records.push(r));
+  assert.equal(records.length, 0);
+});

package/lib/metrics.cjs

@@ -0,0 +1,120 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { NubosPilotError, findProjectRoot } = require('./core.cjs');
+
+const MAX_ERROR_MESSAGE = 300;
+
+const MAX_ERROR_CODE = 40;
+
+const MAX_RECORD_BYTES = 511;
+
+const SCHEMA_FIELDS = [
+  'agent', 'tier', 'resolved_model',
+  'phase', 'plan', 'task',
+  'started_at', 'ended_at', 'duration_ms',
+  'tokens_in', 'tokens_out',
+  'retry_count', 'status', 'runtime', 'error',
+];
+
+const REQUIRED_INPUT_FIELDS = [
+  'agent', 'tier', 'resolved_model',
+  'phase', 'plan', 'task',
+  'started_at', 'ended_at',
+  'status', 'runtime',
+];
+
+const SAFE_PHASE_RE = /^[A-Za-z0-9._-]+$/;
+
+function _truncateError(err) {
+  if (!err || typeof err !== 'object') return null;
+  let code = typeof err.code === 'string' ? err.code : 'unknown';
+  if (code.length > MAX_ERROR_CODE) code = code.slice(0, MAX_ERROR_CODE);
+  let message = typeof err.message === 'string' ? err.message : '';
+  if (message.length > MAX_ERROR_MESSAGE) {
+    message = message.slice(0, MAX_ERROR_MESSAGE) + '…';
+  }
+  return { code, message };
+}
+
+function _durationMs(startedAt, endedAt) {
+  const s = Date.parse(startedAt);
+  const e = Date.parse(endedAt);
+  if (Number.isNaN(s) || Number.isNaN(e)) return 0;
+  return Math.max(0, e - s);
+}
+
+function buildRecord(args) {
+  const input = args || {};
+  const missing = [];
+  for (const f of REQUIRED_INPUT_FIELDS) {
+    const v = input[f];
+    if (v === undefined || v === null) {
+      if (f === 'phase' && v === '') continue;
+      missing.push(f);
+    }
+  }
+  if (missing.length) {
+    throw new NubosPilotError(
+      'metrics-invalid-record',
+      'metrics.buildRecord missing required fields: ' + missing.join(', '),
+      { missing },
+    );
+  }
+
+  const isClaude = input.runtime === 'claude';
+  const record = {
+    agent: String(input.agent),
+    tier: String(input.tier),
+    resolved_model: String(input.resolved_model),
+    phase: String(input.phase),
+    plan: String(input.plan),
+    task: String(input.task),
+    started_at: String(input.started_at),
+    ended_at: String(input.ended_at),
+    duration_ms: _durationMs(input.started_at, input.ended_at),
+    tokens_in: isClaude && typeof input.tokens_in === 'number' ? input.tokens_in : null,
+    tokens_out: isClaude && typeof input.tokens_out === 'number' ? input.tokens_out : null,
+    retry_count: typeof input.retry_count === 'number' ? input.retry_count : 0,
+    status: String(input.status),
+    runtime: String(input.runtime),
+    error: input.status === 'ok' ? null : _truncateError(input.error),
+  };
+
+  if (record.error && typeof record.error.message === 'string') {
+    while (Buffer.byteLength(JSON.stringify(record), 'utf8') > MAX_RECORD_BYTES) {
+      const msg = record.error.message;
+      const base = msg.endsWith('…') ? msg.slice(0, -1) : msg;
+      if (base.length === 0) { record.error.message = ''; break; }
+      record.error.message = base.slice(0, base.length - 1) + '…';
+    }
+  }
+
+  return record;
+}
+
+function appendRecord(record, opts) {
+  const cwd = (opts && opts.cwd) || process.cwd();
+  const root = findProjectRoot(cwd);
+  const dir = path.join(root, '.nubos-pilot', 'metrics');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const phase = record.phase == null ? '' : String(record.phase);
+  let file;
+  if (phase === '') {
+    file = path.join(dir, 'meta.jsonl');
+  } else {
+    if (!SAFE_PHASE_RE.test(phase)) {
+      throw new NubosPilotError(
+        'metrics-invalid-phase',
+        'metrics.appendRecord phase must match /^[A-Za-z0-9._-]+$/: ' + phase,
+        { phase },
+      );
+    }
+    file = path.join(dir, 'phase-' + phase + '.jsonl');
+  }
+  fs.appendFileSync(file, JSON.stringify(record) + os.EOL);
+  return file;
+}
+
+module.exports = { appendRecord, buildRecord, MAX_ERROR_MESSAGE, SCHEMA_FIELDS };

package/lib/metrics.test.cjs

@@ -0,0 +1,182 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const metrics = require('./metrics.cjs');
+const { appendRecord, buildRecord, MAX_ERROR_MESSAGE, SCHEMA_FIELDS } = metrics;
+
+const _sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-metrics-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  _sandboxes.push(root);
+  return root;
+}
+
+test.afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {  }
+  }
+});
+
+function validClaudeArgs(overrides) {
+  return Object.assign({
+    agent: 'np-executor',
+    tier: 'sonnet',
+    resolved_model: 'claude-sonnet-4-6',
+    phase: '09',
+    plan: '09-01',
+    task: '09-01-T02',
+    started_at: '2026-04-16T14:30:12.123Z',
+    ended_at:   '2026-04-16T14:31:08.987Z',
+    tokens_in: 3421,
+    tokens_out: 812,
+    retry_count: 0,
+    status: 'ok',
+    runtime: 'claude',
+    error: null,
+  }, overrides || {});
+}
+
+test('MET-1: SCHEMA_FIELDS equals D-08 15-field list in exact order', () => {
+  assert.deepEqual(SCHEMA_FIELDS, [
+    'agent', 'tier', 'resolved_model',
+    'phase', 'plan', 'task',
+    'started_at', 'ended_at', 'duration_ms',
+    'tokens_in', 'tokens_out',
+    'retry_count', 'status', 'runtime', 'error',
+  ]);
+  assert.equal(SCHEMA_FIELDS.length, 15);
+});
+
+test('MET-2: MAX_ERROR_MESSAGE equals 300', () => {
+  assert.equal(MAX_ERROR_MESSAGE, 300);
+});
+
+test('MET-3: buildRecord with valid claude payload returns complete D-08 record', () => {
+  const rec = buildRecord(validClaudeArgs());
+  assert.equal(rec.agent, 'np-executor');
+  assert.equal(rec.tier, 'sonnet');
+  assert.equal(rec.resolved_model, 'claude-sonnet-4-6');
+  assert.equal(rec.phase, '09');
+  assert.equal(rec.plan, '09-01');
+  assert.equal(rec.task, '09-01-T02');
+  assert.equal(rec.started_at, '2026-04-16T14:30:12.123Z');
+  assert.equal(rec.ended_at, '2026-04-16T14:31:08.987Z');
+  const expectedDuration = Date.parse('2026-04-16T14:31:08.987Z') - Date.parse('2026-04-16T14:30:12.123Z');
+  assert.equal(rec.duration_ms, expectedDuration);
+  assert.equal(rec.tokens_in, 3421);
+  assert.equal(rec.tokens_out, 812);
+  assert.equal(rec.retry_count, 0);
+  assert.equal(rec.status, 'ok');
+  assert.equal(rec.runtime, 'claude');
+  assert.equal(rec.error, null, 'error must be null when status=ok');
+});
+
+test('MET-4: buildRecord with status=error preserves error object shape', () => {
+  const rec = buildRecord(validClaudeArgs({ status: 'error', error: { code: 'X', message: 'm' } }));
+  assert.deepEqual(rec.error, { code: 'X', message: 'm' });
+});
+
+test('MET-5: buildRecord truncates overlong error.message to <=300 chars + ellipsis', () => {
+  const rec = buildRecord(validClaudeArgs({
+    status: 'error',
+    error: { code: 'X', message: 'a'.repeat(1000) },
+  }));
+  assert.ok(
+    rec.error.message.length <= 301,
+    'char-cap: 300 content chars + 1 ellipsis; stricter byte-budget may cut further',
+  );
+  assert.ok(rec.error.message.endsWith('…'), 'truncated message ends with ellipsis');
+  assert.equal(rec.error.message[0], 'a', 'kept content is the prefix of original message');
+  assert.ok(
+    rec.error.message.slice(0, -1).split('').every((c) => c === 'a'),
+    'all kept characters are the original prefix',
+  );
+});
+
+test('MET-6: buildRecord runtime=codex nulls tokens_in/tokens_out (D-09)', () => {
+  const rec = buildRecord(validClaudeArgs({ runtime: 'codex', tokens_in: 9999, tokens_out: 9999 }));
+  assert.equal(rec.tokens_in, null, 'tokens_in must be null for non-claude runtime');
+  assert.equal(rec.tokens_out, null, 'tokens_out must be null for non-claude runtime');
+  assert.equal(rec.runtime, 'codex');
+});
+
+test('MET-7: buildRecord({}) throws metrics-invalid-record with missing[] detail', () => {
+  let thrown = null;
+  try { buildRecord({}); } catch (e) { thrown = e; }
+  assert.ok(thrown, 'expected throw on empty input');
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'metrics-invalid-record');
+  assert.ok(Array.isArray(thrown.details.missing), 'details.missing must be array');
+  for (const f of ['agent', 'tier', 'phase', 'status', 'runtime']) {
+    assert.ok(thrown.details.missing.includes(f), 'missing[] must include ' + f);
+  }
+});
+
+test('MET-8: appendRecord routes phase=09 to phase-09.jsonl (one line, parseable)', () => {
+  const sb = makeSandbox();
+  const rec = buildRecord(validClaudeArgs());
+  appendRecord(rec, { cwd: sb });
+  const filePath = path.join(sb, '.nubos-pilot', 'metrics', 'phase-09.jsonl');
+  assert.ok(fs.existsSync(filePath), 'phase-09.jsonl must exist');
+  const lines = fs.readFileSync(filePath, 'utf-8').split(os.EOL).filter(Boolean);
+  assert.equal(lines.length, 1);
+  const parsed = JSON.parse(lines[0]);
+  assert.equal(parsed.phase, '09');
+  assert.equal(parsed.task, '09-01-T02');
+  assert.deepEqual(parsed, rec, 'round-trip JSON.parse must equal original record');
+});
+
+test('MET-9: appendRecord with phase="" routes to meta.jsonl (not phase-*.jsonl)', () => {
+  const sb = makeSandbox();
+  const rec1 = buildRecord(validClaudeArgs({ phase: '' }));
+  const rec2 = buildRecord(validClaudeArgs({ phase: '', task: '09-01-T03' }));
+  appendRecord(rec1, { cwd: sb });
+  appendRecord(rec2, { cwd: sb });
+  const metaPath = path.join(sb, '.nubos-pilot', 'metrics', 'meta.jsonl');
+  assert.ok(fs.existsSync(metaPath), 'meta.jsonl must exist');
+  const metaLines = fs.readFileSync(metaPath, 'utf-8').split(os.EOL).filter(Boolean);
+  assert.equal(metaLines.length, 2, 'two appends must produce exactly two lines in meta.jsonl');
+  const phaseFiles = fs.readdirSync(path.join(sb, '.nubos-pilot', 'metrics')).filter((f) => f.startsWith('phase-'));
+  assert.equal(phaseFiles.length, 0, 'no phase-*.jsonl files should exist when phase=""');
+});
+
+test('MET-10: two sequential appendRecord calls produce two independently-parseable lines', () => {
+  const sb = makeSandbox();
+  const r1 = buildRecord(validClaudeArgs({ task: '09-01-T01' }));
+  const r2 = buildRecord(validClaudeArgs({ task: '09-01-T02' }));
+  appendRecord(r1, { cwd: sb });
+  appendRecord(r2, { cwd: sb });
+  const filePath = path.join(sb, '.nubos-pilot', 'metrics', 'phase-09.jsonl');
+  const lines = fs.readFileSync(filePath, 'utf-8').split(os.EOL).filter(Boolean);
+  assert.equal(lines.length, 2);
+  const p1 = JSON.parse(lines[0]);
+  const p2 = JSON.parse(lines[1]);
+  assert.equal(p1.task, '09-01-T01');
+  assert.equal(p2.task, '09-01-T02');
+});
+
+test('MET-11: worst-case record size under macOS PIPE_BUF=512 (Pitfall 1)', () => {
+  const worst = buildRecord(validClaudeArgs({
+    status: 'error',
+    error: { code: 'a'.repeat(50), message: 'a'.repeat(1000) },
+  }));
+  const serialised = JSON.stringify(worst);
+  assert.ok(
+    serialised.length < 512,
+    'Worst-case record is ' + serialised.length + ' bytes; must stay < 512 for macOS PIPE_BUF',
+  );
+});
+
+test('MET-12: serialised record has no raw newline bytes even with multiline error message', () => {
+  const rec = buildRecord(validClaudeArgs({
+    status: 'error',
+    error: { code: 'E', message: 'line1\nline2\nline3' },
+  }));
+  const serialised = JSON.stringify(rec);
+  assert.equal(serialised.indexOf('\n'), -1, 'JSON-serialised record must have no raw newline bytes');
+});

package/lib/model-aliases.regression.test.cjs

@@ -0,0 +1,16 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { MODEL_ALIAS_MAP } = require('./model-profiles.cjs');
+
+test('MAR-1: MODEL_ALIAS_MAP snapshot — fail loud on silent alias bump (D-17)', () => {
+  assert.deepEqual(
+    MODEL_ALIAS_MAP,
+    {
+      opus:   'claude-opus-4-7',
+      sonnet: 'claude-sonnet-4-6',
+      haiku:  'claude-haiku-4-5',
+    },
+    'Regression gate: MODEL_ALIAS_MAP changed. Release checklist REQUIRES running this test on pre-bump main and confirming the failure message BEFORE updating the alias map. If this failure is expected, bump the literals in BOTH model-profiles.cjs AND this test in a single commit citing the Anthropic release URL.',
+  );
+});

package/lib/model-profiles.cjs

@@ -0,0 +1,42 @@
+const { NubosPilotError } = require('./core.cjs');
+
+const TIER_PROFILE_MATRIX = {
+  opus:   { quality: 'opus',   balanced: 'opus',   budget: 'sonnet', inherit: '' },
+  sonnet: { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku',  inherit: '' },
+  haiku:  { quality: 'sonnet', balanced: 'haiku',  budget: 'haiku',  inherit: '' },
+};
+
+const MODEL_ALIAS_MAP = {
+  opus:   'claude-opus-4-7',
+  sonnet: 'claude-sonnet-4-6',
+  haiku:  'claude-haiku-4-5',
+};
+
+const VALID_TIERS = ['haiku', 'sonnet', 'opus'];
+const VALID_PROFILES = ['quality', 'balanced', 'budget', 'inherit'];
+
+function resolve(tier, profile) {
+  if (!VALID_TIERS.includes(tier)) {
+    throw new NubosPilotError(
+      'invalid-tier',
+      'tier must be one of ' + VALID_TIERS.join('/'),
+      { got: tier, allowed: VALID_TIERS.slice() },
+    );
+  }
+  if (!VALID_PROFILES.includes(profile)) {
+    throw new NubosPilotError(
+      'invalid-profile',
+      'profile must be one of ' + VALID_PROFILES.join('/'),
+      { got: profile, allowed: VALID_PROFILES.slice() },
+    );
+  }
+  return TIER_PROFILE_MATRIX[tier][profile];
+}
+
+module.exports = {
+  TIER_PROFILE_MATRIX,
+  MODEL_ALIAS_MAP,
+  VALID_TIERS,
+  VALID_PROFILES,
+  resolve,
+};

package/lib/model-profiles.test.cjs

@@ -0,0 +1,61 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const mp = require('./model-profiles.cjs');
+const { TIER_PROFILE_MATRIX, MODEL_ALIAS_MAP, VALID_TIERS, VALID_PROFILES, resolve } = mp;
+
+test('MP-1: TIER_PROFILE_MATRIX matches D-01 3x4 shape', () => {
+  assert.deepEqual(TIER_PROFILE_MATRIX, {
+    opus:   { quality: 'opus',   balanced: 'opus',   budget: 'sonnet', inherit: '' },
+    sonnet: { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku',  inherit: '' },
+    haiku:  { quality: 'sonnet', balanced: 'haiku',  budget: 'haiku',  inherit: '' },
+  });
+});
+
+test('MP-2: MODEL_ALIAS_MAP matches D-04 literals', () => {
+  assert.deepEqual(MODEL_ALIAS_MAP, {
+    opus:   'claude-opus-4-7',
+    sonnet: 'claude-sonnet-4-6',
+    haiku:  'claude-haiku-4-5',
+  });
+});
+
+test('MP-3: VALID_TIERS deepEquals [haiku, sonnet, opus]', () => {
+  assert.deepEqual(VALID_TIERS, ['haiku', 'sonnet', 'opus']);
+});
+
+test('MP-4: VALID_PROFILES deepEquals [quality, balanced, budget, inherit]', () => {
+  assert.deepEqual(VALID_PROFILES, ['quality', 'balanced', 'budget', 'inherit']);
+});
+
+test('MP-5: resolve() returns correct alias per matrix cell', () => {
+  assert.equal(resolve('opus', 'balanced'), 'opus');
+  assert.equal(resolve('haiku', 'budget'),  'haiku');
+  assert.equal(resolve('sonnet', 'budget'), 'haiku');
+  assert.equal(resolve('opus', 'budget'),   'sonnet');
+  assert.equal(resolve('haiku', 'quality'), 'sonnet');
+});
+
+test('MP-6: resolve() returns empty string for inherit profile (D-03)', () => {
+  assert.equal(resolve('opus', 'inherit'),   '');
+  assert.equal(resolve('haiku', 'inherit'),  '');
+  assert.equal(resolve('sonnet', 'inherit'), '');
+});
+
+test('MP-7: resolve() throws NubosPilotError(invalid-tier) on unknown tier', () => {
+  let thrown = null;
+  try { resolve('gpt-4', 'balanced'); } catch (e) { thrown = e; }
+  assert.ok(thrown);
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'invalid-tier');
+  assert.equal(thrown.details.got, 'gpt-4');
+});
+
+test('MP-8: resolve() throws NubosPilotError(invalid-profile) on unknown profile', () => {
+  let thrown = null;
+  try { resolve('opus', 'eco'); } catch (e) { thrown = e; }
+  assert.ok(thrown);
+  assert.equal(thrown.name, 'NubosPilotError');
+  assert.equal(thrown.code, 'invalid-profile');
+  assert.equal(thrown.details.got, 'eco');
+});