@bongos/core 1.17.0

package/modules/builder-settings/event-sound-prefs.js

@@ -0,0 +1,169 @@
+'use strict';
+// src/bongos/event-sound-prefs.js — per-builder per-event sound variant selection
+// (task 582). Extends the mute-toggle system (sound-prefs.js) with variant
+// picking: for each of 5 build events a builder can choose which world-themed
+// sound variant plays. Each variant maps to an EXISTING .wav in .claude/sounds/;
+// the dedicated world-themed audio assets (lyre-pluck.wav etc.) ship separately.
+
+// 5 build events, ordered for the UI. Each has a world-themed default variant
+// plus alternates. `wav` is the existing .claude/sounds/<name>.wav that backs
+// the variant until dedicated audio ships.
+const EVENTS = Object.freeze([
+  {
+    id:    'user-input',
+    label: 'Awaiting Thy Counsel',
+    desc:  'Claude has paused and needs thy response',
+    variants: [
+      { id: 'lyre-pluck',  label: 'Lyre Pluck',  wav: 'alert', isDefault: true },
+      { id: 'chime-soft',  label: 'Chime Soft',  wav: 'chime' },
+    ],
+  },
+  {
+    id:    'task-shipped',
+    label: 'Task Shipped',
+    desc:  'A task has been confirmed and merged',
+    variants: [
+      { id: 'bronze-fanfare', label: 'Bronze Fanfare', wav: 'ship',    isDefault: true },
+      { id: 'triumph-call',   label: 'Triumph Call',   wav: 'triumph' },
+    ],
+  },
+  {
+    id:    'credits-awarded',
+    label: 'Drachmae Awarded',
+    desc:  'Drachmae have been credited to thy treasury',
+    variants: [
+      { id: 'coin-clink',   label: 'Coin Clink',   wav: 'chime', isDefault: true },
+      { id: 'herald-short', label: 'Herald Short', wav: 'alert' },
+    ],
+  },
+  {
+    id:    'rank-promoted',
+    label: 'Rank Promotion',
+    desc:  'Thou hast advanced to a new rank',
+    variants: [
+      { id: 'herald-call',   label: 'Herald Call',   wav: 'fanfare', isDefault: true },
+      { id: 'grand-fanfare', label: 'Grand Fanfare', wav: 'triumph' },
+    ],
+  },
+  {
+    id:    'achievement',
+    label: 'Achievement Unlocked',
+    desc:  'A badge or milestone has been earned',
+    variants: [
+      { id: 'harp-flourish',  label: 'Harp Flourish',  wav: 'triumph', isDefault: true },
+      { id: 'brass-flourish', label: 'Brass Flourish', wav: 'fanfare' },
+    ],
+  },
+]);
+
+// flat: variantId → wav file name
+const VARIANT_WAV = Object.freeze(
+  Object.fromEntries(EVENTS.flatMap(e => e.variants.map(v => [v.id, v.wav])))
+);
+
+// flat: eventId → default variant id
+const EVENT_DEFAULT = Object.freeze(
+  Object.fromEntries(
+    EVENTS.map(e => [e.id, e.variants.find(v => v.isDefault)?.id ?? e.variants[0].id])
+  )
+);
+
+// Sets for fast membership checks
+const KNOWN_EVENT_IDS   = Object.freeze(new Set(EVENTS.map(e => e.id)));
+const KNOWN_VARIANT_IDS = Object.freeze(new Set(EVENTS.flatMap(e => e.variants.map(v => v.id))));
+
+// Map: eventId → Set of valid variant ids for that event
+const EVENT_VARIANTS = Object.freeze(
+  Object.fromEntries(EVENTS.map(e => [e.id, new Set(e.variants.map(v => v.id))]))
+);
+
+function resolveVariant(eventId, builderPrefs) {
+  const stored = builderPrefs && builderPrefs[eventId];
+  if (typeof stored === 'string' && KNOWN_VARIANT_IDS.has(stored)) return stored;
+  return EVENT_DEFAULT[eventId];
+}
+
+function resolveWav(eventId, builderPrefs) {
+  return VARIANT_WAV[resolveVariant(eventId, builderPrefs)] ?? 'chime';
+}
+
+// Full list for the API/UI — every event with variants, current selection,
+// and the resolved wav file name.
+function listEffective(builderPrefs) {
+  return EVENTS.map(event => ({
+    event:    event.id,
+    label:    event.label,
+    desc:     event.desc,
+    variants: event.variants.map(v => ({
+      id:        v.id,
+      label:     v.label,
+      wav:       v.wav,
+      is_default: !!v.isDefault,
+    })),
+    selected: resolveVariant(event.id, builderPrefs),
+    wav:      resolveWav(event.id, builderPrefs),
+  }));
+}
+
+// Compact event→wav map written to the local prefs file so the offline hook
+// can play the right sound without a network call.
+function effectiveWavMap(builderPrefs) {
+  const out = {};
+  for (const e of EVENTS) out[e.id] = resolveWav(e.id, builderPrefs);
+  return out;
+}
+
+// Validate a PATCH body: { <eventId>: <variantId|null>, ... }
+// null = clear override → fall back to default.
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  }
+  const errors = [];
+  const patch = {};
+  for (const [eventId, variantId] of Object.entries(body)) {
+    if (!KNOWN_EVENT_IDS.has(eventId)) {
+      errors.push({ event: eventId, error: 'unknown_event' });
+      continue;
+    }
+    if (variantId === null) {
+      patch[eventId] = null;
+      continue;
+    }
+    if (typeof variantId !== 'string') {
+      errors.push({ event: eventId, variant: variantId, error: 'variant_must_be_string_or_null' });
+      continue;
+    }
+    if (!EVENT_VARIANTS[eventId].has(variantId)) {
+      errors.push({ event: eventId, variant: variantId, error: 'variant_not_for_event' });
+      continue;
+    }
+    patch[eventId] = variantId;
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, patch };
+}
+
+function applyPatch(existing, patch) {
+  const next = { ...(existing || {}) };
+  for (const [eventId, variantId] of Object.entries(patch)) {
+    if (variantId === null) delete next[eventId];
+    else next[eventId] = variantId;
+  }
+  return next;
+}
+
+module.exports = {
+  EVENTS,
+  VARIANT_WAV,
+  EVENT_DEFAULT,
+  KNOWN_EVENT_IDS,
+  KNOWN_VARIANT_IDS,
+  EVENT_VARIANTS,
+  resolveVariant,
+  resolveWav,
+  listEffective,
+  effectiveWavMap,
+  validatePatch,
+  applyPatch,
+};

package/modules/builder-settings/interaction-prefs.js

@@ -0,0 +1,201 @@
+// modules/builder-settings/interaction-prefs.js — the per-builder INTERACTION
+// PROFILE (task 2010 / BONGOS-V1).
+//
+// Principle (2026-07-04 review, bullets 85/87/92): there is NO special "owner"
+// entity — an owner is just a builder with elevated permissions + a profile. So
+// "how to work with me" (the old CLAUDE.md §2 "The Prompter" defaults) is NOT
+// portable-core prose; it's a PER-BUILDER profile — tone, technical level, and
+// local-toolchain familiarity — captured at onboarding and injected each
+// session, exactly like the `wandering` knob (wandering-prefs.js is the sibling
+// this mirrors). CLAUDE.md keeps only the PORTABLE DEFAULTS as the fallback.
+//
+// Storage. One reserved key ('interaction') inside the `behavior_prefs` jsonb
+// (migration 119, shared with wandering/sound). Its value is a small object of
+// field → chosen value; unset/invalid fields fall back to the field default.
+//
+// The defaults below are the portable §2 defaults verbatim: assume the reader
+// may not be a software engineer, define jargon on first use, treat local
+// toolchains as new, frame trade-offs as cost/time/what-the-user-sees, be
+// concise. An engineer builder overrides to a more technical profile; the
+// injected contract then tells the agent how to pitch its replies for THAT
+// builder.
+
+const RESERVED_KEY = 'interaction';
+
+// Each field: allowed values (first = default), a short label per value, and a
+// one-line contract fragment injected when the value is NON-default (the default
+// already matches the portable baseline, so injecting it would be noise —
+// mirrors wandering's `inject` idea).
+const FIELDS = {
+  technical_level: {
+    label: 'Technical level',
+    blurb: 'How much software-engineering vocabulary to assume.',
+    values: {
+      non_technical: {
+        label: 'Non-technical (default)',
+        // default — matches the portable baseline; not injected.
+        contract: '',
+      },
+      mixed: {
+        label: 'Some technical background',
+        contract: 'Technical level: mixed — plain language by default, but light SWE vocabulary is fine without defining every term.',
+      },
+      engineer: {
+        label: 'Engineer',
+        contract: 'Technical level: engineer — assume software-engineering fluency; skip basic explanations and speak in code/architecture terms.',
+      },
+    },
+  },
+  toolchain_familiarity: {
+    label: 'Local-toolchain familiarity',
+    blurb: 'Whether local dev tools (package managers, ports, env vars) need step-by-step help.',
+    values: {
+      new: {
+        label: 'New to local tooling (default)',
+        contract: '',
+      },
+      comfortable: {
+        label: 'Comfortable with local tooling',
+        contract: 'Toolchain familiarity: comfortable — no need to walk through local toolchains (Homebrew, ports, env vars) step by step.',
+      },
+    },
+  },
+  verbosity: {
+    label: 'Reply length',
+    blurb: 'How much prose to return by default.',
+    values: {
+      concise: {
+        label: 'Concise (default)',
+        contract: '',
+      },
+      detailed: {
+        label: 'Detailed',
+        contract: 'Verbosity: detailed — this builder wants fuller explanations and context, not just the short answer.',
+      },
+    },
+  },
+};
+
+const FIELD_KEYS = Object.keys(FIELDS);
+
+// The default value for a field is its FIRST declared value.
+function defaultValue(field) {
+  return Object.keys(FIELDS[field].values)[0];
+}
+
+function isValidValue(field, value) {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(FIELDS[field].values, value);
+}
+
+// The raw stored profile (the `interaction` object off behavior_prefs), sanitized
+// to only known fields/values. Unknown keys/values are dropped (not an error —
+// the effective profile falls back to defaults).
+function storedProfile(behaviorPrefs) {
+  const raw = (behaviorPrefs && typeof behaviorPrefs[RESERVED_KEY] === 'object' && behaviorPrefs[RESERVED_KEY]) || {};
+  const out = {};
+  for (const f of FIELD_KEYS) {
+    if (isValidValue(f, raw[f])) out[f] = raw[f];
+  }
+  return out;
+}
+
+// The effective profile: stored override per field, else the field default.
+function effectiveProfile(behaviorPrefs) {
+  const stored = storedProfile(behaviorPrefs);
+  const out = {};
+  for (const f of FIELD_KEYS) out[f] = stored[f] || defaultValue(f);
+  return out;
+}
+
+// The session-injected contract: the non-default fragments joined into one
+// paragraph. Empty string when the builder is on all defaults (the portable
+// baseline already covers that — nothing to inject).
+function contractFor(behaviorPrefs) {
+  const eff = effectiveProfile(behaviorPrefs);
+  const parts = [];
+  for (const f of FIELD_KEYS) {
+    const frag = FIELDS[f].values[eff[f]].contract;
+    if (frag) parts.push(frag);
+  }
+  if (!parts.length) return '';
+  return 'Interaction profile for this builder — pitch replies accordingly:\n- ' + parts.join('\n- ');
+}
+
+function shouldInject(behaviorPrefs) {
+  return contractFor(behaviorPrefs) !== '';
+}
+
+// The full catalog the /settings UI renders.
+function fieldCatalog() {
+  return FIELD_KEYS.map((f) => ({
+    field: f,
+    label: FIELDS[f].label,
+    blurb: FIELDS[f].blurb,
+    default_value: defaultValue(f),
+    values: Object.entries(FIELDS[f].values).map(([value, meta]) => ({ value, label: meta.label })),
+  }));
+}
+
+// Everything the /me payload + the /settings UI need in one object.
+function describeForApi(behaviorPrefs) {
+  return {
+    fields: fieldCatalog(),
+    stored: storedProfile(behaviorPrefs),
+    effective: effectiveProfile(behaviorPrefs),
+    contract: contractFor(behaviorPrefs),
+    inject: shouldInject(behaviorPrefs),
+  };
+}
+
+// Validate a PATCH body: { <field>: <value> | null }. `null` clears a field
+// (fall back to its default). Unknown fields/values → 422. Returns
+// { ok, patch } or { ok:false, errors }. The route merges `patch` into the
+// stored `interaction` object.
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  }
+  const errors = [];
+  const patch = {};
+  for (const [key, value] of Object.entries(body)) {
+    if (!FIELD_KEYS.includes(key)) {
+      errors.push({ error: 'unknown_field', field: key });
+      continue;
+    }
+    if (value === null) { patch[key] = null; continue; }
+    if (!isValidValue(key, value)) {
+      errors.push({ error: 'bad_value', field: key, allowed: Object.keys(FIELDS[key].values) });
+      continue;
+    }
+    patch[key] = value;
+  }
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, patch };
+}
+
+// Merge a validated patch into an existing stored profile (null clears). Pure —
+// the route persists the result into behavior_prefs.interaction.
+function applyPatch(stored, patch) {
+  const next = { ...(stored || {}) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete next[k];
+    else next[k] = v;
+  }
+  return next;
+}
+
+module.exports = {
+  RESERVED_KEY,
+  FIELDS,
+  FIELD_KEYS,
+  defaultValue,
+  isValidValue,
+  storedProfile,
+  effectiveProfile,
+  contractFor,
+  shouldInject,
+  fieldCatalog,
+  describeForApi,
+  validatePatch,
+  applyPatch,
+};

package/modules/builder-settings/model-alloc-prefs.js

@@ -0,0 +1,147 @@
+// modules/builder-settings/model-alloc-prefs.js — per-builder / per-instance
+// MODEL ALLOCATION (task 2011 / BONGOS-V1).
+//
+// The subagent model-routing policy (main session = top tier; subagents default
+// to the development tier, routine plumbing to the cheap tier; "no Sonnet") was
+// a hardcoded TABLE in CLAUDE.md §2 — it rots as model names change and is the
+// same class of leak as the reward formula (task 2009). This makes the tier
+// VALUES settings-driven: an INSTANCE default (`config/branding.json` `models`)
+// with an optional PER-BUILDER override (behavior_prefs `model_allocation`),
+// resolved over the code defaults. §2 keeps only the stable SHAPE + rationale
+// and points here; changing a tier no longer needs a doc edit.
+//
+// PURE lib (the wandering/interaction-prefs pattern): it takes the instance
+// default as a param (the route reads `branding().models` via the doorway and
+// passes it), so it stays testable with no global-config read.
+
+const RESERVED_KEY = 'model_allocation';
+
+// Tier vocabulary — mirrors skill-prefs.ALLOWED_MODELS (minus 'script', which is
+// a per-skill escape hatch, not a session tier). Ordered cheap→capable for UIs.
+const ALLOWED_TIERS = Object.freeze(['haiku', 'sonnet', 'opus', 'fable']);
+
+// The allocation slots + their code defaults (the current §2 policy verbatim):
+// the main interactive session runs top-tier; subagents default to the
+// development tier; routine plumbing (known-path GDS/DB reads) drops to cheap.
+const SLOTS = Object.freeze({
+  main: { label: 'Main interactive session', default: 'opus', blurb: 'The session the builder sits in front of.' },
+  subagentDefault: { label: 'Subagents (default)', default: 'opus', blurb: 'Research, audits, code review, design, code that ships, parallel build sessions.' },
+  subagentRoutine: { label: 'Subagents (routine plumbing)', default: 'haiku', blurb: 'Mechanical known-path GDS/DB ops: list, fetch-by-id, log a cost row, read a known file.' },
+});
+
+const SLOT_KEYS = Object.keys(SLOTS);
+
+function isValidTier(t) {
+  return typeof t === 'string' && ALLOWED_TIERS.includes(t);
+}
+
+// Sanitize a raw slot→tier map to known slots + valid tiers.
+function sanitize(raw) {
+  const out = {};
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    for (const k of SLOT_KEYS) if (isValidTier(raw[k])) out[k] = raw[k];
+  }
+  return out;
+}
+
+function codeDefaults() {
+  const out = {};
+  for (const k of SLOT_KEYS) out[k] = SLOTS[k].default;
+  return out;
+}
+
+// The builder's stored override (behavior_prefs.model_allocation), sanitized.
+function storedOverride(behaviorPrefs) {
+  return sanitize(behaviorPrefs && behaviorPrefs[RESERVED_KEY]);
+}
+
+// The instance default (branding.models), sanitized. Passed in by the route.
+function instanceDefault(instanceModels) {
+  return sanitize(instanceModels);
+}
+
+// Effective allocation: builder override → instance default → code default,
+// per slot. This is what the agent consults when spawning subagents.
+function effectiveAllocation(behaviorPrefs, instanceModels) {
+  const override = storedOverride(behaviorPrefs);
+  const inst = instanceDefault(instanceModels);
+  const code = codeDefaults();
+  const out = {};
+  for (const k of SLOT_KEYS) out[k] = override[k] || inst[k] || code[k];
+  return out;
+}
+
+// A compact human/agent-facing guidance line for the effective allocation.
+function contractFor(behaviorPrefs, instanceModels) {
+  const eff = effectiveAllocation(behaviorPrefs, instanceModels);
+  return `Model allocation — main session: ${eff.main}; subagents default: ${eff.subagentDefault}, routine plumbing: ${eff.subagentRoutine}. Set the Agent \`model\` param explicitly per this allocation.`;
+}
+
+// The catalog the /settings UI renders.
+function slotCatalog() {
+  return SLOT_KEYS.map((k) => ({
+    slot: k,
+    label: SLOTS[k].label,
+    blurb: SLOTS[k].blurb,
+    code_default: SLOTS[k].default,
+    tiers: ALLOWED_TIERS.slice(),
+  }));
+}
+
+// Everything /me + /settings need in one object.
+function describeForApi(behaviorPrefs, instanceModels) {
+  return {
+    slots: slotCatalog(),
+    allowed_tiers: ALLOWED_TIERS.slice(),
+    code_defaults: codeDefaults(),
+    instance_default: instanceDefault(instanceModels),
+    override: storedOverride(behaviorPrefs),
+    effective: effectiveAllocation(behaviorPrefs, instanceModels),
+    contract: contractFor(behaviorPrefs, instanceModels),
+  };
+}
+
+// Validate a PATCH body: { <slot>: <tier> | null }. null clears the override for
+// that slot (fall back to instance/code default). Unknown slot / bad tier → 422.
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  }
+  const errors = [];
+  const patch = {};
+  for (const [key, value] of Object.entries(body)) {
+    if (!SLOT_KEYS.includes(key)) { errors.push({ error: 'unknown_slot', slot: key }); continue; }
+    if (value === null) { patch[key] = null; continue; }
+    if (!isValidTier(value)) { errors.push({ error: 'bad_tier', slot: key, allowed: ALLOWED_TIERS }); continue; }
+    patch[key] = value;
+  }
+  if (errors.length) return { ok: false, errors };
+  return { ok: true, patch };
+}
+
+// Merge a validated patch into the stored override (null clears). Pure.
+function applyPatch(stored, patch) {
+  const next = { ...(stored || {}) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete next[k];
+    else next[k] = v;
+  }
+  return next;
+}
+
+module.exports = {
+  RESERVED_KEY,
+  ALLOWED_TIERS,
+  SLOTS,
+  SLOT_KEYS,
+  isValidTier,
+  codeDefaults,
+  storedOverride,
+  instanceDefault,
+  effectiveAllocation,
+  contractFor,
+  slotCatalog,
+  describeForApi,
+  validatePatch,
+  applyPatch,
+};

package/modules/builder-settings/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "builder-settings",
+  "title": "Builder settings (prefs · needs)",
+  "description": "The per-builder PREFERENCE domain — the wandering knob (how readily the agent opens off-task threads, rank-clamped), per-skill model ceilings, per-sound + per-event-sound on/off, and the render-widgets toggle — plus builder-needs (the 'the system needs an input from you' list). A core-domain module carved out of the GDS core in BV1.R80 (ADR 0093 §1); default-on because every instance configures its own builders. The `/me/*-prefs` routes mount here; the `GET /me` aggregator stays a thin core facade that resolves the `builder-settings` kernel PORT for its wandering/render/needs slices (02-module-map §2).",
+  "coreVersion": "^1.8.0",
+  "default": true,
+  "contributes": { "routes": ["settings"] },
+  "provides": ["builder-settings"],
+  "consumes": []
+}

package/modules/builder-settings/render-prefs.js

@@ -0,0 +1,103 @@
+// src/bongos/render-prefs.js — the per-builder "render widgets" knob (task 1279).
+//
+// Governs whether the deterministic session cards (start.js's /builder-start
+// card + the ship-card lifecycle card: claimed → review → confirmed → shipped)
+// render as a rich in-feed HTML widget (via the app's show_widget tool) or as
+// the plain markdown / monospace fallback.
+//
+// Why it's a knob: the widget is nicer, but the agent must relay its full markup
+// VERBATIM into show_widget — reading it once and re-emitting it once — so every
+// byte of HTML is shuttled through the model twice, at every session-start,
+// claim, and ship stage. Measured: the /builder-start widget is ~4.7K tokens vs
+// ~0.5K for the markdown form (9×); the lifecycle card ~0.9K vs ~0.12K monospace
+// (7×). This knob lets a builder turn that token cost off. When off, the CLIs
+// emit ONLY the text form (no HTML is ever written or relayed) — so it's a real
+// saving, not just a visual change.
+//
+// Unlike the wandering knob ([[wandering-prefs]]) this is pure cost/taste, NOT a
+// trust gate — so there is NO rank cap: any builder may pick either value, and
+// the default is ON (the experience tasks 1273/1275 deliberately shipped).
+//
+// Storage: one reserved key ('widgets') inside the `behavior_prefs` jsonb column
+// on `builders` (migration 119 — the same blob the wandering knob uses). Value
+// is a scalar boolean; a missing key falls back to DEFAULT_ENABLED, so the
+// column stays sparse. applyPatch leaves sibling keys (e.g. 'wandering') alone.
+//
+// This module is the single source of truth: GET/PATCH /api/gds/me/render + the
+// /me payload surface it, the /settings UI reads it, and the start/claim/ship
+// CLIs read the resolved boolean to decide whether to emit HTML at all.
+
+const RESERVED_KEY = 'widgets';
+const DEFAULT_ENABLED = true;
+
+// ---- pure helpers ----
+
+// The raw override a builder has stored (the 'widgets' key off behavior_prefs),
+// or null when unset/invalid. Kept separate from the effective value so the UI
+// can show "you chose X" vs "the default (Y)".
+function overrideEnabled(behaviorPrefs) {
+  const raw = behaviorPrefs && behaviorPrefs[RESERVED_KEY];
+  return typeof raw === 'boolean' ? raw : null;
+}
+
+// The resolved boolean — the value the CLIs act on. Override if set, else the
+// default. This is the one function the start/claim/ship scripts care about.
+function widgetsEnabled(behaviorPrefs) {
+  const o = overrideEnabled(behaviorPrefs);
+  return o === null ? DEFAULT_ENABLED : o;
+}
+
+// Everything the /me payload + the /settings UI need in one object.
+function describeForApi(behaviorPrefs) {
+  return {
+    widgets_enabled: widgetsEnabled(behaviorPrefs),
+    default_enabled: DEFAULT_ENABLED,
+    override: overrideEnabled(behaviorPrefs),
+  };
+}
+
+// Validate a PATCH body: { widgets: <bool> | null }. `null` clears the override
+// (fall back to the default). Unknown keys → 422. Non-boolean values → 422.
+// Returns { ok, patch } or { ok:false, errors }. An empty body is a valid no-op.
+function validatePatch(body) {
+  if (body == null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, errors: [{ error: 'body_must_be_object' }] };
+  }
+  const errors = [];
+  const patch = {};
+  for (const [key, value] of Object.entries(body)) {
+    if (key !== RESERVED_KEY) {
+      errors.push({ key, error: 'unknown_key', allowed: [RESERVED_KEY] });
+      continue;
+    }
+    if (value === null || typeof value === 'boolean') {
+      patch[RESERVED_KEY] = value; // null = clear → default
+      continue;
+    }
+    errors.push({ key, error: 'invalid_value', value, allowed: 'boolean or null' });
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, patch };
+}
+
+// Apply a validated patch to a builder's existing behavior_prefs. Pure. null
+// deletes the key (fall back to default); a boolean overwrites. Other keys in
+// the blob (e.g. the wandering knob) are left untouched.
+function applyPatch(existing, patch) {
+  const next = { ...(existing || {}) };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
+
+module.exports = {
+  RESERVED_KEY,
+  DEFAULT_ENABLED,
+  overrideEnabled,
+  widgetsEnabled,
+  describeForApi,
+  validatePatch,
+  applyPatch,
+};