@ngockhoale/ukit 3.4.26 → 3.4.28

package/src/core/agentRuntime/context.js

@@ -15,6 +15,7 @@ import crypto from 'node:crypto';
 
 import { validateTaskContract } from './contract.js';
 import { eligible } from '../memory/policy.js';
+import { isSensitivePath } from '../../index/sensitivePath.js';
 
 const STALE_MS = 15 * 60 * 1000; // default freshness window for evidence
 
@@ -491,3 +492,80 @@ export async function buildSubagentContext({
     contextRefs,
   };
 }
+
+// --- TASK-B3 (PLAN-ENDUR-B §B3): context pack → delegation candidates -------
+// Pure mapping from a buildContextPack result (TASK-B2, plain data) into
+// candidates for buildSubagentContext. No fs/config/network/LLM access here —
+// the pack is supplied by the caller; this module stays I/O-free.
+//
+// Freshness honesty (documented choice, TASK-B3 Discussion): the pack carries
+// no generation timestamp (B2 is clock-free), so "not fresh" is expressed via
+// the EXISTING observedAt/ttlMs staleness path of buildSubagentContext —
+// no new exclusion machinery, no change to its output shape:
+// - fresh pack (stale:false, fallback:null): observedAt = mapping `now`,
+//   ttlMs = STALE_MS → included while within the default evidence window.
+// - degraded pack (stale:true OR fallback set): observedAt = 0, ttlMs = 0 →
+//   excluded 'stale' by any real downstream clock (nowMs > 0). Candidates are
+//   still mapped (visible as excluded manifest items), never fresh-labeled.
+// Sensitive paths use the shared pure predicate src/index/sensitivePath.js
+// (same one contextPack.js uses — no mirrored copy) and map with
+// sensitivity:'sensitive' so the existing redaction path excludes them.
+
+// Deterministic content text over path/reason/outline only. Outline order is
+// authoritative from the pack (B2 emits line-sorted outlines).
+function packEntryText(entry) {
+  const lines = [
+    `path: ${entry.path}`,
+    `reason: ${isNonEmptyStr(entry.reason) ? entry.reason : 'unknown'}`,
+  ];
+  for (const symbol of Array.isArray(entry.outline) ? entry.outline : []) {
+    if (symbol == null || typeof symbol !== 'object' || !isNonEmptyStr(symbol.name)) {
+      continue;
+    }
+    const type = isNonEmptyStr(symbol.type) ? symbol.type : 'symbol';
+    const signature = isNonEmptyStr(symbol.signature) ? ` ${symbol.signature}` : '';
+    lines.push(`symbol: ${symbol.name} (${type})${signature}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Map a buildContextPack result to buildSubagentContext candidates (pure).
+ *
+ * @param {object|null} pack buildContextPack result; malformed input maps to [].
+ * @param {object} [options]
+ * @param {number} [options.now] Mapping clock; anchors fresh candidates'
+ *   observedAt (default Date.now(), matching module convention).
+ * @returns {Array<object>} One candidate per pack file: ref `pack:<path>`,
+ *   kind 'evidence', provenance 'context-pack', required:false, deterministic
+ *   content; degraded packs (stale/fallback) carry observedAt:0/ttlMs:0 so the
+ *   existing staleness path excludes them; sensitive paths carry
+ *   sensitivity:'sensitive' for the existing redaction path.
+ */
+export function contextPackToCandidates(pack, { now } = {}) {
+  const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+  const files = pack != null && typeof pack === 'object' && Array.isArray(pack.files)
+    ? pack.files
+    : [];
+  const degraded = pack?.stale === true || pack?.fallback != null;
+  const observedAt = degraded ? 0 : nowMs;
+  const ttlMs = degraded ? 0 : STALE_MS;
+
+  const candidates = [];
+  for (const entry of files) {
+    if (entry == null || typeof entry !== 'object' || !isNonEmptyStr(entry.path)) {
+      continue;
+    }
+    candidates.push({
+      ref: `pack:${entry.path}`,
+      content: packEntryText(entry),
+      required: false,
+      kind: 'evidence',
+      provenance: 'context-pack',
+      observedAt,
+      ttlMs,
+      ...(isSensitivePath(entry.path) ? { sensitivity: 'sensitive' } : {}),
+    });
+  }
+  return candidates;
+}

package/src/core/diffPlan.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { isSymlinkTo } from './fileOps.js';
 import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
 import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
+import { mergeRuntimeConfigText } from './runtimeConfigMerge.js';
 
 const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS));
 
@@ -45,130 +46,121 @@ async function checkLinkStatus(targetPath, linkTarget) {
   }
 }
 
-// Settings.json uses a strategy where only the gateway-resilience env keys (managed by
-// applyGatewayResilienceEnv post-apply) are ignored during the diff. Every other top-level
-// key — including the rest of the env block — is still compared byte-for-byte against the
-// template, so a template-side change to e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW still triggers
-// a real reinstall. Without this carve-out, the managed gateway keys written by the post-apply
-// step would cause a spurious "update" on every subsequent install.
-//
-// `permissions.defaultMode` is user-owned: the user picks their permission mode
-// (bypassPermissions / plan / acceptEdits / default) and UKit must never change it.
-// It is excluded from the drift comparison AND re-injected into the rendered content
-// before write (mergeSettingsJson), so an install/update can never flip the user's mode.
-// When the user has NOT set it, the template's shipped default applies on create/update.
-const USER_OWNED_PERMISSION_KEYS = new Set(['defaultMode']);
+// Settings.json ownership model (U1). `.claude/settings.json` is a shared file: UKit ships
+// a baseline and users customise it. Ownership per key:
+//   UKit-owned (template always wins):  `hooks` (the safety/enforcement wiring), the
+//                                       template's own `env` keys, and every `permissions.deny`
+//                                       entry the template ships.
+//   Additive (union, template first):   `permissions.allow|deny|ask|additionalDirectories` —
+//                                       user entries are kept; the template's entries are
+//                                       always present.
+//   User-owned (existing wins):         `permissions.defaultMode`, and every other key the
+//                                       user already has (model, effortLevel, statusLine,
+//                                       enabledPlugins, unknown/future keys, user env keys…).
+//   Template-filled:                    keys the user does not have take the template value.
+// Gateway-resilience env keys are post-apply managed (applyGatewayResilienceEnv) and are
+// ignored by the drift comparison.
+const UKIT_OWNED_TOP_LEVEL_KEYS = new Set(['hooks']);
+const PERMISSION_LIST_KEYS = new Set(['allow', 'deny', 'ask', 'additionalDirectories']);
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 
 function parseSettingsJson(content) {
   if (typeof content !== 'string') return null;
   try {
     const parsed = JSON.parse(content);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    return isPlainObject(parsed) ? parsed : null;
   } catch {
     return null;
   }
 }
 
-// Strip user-owned permission keys from a parsed permissions object for comparison.
-// Returns a new object; never mutates the input.
-function stripUserOwnedPermissionKeys(permissions) {
-  if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
-    return permissions;
-  }
-  const stripped = { ...permissions };
-  for (const key of USER_OWNED_PERMISSION_KEYS) delete stripped[key];
-  return stripped;
-}
-
-// Merge rendered settings.json with the user's existing file: the rendered template
-// wins every key EXCEPT user-owned permission keys (currently permissions.defaultMode),
-// which keep the value the user set. Returns the merged JSON as a string, or the
-// rendered content unchanged when either side is unparseable.
-export function mergeSettingsJson(existingContent, renderedContent) {
-  const existing = parseSettingsJson(existingContent);
-  const rendered = parseSettingsJson(renderedContent);
-  if (!existing || !rendered) return renderedContent;
-  const merged = { ...rendered };
-  if (existing.permissions && typeof existing.permissions === 'object' && !Array.isArray(existing.permissions)) {
-    const mergedPermissions = { ...(rendered.permissions && typeof rendered.permissions === 'object' ? rendered.permissions : {}) };
-    for (const key of USER_OWNED_PERMISSION_KEYS) {
-      if (key in existing.permissions) mergedPermissions[key] = existing.permissions[key];
+function unionList(templateList, userList) {
+  const out = Array.isArray(templateList) ? [...templateList] : [];
+  if (!Array.isArray(userList)) return out;
+  const seen = new Set(out.map((item) => JSON.stringify(item)));
+  for (const item of userList) {
+    const key = JSON.stringify(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(item);
     }
-    merged.permissions = mergedPermissions;
   }
-  return `${JSON.stringify(merged, null, 2)}\n`;
+  return out;
 }
 
-function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
-  if (typeof existingContent !== 'string' || typeof renderedContent !== 'string') {
-    return false;
-  }
-  let parsedExisting;
-  let parsedRendered;
-  try {
-    parsedExisting = JSON.parse(existingContent);
-    parsedRendered = JSON.parse(renderedContent);
-  } catch {
-    return false;
+function mergeSettingsObjects(existing, rendered) {
+  const merged = {};
+  for (const key of Object.keys(rendered)) {
+    if (BLOCKED_KEYS.has(key)) continue;
+    merged[key] = rendered[key];
   }
-  if (!parsedExisting || typeof parsedExisting !== 'object' || Array.isArray(parsedExisting)) {
-    return false;
-  }
-  if (!parsedRendered || typeof parsedRendered !== 'object' || Array.isArray(parsedRendered)) {
-    return false;
-  }
-
-  for (const key of Object.keys(parsedRendered)) {
-    if (key === 'env') continue;
-    if (!(key in parsedExisting)) return false;
-    const renderedValue = key === 'permissions'
-      ? stripUserOwnedPermissionKeys(parsedRendered[key])
-      : parsedRendered[key];
-    const existingValue = key === 'permissions'
-      ? stripUserOwnedPermissionKeys(parsedExisting[key])
-      : parsedExisting[key];
-    if (JSON.stringify(existingValue) !== JSON.stringify(renderedValue)) {
-      return false;
+  for (const [key, userValue] of Object.entries(existing)) {
+    if (BLOCKED_KEYS.has(key) || UKIT_OWNED_TOP_LEVEL_KEYS.has(key)) continue;
+    if (!(key in rendered)) {
+      merged[key] = userValue; // unknown/user key — preserved
+      continue;
+    }
+    const templateValue = rendered[key];
+    if (key === 'permissions' && isPlainObject(userValue) && isPlainObject(templateValue)) {
+      const permissions = { ...templateValue };
+      for (const [pKey, pValue] of Object.entries(userValue)) {
+        if (BLOCKED_KEYS.has(pKey)) continue;
+        if (PERMISSION_LIST_KEYS.has(pKey)) {
+          permissions[pKey] = unionList(templateValue[pKey], pValue);
+        } else {
+          permissions[pKey] = pValue; // defaultMode + unknown permission keys are user-owned
+        }
+      }
+      merged.permissions = permissions;
+    } else if (key === 'env' && isPlainObject(userValue) && isPlainObject(templateValue)) {
+      merged.env = { ...userValue, ...templateValue };
+    } else if (key === 'permissions' || key === 'env') {
+      // user value has the wrong shape (e.g. permissions: "x") — template shape wins
+      merged[key] = templateValue;
+    } else {
+      merged[key] = userValue; // user-owned scalar/section (model, effortLevel, …)
     }
   }
+  return merged;
+}
 
-  // Reverse direction: an existing top-level key that the template does NOT ship is also
-  // drift. Catches template key REMOVAL (e.g. a previous template shipped `permissions`
-  // and the new one dropped it) and user-side additions. The `merge_env_overwrite_with_backup`
-  // strategy is a narrowed overwrite — the only carve-out is the UKit-managed gateway env
-  // keys below — so every other byte mismatch must reinstall, in either direction.
-  for (const key of Object.keys(parsedExisting)) {
-    if (key === 'env') continue;
-    if (!(key in parsedRendered)) return false;
-  }
+// Merge rendered settings.json with the user's existing file per the ownership model above.
+// Returns the merged JSON as a string, or the rendered content unchanged when either side is
+// unparseable (the caller still takes a timestamped backup before writing).
+export function mergeSettingsJson(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return renderedContent;
+  return `${JSON.stringify(mergeSettingsObjects(existing, rendered), null, 2)}\n`;
+}
 
-  const templateEnv = parsedRendered.env && typeof parsedRendered.env === 'object' && !Array.isArray(parsedRendered.env)
-    ? parsedRendered.env
-    : {};
-  const fileEnv = parsedExisting.env && typeof parsedExisting.env === 'object' && !Array.isArray(parsedExisting.env)
-    ? parsedExisting.env
-    : {};
+function withoutGatewayEnv(settings) {
+  if (!isPlainObject(settings.env)) return settings;
+  const env = { ...settings.env };
+  for (const key of GATEWAY_RESILIENCE_KEYS) delete env[key];
+  return { ...settings, env };
+}
 
-  // Only enforce template env keys that are NOT UKit-managed. UKit-managed keys
-  // (CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, CLAUDE_STREAM_IDLE_TIMEOUT_MS) are owned by
-  // applyGatewayResilienceEnv — it adds them post-apply and preserves user overrides.
-  for (const key of Object.keys(templateEnv)) {
-    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
-    if (JSON.stringify(fileEnv[key]) !== JSON.stringify(templateEnv[key])) {
-      return false;
-    }
-  }
+function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return false;
+  const merged = mergeSettingsObjects(existing, rendered);
+  return JSON.stringify(canonicalize(withoutGatewayEnv(merged)))
+    === JSON.stringify(canonicalize(withoutGatewayEnv(existing)));
+}
 
-  // Reverse direction for env: an env key in the file that the template does NOT ship
-  // (and that is not UKit-managed) is also drift — a removed template env key, or a
-  // user-added env key, must reinstall. UKit-managed gateway keys remain carved out
-  // because applyGatewayResilienceEnv owns them post-apply.
-  for (const key of Object.keys(fileEnv)) {
-    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
-    if (!(key in templateEnv)) return false;
+// Key-order-insensitive structure for comparison (arrays keep order).
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, canonicalize(value[k])]));
   }
-
-  return true;
+  return value;
 }
 
 function resolveFileAction(entry, existingContent) {
@@ -205,6 +197,12 @@ function resolveFileAction(entry, existingContent) {
     const merged = mergeSettingsJson(existingContent, entry.renderedContent);
     action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
     return { ...entry, renderedContent: merged, exists, action, existingContent };
+  } else if (entry.id === 'runtime-config' && typeof existingContent === 'string' && typeof entry.renderedContent === 'string') {
+    // U2: .ukit/storage/config.json is user-owned state seeded from the template — merge
+    // by ownership instead of overwriting (see runtimeConfigMerge.js).
+    const merged = mergeRuntimeConfigText(existingContent, entry.renderedContent);
+    action = merged.changed ? 'update' : 'unchanged';
+    return { ...entry, renderedContent: merged.text, migrationReport: merged.report, exists, action, existingContent };
   } else if (existingContent === entry.renderedContent) {
     action = 'unchanged';
   } else if (entry.mergeStrategy === 'skip') {

package/src/core/docContracts.js

@@ -232,6 +232,7 @@ function validateRegistryDoc(doc, fileExists) {
       }
     }
     if (e.notes !== undefined && typeof e.notes !== 'string') problems.push(`${tag}: notes must be a string`);
+    if (e.local_only !== undefined && typeof e.local_only !== 'boolean') problems.push(`${tag}: local_only must be a boolean`);
   });
   return problems;
 }
@@ -626,6 +627,8 @@ async function checkRegistry(rootDir, registry, fileExists) {
   const problems = validateRegistryDoc(registry, fileExists);
   for (const e of registry.entries || []) {
     if (typeof e.path !== 'string' || e.path.length === 0) continue;
+    // local_only = optional gitignored machine-local doc: absent on a clean checkout is valid
+    if (e.local_only === true && !fileExists(e.path)) continue;
     if (!fileExists(e.path)) problems.push(`entry path '${e.path}' does not exist on disk`);
     if (typeof e.source_of_truth === 'string' && e.source_of_truth.length > 0 && !fileExists(e.source_of_truth)) {
       problems.push(`entry '${e.path}': source_of_truth '${e.source_of_truth}' does not exist on disk`);

package/src/core/observability/emit/sessionBoot.js

@@ -334,6 +334,15 @@ function outcomeCost(value) {
   };
 }
 
+// A3 (C100 O8): agent/model/provider linkage. Nullable and additive: a value the hook payload
+// or emitter did not supply stays null (UNKNOWN) — never a guess, never 0, never inferred from a model name.
+function linkageField(...candidates) {
+  for (const value of candidates) {
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim().slice(0, 96);
+  }
+  return null;
+}
+
 /**
  * buildOutcomeObservedRecord({ outcome, projectRoot, payload, sessionId,
  * engine, env }) → semantic-record candidate for `outcome.observed`.
@@ -375,6 +384,11 @@ export function buildOutcomeObservedRecord({
     evidenceIds: outcomeStringList(safe.evidenceIds, 32),
     cost: outcomeCost(safe.cost),
     reviewActions: outcomeStringList(safe.reviewActions, 32),
+    agentId: linkageField(safe.agentId, payload?.agent_id),
+    parentAgentId: linkageField(safe.parentAgentId, payload?.parent_agent_id),
+    agentType: linkageField(safe.agentType, payload?.agent_type),
+    model: linkageField(safe.model, payload?.model),
+    provider: linkageField(safe.provider),
     enforcement: OUTCOME_ENFORCEMENTS.has(safe.enforcement)
       ? safe.enforcement
       : deriveEnforcement({ engine: engineName, env }),

package/src/core/runtimeConfigMerge.js

@@ -0,0 +1,125 @@
+import { buildDefaultRuntimeConfig, validateRuntimeConfig } from './runtimeConfig.js';
+
+// U2: ownership-based migration for `.ukit/storage/config.json`.
+//
+//   Template-owned (always the new release's value): `version`, `agent`, `_help`
+//     (documentation block) and every key listed in REMOVED_KEYS (dropped on migration).
+//   Security-reset (never carried over silently, reported instead): SECURITY_RESET_KEYS —
+//     an unsafe opt-in must be re-confirmed after an upgrade; the new default applies.
+//   User-owned (existing value wins): every other key the user already has — model routing
+//     (`modelRoles`, `router`, `subagents.*`), `autonomy`, `orchestration.permissionMode`,
+//     thresholds, arrays, and unknown keys (kept verbatim).
+//   Template-filled: keys the user does not have take the new default (so new features get
+//     their defaults, and a partial/old config is upgraded without losing user values).
+//
+// If the merged result fails validateRuntimeConfig, the merge refuses to guess: the existing
+// file is left untouched and the report says why. An unparseable (corrupt) existing file is
+// replaced by the rendered template (applyPlan takes a timestamped backup first).
+
+export const TEMPLATE_OWNED_KEYS = Object.freeze(['version', 'agent', '_help']);
+export const SECURITY_RESET_KEYS = Object.freeze(['orchestration.allowUnsafeEval']);
+export const REMOVED_KEYS = Object.freeze([]);
+
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function getPath(obj, dotted) {
+  return dotted.split('.').reduce((acc, k) => (isPlainObject(acc) ? acc[k] : undefined), obj);
+}
+
+function deletePath(obj, dotted) {
+  const parts = dotted.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (!isPlainObject(cur[parts[i]])) return;
+    cur = cur[parts[i]];
+  }
+  delete cur[parts[parts.length - 1]];
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, canonicalize(value[k])]));
+  }
+  return value;
+}
+
+function mergeOwned(template, existing) {
+  const merged = {};
+  for (const key of Object.keys(template)) {
+    if (!BLOCKED_KEYS.has(key)) merged[key] = template[key];
+  }
+  for (const [key, userValue] of Object.entries(existing)) {
+    if (BLOCKED_KEYS.has(key)) continue;
+    if (!(key in template)) {
+      merged[key] = userValue;
+    } else if (isPlainObject(template[key]) && isPlainObject(userValue)) {
+      merged[key] = mergeOwned(template[key], userValue);
+    } else {
+      merged[key] = userValue;
+    }
+  }
+  return merged;
+}
+
+export function mergeRuntimeConfigText(existingText, renderedText) {
+  const report = { merged: false, fallback: null, resetSecurityKeys: [], removedKeys: [] };
+  let existing;
+  let rendered;
+  try {
+    rendered = JSON.parse(renderedText);
+  } catch {
+    report.fallback = 'rendered-template-unparseable';
+    return { text: renderedText, changed: renderedText !== existingText, report };
+  }
+  try {
+    existing = JSON.parse(existingText);
+  } catch {
+    report.fallback = 'existing-unparseable';
+    return { text: renderedText, changed: true, report };
+  }
+  if (!isPlainObject(existing) || !isPlainObject(rendered)) {
+    report.fallback = 'not-an-object';
+    return { text: renderedText, changed: true, report };
+  }
+
+  const merged = mergeOwned(rendered, existing);
+  for (const key of TEMPLATE_OWNED_KEYS) {
+    if (key in rendered) merged[key] = rendered[key];
+    else delete merged[key];
+  }
+  for (const dotted of REMOVED_KEYS) {
+    if (getPath(existing, dotted) !== undefined) report.removedKeys.push(dotted);
+    deletePath(merged, dotted);
+  }
+  for (const dotted of SECURITY_RESET_KEYS) {
+    const before = getPath(merged, dotted);
+    const fallback = getPath(rendered, dotted);
+    if (before !== fallback) {
+      report.resetSecurityKeys.push(dotted);
+      const parts = dotted.split('.');
+      let cur = merged;
+      for (let i = 0; i < parts.length - 1; i += 1) {
+        if (!isPlainObject(cur[parts[i]])) cur[parts[i]] = {};
+        cur = cur[parts[i]];
+      }
+      if (fallback === undefined) delete cur[parts[parts.length - 1]];
+      else cur[parts[parts.length - 1]] = fallback;
+    }
+  }
+
+  // The runtime loader validates the file layered over built-in defaults, so do the same.
+  const validation = validateRuntimeConfig(mergeOwned(buildDefaultRuntimeConfig(), merged));
+  if (!validation.valid) {
+    // Never discard the user's customisations on a guess: leave the file untouched and
+    // report why. `ukit doctor` surfaces the invalid value; the user's file stays intact.
+    report.fallback = `merged-config-invalid (file left untouched): ${validation.errors.slice(0, 3).join('; ')}`;
+    return { text: existingText, changed: false, report };
+  }
+
+  report.merged = true;
+  const changed = JSON.stringify(canonicalize(merged)) !== JSON.stringify(canonicalize(existing));
+  return { text: `${JSON.stringify(merged, null, 2)}\n`, changed, report };
+}