@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/handshake-serialized.cjs

@@ -0,0 +1,70 @@
+/**
+ * Serialized (out-of-process) capability-exchange handshake (ADR-1239 Phase E / #1683).
+ *
+ * Phase 1's `negotiateHostCapabilities` is IN-PROCESS (a host descriptor merged
+ * directly into the engine). Out-of-process SDK hosts (pi, VS Code) cannot share
+ * object references with the engine — they exchange a SERIALIZED capability set
+ * over a wire boundary (an MCP-style `initialize`). This module is the wire form
+ * of that handshake, kept CONSISTENT with the in-process negotiation: a request
+ * built + serialized here MUST yield the same NegotiationResult the in-process
+ * call produces for the same axes (asserted in tests/handshake-serialized.test.cjs).
+ *
+ * Wire shape (JSON — no object refs, safe across a process/IPC boundary):
+ *
+ *   request  = { protocolVersion: number, axes: Partial<HostIntegrationAxes> }
+ *   response = NegotiationResult = { protocolVersion, effective, points, warnings }
+ *
+ * The engine side delegates to negotiateHostCapabilities; the host side builds
+ * the request from a descriptor. Both round-trip through JSON so the exchange is
+ * strictly serializable (a non-JSON-safe value would break the wire contract).
+ *
+ * Pure + additive: no I/O, no global state. The companion MCP server (Phase 4)
+ * or an SDK host binds this to a real transport.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+/** The wire method name for the initialize-style exchange. */
+const HANDSHAKE_METHOD = 'gsd/host-initialize';
+/**
+ * Host side: build a JSON-serializable handshake request from a host descriptor.
+ * Accepts either `{ protocolVersion?, axes }` or a bare axes object.
+ * Defaults protocolVersion to the engine's current PROTOCOL_VERSION.
+ */
+function buildHandshakeRequest(hostDescriptor) {
+    if (!hostDescriptor || typeof hostDescriptor !== 'object') {
+        throw new TypeError('buildHandshakeRequest: host descriptor (object) is required');
+    }
+    const desc = hostDescriptor;
+    const hasAxes = Object.prototype.hasOwnProperty.call(desc, 'axes');
+    const axes = (hasAxes ? desc.axes : desc);
+    if (!axes || typeof axes !== 'object') {
+        throw new TypeError('buildHandshakeRequest: descriptor.axes (object) is required');
+    }
+    const protocolVersion = typeof desc.protocolVersion === 'number' && Number.isFinite(desc.protocolVersion)
+        ? desc.protocolVersion
+        : hostIntegration.PROTOCOL_VERSION;
+    // Force a wire round-trip so a non-JSON-safe descriptor fails HERE, not later.
+    return JSON.parse(JSON.stringify({ protocolVersion, axes }));
+}
+/**
+ * Engine side: handle a serialized handshake request → a JSON-serializable
+ * NegotiationResult. Delegates to negotiateHostCapabilities, so the result is
+ * identical to the in-process negotiation for the same axes.
+ */
+function handleHandshakeRequest(request, engine = hostIntegration.DEFAULT_ENGINE) {
+    if (!request || typeof request !== 'object') {
+        throw new TypeError('handleHandshakeRequest: request (object) is required');
+    }
+    const req = request;
+    const axes = (req.axes && typeof req.axes === 'object' ? req.axes : {});
+    const protocolVersion = req.protocolVersion;
+    const result = hostIntegration.negotiateHostCapabilities({ ...axes, ...(typeof protocolVersion === 'number' && Number.isFinite(protocolVersion) ? { protocolVersion } : {}) }, engine);
+    // Force a wire round-trip: the response must be strictly JSON-serializable.
+    return JSON.parse(JSON.stringify(result));
+}
+module.exports = {
+    HANDSHAKE_METHOD,
+    buildHandshakeRequest,
+    handleHandshakeRequest,
+};

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-sdk.cjs

@@ -0,0 +1,53 @@
+/**
+ * Host-Integration SDK — the published public surface (ADR-1239 Phase E / #1683).
+ *
+ * External host-plugin authors import ONLY from this entry. It IS the contract:
+ * everything it re-exports is public + versioned (PROTOCOL_VERSION governs the
+ * set); everything else in gsd-core is internal. An SDK smoke test
+ * (tests/sdk-smoke.test.cjs) builds a new host-plugin against this surface only
+ * — proving an external author can wire a host without reading gsd-core internals.
+ *
+ * Surface: the negotiated schema + classification, the five adapters
+ * (declarative/imperative/model/hook/state), and the serialized handshake.
+ * Frozen so the public shape cannot be mutated by consumers.
+ */
+'use strict';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hostIntegration = require("./host-integration.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterDeclarative = require("./adapter-declarative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const adapterImperative = require("./adapter-imperative.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const modelAdapter = require("./model-adapter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const hookBus = require("./hook-bus.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const stateIo = require("./state-io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const handshake = require("./handshake-serialized.cjs");
+const SDK = Object.freeze({
+    // ── Schema + protocol version ────────────────────────────────────────────
+    PROTOCOL_VERSION: hostIntegration.PROTOCOL_VERSION,
+    HOST_INTEGRATION_AXES: hostIntegration.HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS: hostIntegration.INTERFACE_POINTS,
+    PROFILE_BASELINES: hostIntegration.PROFILE_BASELINES,
+    // ── Negotiation + classification ─────────────────────────────────────────
+    negotiateHostCapabilities: hostIntegration.negotiateHostCapabilities,
+    profileOf: hostIntegration.profileOf,
+    degradationFor: hostIntegration.degradationFor,
+    hookEventSurfaceFor: hostIntegration.hookEventSurfaceFor,
+    extensionEventSurfaceFor: hostIntegration.extensionEventSurfaceFor,
+    shouldFlattenDispatch: hostIntegration.shouldFlattenDispatch,
+    // ── Embedding + engine adapters ──────────────────────────────────────────
+    createDeclarativeAdapter: adapterDeclarative.createDeclarativeAdapter,
+    createImperativeAdapter: adapterImperative.createImperativeAdapter,
+    createModelAdapter: modelAdapter.createModelAdapter,
+    createHookBus: hookBus.createHookBus,
+    createStateIO: stateIo.createStateIO,
+    // ── Serialized handshake (out-of-process SDK hosts: pi / VS Code) ─────────
+    HANDSHAKE_METHOD: handshake.HANDSHAKE_METHOD,
+    buildHandshakeRequest: handshake.buildHandshakeRequest,
+    handleHandshakeRequest: handshake.handleHandshakeRequest,
+});
+module.exports = SDK;

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

@@ -0,0 +1,469 @@
+'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;
+}
+// ---------------------------------------------------------------------------
+// Managed-hook event surface per hookEvents dialect (ADR-1239 / ADR-1016)
+// ---------------------------------------------------------------------------
+// Host-fireable MANAGED-hook events per `hookEvents` dialect. `hookEvents` is the
+// managed-hook dialect — the event names GSD writes into a DECLARATIVE host's
+// settings.json (claude = SessionStart/PreToolUse/…; gemini = BeforeTool/AfterTool).
+// This is DISTINCT from the extension-system event surface (below): a host's
+// plugin/extension API fires a different, plugin-owned event set. The two must
+// not be conflated (ADR-1239 amendment / #1943 — the former 'opencode-subset'
+// `hookEvents` value was this conflation; it is now `extensionEvents: opencode`).
+const HOOK_EVENT_SURFACES = Object.freeze({
+    claude: Object.freeze(['SessionStart', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd', 'PreCompact']),
+    gemini: Object.freeze(['SessionStart', 'BeforeTool', 'AfterTool', 'SessionEnd']),
+});
+/**
+ * Resolve the managed-hook event surface for a `hookEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ */
+function hookEventSurfaceFor(hookEvents) {
+    if (typeof hookEvents !== 'string')
+        return null;
+    return HOOK_EVENT_SURFACES[hookEvents] || null;
+}
+// ---------------------------------------------------------------------------
+// Extension-system event surface (ADR-1239 amendment / #1943)
+// ---------------------------------------------------------------------------
+// The events a host's PLUGIN/EXTENSION API exposes — for imperative-embedding
+// hosts that load GSD as a plugin. This is a SEPARATE vocabulary + descriptor
+// field (`extensionEvents`) from `hookEvents`: hookEvents = the managed-hook
+// dialect (declarative hosts' settings.json); extensionEvents = the plugin-owned
+// event subset (imperative hosts' extension API). They are not the same thing.
+//
+// Values are documentation-sourced (ADR-1239 §research): OpenCode ~25 plugin
+// events (session/tool/file/permission); pi ~30 fine-grained extension events;
+// 'none' = the host exposes no extension surface and the engine owns the bus
+// (VS Code). Declarative hosts (no plugin API) do not set `extensionEvents`.
+const EXTENSION_EVENT_SURFACES = Object.freeze({
+    opencode: Object.freeze([
+        'session.created', 'session.idle', 'experimental.session.compacting',
+        'tool.execute.before', 'tool.execute.after', 'file.edited',
+    ]),
+    pi: Object.freeze(['tool_call']),
+    none: Object.freeze([]),
+});
+/**
+ * Resolve the extension-system event surface for an `extensionEvents` dialect.
+ * Returns null for unknown/missing dialects (fail-closed). Pure, never throws.
+ *
+ * A non-null result is what makes an `extensionEvents` value a CONSUMED value
+ * rather than reserved vocab. For 'opencode' it carries NO workflow-phase events
+ * — the engine owns phase sequencing internally on such hosts (ADR-1239 §OpenCode).
+ */
+function extensionEventSurfaceFor(extensionEvents) {
+    if (typeof extensionEvents !== 'string')
+        return null;
+    return EXTENSION_EVENT_SURFACES[extensionEvents] || null;
+}
+module.exports = {
+    PROTOCOL_VERSION,
+    UNDOCUMENTED,
+    HOST_INTEGRATION_AXES,
+    INTERFACE_POINTS,
+    PROFILE_BASELINES,
+    DEFAULT_ENGINE,
+    HOOK_EVENT_SURFACES,
+    EXTENSION_EVENT_SURFACES,
+    degradationFor,
+    profileOf,
+    negotiateHostCapabilities,
+    shouldFlattenDispatch,
+    hookEventSurfaceFor,
+    extensionEventSurfaceFor,
+};