@opengsd/gsd-core 1.6.0-rc.3 → 1.7.0-rc.1

package/gsd-core/bin/lib/frontmatter.cjs

@@ -205,20 +205,59 @@ function reconstructFrontmatter(obj) {
     }
     return lines.join('\n');
 }
+/**
+ * Slice a frontmatter YAML body into per-top-level-key raw text segments. Each segment
+ * runs from a column-0 `key:` line through the line before the next column-0 key (or the
+ * end), capturing all nested indented content. Used by `spliceFrontmatter` for per-key
+ * identity preservation (#1572): a structurally-unchanged key keeps its original raw
+ * text, so the lossy `reconstructFrontmatter` never touches object-lists the caller did
+ * not modify (e.g. must_haves.artifacts / .prohibitions).
+ */
+function sliceTopLevelFrontmatterSegments(yaml) {
+    const lines = yaml.split(/\r?\n/);
+    const segments = [];
+    let current = null;
+    for (const line of lines) {
+        // A column-0 `key:` (no leading whitespace) starts a new top-level segment.
+        if (/^[A-Za-z0-9_-]+:/.test(line)) {
+            if (current)
+                segments.push({ key: current.key, raw: current.raw.join('\n') });
+            const keyName = line.match(/^([A-Za-z0-9_-]+):/)[1];
+            current = { key: keyName, raw: [line] };
+        }
+        else if (current) {
+            current.raw.push(line);
+        }
+        // Stray lines before the first top-level key (rare in frontmatter) are dropped.
+    }
+    if (current)
+        segments.push({ key: current.key, raw: current.raw.join('\n') });
+    return segments;
+}
+/**
+ * Regenerate one frontmatter key's serialization, fail-closed if the lossy
+ * `reconstructFrontmatter` cannot represent the value (#1572 codex review). Object-list
+ * items (e.g. must_haves.artifacts `{path, provides}` maps) serialize as the literal
+ * string "[object Object]"; rather than silently emit that and destroy the data, refuse
+ * so the caller (cmdFrontmatterSet/Merge) errors out WITHOUT writing — directing the
+ * user to edit the file directly. The reported #1572 case (mutating an UNRELATED field)
+ * is unaffected: unchanged keys preserve their original raw text and never reach here.
+ */
+function regenerateFrontmatterKey(key, value) {
+    const rendered = reconstructFrontmatter({ [key]: value });
+    if (/\[object Object\]/.test(rendered)) {
+        throw new Error(`frontmatter: cannot faithfully serialize key "${key}" — it contains a nested object-list ` +
+            `(e.g. must_haves.artifacts) the frontmatter writer cannot represent, and serializing it would ` +
+            `emit "[object Object]". Edit the file directly instead of using frontmatter set/merge.`);
+    }
+    return rendered;
+}
 function spliceFrontmatter(content, newObj) {
     const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
     if (match) {
-        // Identity-preservation (additive, lossless round-trip): `reconstructFrontmatter` is a
-        // deliberately lossy serializer — it cannot faithfully re-emit nested object-list items
-        // (e.g. must_haves.artifacts / must_haves.prohibitions, whose items are `{ path, provides }`
-        // / `{ statement, status, … }` maps). When the caller is writing back a value that is
-        // STRUCTURALLY UNCHANGED from the original parse (the canonical CRUD round-trip and the
-        // #644 prohibition schema round-trip both do this), regenerating from the lossy object would
-        // silently mangle those blocks. Detect that case by deep-equality against a re-parse of the
-        // original frontmatter and preserve the ORIGINAL raw text verbatim — a true no-op splice.
-        // This touches neither the parser (`extractFrontmatter`) nor `parseMustHavesBlock`; it only
-        // makes the existing splice faithful when nothing changed. A genuine mutation (different
-        // object) still flows through `reconstructFrontmatter` exactly as before.
+        const fmBlock = match[0];
+        // Whole-document no-op guard: a true no-op returns content verbatim (byte-exact,
+        // including any formatting the lossy serializer would normalize).
         try {
             if (frontmatterDeepEqual(extractFrontmatter(content), newObj)) {
                 return content;
@@ -227,10 +266,63 @@ function spliceFrontmatter(content, newObj) {
         catch {
             /* fall through to regeneration on any comparison hiccup */
         }
-        const yamlStr = reconstructFrontmatter(newObj);
-        return `---\n${yamlStr}\n---` + content.slice(match[0].length);
+        // Per-key identity preservation (#1572). `reconstructFrontmatter` is a deliberately
+        // lossy serializer — it cannot faithfully re-emit nested object-list items (e.g.
+        // must_haves.artifacts / .prohibitions, whose items are `{ path, provides }` /
+        // `{ statement, status }` maps; `extractFrontmatter` flattens those to scalar
+        // strings, so a round-trip drops `provides:` and collapses the list to a malformed
+        // inline array). For any top-level key whose value is STRUCTURALLY UNCHANGED between
+        // the original parse and `newObj`, preserve that key's ORIGINAL raw text verbatim;
+        // regenerate only keys that actually changed. This generalizes the whole-document
+        // no-op guard above to per-key fidelity, so mutating `wave` no longer destroys an
+        // unrelated `must_haves` block. Keys absent from the original (genuinely new) are
+        // regenerated and appended; keys absent from `newObj` are preserved (never silently
+        // deleted by a set/merge).
+        const fmLines = fmBlock.split(/\r?\n/);
+        const inner = fmLines.slice(1, -1).join('\n'); // drop the opening `---` and closing `---`
+        let originalParsed;
+        try {
+            originalParsed = extractFrontmatter(fmBlock);
+        }
+        catch {
+            originalParsed = {};
+        }
+        const segments = sliceTopLevelFrontmatterSegments(inner);
+        const emitted = [];
+        const seen = new Set();
+        for (const seg of segments) {
+            seen.add(seg.key);
+            if (Object.prototype.hasOwnProperty.call(newObj, seg.key)) {
+                // Key is in newObj: preserve original raw text if structurally unchanged,
+                // otherwise regenerate. The key SET is defined by newObj — keys that were in
+                // the original but are absent from newObj are intentionally dropped (the real
+                // cmdSet/cmdMerge flow always passes the full merged object, so this only
+                // matters for direct unit callers and matches spliceFrontmatter's contract:
+                // the result frontmatter IS newObj).
+                if (frontmatterDeepEqual(newObj[seg.key], originalParsed[seg.key])) {
+                    emitted.push(seg.raw); // unchanged → preserve original raw text verbatim
+                }
+                else {
+                    emitted.push(regenerateFrontmatterKey(seg.key, newObj[seg.key])); // changed → regenerate (fail-closed on object-lists)
+                }
+            }
+            // else: key absent from newObj → drop (not emitted).
+        }
+        // Append genuinely-new keys not present in the original frontmatter.
+        for (const k of Object.keys(newObj)) {
+            if (!seen.has(k)) {
+                emitted.push(regenerateFrontmatterKey(k, newObj[k]));
+            }
+        }
+        const yamlStr = emitted.join('\n');
+        return `---\n${yamlStr}\n---` + content.slice(fmBlock.length);
     }
+    // No existing frontmatter — generate from scratch, fail-closed on unrepresentable values.
     const yamlStr = reconstructFrontmatter(newObj);
+    if (/\[object Object\]/.test(yamlStr)) {
+        throw new Error('frontmatter: cannot faithfully serialize the requested frontmatter — it contains a nested ' +
+            'object-list (e.g. must_haves.artifacts) the writer cannot represent. Edit the file directly.');
+    }
     return `---\n${yamlStr}\n---\n\n` + content;
 }
 /**
@@ -434,9 +526,35 @@ function cmdFrontmatterSet(cwd, filePath, field, value, raw) {
     }
     fm[field] = parsedValue;
     const newContent = spliceFrontmatter(content, fm);
+    // #1660: a no-op set (newContent unchanged) with a dict-valued field means the lossy
+    // frontmatter parser made the new value's projection equal the original's — the change
+    // did not apply (bites object-list fields like must_haves). Detection lives in the pure
+    // exported helper noOpObjectListSetError so the mutation gate (property/unit set) covers
+    // it — the cmd path itself is not in that set.
+    const noOpErr = noOpObjectListSetError(content, newContent, parsedValue);
+    if (noOpErr) {
+        output({ error: noOpErr, field }, raw, undefined);
+        return;
+    }
     (0, shell_command_projection_cjs_1.platformWriteSync)(fullPath, newContent);
     output({ updated: true, field, value: parsedValue }, raw, 'true');
 }
+/**
+ * #1660: detect a frontmatter `set` that would be a silent no-op on a dict-valued field.
+ * Returns an error message when the splice produced no content change but the new value
+ * is a dict (object-list fields like must_haves, whose `{path, provides}` items flatten to
+ * scalar strings under extractFrontmatter so a replacement can deep-equal the original's
+ * projection), else null. Scalars and scalar arrays round-trip faithfully, so idempotent
+ * sets of those are intentionally NOT flagged. Pure and unit-tested directly (the cmd path
+ * is not in Stryker's property/unit set, so the detection must be testable in isolation).
+ */
+function noOpObjectListSetError(originalContent, newContent, parsedValue) {
+    if (newContent !== originalContent)
+        return null;
+    if (parsedValue === null || typeof parsedValue !== 'object' || Array.isArray(parsedValue))
+        return null;
+    return 'frontmatter set had no effect — the supplied value is equivalent to the existing field under the frontmatter parser, which cannot faithfully round-trip object-list fields like must_haves. Edit the file directly.';
+}
 function cmdFrontmatterMerge(cwd, filePath, data, raw) {
     if (!filePath || !data) {
         error('file and data required');
@@ -489,6 +607,7 @@ module.exports = {
     parseFrontmatter: extractFrontmatter,
     reconstructFrontmatter,
     spliceFrontmatter,
+    noOpObjectListSetError,
     parseMustHavesBlock,
     FRONTMATTER_SCHEMAS,
     cmdFrontmatterGet,

package/gsd-core/bin/lib/hook-bus.cjs

@@ -0,0 +1,81 @@
+/**
+ * Hook-bus seam (ADR-1239 Phase C-1, AC4 / #1680).
+ *
+ * The lifecycle-hook ownership model, selected by the negotiated `hookBus`
+ * axis (host-integration.cts):
+ *
+ *   - `engine` — GSD owns the bus internally (in-process pub/sub). Used by
+ *     hosts that have no event bus (VS Code). Full subscribe + emit.
+ *   - `host`   — the host fires events; GSD subscribes. Handlers register
+ *     locally for a Phase-5 host binding to dispatch to; `emit` delegates to a
+ *     host-supplied emitter (fail-closed until bound — GSD does not drive a
+ *     host-owned bus).
+ *   - `none`   — no bus (Cline-rules). Degrades to rule-text instructions;
+ *     subscribe/emit are no-ops.
+ *
+ * Portable event floor — the "claude dialect" all hook-capable hosts share
+ * (sourced from src/runtime-hooks-surface.cts). Extended events are negotiated
+ * per-host (Phase 5).
+ *
+ * Minimal seam (per ADR-1239 open wire-shape question): the host-side dispatch
+ * wiring lands in Phase 5 (#1682). This slice ships the three ownership modes
+ * + the engine pub-sub + the fail-closed contract.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PORTABLE_EVENT_FLOOR = void 0;
+exports.createHookBus = createHookBus;
+exports.PORTABLE_EVENT_FLOOR = Object.freeze(['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd']);
+function createHookBus({ bus }, options = {}) {
+    if (bus !== 'host' && bus !== 'engine' && bus !== 'none') {
+        throw new TypeError(`createHookBus: bus must be 'host' | 'engine' | 'none' (got ${JSON.stringify(bus)})`);
+    }
+    if (bus === 'none') {
+        return Object.freeze({
+            bus,
+            subscribe() { },
+            emit() { },
+        });
+    }
+    if (bus === 'engine') {
+        const subs = new Map();
+        return Object.freeze({
+            bus: 'engine',
+            subscribe(event, handler) {
+                const list = subs.get(event);
+                if (list)
+                    list.push(handler);
+                else
+                    subs.set(event, [handler]);
+            },
+            emit(event, payload) {
+                const list = subs.get(event);
+                if (!list)
+                    return;
+                for (const h of list) {
+                    // Handler errors are isolated — one throwing handler must not break the bus.
+                    try {
+                        h(payload);
+                    }
+                    catch { /* swallow; bus stays up */ }
+                }
+            },
+        });
+    }
+    // host: GSD subscribes; emits go to the host-supplied emitter (fail-closed until bound).
+    const hostEmit = options.hostEmit;
+    return Object.freeze({
+        bus: 'host',
+        subscribe(_event, _handler) {
+            // Host owns the bus; GSD's subscriptions are dispatched by a Phase-5 host
+            // binding that calls the registered handlers when the host fires events.
+            // Stored host-side; locally this is a seam until that binding lands.
+        },
+        emit(event, payload) {
+            if (typeof hostEmit !== 'function') {
+                throw new Error("host hook-bus emit: no host emitter bound — the 'host' bus requires a hostEmit primitive (Phase 5 wires the concrete host).");
+            }
+            hostEmit(event, payload);
+        },
+    });
+}

package/gsd-core/bin/lib/host-integration.cjs

@@ -0,0 +1,408 @@
+'use strict';
+/**
+ * Host Integration module — ADR-1239 Phase A.
+ *
+ * Pure, additive, no-I/O module providing a closed vocabulary for host
+ * integration axes, degradation ladder, profile classification, and
+ * capability negotiation.
+ *
+ * The SINGLE source of truth for integration axes and degradation levels.
+ * All functions are pure (no side effects, no I/O).
+ *
+ * Per-CLI sourced axis VALUES (with citations) live in docs/reference/host-integration-capability-matrix.md — every value is documented or explicitly 'undocumented'.
+ */
+// ---------------------------------------------------------------------------
+// Protocol version
+// ---------------------------------------------------------------------------
+const PROTOCOL_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Undocumented sentinel — fail-closed when a host omits CLI docs for an axis
+// ---------------------------------------------------------------------------
+/**
+ * Sentinel value used when a host descriptor's CLI docs do not state a value
+ * for an axis. It VALIDATES (accepted by the validator) but NEVER propagates
+ * into effective axes — it fails closed exactly like an unknown/missing value.
+ *
+ * Do NOT add to HOST_INTEGRATION_AXES (which is the documented vocabulary).
+ */
+const UNDOCUMENTED = 'undocumented';
+// ---------------------------------------------------------------------------
+// Closed vocabulary — axes and interface points
+// ---------------------------------------------------------------------------
+const HOST_INTEGRATION_AXES = Object.freeze({
+    embeddingMode: Object.freeze(['imperative', 'declarative']),
+    commandSurface: Object.freeze(['slash-file', 'slash-programmatic', 'slash-toml', 'palette', 'prose-only']),
+    modelMode: Object.freeze(['active', 'passive']),
+    hookBus: Object.freeze(['host', 'engine', 'none']),
+    stateIO: Object.freeze(['filesystem', 'sandboxed-storage', 'session-log-append']),
+    transport: Object.freeze(['mcp', 'native-extension']),
+    runtime: Object.freeze(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']),
+    subagentToolkit: Object.freeze(['full', 'read-only']),
+});
+const INTERFACE_POINTS = Object.freeze(['command', 'dispatch', 'model', 'hooks', 'state', 'artifact']);
+// ---------------------------------------------------------------------------
+// Profile baselines
+// ---------------------------------------------------------------------------
+// Fail-closed floor: the most restrictive known value per axis, injected when a host omits an axis (degrade-closed, never assume capability).
+const SAFE_DEFAULTS = {
+    embeddingMode: 'declarative',
+    commandSurface: 'prose-only',
+    dispatch: { namedDispatch: false, nested: false, maxDepth: 0, background: false, subagentToolkit: 'read-only', backgroundDispatch: false },
+    modelMode: 'passive',
+    hookBus: 'none',
+    stateIO: 'session-log-append',
+    transport: 'mcp',
+    runtime: 'node',
+};
+const PROFILE_BASELINES = Object.freeze({
+    'programmatic-cli': Object.freeze({
+        embeddingMode: 'imperative',
+        commandSurface: 'slash-file',
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        modelMode: 'passive',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    }),
+    'declarative-cli': Object.freeze({
+        embeddingMode: 'declarative',
+        commandSurface: 'slash-file',
+        dispatch: Object.freeze({ namedDispatch: true, nested: false, maxDepth: 1, background: false, subagentToolkit: 'full', backgroundDispatch: false }),
+        modelMode: 'passive',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    }),
+    'ide': Object.freeze({
+        embeddingMode: 'imperative',
+        commandSurface: 'palette',
+        dispatch: Object.freeze({ namedDispatch: true, nested: true, maxDepth: 5, background: true, subagentToolkit: 'full', backgroundDispatch: true }),
+        modelMode: 'active',
+        hookBus: 'engine',
+        stateIO: 'sandboxed-storage',
+        transport: 'mcp',
+        runtime: 'sandboxed-web',
+    }),
+});
+// ---------------------------------------------------------------------------
+// degradationFor — plain data-table lookup (NOT clever code)
+// ---------------------------------------------------------------------------
+/**
+ * Look up the degradation level for a given interface point and partial axes.
+ *
+ * NEVER throws. Returns { level:'absent', fallback:'...', unknown:true } for
+ * any missing or unrecognised axis value.
+ */
+function degradationFor(point, axes) {
+    const UNKNOWN = {
+        level: 'absent',
+        fallback: 'unknown capability — degraded closed',
+        unknown: true,
+    };
+    switch (point) {
+        case 'command': {
+            const cs = axes.commandSurface;
+            if (cs === 'slash-file' || cs === 'slash-programmatic')
+                return { level: 'full', fallback: '' };
+            if (cs === 'slash-toml' || cs === 'palette')
+                return { level: 'degraded', fallback: 'toml/palette surface — limited command routing' };
+            if (cs === 'prose-only')
+                return { level: 'absent', fallback: 'AGENTS.md prose + skills menu' };
+            return UNKNOWN;
+        }
+        case 'dispatch': {
+            const d = axes.dispatch;
+            if (!d || typeof d !== 'object')
+                return UNKNOWN;
+            const disp = d;
+            if (disp.namedDispatch !== true || disp.maxDepth === 0) {
+                return { level: 'absent', fallback: 'single-agent inline / SDK sub-session' };
+            }
+            // maxDepth < 0 means unbounded
+            const isUnbounded = typeof disp.maxDepth === 'number' && Number.isFinite(disp.maxDepth) && disp.maxDepth < 0;
+            const depth = (typeof disp.maxDepth === 'number' && Number.isFinite(disp.maxDepth)) ? disp.maxDepth : 0;
+            const isFullDepth = isUnbounded || (disp.nested === true && depth >= 2);
+            if (isFullDepth) {
+                // Fail-closed: return 'full' ONLY when subagentToolkit is explicitly 'full';
+                // any other value (read-only, undocumented, unknown, missing) → degraded.
+                if (disp.subagentToolkit === 'full') {
+                    return { level: 'full', fallback: '' };
+                }
+                return { level: 'degraded', fallback: 'restricted/undocumented subagent toolkit — limited dispatch surface' };
+            }
+            // flat (maxDepth===1)
+            return { level: 'degraded', fallback: 'flat dispatch — waves run inline' };
+        }
+        case 'model': {
+            const mm = axes.modelMode;
+            if (mm === 'active')
+                return { level: 'full', fallback: '' };
+            if (mm === 'passive')
+                return { level: 'degraded', fallback: 'instruction-injection / per-agent model field' };
+            return UNKNOWN;
+        }
+        case 'hooks': {
+            const hb = axes.hookBus;
+            if (hb === 'host')
+                return { level: 'full', fallback: '' };
+            if (hb === 'engine')
+                return { level: 'degraded', fallback: 'engine-owned bus' };
+            if (hb === 'none')
+                return { level: 'absent', fallback: 'rule-text instructions' };
+            return UNKNOWN;
+        }
+        case 'state': {
+            const si = axes.stateIO;
+            if (si === 'filesystem')
+                return { level: 'full', fallback: '' };
+            if (si === 'sandboxed-storage')
+                return { level: 'degraded', fallback: 'sandboxed storage' };
+            if (si === 'session-log-append')
+                return { level: 'degraded', fallback: 'append-only session log' };
+            return UNKNOWN;
+        }
+        case 'artifact': {
+            const cs = axes.commandSurface;
+            if (cs === 'slash-file' || cs === 'slash-programmatic')
+                return { level: 'full', fallback: '' };
+            if (cs === 'slash-toml' || cs === 'prose-only')
+                return { level: 'degraded', fallback: 'menu / @-only' };
+            if (cs === 'palette')
+                return { level: 'absent', fallback: 'palette + chat participant; skills become LM tools' };
+            return UNKNOWN;
+        }
+        default:
+            return UNKNOWN;
+    }
+}
+// ---------------------------------------------------------------------------
+// profileOf
+// ---------------------------------------------------------------------------
+/**
+ * Classify a partial set of integration axes into a named profile.
+ * Returns null when no profile can be determined.
+ */
+function profileOf(axes) {
+    const a = axes;
+    if (a.embeddingMode === 'imperative' && a.runtime === 'sandboxed-web')
+        return 'ide';
+    if (a.embeddingMode === 'imperative')
+        return 'programmatic-cli';
+    if (a.embeddingMode === 'declarative')
+        return 'declarative-cli';
+    return null;
+}
+const DEFAULT_ENGINE = {
+    protocolVersion: PROTOCOL_VERSION,
+    axes: {
+        embeddingMode: 'imperative',
+        commandSurface: 'slash-file',
+        dispatch: { namedDispatch: true, nested: true, maxDepth: -1, background: true, subagentToolkit: 'full', backgroundDispatch: true },
+        modelMode: 'active',
+        hookBus: 'host',
+        stateIO: 'filesystem',
+        transport: 'mcp',
+        runtime: 'node',
+    },
+    known: HOST_INTEGRATION_AXES,
+};
+// ---------------------------------------------------------------------------
+// negotiateHostCapabilities
+// ---------------------------------------------------------------------------
+/**
+ * Negotiate host integration capabilities against an engine.
+ *
+ * POST-CONDITION: every effective scalar axis value is in engine.known[axis].
+ * effective never contains a value the host didn't declare AND the engine
+ * cannot drive.
+ *
+ * NEVER throws. Returns a fresh object each call (mutation-safe).
+ */
+function negotiateHostCapabilities(host, engine = DEFAULT_ENGINE) {
+    const warnings = [];
+    const h = host;
+    // Warn if protocolVersion is present but not a finite number
+    if (h.protocolVersion !== undefined && (typeof h.protocolVersion !== 'number' || !Number.isFinite(h.protocolVersion))) {
+        warnings.push(`host protocolVersion is not a finite number — using engine version ${engine.protocolVersion}`);
+    }
+    const hostPV = (typeof h.protocolVersion === 'number' && Number.isFinite(h.protocolVersion)) ? h.protocolVersion : engine.protocolVersion;
+    const enginePV = engine.protocolVersion;
+    // Warn if host declares a newer protocol version
+    if (hostPV > enginePV) {
+        warnings.push(`host protocolVersion ${hostPV} newer than engine ${enginePV} — capabilities beyond version ${enginePV} not trusted`);
+    }
+    // ---------------------------------------------------------------------------
+    // Helper: negotiate a single scalar axis
+    // ---------------------------------------------------------------------------
+    function negotiateScalar(axis) {
+        const knownValues = engine.known[axis];
+        const hostVal = h[axis];
+        const engineVal = engine.axes[axis];
+        const safeDefault = SAFE_DEFAULTS[axis];
+        if (hostVal === undefined || hostVal === null) {
+            // Host did not declare this axis
+            warnings.push(`host did not declare '${axis}'`);
+            return safeDefault;
+        }
+        if (hostVal === UNDOCUMENTED) {
+            // Host declared the undocumented sentinel — treat as fail-closed (degrade to safe default)
+            warnings.push(`host axis '${axis}' is undocumented — degraded closed`);
+            return safeDefault;
+        }
+        if (!knownValues.includes(hostVal)) {
+            // Host declared an unknown/future value — NEVER copy into effective
+            warnings.push(`host declared unknown '${axis}' value '${String(hostVal)}' — not trusted (host protocolVersion ${hostPV} vs engine ${enginePV})`);
+            return safeDefault;
+        }
+        // Engine capability cap: if the engine can't drive the host's value,
+        // use the engine's lesser capability.
+        // For modelMode: 'active' > 'passive' — if host wants active but engine
+        // is passive, cap to passive.
+        if (axis === 'modelMode') {
+            if (hostVal === 'active' && engineVal === 'passive')
+                return 'passive';
+        }
+        return hostVal;
+    }
+    // Negotiate all scalar axes
+    const effectiveEmbeddingMode = negotiateScalar('embeddingMode');
+    const effectiveCommandSurface = negotiateScalar('commandSurface');
+    const effectiveModelMode = negotiateScalar('modelMode');
+    const effectiveHookBus = negotiateScalar('hookBus');
+    const effectiveStateIO = negotiateScalar('stateIO');
+    const effectiveTransport = negotiateScalar('transport');
+    const effectiveRuntime = negotiateScalar('runtime');
+    // ---------------------------------------------------------------------------
+    // Dispatch struct negotiation
+    // ---------------------------------------------------------------------------
+    const hostDispatch = (typeof h.dispatch === 'object' && h.dispatch !== null)
+        ? h.dispatch
+        : null;
+    const engineDispatch = engine.axes.dispatch;
+    let effectiveNamedDispatch;
+    let effectiveNested;
+    let effectiveBackground;
+    let effectiveBackgroundDispatch;
+    let effectiveSubagentToolkit;
+    let effectiveMaxDepth;
+    if (hostDispatch === null) {
+        // Host didn't declare dispatch at all — fail-closed to most-restrictive values
+        warnings.push(`host did not declare 'dispatch'`);
+        effectiveNamedDispatch = false;
+        effectiveNested = false;
+        effectiveBackground = false;
+        effectiveBackgroundDispatch = false;
+        effectiveSubagentToolkit = 'read-only';
+        effectiveMaxDepth = 0;
+    }
+    else {
+        // N1: observability warnings for 'undocumented' sentinel on dispatch fields
+        if (hostDispatch.namedDispatch === 'undocumented') {
+            warnings.push(`dispatch.namedDispatch is undocumented — degraded closed`);
+        }
+        if (hostDispatch.nested === 'undocumented') {
+            warnings.push(`dispatch.nested is undocumented — degraded closed`);
+        }
+        if (hostDispatch.background === 'undocumented') {
+            warnings.push(`dispatch.background is undocumented — degraded closed`);
+        }
+        if (hostDispatch.subagentToolkit === 'undocumented') {
+            warnings.push(`dispatch.subagentToolkit is undocumented — degraded closed (read-only)`);
+        }
+        if (hostDispatch.backgroundDispatch === 'undocumented') {
+            warnings.push(`dispatch.backgroundDispatch is undocumented — degraded closed`);
+        }
+        effectiveNamedDispatch = (hostDispatch.namedDispatch === true) && engineDispatch.namedDispatch;
+        effectiveNested = (hostDispatch.nested === true) && engineDispatch.nested;
+        effectiveBackground = (hostDispatch.background === true) && engineDispatch.background;
+        effectiveBackgroundDispatch = (hostDispatch.backgroundDispatch === true) && engineDispatch.backgroundDispatch;
+        // subagentToolkit: fail closed to read-only unless explicitly 'full'
+        // (an 'undocumented' or 'read-only' value → read-only)
+        const hostToolkit = hostDispatch.subagentToolkit === 'full' ? 'full' : 'read-only';
+        const engineToolkit = engineDispatch.subagentToolkit === 'read-only' ? 'read-only' : 'full';
+        effectiveSubagentToolkit = (hostToolkit === 'read-only' || engineToolkit === 'read-only') ? 'read-only' : 'full';
+        // maxDepth: missing/non-number/non-finite → 0 + warning
+        let hostMaxDepth;
+        if (typeof hostDispatch.maxDepth !== 'number' || !Number.isFinite(hostDispatch.maxDepth)) {
+            warnings.push(`host dispatch.maxDepth is missing or not a number — treating as 0`);
+            hostMaxDepth = 0;
+        }
+        else {
+            hostMaxDepth = hostDispatch.maxDepth;
+        }
+        // Treat negative as +Infinity for the min, then if result is +Infinity emit -1
+        const hDepthNum = hostMaxDepth < 0 ? Infinity : hostMaxDepth;
+        const eDepthNum = engineDispatch.maxDepth < 0 ? Infinity : engineDispatch.maxDepth;
+        const minDepth = Math.min(hDepthNum, eDepthNum);
+        effectiveMaxDepth = minDepth === Infinity ? -1 : minDepth;
+        // If namedDispatch is false, cap maxDepth/nested/background/backgroundDispatch to 0/false/false/false (struct consistency)
+        if (!effectiveNamedDispatch) {
+            effectiveMaxDepth = 0;
+            effectiveNested = false;
+            effectiveBackground = false;
+            effectiveBackgroundDispatch = false;
+        }
+    }
+    const effectiveDispatch = {
+        namedDispatch: effectiveNamedDispatch,
+        nested: effectiveNested,
+        maxDepth: effectiveMaxDepth,
+        background: effectiveBackground,
+        subagentToolkit: effectiveSubagentToolkit,
+        backgroundDispatch: effectiveBackgroundDispatch,
+    };
+    // ---------------------------------------------------------------------------
+    // Assemble effective axes
+    // ---------------------------------------------------------------------------
+    const effective = {
+        embeddingMode: effectiveEmbeddingMode,
+        commandSurface: effectiveCommandSurface,
+        dispatch: effectiveDispatch,
+        modelMode: effectiveModelMode,
+        hookBus: effectiveHookBus,
+        stateIO: effectiveStateIO,
+        transport: effectiveTransport,
+        runtime: effectiveRuntime,
+    };
+    // ---------------------------------------------------------------------------
+    // Compute points (fresh objects — mutation-safe)
+    // ---------------------------------------------------------------------------
+    const points = {};
+    for (const point of INTERFACE_POINTS) {
+        const hostDeg = degradationFor(point, host);
+        const effectiveDeg = degradationFor(point, effective);
+        points[point] = {
+            hostLevel: hostDeg.level,
+            effectiveLevel: effectiveDeg.level,
+            fallback: effectiveDeg.fallback,
+        };
+    }
+    // protocolVersion: min of host and engine
+    const resultProtocolVersion = Math.min(hostPV, enginePV);
+    return {
+        protocolVersion: resultProtocolVersion,
+        effective,
+        points,
+        warnings: [...warnings], // fresh copy
+    };
+}
+function shouldFlattenDispatch(dispatch) {
+    if (!dispatch || typeof dispatch !== 'object')
+        return true;
+    const canBackground = dispatch.background === true && dispatch.backgroundDispatch === true;
+    return !canBackground;
+}
+module.exports = {
+    PROTOCOL_VERSION,
+    UNDOCUMENTED,
+    HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS,
+    PROFILE_BASELINES,
+    DEFAULT_ENGINE,
+    degradationFor,
+    profileOf,
+    negotiateHostCapabilities,
+    shouldFlattenDispatch,
+};