@bongos/core 1.17.0

package/tests/api_docs.mjs

@@ -0,0 +1,283 @@
+// tests/api_docs.mjs
+//
+// Task 1918 (BONGOS-V1) — the generated OpenAPI 3.1 contract + the pure helpers of
+// scripts/gds/gen-api-docs.js. DB-free: the generator only reads the route source.
+//
+// Pins:
+//   1. build() produces a STRUCTURALLY VALID OpenAPI 3.1 doc (built-in validator).
+//   2. the endpoint count matches the ENFORCED route auditor (route-rank-check) —
+//      the docs can't silently document more/fewer routes than the server mounts.
+//   3. the pure extractors (pathParams, commentBlockAbove, topLevelKeys, captureBalanced)
+//      behave, incl. the inline-comment case that once leaked a nested `min` key.
+//   4. the committed docs/api/openapi.json is FRESH (matches a fresh build).
+//
+// Run:  node tests/api_docs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const gen = require('../scripts/gds/gen-api-docs.js');
+const { checkRouteRanks } = require('../src/bongos/route-rank-check.js');
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const { spec, model } = gen.build();
+
+// ---- 1. structurally valid OpenAPI 3.1 -------------------------------------
+t('build() emits valid OpenAPI 3.1 (no structural problems)', () => {
+  const problems = gen.validateOpenapi(spec);
+  assert.deepEqual(problems, [], 'expected zero structural problems, got: ' + problems.join('; '));
+  assert.equal(spec.openapi, '3.1.0');
+  assert.ok(spec.info.title && spec.info.version, 'info.title + version present');
+  assert.ok(Array.isArray(spec.servers) && spec.servers.length, 'servers present');
+  assert.ok(spec.components.securitySchemes.builderSession, 'builderSession scheme defined');
+});
+
+// ---- 2. count parity with the enforced auditor -----------------------------
+t('endpoint count matches route-rank-check (no drift)', () => {
+  const audit = checkRouteRanks();
+  assert.equal(spec['x-endpoint-count'], audit.routeCount, `openapi ${spec['x-endpoint-count']} vs auditor ${audit.routeCount}`);
+  assert.equal(model.length, audit.routeCount);
+});
+
+// ---- 3. rank + security wiring ---------------------------------------------
+t('public routes carry no security; gated routes reference builderSession + x-rank', () => {
+  let sawPublic = false;
+  let sawGated = false;
+  for (const p of Object.values(spec.paths)) {
+    for (const op of Object.values(p)) {
+      assert.ok(op.responses && Object.keys(op.responses).length, 'op has responses');
+      if (op['x-rank'] === 'public') {
+        sawPublic = true;
+        assert.deepEqual(op.security, [], 'public op has empty security');
+      } else {
+        sawGated = true;
+        assert.deepEqual(op.security, [{ builderSession: [] }], 'gated op references builderSession');
+      }
+    }
+  }
+  assert.ok(sawPublic && sawGated, 'expected at least one public and one gated route');
+});
+
+// ---- 4. pure extractors ----------------------------------------------------
+t('pathParams: :id → {id} and names captured', () => {
+  const r = gen.pathParams('/tasks/:id/dependencies');
+  assert.equal(r.openapiPath, '/tasks/{id}/dependencies');
+  assert.deepEqual(r.names, ['id']);
+});
+
+t('topLevelKeys: depth-1 keys only, ignores nested min/max + inline comments', () => {
+  const lit = `{
+    title: { required: true, type: 'string', maxLength: 200 },
+    est_minutes: { type: 'integer', min: 0, max: 100000 },
+    parallel_safe: {},  // accepts true/false/null
+    goal_id: { type: 'integer', min: 1 },
+  }`;
+  assert.deepEqual(gen.topLevelKeys(lit), ['title', 'est_minutes', 'parallel_safe', 'goal_id']);
+});
+
+t('captureBalanced: balances braces, skips braces inside strings', () => {
+  const s = "x, { a: '}', b: { c: 1 } })";
+  assert.equal(gen.captureBalanced(s, 0), "{ a: '}', b: { c: 1 } }");
+});
+
+t('commentBlockAbove: contiguous // block, strips a leading rank: token', () => {
+  const lines = [
+    '  // rank: metic+archon — create work',
+    '  // second line',
+    "  router.post('/tasks', ...)",
+  ];
+  assert.equal(gen.commentBlockAbove(lines, 2), 'create work second line');
+});
+
+// ---- 4b. api-prefix chokepoint (task 1919) + versioning (task 1993 / ADR 0117)
+t('api-prefix: /api/bongos/v1 versioned, /api/bongos + /api/gds PERMANENT aliases', () => {
+  const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_API_PREFIXES } = require('../src/bongos/api-prefix.js');
+  assert.equal(API_PREFIX, '/api/bongos', 'unversioned canonical path');
+  assert.ok(LEGACY_API_PREFIXES.includes('/api/gds'), '/api/gds must stay a permanent alias (shipped binaries + cached mirror)');
+  // R06: the explicit contract version is a path segment after the prefix
+  assert.equal(API_VERSION, 'v1');
+  assert.equal(VERSIONED_API_PREFIX, '/api/bongos/v1');
+  // mount order is most-specific-first so /v1 wins over the bare prefix
+  assert.deepEqual(ALL_API_PREFIXES, ['/api/bongos/v1', '/api/bongos', '/api/gds']);
+  // the generated spec stamps the version + advertises the versioned base first
+  assert.equal(spec['x-api-version'], API_VERSION);
+  assert.equal(spec.servers[0].url, VERSIONED_API_PREFIX, 'versioned base is the first server (pin here)');
+  assert.equal(spec.servers[1].url, API_PREFIX, 'unversioned alias is the second server');
+});
+
+// ---- 5. committed spec is fresh --------------------------------------------
+t('committed docs/api/openapi.json matches a fresh build (run gen-api-docs.js if this fails)', () => {
+  const onDisk = fs.readFileSync(path.join(ROOT, 'docs/api/openapi.json'), 'utf8');
+  const fresh = JSON.stringify(spec, null, 2) + '\n';
+  assert.equal(onDisk, fresh, 'docs/api/openapi.json is STALE — run `node scripts/gds/gen-api-docs.js`');
+});
+
+// ---- 6. FIELD-LEVEL enrichment (task 2050 / ADR 0118) ----------------------
+// The extractor now parses the FULL validate() rule set (not just field names),
+// resolving named constants statically, so the spec emits typed request schemas +
+// named components.schemas + the documented error envelope.
+
+t('resolveScalar: literals, numeric separators, arithmetic, named consts, dynamic→undefined', () => {
+  assert.equal(gen.resolveScalar('true'), true);
+  assert.equal(gen.resolveScalar("'string'"), 'string');
+  assert.equal(gen.resolveScalar('64'), 64);
+  assert.equal(gen.resolveScalar('2_000_000'), 2000000, 'numeric separators');
+  assert.equal(gen.resolveScalar('30 * 1024 * 1024'), 31457280, 'pure arithmetic evaluates');
+  assert.equal(gen.resolveScalar('LIMITS.TITLE', { LIMITS: { TITLE: 200 } }), 200, 'dotted named const');
+  assert.equal(gen.resolveScalar('someFn(x)'), undefined, 'a call expression is unresolvable');
+  assert.equal(gen.resolveScalar('decision.required ?? null'), undefined, 'a dynamic expr is unresolvable');
+});
+
+t('resolveArray: literal array + named const array; all-or-nothing', () => {
+  assert.deepEqual(gen.resolveArray("['a', 'b']"), ['a', 'b']);
+  assert.deepEqual(gen.resolveArray('[-1, 0, 1]'), [-1, 0, 1], 'numeric enum');
+  assert.deepEqual(gen.resolveArray('OUTCOMES', { OUTCOMES: ['x', 'y'] }), ['x', 'y'], 'named const array');
+  assert.equal(gen.resolveArray('[a, 1]'), undefined, 'one unresolvable element drops the whole enum');
+});
+
+t('scanFileConstants: top-level literal consts (numbers, arithmetic, arrays)', () => {
+  const src = "const CAP = 30 * 1024 * 1024;\nconst BIG = 2_000_000;\nconst STATUSES = ['open', 'closed'];\nconst fn = () => {};\n";
+  const c = gen.scanFileConstants(src);
+  assert.equal(c.CAP, 31457280);
+  assert.equal(c.BIG, 2000000);
+  assert.deepEqual(c.STATUSES, ['open', 'closed']);
+});
+
+t('parseRule: resolves type/required/enum/caps; LIMITS + file-local refs', () => {
+  const consts = { LIMITS: { TITLE: 200 }, OUTCOMES: ['shipped', 'abandoned'] };
+  assert.deepEqual(gen.parseRule('{ required: true, type: \'string\', maxLength: LIMITS.TITLE }', consts),
+    { required: true, type: 'string', maxLength: 200 });
+  assert.deepEqual(gen.parseRule('{ type: \'string\', enum: OUTCOMES }', consts),
+    { type: 'string', enum: ['shipped', 'abandoned'] });
+  assert.deepEqual(gen.parseRule('{ type: \'array\', itemsType: \'integer\', maxItems: 500 }', {}),
+    { type: 'array', itemsType: 'integer', maxItems: 500 });
+  // an unresolvable bound is omitted, but the type still lands
+  assert.deepEqual(gen.parseRule('{ type: \'integer\', min: TASK_FIELD_BOUNDS.priority.min }', {}),
+    { type: 'integer' });
+});
+
+t('isIdField + ruleToSchema: pg-bigint id convention, not version_id', () => {
+  assert.equal(gen.isIdField('task_id'), true);
+  assert.equal(gen.isIdField('id'), true);
+  assert.equal(gen.isIdField('version_id'), false, 'version_id is a text slug, excluded');
+  assert.deepEqual(gen.ruleToSchema('task_id', {}), { $ref: '#/components/schemas/StringifiableId' });
+  assert.deepEqual(gen.ruleToSchema('title', { type: 'string', maxLength: 200 }), { type: 'string', maxLength: 200 });
+  assert.deepEqual(gen.ruleToSchema('priority', { type: 'integer', min: 1, max: 5 }), { type: 'integer', minimum: 1, maximum: 5 });
+  assert.deepEqual(gen.ruleToSchema('touches', { type: 'array', itemsType: 'string', maxItems: 500 }),
+    { type: 'array', items: { type: 'string' }, maxItems: 500 });
+  assert.deepEqual(gen.ruleToSchema('outcome', { type: 'string', enum: ['a', 'b'] }), { type: 'string', enum: ['a', 'b'] });
+});
+
+t('components.schemas is populated + carries the base components (was empty)', () => {
+  const s = spec.components.schemas;
+  assert.ok(Object.keys(s).length > 0, 'components.schemas > 0');
+  assert.equal(spec['x-schema-count'], Object.keys(s).length);
+  for (const base of ['ErrorEnvelope', 'ApiErrorObject', 'StringifiableId']) {
+    assert.ok(s[base], `${base} component present`);
+  }
+  assert.deepEqual(s.StringifiableId.type, ['integer', 'string'], 'stringifiable-integer id convention');
+  assert.deepEqual(s.ErrorEnvelope.required, ['error']);
+});
+
+t('a real write route: POST /claims has a typed schema, required[], id $ref (no more {})', () => {
+  const op = spec.paths['/claims'].post;
+  const ref = op.requestBody.content['application/json'].schema.$ref;
+  assert.ok(ref, 'requestBody references a named component');
+  assert.equal(op.requestBody.required, true, 'a body with a required field is marked required');
+  const schema = spec.components.schemas[ref.split('/').pop()];
+  assert.deepEqual(schema.required, ['task_id'], 'required[] propagated from the validate() rule');
+  assert.deepEqual(schema.properties.task_id, { $ref: '#/components/schemas/StringifiableId' }, 'untyped id → StringifiableId, not {}');
+  assert.equal(schema.properties.worktree_name.type, 'string');
+  assert.equal(schema.properties.worktree_name.maxLength, 200, 'LIMITS.WORKTREE_NAME resolved');
+  assert.equal(schema.additionalProperties, false, 'strict validateOrRespond → additionalProperties:false');
+});
+
+t('enum resolves from a file-local const array (CLAIM_OUTCOMES → outcome enum)', () => {
+  const op = spec.paths['/claims/{id}/resolve'].post;
+  const schema = spec.components.schemas[op.requestBody.content['application/json'].schema.$ref.split('/').pop()];
+  assert.deepEqual(schema.properties.outcome.enum, ['shipped', 'abandoned', 'partial']);
+});
+
+t('every non-2xx response $refs a shared response carrying the ErrorEnvelope; taxonomy advertised', () => {
+  const op = spec.paths['/claims'].post;
+  const shared = spec.components.responses;
+  assert.ok(shared && shared.ValidationFailed && shared.Unauthorized, 'components.responses defines the reusable errors');
+  for (const code of ['400', '401', '403']) {
+    const ref = op.responses[code] && op.responses[code].$ref;
+    assert.ok(ref && ref.startsWith('#/components/responses/'), `response ${code} $refs a shared response`);
+    const resp = shared[ref.split('/').pop()];
+    assert.equal(resp.content['application/json'].schema.$ref, '#/components/schemas/ErrorEnvelope', `${code} → ErrorEnvelope`);
+  }
+  assert.ok(spec['x-error-categories'] && spec['x-error-categories'].validation_failed, 'x-error-categories advertises the ADR-0116 taxonomy');
+});
+
+// ---- 7. RESPONSE-shape extraction (task 2061 / ADR 0124) -------------------
+// The success response body is inferred statically from the route's res.json({…})
+// literal — keys concrete, values only where trivially safe, degrade otherwise.
+
+t('responseValueSchema: boolean literal + pageMeta() typed; everything else opens to {}', () => {
+  assert.deepEqual(gen.responseValueSchema('true'), { type: 'boolean' });
+  assert.deepEqual(gen.responseValueSchema('false'), { type: 'boolean' });
+  assert.deepEqual(gen.responseValueSchema('pageMeta(limit, offset, total)'), { $ref: '#/components/schemas/PageInfo' });
+  assert.deepEqual(gen.responseValueSchema('rows'), {}, 'a variable is unknowable');
+  assert.deepEqual(gen.responseValueSchema('result || null'), {}, 'an expression is unknowable');
+});
+
+t('parseResponseObject: shorthand + key:value; spread/computed/empty → null (degrade)', () => {
+  assert.deepEqual(gen.parseResponseObject('{ tasks }'), { tasks: {} }, 'shorthand key captured');
+  assert.deepEqual(gen.parseResponseObject('{ ok: true, page: pageMeta(l, o) }'),
+    { ok: { type: 'boolean' }, page: { $ref: '#/components/schemas/PageInfo' } });
+  assert.equal(gen.parseResponseObject('{ ok: true, ...rest }'), null, 'a top-level spread degrades');
+  assert.equal(gen.parseResponseObject('{ [k]: v }'), null, 'a computed key degrades');
+  assert.equal(gen.parseResponseObject('{}'), null, 'an empty object carries no shape');
+});
+
+t('mergeResponseShapes: union keys; required = present in ALL branches; disagreement opens', () => {
+  const merged = gen.mergeResponseShapes([
+    { hit: { type: 'boolean' }, result: {} },
+    { hit: { type: 'boolean' }, result: {}, extra: {} },
+  ]);
+  assert.deepEqual(merged.properties, { hit: { type: 'boolean' }, result: {}, extra: {} });
+  assert.deepEqual(merged.required, ['hit', 'result'], 'extra is optional (only one branch)');
+  // a key whose value schema disagrees across branches opens to {} (unknown)
+  const disagree = gen.mergeResponseShapes([{ x: { type: 'boolean' } }, { x: {} }]);
+  assert.deepEqual(disagree.properties.x, {}, 'disagreeing value types open to unknown');
+});
+
+t('extractResponse: object literal → shape; bare value / error-only → null (degrade)', () => {
+  const objLit = ["router.get('/x', (req, res) => {", '  res.json({ tasks, page: pageMeta(l, o) });', '});'];
+  assert.deepEqual(gen.extractResponse(objLit, 0), { properties: { tasks: {}, page: { $ref: '#/components/schemas/PageInfo' } }, required: ['tasks', 'page'] });
+  const bare = ["router.get('/y', (req, res) => {", '  res.json(row);', '});'];
+  assert.equal(gen.extractResponse(bare, 0), null, 'a bare value is unprovable');
+  const errOnly = ["router.post('/z', (req, res) => {", "  res.status(400).json({ error: 'x' });", '});'];
+  assert.equal(gen.extractResponse(errOnly, 0), null, 'a non-2xx json is not a success shape');
+  const branches = ["router.get('/w', (req, res) => {", '  if (a) return res.json({ hit: true, result });', '  res.json({ hit: false, result: null });', '});'];
+  assert.deepEqual(gen.extractResponse(branches, 0).required, ['hit', 'result'], 'branch shapes merge');
+});
+
+t('spec: PageInfo component + x-response-schemas; a provable route 200 carries content, a bare-value route does not', () => {
+  assert.ok(spec.components.schemas.PageInfo, 'PageInfo component present');
+  assert.ok(spec['x-response-schemas'] > 0, 'some routes got a response schema');
+  // POST /claims returns res.status(201).json({ claim, task, … }) → typed 200 content
+  const claims = spec.paths['/claims'].post;
+  const ref = claims.responses['200'].content['application/json'].schema.$ref;
+  assert.ok(ref && ref.endsWith('Response'), '/claims 200 references a <…>Response component');
+  const schema = spec.components.schemas[ref.split('/').pop()];
+  assert.ok(schema.properties.claim && schema.properties.task, 'response shape carries its keys');
+  // GET /tasks/{id} returns res.json(body) (bare value) → 200 stays content-less
+  assert.equal(spec.paths['/tasks/{id}'].get.responses['200'].content, undefined, 'unprovable route has no 200 content');
+});
+
+console.log(`\napi_docs: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/api_error_envelope_buildcheck.mjs

@@ -0,0 +1,56 @@
+// tests/api_error_envelope_buildcheck.mjs
+//
+// Guard for the flat-error build check (task 1990, R03 / ADR 0116). Locks the
+// DETECTOR (what counts as a hand-rolled flat error vs the compliant envelope)
+// and the ratchet's shape. Pure + DB-free.
+//
+// Run:  node tests/api_error_envelope_buildcheck.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const F = require('../scripts/gds/fitness.js');
+
+test('detector flags hand-rolled flat errors', () => {
+  assert.equal(F.countFlatErrors(`res.status(404).json({ error: 'task_not_found' })`), 1);
+  assert.equal(F.countFlatErrors(`res.status(500).json({ error: 'x', message: err.message })`), 1);
+  assert.equal(F.countFlatErrors(`res.json({ error: code })`), 1, 'flat variable value');
+  assert.equal(F.countFlatErrors(`res.json({ error })`), 1, 'shorthand');
+  assert.equal(F.countFlatErrors(`res.json({ error, retryable: true })`), 1, 'shorthand w/ more keys');
+});
+
+test('detector does NOT flag the compliant envelope', () => {
+  assert.equal(F.countFlatErrors(`res.status(404).json({ error: { code: 'task_not_found', message: 'x' } })`), 0);
+  assert.equal(F.countFlatErrors(`res.status(404).json(envelope('task_not_found'))`), 0);
+  assert.equal(F.countFlatErrors(`res.fail('task_not_found', 404)`), 0);
+  assert.equal(F.countFlatErrors(`throw new ApiError('task_not_found')`), 0);
+  // The detector keys on `error` as the FIRST key of the body — the real
+  // hand-rolled-error shape. A stray `error` as a later key is not an error
+  // emission and is not flagged.
+  assert.equal(F.countFlatErrors(`res.json({ ok: true, error: null })`), 0, 'error as a non-first key is not the anti-pattern');
+});
+
+test('detector ignores non-error json bodies', () => {
+  assert.equal(F.countFlatErrors(`res.json({ tasks: [], total: 0 })`), 0);
+  assert.equal(F.countFlatErrors(`res.json({ data: { error: 'nested-not-first-key' } })`), 0);
+});
+
+test('the surface is swept clean and the gate is hard-zero (R04 landed)', () => {
+  const { total, byFile } = F.scanFlatErrorSites();
+  assert.equal(F.FLAT_ERROR_BASELINE, 0, 'baseline is hard-zero after the sweep');
+  assert.equal(total, 0, `no hand-rolled flat errors remain (found: ${JSON.stringify(byFile)})`);
+  assert.ok(total <= F.FLAT_ERROR_BASELINE, 'at/below the baseline');
+});
+
+test('detector ignores a doc-comment example of the anti-pattern', () => {
+  assert.equal(F.countFlatErrors(`// res.status(n).json({error:'x'}) is the OLD way`), 0);
+  assert.equal(F.countFlatErrors(`/* e.g. res.status(404).json({ error: 'nope' }) */`), 0);
+  assert.equal(F.countFlatErrors(`const s = "res.status(1).json({error:'y'})"; // string, not code`), 0);
+});
+
+test('the check passes at the baseline and is wired into runAll', () => {
+  const r = F.checkErrorEnvelope();
+  assert.equal(r.hardFail, false);
+  assert.ok(F.runAll().some((x) => x.name === r.name), 'registered in CHECKS');
+});

package/tests/api_error_envelope_middleware.mjs

@@ -0,0 +1,99 @@
+// tests/api_error_envelope_middleware.mjs
+//
+// Guard for the central error contract (task 1989, R02): the res.fail decorator
+// and the trailing errorEnvelopeHandler. Pure + DB-free — fakes req/res.
+//
+// Run:  node tests/api_error_envelope_middleware.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { attachFail, errorEnvelopeHandler } = require('../src/bongos/middleware/error-envelope.js');
+const { ApiError } = require('../src/bongos/api-errors.js');
+
+function fakeRes() {
+  return {
+    statusCode: 200,
+    headersSent: false,
+    body: undefined,
+    status(n) { this.statusCode = n; return this; },
+    json(b) { this.body = b; this.headersSent = true; return this; },
+  };
+}
+
+test('attachFail: res.fail(code) uses the registry status + code', () => {
+  const res = fakeRes();
+  let nexted = false;
+  attachFail({}, res, () => { nexted = true; });
+  assert.ok(nexted, 'calls next');
+  res.fail('task_not_found');
+  assert.equal(res.statusCode, 404);
+  assert.deepEqual(res.body, { error: { code: 'task_not_found', message: 'task_not_found' } });
+});
+
+test('attachFail: explicit status wins; details flow through', () => {
+  const res = fakeRes();
+  attachFail({}, res, () => {});
+  res.fail('validation_failed', 400, [{ field: 'title', reason: 'missing' }]);
+  assert.equal(res.statusCode, 400);
+  assert.deepEqual(res.body.error.details, [{ field: 'title', reason: 'missing' }]);
+});
+
+test('attachFail: object form { status, message, details }', () => {
+  const res = fakeRes();
+  attachFail({}, res, () => {});
+  res.fail('conflict_special', { status: 409, message: 'already there', details: { x: 1 } });
+  assert.equal(res.statusCode, 409);
+  assert.equal(res.body.error.message, 'already there');
+  assert.deepEqual(res.body.error.details, { x: 1 });
+});
+
+test('attachFail: does not write once headers are sent', () => {
+  const res = fakeRes();
+  attachFail({}, res, () => {});
+  res.headersSent = true;
+  const ret = res.fail('task_not_found');
+  assert.equal(res.body, undefined, 'no double-send');
+  assert.equal(ret, res);
+});
+
+test('errorEnvelopeHandler: an ApiError formats to its status + envelope', () => {
+  const res = fakeRes();
+  errorEnvelopeHandler(new ApiError('goal_not_found'), { method: 'GET', originalUrl: '/x' }, res, () => {});
+  assert.equal(res.statusCode, 404);
+  assert.deepEqual(res.body, { error: { code: 'goal_not_found', message: 'goal_not_found' } });
+});
+
+test('errorEnvelopeHandler: malformed JSON → bad_json 400', () => {
+  const res = fakeRes();
+  const err = new SyntaxError('Unexpected token');
+  err.type = 'entity.parse.failed';
+  errorEnvelopeHandler(err, { method: 'POST', originalUrl: '/tasks' }, res, () => {});
+  assert.equal(res.statusCode, 400);
+  assert.equal(res.body.error.code, 'bad_json');
+});
+
+test('errorEnvelopeHandler: oversized body → payload_too_large 413', () => {
+  const res = fakeRes();
+  const err = new Error('too big'); err.type = 'entity.too.large';
+  errorEnvelopeHandler(err, { method: 'POST', originalUrl: '/tasks' }, res, () => {});
+  assert.equal(res.statusCode, 413);
+  assert.equal(res.body.error.code, 'payload_too_large');
+});
+
+test('errorEnvelopeHandler: unknown error → leak-free internal 500', () => {
+  const res = fakeRes();
+  errorEnvelopeHandler(new Error('db password = hunter2'), { method: 'GET', originalUrl: '/x' }, res, () => {});
+  assert.equal(res.statusCode, 500);
+  assert.equal(res.body.error.code, 'internal_error');
+  assert.ok(!/hunter2/.test(JSON.stringify(res.body)), 'raw message must not leak');
+});
+
+test('errorEnvelopeHandler: headers already sent → delegates to next(err)', () => {
+  const res = fakeRes();
+  res.headersSent = true;
+  let passed = null;
+  errorEnvelopeHandler(new ApiError('x'), {}, res, (e) => { passed = e; });
+  assert.ok(passed instanceof Error, 'delegates to Express default finisher');
+});

package/tests/api_error_registry.mjs

@@ -0,0 +1,108 @@
+// tests/api_error_registry.mjs
+//
+// Contract guard for the API error registry (task 1988, R01 — the error-envelope
+// contract). Locks the envelope SHAPE, the code→category→status classification,
+// and the `ApiError` carrier so R02's middleware + R04's sweep build on a stable
+// base. Pure + DB-free — runs in the unit gate.
+//
+// Run:  node tests/api_error_registry.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const E = require('../src/bongos/api-errors.js');
+
+test('envelope has the documented { error: { code, message } } shape', () => {
+  const env = E.envelope('task_not_found', 'no such task');
+  assert.deepEqual(env, { error: { code: 'task_not_found', message: 'no such task' } });
+  assert.equal(env.error.details, undefined, 'details omitted when not given');
+});
+
+test('envelope carries structured details when provided', () => {
+  const env = E.envelope('validation_failed', 'bad', [{ field: 'title', reason: 'missing' }]);
+  assert.deepEqual(env.error.details, [{ field: 'title', reason: 'missing' }]);
+});
+
+test('envelope defaults message to the code', () => {
+  assert.equal(E.envelope('bad_id').error.message, 'bad_id');
+});
+
+test('classify: explicit overrides win over the heuristic', () => {
+  assert.equal(E.classify('self_dep'), 'conflict');       // ends _dep, would else fall through to internal
+  assert.equal(E.classify('rank_forbidden'), 'forbidden');
+  assert.equal(E.classify('unauthenticated'), 'unauthenticated');
+  assert.equal(E.classify('no_active_claim'), 'conflict'); // precondition, not not_found
+  assert.equal(E.classify('grading_unavailable'), 'unavailable');
+});
+
+test('classify: suffix/prefix heuristic for the long tail', () => {
+  assert.equal(E.classify('list_failed'), 'internal');
+  assert.equal(E.classify('patch_failed'), 'internal');
+  assert.equal(E.classify('task_not_found'), 'not_found');
+  assert.equal(E.classify('goal_not_found'), 'not_found');
+  assert.equal(E.classify('bad_builder_id'), 'bad_request');
+  assert.equal(E.classify('invalid_patch'), 'bad_request');
+  assert.equal(E.classify('title_required'), 'bad_request');
+  assert.equal(E.classify('already_member'), 'conflict');
+  assert.equal(E.classify('slug_taken'), 'conflict');
+  assert.equal(E.classify('push_unconfigured'), 'unavailable');
+});
+
+test('classify: unknown code falls back to internal (safe default), never throws', () => {
+  assert.equal(E.classify('some_brand_new_code_2099'), 'internal');
+  assert.equal(E.classify(''), 'internal');
+  assert.equal(E.classify(undefined), 'internal');
+  assert.equal(E.classify(42), 'internal');
+});
+
+test('statusForCode: category default, with explicit override winning', () => {
+  assert.equal(E.statusForCode('task_not_found'), 404);
+  assert.equal(E.statusForCode('rank_forbidden'), 403);
+  assert.equal(E.statusForCode('rate_limited'), 429);
+  assert.equal(E.statusForCode('list_failed'), 500);
+  assert.equal(E.statusForCode('bad_request'), 400);
+  assert.equal(E.statusForCode('validation_failed', 422), 422, 'a site keeping 422 wins over the 400 default');
+});
+
+test('every category maps to a real HTTP status + retriable flag', () => {
+  for (const [name, c] of Object.entries(E.CATEGORIES)) {
+    assert.ok(Number.isInteger(c.status) && c.status >= 400 && c.status <= 599, `${name} status`);
+    assert.equal(typeof c.retriable, 'boolean', `${name} retriable`);
+    assert.ok(c.description && c.description.length > 0, `${name} description`);
+  }
+  // retriable is a client contract: rate_limited/internal/unavailable are; 4xx client errors are not.
+  assert.equal(E.isRetriable('rate_limited'), true);
+  assert.equal(E.isRetriable('list_failed'), true);
+  assert.equal(E.isRetriable('bad_id'), false);
+});
+
+test('every OVERRIDE points at a defined category', () => {
+  for (const [code, cat] of Object.entries(E.OVERRIDES)) {
+    assert.ok(E.CATEGORIES[cat], `override ${code} -> unknown category ${cat}`);
+  }
+});
+
+test('ApiError carries code, derived status + category, and formats to the envelope', () => {
+  const err = new E.ApiError('task_not_found');
+  assert.equal(err.status, 404);
+  assert.equal(err.category, 'not_found');
+  assert.equal(err.code, 'task_not_found');
+  assert.ok(err instanceof Error);
+  assert.equal(E.isApiError(err), true);
+  assert.deepEqual(E.envelope(err), { error: { code: 'task_not_found', message: 'task_not_found' } });
+
+  const withDetails = new E.ApiError('validation_failed', { message: 'bad', details: [{ field: 'x' }], status: 400 });
+  assert.deepEqual(E.envelope(withDetails), { error: { code: 'validation_failed', message: 'bad', details: [{ field: 'x' }] } });
+});
+
+test('ApiError honours an explicit status override', () => {
+  const err = new E.ApiError('task_conflict_special', { status: 409 });
+  assert.equal(err.status, 409);
+});
+
+test('envelope never leaks a raw thrown value', () => {
+  const env = E.envelope(new Error('secret internal detail: db password = hunter2'));
+  assert.equal(env.error.code, 'internal_error');
+  assert.ok(!/hunter2/.test(JSON.stringify(env)), 'raw message must not leak');
+});

package/tests/api_pagination_contract.mjs

@@ -0,0 +1,51 @@
+// tests/api_pagination_contract.mjs
+//
+// Contract guard for the pagination helper (task 2000, R13 / ADR 0119): the ONE
+// limit/offset convention. Pure + DB-free.
+//
+// Run:  node tests/api_pagination_contract.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { parsePagination, pageMeta, PAGINATION } = require('../src/bongos/routes/_helpers.js');
+
+const q = (query) => ({ query });
+
+test('defaults when limit/offset absent', () => {
+  assert.deepEqual(parsePagination(q({})), { limit: PAGINATION.DEFAULT_LIMIT, offset: 0 });
+  assert.deepEqual(parsePagination({}), { limit: PAGINATION.DEFAULT_LIMIT, offset: 0 });
+});
+
+test('parses valid limit + offset', () => {
+  assert.deepEqual(parsePagination(q({ limit: '25', offset: '100' })), { limit: 25, offset: 100 });
+});
+
+test('clamps limit to MAX_LIMIT (no unbounded list)', () => {
+  assert.deepEqual(parsePagination(q({ limit: '99999' })), { limit: PAGINATION.MAX_LIMIT, offset: 0 });
+  assert.deepEqual(parsePagination(q({ limit: '9999' }), { maxLimit: 10 }), { limit: 10, offset: 0 });
+});
+
+test('bad/zero/negative limit falls back to default (clamp, never reject)', () => {
+  for (const bad of ['0', '-5', 'abc', '', '1.5']) {
+    const r = parsePagination(q({ limit: bad }));
+    assert.equal(r.limit, bad === '1.5' ? 1 : PAGINATION.DEFAULT_LIMIT, `limit=${bad}`);
+  }
+});
+
+test('negative/bad offset clamps to 0', () => {
+  assert.equal(parsePagination(q({ offset: '-3' })).offset, 0);
+  assert.equal(parsePagination(q({ offset: 'nope' })).offset, 0);
+  assert.equal(parsePagination(q({ offset: '7' })).offset, 7);
+});
+
+test('custom defaultLimit honoured', () => {
+  assert.equal(parsePagination(q({}), { defaultLimit: 10 }).limit, 10);
+});
+
+test('pageMeta shapes the response page block; total optional', () => {
+  assert.deepEqual(pageMeta(50, 0), { limit: 50, offset: 0 });
+  assert.deepEqual(pageMeta(50, 100, 512), { limit: 50, offset: 100, total: 512 });
+  assert.equal(pageMeta(50, 0, undefined).total, undefined);
+});