arkgate 4.4.0 → 4.5.0

package/bin/lib/managed-upgrade-honesty.mjs

@@ -0,0 +1,201 @@
+/**
+ * DF05 — managed-upgrade self-service honesty (one residual pilot).
+ *
+ * Self-service criterion (must stay answerable from package surfaces without a maintainer):
+ *   After a managed upgrade (or equivalent), can a consumer learn from package surfaces whether
+ *   the write-path is still honestly labeled active/advisory and whether customized install
+ *   content was preserved — without asking a maintainer?
+ *
+ * This module projects that answer onto `ark upgrade` JSON/human output:
+ * - write-path activation labels per selected host (hard | advisory | unavailable)
+ * - customized (and conflicted) content-identity preserve proof
+ *
+ * Soft hosts never claim hard. Upgrade never invents hardWriteActive from disk alone —
+ * hard requires runtime evidence elsewhere (hooks/doctor/status); upgrade labels fail-closed.
+ * Always notAScore; never a gate input.
+ */
+import { getHostSupportProfile } from './host-support-matrix.mjs';
+import { classifyStatusWritePath, defaultHonestLabel } from './status-manifest.mjs';
+
+/**
+ * @param {string} host
+ * @param {{ hardWriteActive?: boolean }} [evidence]
+ * @returns {{
+ *   host: string,
+ *   writePath: 'hard'|'advisory'|'unavailable',
+ *   softWriteHost: boolean,
+ *   hardWriteSupported: boolean,
+ *   hardWriteActive: boolean,
+ *   label: string,
+ * }}
+ */
+export function projectHostWritePathActivation(host, evidence = {}) {
+  const normalized = typeof host === 'string' ? host.trim().toLowerCase() : '';
+  if (!normalized) {
+    return {
+      host: 'unknown',
+      writePath: 'unavailable',
+      softWriteHost: false,
+      hardWriteSupported: false,
+      hardWriteActive: false,
+      label: defaultHonestLabel('unavailable', null),
+    };
+  }
+
+  const profile = getHostSupportProfile(normalized);
+  if (!profile) {
+    return {
+      host: normalized,
+      writePath: 'unavailable',
+      softWriteHost: false,
+      hardWriteSupported: false,
+      hardWriteActive: false,
+      label: defaultHonestLabel('unavailable', normalized),
+    };
+  }
+
+  const hardWriteSupported = profile.capabilities?.['hard-write'] === true;
+  const softWriteHost = !hardWriteSupported;
+  // Fail-closed: soft never hard; hard only when caller supplies proven active evidence.
+  const hardWriteActive =
+    !softWriteHost && hardWriteSupported && evidence.hardWriteActive === true;
+  const writePath = classifyStatusWritePath({
+    softWriteHost,
+    hardWriteActive,
+    activeHost: normalized,
+  });
+  return {
+    host: normalized,
+    writePath,
+    softWriteHost,
+    hardWriteSupported,
+    hardWriteActive,
+    label: defaultHonestLabel(writePath, normalized),
+  };
+}
+
+/**
+ * Project self-service honesty facts from a managed upgrade plan.
+ *
+ * @param {{
+ *   hosts?: string[],
+ *   assets?: Array<{ path?: string, state?: string, willApply?: boolean, blocked?: boolean }>,
+ *   summary?: { customizedPreserved?: number, blocked?: number, states?: Record<string, number> },
+ * }} plan
+ * @param {{
+ *   hardWriteActiveByHost?: Record<string, boolean>,
+ * }} [options]
+ * @returns {{
+ *   schemaVersion: '1.0',
+ *   notAScore: true,
+ *   criterionId: 'df05-upgrade-activation-preserve',
+ *   customizedPreserved: number,
+ *   customizedPaths: string[],
+ *   conflictedPaths: string[],
+ *   customizedContentPreserved: boolean,
+ *   writePathActivation: ReturnType<typeof projectHostWritePathActivation>[],
+ *   writePathHonestlyLabeled: boolean,
+ *   answers: {
+ *     writePathActivationLabeled: boolean,
+ *     customizedContentPreserved: boolean,
+ *   },
+ * }}
+ */
+export function projectManagedUpgradeSelfServiceHonesty(plan, options = {}) {
+  const assets = Array.isArray(plan?.assets) ? plan.assets : [];
+  const hosts = Array.isArray(plan?.hosts) ? plan.hosts : [];
+  const hardByHost =
+    options.hardWriteActiveByHost && typeof options.hardWriteActiveByHost === 'object'
+      ? options.hardWriteActiveByHost
+      : {};
+
+  const customizedPaths = assets
+    .filter((asset) => asset?.state === 'customized' && typeof asset.path === 'string')
+    .map((asset) => asset.path)
+    .sort();
+  const conflictedPaths = assets
+    .filter((asset) => asset?.state === 'conflicted' && typeof asset.path === 'string')
+    .map((asset) => asset.path)
+    .sort();
+
+  // Preserve contract: customized assets must never be scheduled writes without consent.
+  const customizedContentPreserved = assets
+    .filter((asset) => asset?.state === 'customized' || asset?.state === 'conflicted')
+    .every((asset) => asset.willApply !== true);
+
+  const summaryCount =
+    typeof plan?.summary?.customizedPreserved === 'number'
+      ? plan.summary.customizedPreserved
+      : customizedPaths.length;
+
+  const writePathActivation = hosts.map((host) => {
+    const key = typeof host === 'string' ? host.trim().toLowerCase() : '';
+    return projectHostWritePathActivation(host, {
+      hardWriteActive: hardByHost[key] === true,
+    });
+  });
+
+  // Soft hosts never labeled hard; hard only when evidence supplied.
+  const writePathHonestlyLabeled = writePathActivation.every((entry) => {
+    if (entry.softWriteHost && entry.writePath === 'hard') return false;
+    if (entry.softWriteHost && entry.hardWriteActive) return false;
+    if (!entry.hardWriteSupported && entry.writePath === 'hard') return false;
+    if (entry.writePath === 'hard' && !entry.hardWriteActive) return false;
+    return true;
+  });
+
+  const answers = {
+    // Empty host list is not "labeled activation" — only claim labeled when hosts were projected.
+    writePathActivationLabeled:
+      writePathActivation.length > 0 && writePathHonestlyLabeled,
+    customizedContentPreserved,
+  };
+
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    criterionId: 'df05-upgrade-activation-preserve',
+    customizedPreserved: summaryCount,
+    customizedPaths,
+    conflictedPaths,
+    customizedContentPreserved,
+    writePathActivation,
+    writePathHonestlyLabeled,
+    answers,
+  };
+}
+
+/**
+ * Human one-liner block for upgrade preview/apply (stdout).
+ * @param {ReturnType<typeof projectManagedUpgradeSelfServiceHonesty>} honesty
+ */
+export function formatManagedUpgradeSelfServiceHonesty(honesty) {
+  if (!honesty) return [];
+  const lines = ['Self-service honesty (no maintainer required):'];
+  if (honesty.writePathActivation.length === 0) {
+    lines.push('  Write-path: shared/gates only (no host selected) — activation unavailable.');
+  } else {
+    for (const entry of honesty.writePathActivation) {
+      const soft = entry.softWriteHost ? 'soft host' : 'hard-capable';
+      const active = entry.hardWriteActive ? 'active' : 'not proven this invocation';
+      lines.push(
+        `  Write-path ${entry.host}: ${entry.writePath} (${soft}; hard ${active}).`
+      );
+    }
+  }
+  if (honesty.customizedPaths.length > 0) {
+    lines.push(
+      `  Customized preserved: ${honesty.customizedPreserved} (${honesty.customizedPaths.join(', ')}).`
+    );
+  } else {
+    lines.push(
+      `  Customized preserved: ${honesty.customizedPreserved} (no customized managed assets).`
+    );
+  }
+  if (honesty.conflictedPaths.length > 0) {
+    lines.push(
+      `  Conflicted (consent required): ${honesty.conflictedPaths.join(', ')}.`
+    );
+  }
+  return lines;
+}

package/bin/lib/managed-upgrade.mjs

@@ -4,6 +4,10 @@ import path from 'node:path';
 
 import { codexPrimaryTable, upsertCodexMcpTable } from './codex-home.mjs';
 import { buildManagedAssetCatalog } from './install-migrate.mjs';
+import {
+  formatManagedUpgradeSelfServiceHonesty,
+  projectManagedUpgradeSelfServiceHonesty,
+} from './managed-upgrade-honesty.mjs';
 import {
   KNOWN_TOOLS,
   arkPackageVersion,
@@ -12,6 +16,12 @@ import {
   skillContentIdentity,
 } from './skill-install.mjs';
 
+export {
+  formatManagedUpgradeSelfServiceHonesty,
+  projectHostWritePathActivation,
+  projectManagedUpgradeSelfServiceHonesty,
+} from './managed-upgrade-honesty.mjs';
+
 export const MANAGED_MANIFEST_PATH = 'ark.managed.json';
 const MANIFEST_VERSION = '1.0';
 const AFTER_CONTENT = Symbol('managed-after-content');
@@ -534,7 +544,10 @@ export function planManagedUpgrade(root, options = {}) {
 }
 
 function publicPlan(plan, overrides = {}) {
-  return {
+  const assets = plan.assets.map(
+    ({ containerBeforeHash: _container, [AFTER_CONTENT]: _content, ...asset }) => asset
+  );
+  const base = {
     schemaVersion: plan.schemaVersion,
     root: plan.root,
     readOnly: overrides.readOnly ?? plan.readOnly,
@@ -544,11 +557,21 @@ function publicPlan(plan, overrides = {}) {
     profile: plan.profile,
     hosts: plan.hosts,
     acceptConflicts: plan.acceptConflicts,
-    assets: plan.assets.map(
-      ({ containerBeforeHash: _container, [AFTER_CONTENT]: _content, ...asset }) => asset
-    ),
+    assets,
     summary: plan.summary,
+  };
+  // DF05: self-service honesty (write-path labels + customized preserve) on every public plan.
+  // Not part of planDigest — advisory projection only; never invents hard write on soft hosts.
+  const selfService = projectManagedUpgradeSelfServiceHonesty({
+    hosts: base.hosts,
+    assets,
+    summary: base.summary,
+  });
+  return {
+    ...base,
     ...overrides,
+    // DF05 projection always present unless an override supplies a replacement.
+    selfService: overrides.selfService ?? selfService,
   };
 }
 
@@ -738,6 +761,16 @@ export function renderManagedUpgrade(plan, options = {}) {
     `Managed assets: ${managedAssets}; would write: ${wouldWrite}; ` +
       `customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
+  const honesty =
+    plan.selfService ??
+    projectManagedUpgradeSelfServiceHonesty({
+      hosts: plan.hosts,
+      assets: plan.assets,
+      summary: plan.summary,
+    });
+  for (const line of formatManagedUpgradeSelfServiceHonesty(honesty)) {
+    console.log(line);
+  }
   if (plan.applied) {
     console.log(
       `Applied ${wouldWrite} content write(s)` +

package/bin/lib/status-command.mjs

@@ -1,15 +1,21 @@
 /**
- * ACS03 — gather session/project evidence for `ark status` / MCP `ark_status`.
+ * ACS03 + DF02 — gather session/project evidence for `ark status` / MCP `ark_status`.
  *
  * Fail-closed and CI-safe: never prompts (no readline), never invents hard write,
  * never invents a numeric score. Pure assembly lives in Domain statusManifest.
+ * Improvement compass carries explicit honesty mode (full|subset|unavailable).
  */
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { buildStatusManifest } from './status-manifest.mjs';
+import {
+  buildStatusManifest,
+  normalizeStatusImprovementCompass,
+  projectStatusImprovementCompass,
+  unavailableStatusImprovementCompass,
+} from './status-manifest.mjs';
 import { createProjectId } from './project-identity.mjs';
 import { resolveEffectiveProjectRoot } from './project-root.mjs';
 import { detectWritePathCapabilities } from './write-path-detect.mjs';
@@ -130,6 +136,94 @@ export function lastCheckFactsFromSnapshot(latest, baseline) {
   };
 }
 
+/**
+ * Project status improvementCompass honesty from a report/session snapshot (DF02).
+ * Prefer stored thin slice; never invent green residual when facts are missing.
+ *
+ * @param {object|null|undefined} latest
+ * @param {{ contractHash?: string|null }} [opts]
+ * @returns {import('./status-manifest.mjs').StatusImprovementCompassSlice}
+ */
+export function statusCompassFromSnapshot(latest, opts = {}) {
+  const contractHash =
+    typeof opts.contractHash === 'string' && opts.contractHash.length > 0
+      ? opts.contractHash
+      : null;
+
+  if (!latest || typeof latest !== 'object') {
+    return unavailableStatusImprovementCompass({
+      reasonCode: 'NO_SESSION_SNAPSHOT',
+      reason:
+        'No session report snapshot yet — run ark-check --doctor or --report for residual lenses. Status never invents green.',
+      contractHash,
+    });
+  }
+
+  // Prefer explicit thin status slice on the snapshot (report path stores mode+residual).
+  if (latest.improvementCompass && typeof latest.improvementCompass === 'object') {
+    const normalized = normalizeStatusImprovementCompass({
+      ...latest.improvementCompass,
+      ...(contractHash && !latest.improvementCompass.contractHash
+        ? { contractHash }
+        : {}),
+      factsSource: latest.improvementCompass.factsSource || 'report-snapshot',
+    });
+    if (normalized) return normalized;
+  }
+
+  // Doctor-equivalent residual ids stored without honesty wrapper → full if complete flag set.
+  if (
+    latest.doctorImprovementCompass &&
+    typeof latest.doctorImprovementCompass === 'object' &&
+    latest.doctorImprovementCompass.notAScore === true &&
+    Array.isArray(latest.doctorImprovementCompass.topResidual)
+  ) {
+    const complete = latest.compassFactsComplete === true || latest.completeness === 'complete';
+    return projectStatusImprovementCompass({
+      mode: complete ? 'full' : 'subset',
+      topResidual: latest.doctorImprovementCompass.topResidual,
+      reasonCode: complete ? undefined : 'FACTS_PARTIAL',
+      reason: complete
+        ? undefined
+        : 'Session snapshot residual is partial — re-run doctor/report for full compass.',
+      factsSource: 'report-snapshot',
+      contractHash,
+    });
+  }
+
+  return unavailableStatusImprovementCompass({
+    reasonCode: 'NO_SESSION_SNAPSHOT',
+    reason:
+      'Session snapshot has no improvement compass facts — run ark-check --doctor or --report. Status never invents green.',
+    contractHash,
+  });
+}
+
+/**
+ * Build a storeable thin status compass from a full doctor ImprovementCompass (DF02).
+ * Used by report snapshot so status residual ⊆ doctor residual for the same tree.
+ *
+ * @param {{ notAScore?: boolean, topResidual?: string[] }|null|undefined} doctorCompass
+ * @param {{ mode?: 'full'|'subset', contractHash?: string|null, reasonCode?: string, reason?: string }} [opts]
+ */
+export function thinStatusCompassFromDoctor(doctorCompass, opts = {}) {
+  if (!doctorCompass || doctorCompass.notAScore !== true) {
+    return unavailableStatusImprovementCompass({
+      reasonCode: 'FACTS_UNAVAILABLE',
+      contractHash: opts.contractHash,
+    });
+  }
+  const mode = opts.mode === 'subset' ? 'subset' : 'full';
+  return projectStatusImprovementCompass({
+    mode,
+    topResidual: Array.isArray(doctorCompass.topResidual) ? doctorCompass.topResidual : [],
+    reasonCode: opts.reasonCode,
+    reason: opts.reason,
+    factsSource: 'report-snapshot',
+    contractHash: opts.contractHash,
+  });
+}
+
 /**
  * Collect status facts from disk (no prompts).
  * @param {{
@@ -140,6 +234,8 @@ export function lastCheckFactsFromSnapshot(latest, baseline) {
  *   host?: string,
  *   arkgateVersion?: string,
  *   env?: NodeJS.ProcessEnv,
+ *   improvementCompass?: object | null,
+ *   contractHash?: string | null,
  * }} [options]
  */
 export function collectStatusFacts(options = {}) {
@@ -242,6 +338,22 @@ export function collectStatusFacts(options = {}) {
 
   const arkruleFrozenFallback = countArkruleFrozenKeys(baseline);
 
+  // DF02 — always project compass with honesty mode (never invent green residual).
+  // Prefer explicit override (tests/MCP inject doctor-facts); else report snapshot.
+  let improvementCompass = null;
+  if (options.improvementCompass != null) {
+    improvementCompass = normalizeStatusImprovementCompass(options.improvementCompass);
+  }
+  if (!improvementCompass) {
+    const contractHash =
+      typeof options.contractHash === 'string' && options.contractHash.length > 0
+        ? options.contractHash
+        : configExists && config
+          ? sha256Hex(JSON.stringify(config))
+          : null;
+    improvementCompass = statusCompassFromSnapshot(latest, { contractHash });
+  }
+
   return {
     arkgateVersion: options.arkgateVersion || packageVersion(),
     resolvedRoot: realpathOrResolve(resolvedRoot),
@@ -269,6 +381,7 @@ export function collectStatusFacts(options = {}) {
           : arkRulesLoaded
             ? 0
             : null,
+    improvementCompass,
   };
 }
 
@@ -346,6 +459,18 @@ export function runStatusCommand(args = {}) {
             ? ` · frozen=${manifest.rules.frozenResidual}`
             : '')
       );
+      const ic = manifest.improvementCompass;
+      if (ic) {
+        const residual =
+          Array.isArray(ic.topResidual) && ic.topResidual.length > 0
+            ? ic.topResidual.join(', ')
+            : '(none)';
+        write(
+          `  compass: mode=${ic.mode}` +
+            (ic.mode === 'unavailable' ? '' : ` · residual=${residual}`) +
+            ' · not a score'
+        );
+      }
       write(`  next: [${manifest.nextAction.id}] ${manifest.nextAction.summary}`);
     }
 

package/bin/lib/status-manifest.mjs

@@ -10,6 +10,25 @@
 
 export const ARK_STATUS_MANIFEST_SCHEMA_VERSION = '1.0';
 export const ARK_STATUS_MANIFEST_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json';
+/**
+ * Honesty mode for status improvementCompass (DF02).
+ * - full: residual projected from doctor-equivalent facts (residual ⊆ doctor)
+ * - subset: incomplete facts; residual may omit doctor residual; never invent green
+ * - unavailable: no usable facts; empty residual + reason (never silent ok)
+ */
+export const STATUS_COMPASS_MODES = ['full', 'subset', 'unavailable'];
+/** Provenance for status compass residual (same-tree intent). */
+export const STATUS_COMPASS_FACTS_SOURCES = [
+    'doctor-facts',
+    'report-snapshot',
+    'none',
+];
+/** Stable reason codes when mode is not full. */
+export const STATUS_COMPASS_REASON_CODES = {
+    FACTS_UNAVAILABLE: 'FACTS_UNAVAILABLE',
+    FACTS_PARTIAL: 'FACTS_PARTIAL',
+    NO_SESSION_SNAPSHOT: 'NO_SESSION_SNAPSHOT',
+};
 const PROJECT_ID_PATTERN = /^sha256:[a-f0-9]{64}$/;
 /**
  * Evaluate project binding for status without filesystem.
@@ -294,23 +313,148 @@ export function buildStatusManifest(facts) {
         status.improvementCompass = compass;
     return status;
 }
-function normalizeStatusImprovementCompass(value) {
+const STATUS_COMPASS_MODE_SET = new Set(STATUS_COMPASS_MODES);
+const STATUS_COMPASS_SOURCE_SET = new Set(STATUS_COMPASS_FACTS_SOURCES);
+/**
+ * Project a thin status improvementCompass with explicit honesty mode (DF02).
+ *
+ * Rules:
+ * - always notAScore: true
+ * - mode full | subset | unavailable (invalid mode → unavailable)
+ * - unavailable: topResidual forced empty (never invent residual or silent green)
+ * - full/subset: residual ids from input only (never fabricate ok lenses)
+ * - never carries valid / goal.met / score fields
+ */
+export function projectStatusImprovementCompass(input) {
+    const mode = STATUS_COMPASS_MODE_SET.has(input.mode)
+        ? input.mode
+        : 'unavailable';
+    const factsSource = input.factsSource != null && STATUS_COMPASS_SOURCE_SET.has(input.factsSource)
+        ? input.factsSource
+        : mode === 'unavailable'
+            ? 'none'
+            : undefined;
+    const contractHash = typeof input.contractHash === 'string' && input.contractHash.length > 0
+        ? input.contractHash
+        : undefined;
+    if (mode === 'unavailable') {
+        const out = {
+            schemaVersion: '1.0',
+            notAScore: true,
+            mode: 'unavailable',
+            topResidual: [],
+            reasonCode: typeof input.reasonCode === 'string' && input.reasonCode.length > 0
+                ? input.reasonCode
+                : STATUS_COMPASS_REASON_CODES.FACTS_UNAVAILABLE,
+            reason: typeof input.reason === 'string' && input.reason.length > 0
+                ? input.reason
+                : 'Improvement compass facts are unavailable — run ark-check --doctor for residual lenses. Status never invents green.',
+            factsSource: factsSource ?? 'none',
+        };
+        if (contractHash)
+            out.contractHash = contractHash;
+        return out;
+    }
+    const topResidual = Array.isArray(input.topResidual)
+        ? input.topResidual
+            .filter((id) => typeof id === 'string' && id.length > 0)
+            .slice(0, 15)
+        : [];
+    const out = {
+        schemaVersion: '1.0',
+        notAScore: true,
+        mode,
+        topResidual,
+    };
+    if (mode === 'subset') {
+        out.reasonCode =
+            typeof input.reasonCode === 'string' && input.reasonCode.length > 0
+                ? input.reasonCode
+                : STATUS_COMPASS_REASON_CODES.FACTS_PARTIAL;
+        out.reason =
+            typeof input.reason === 'string' && input.reason.length > 0
+                ? input.reason
+                : 'Status compass is a subset of doctor residual — incomplete session facts; run doctor for full.';
+    }
+    else if (typeof input.reasonCode === 'string' && input.reasonCode.length > 0) {
+        out.reasonCode = input.reasonCode;
+    }
+    if (typeof input.reason === 'string' && input.reason.length > 0 && mode === 'full') {
+        out.reason = input.reason;
+    }
+    if (factsSource)
+        out.factsSource = factsSource;
+    if (contractHash)
+        out.contractHash = contractHash;
+    return out;
+}
+/**
+ * Unavailable compass when Tooling has no doctor/report residual facts.
+ * Empty residual + mode label — never a green / ok claim.
+ */
+export function unavailableStatusImprovementCompass(input = {}) {
+    return projectStatusImprovementCompass({
+        mode: 'unavailable',
+        topResidual: [],
+        reasonCode: input.reasonCode ?? STATUS_COMPASS_REASON_CODES.NO_SESSION_SNAPSHOT,
+        reason: input.reason ??
+            'No session compass facts yet — run ark-check --doctor or --report for residual lenses. Status never invents green.',
+        factsSource: 'none',
+        contractHash: input.contractHash,
+    });
+}
+/**
+ * Normalize an incoming status compass slice (Tooling pass-through / snapshot).
+ * Rejects score-like shapes; coerces missing mode to subset (never silent full).
+ * Unavailable always clears residual.
+ */
+export function normalizeStatusImprovementCompass(value) {
     if (value == null || typeof value !== 'object')
         return null;
-    if (value.notAScore !== true)
+    const record = value;
+    if (record.notAScore !== true)
         return null;
-    if (value.schemaVersion !== '1.0')
+    if (record.schemaVersion !== '1.0')
         return null;
-    if (!Array.isArray(value.topResidual))
+    // Score-like fields never allowed on status compass.
+    if ('score' in record || 'valid' in record || 'goal' in record)
         return null;
-    const topResidual = value.topResidual
-        .filter((id) => typeof id === 'string' && id.length > 0)
-        .slice(0, 15);
-    return {
-        schemaVersion: '1.0',
-        notAScore: true,
-        topResidual,
-    };
+    let mode;
+    if (typeof record.mode === 'string' && STATUS_COMPASS_MODE_SET.has(record.mode)) {
+        mode = record.mode;
+    }
+    else if (Array.isArray(record.topResidual)) {
+        // Legacy thin slice without mode → subset honesty (never silent full).
+        mode = 'subset';
+    }
+    else {
+        mode = 'unavailable';
+    }
+    return projectStatusImprovementCompass({
+        mode,
+        topResidual: Array.isArray(record.topResidual)
+            ? record.topResidual
+            : [],
+        reasonCode: typeof record.reasonCode === 'string' ? record.reasonCode : null,
+        reason: typeof record.reason === 'string' ? record.reason : null,
+        factsSource: typeof record.factsSource === 'string' ? record.factsSource : null,
+        contractHash: typeof record.contractHash === 'string' ? record.contractHash : null,
+    });
+}
+/**
+ * Residual-id subset check for status ⊆ doctor parity fixtures (DF02).
+ * Returns true when every status residual id appears in doctor residual ids.
+ */
+export function statusCompassResidualIsSubsetOfDoctor(statusResidual, doctorResidual) {
+    const status = Array.isArray(statusResidual) ? statusResidual : [];
+    const doctor = new Set(Array.isArray(doctorResidual) ? doctorResidual : []);
+    for (const id of status) {
+        if (typeof id !== 'string' || id.length === 0)
+            continue;
+        if (!doctor.has(id))
+            return false;
+    }
+    return true;
 }
 function numberOrNull(value) {
     if (value == null)
@@ -414,17 +558,22 @@ export const ARK_STATUS_MANIFEST_SCHEMA = {
         },
         improvementCompass: {
             type: 'object',
-            description: 'Optional thin improvement-compass residual ids (notAScore). Never a gate input; full lenses on doctor JSON.',
+            description: 'Thin improvement-compass residual ids with honesty mode (notAScore). full | subset | unavailable. Never a gate input; full lenses on doctor JSON. When full, residual ids ⊆ doctor residual for the same facts. unavailable never invents green residual.',
             additionalProperties: false,
-            required: ['schemaVersion', 'notAScore', 'topResidual'],
+            required: ['schemaVersion', 'notAScore', 'mode', 'topResidual'],
             properties: {
                 schemaVersion: { const: '1.0' },
                 notAScore: { const: true },
+                mode: { enum: ['full', 'subset', 'unavailable'] },
                 topResidual: {
                     type: 'array',
                     items: { type: 'string', minLength: 1 },
                     maxItems: 15,
                 },
+                reasonCode: { type: 'string', minLength: 1 },
+                reason: { type: 'string', minLength: 1 },
+                factsSource: { enum: ['doctor-facts', 'report-snapshot', 'none'] },
+                contractHash: { type: 'string', minLength: 1 },
             },
         },
     },