@askdkc/dsh-cli 0.11.3

package/lib/types/adapter/upstream/channel-driver.js

@@ -0,0 +1,424 @@
+/**
+ * Upstream driver for the TUI live Channel.
+ *
+ * The live Channel is a TUI host-internal stateful object, not a DSH service.
+ * The driver mounts the five Channel Host Ports (projection/actions/state/
+ * plugins/transcript) over the channel registered for the composition root.
+ * It is deliberately read-only at mount time: the HostFacade shadow wrapper
+ * gates every action method before a caller can mutate the Channel.
+ *
+ * Publication is feature-level and honest:
+ * - read-only projection/state/transcript features become live after a real
+ *   snapshot/row probe;
+ * - action/plugin mutation methods stay degraded because they cannot be
+ *   safely auto-reversed on a live TUI.
+ */
+import { lifecycleFromDetection } from '../kernel/lifecycle.js';
+import { createChannelUi, createChannelUiLease } from '../channel/ui.js';
+import { adapterRuntimeFor } from '../kernel/runtime-context.js';
+import { getTuiChannelRegistration, onTuiChannelRegistration } from '../channel/host-registry.js';
+import { createChannelActions, createChannelConsumer, createChannelPlugins, createChannelTranscript, createReplayChannelProvider, projectChannelRows, projectChannelSnapshot, projectChannelState, TUI_CHANNEL_WIRE_REVISION, } from '../channel/index.js';
+import { getRegisteredTuiChannel } from '../channel/host-registry.js';
+import { CHANNEL_FEATURES } from '../channel/features.js';
+import { CHANNEL_SPLIT_TOKEN } from '../channel/internal-token.js';
+import { withReplayIsolation } from '../kernel/replay-isolation.js';
+import { onChannelOwnerDispose } from '../../dsh-adapter/channel/owner.js';
+const CAPABILITY = 'host.channel';
+function serviceEvidence(id) {
+    return { kind: 'service', id };
+}
+function methodEvidence(service, method) {
+    return { kind: 'method', id: `${service}:${method}` };
+}
+function probeEvidence(id, detail) {
+    return { kind: 'probe', id, detail };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function channelFor(ctx) {
+    const candidate = getRegisteredTuiChannel(ctx);
+    if (candidate === null || typeof candidate !== 'object')
+        return undefined;
+    return candidate;
+}
+export function detectChannelCapability(ctx) {
+    const channel = channelFor(ctx);
+    if (channel === undefined) {
+        return { state: 'unsupported', reason: 'live TUI Channel is not registered for this composition root' };
+    }
+    const evidence = [serviceEvidence('tuiChannel')];
+    if (typeof channel.version !== 'number') {
+        return { state: 'degraded', missing: ['channel.version'], evidence };
+    }
+    if (!Array.isArray(channel.rows)) {
+        return { state: 'degraded', missing: ['channel.rows'], evidence };
+    }
+    const methods = ['submit', 'cancel', 'clear', 'notify', 'traceEvents'];
+    const missing = [];
+    for (const method of methods) {
+        if (typeof channel[method] === 'function') {
+            evidence.push(methodEvidence('tuiChannel', method));
+        }
+        else {
+            missing.push(`tuiChannel.${method}()`);
+        }
+    }
+    if (missing.length > 0)
+        return { state: 'degraded', missing, evidence };
+    return { state: 'supported', evidence };
+}
+export function verifyChannelLive(ctx) {
+    return verifyChannelLiveAsync(ctx);
+}
+async function verifyChannelLiveAsync(ctx) {
+    const lifecycles = verifyChannelLiveSync(ctx);
+    const channel = channelFor(ctx);
+    if (channel === undefined)
+        return lifecycles;
+    try {
+        // Real production use of the Provider/Consumer protocol path: project the
+        // live Channel into a `tui.dsh/v1alpha1#Channel` snapshot and validate it
+        // through the same consumer used by the replay harness. This is not a
+        // self-referential string check; it exercises the actual protocol
+        // envelope against the live Channel projection.
+        const projection = projectChannelSnapshot(channel);
+        const state = projectChannelState(channel);
+        const protocolSnapshot = {
+            wireRevision: TUI_CHANNEL_WIRE_REVISION,
+            channelId: String(projection.agentId || 'live-channel'),
+            version: projection.version,
+            state: Object.freeze({
+                ...projection,
+                ...state,
+            }),
+        };
+        // Exercise the full protocol envelope (open/subscribe/invoke/close) using
+        // the same Provider/Consumer pair as the replay harness. The only method
+        // exposed here is the read-only traceEvents projection, and it runs under
+        // replay isolation so the method-handler gate is satisfied.
+        const methods = typeof channel.traceEvents === 'function'
+            ? { traceEvents: () => channel.traceEvents() }
+            : undefined;
+        const protocolProvider = createReplayChannelProvider({
+            snapshots: [protocolSnapshot],
+            ...(methods === undefined ? {} : { methods }),
+        });
+        const protocolConsumer = createChannelConsumer(protocolProvider);
+        const subscriptionConsumer = createChannelConsumer(protocolProvider);
+        await withReplayIsolation(async () => {
+            const opened = await protocolConsumer.open({});
+            await subscriptionConsumer.subscribe(opened.channelId, 0, () => undefined);
+            if (methods !== undefined) {
+                await protocolConsumer.invoke(opened.channelId, 'traceEvents', []);
+            }
+            await protocolConsumer.close(opened.channelId);
+        });
+    }
+    catch (error) {
+        // A live Channel that cannot be represented as a protocol snapshot must
+        // never be promoted to live by the Kernel. `verifyChannelLiveSync()` may
+        // return `staged` lifecycles carrying probe evidence; the Kernel's
+        // `verifyAndPromote()` would otherwise turn them into live after this
+        // function returns. Force every channel lifecycle (including staged
+        // read-only features) to degraded when protocol validation fails.
+        const reason = `channel protocol snapshot rejected: ${errorText(error)}`;
+        return lifecycles.map(lifecycle => lifecycle.capability.startsWith('host.channel.')
+            ? lifecycleFromDetection(lifecycle.capability, {
+                state: 'degraded',
+                missing: [reason],
+                evidence: 'evidence' in lifecycle.detection ? lifecycle.detection.evidence ?? [] : [],
+            })
+            : lifecycle);
+    }
+    return lifecycles;
+}
+function liveFeature(capability, evidence) {
+    return lifecycleFromDetection(capability, { state: 'supported', evidence });
+}
+function degradedFeature(capability, evidence, missing) {
+    return lifecycleFromDetection(capability, { state: 'degraded', missing: [missing], evidence });
+}
+function verifyChannelLiveSync(ctx) {
+    const channel = channelFor(ctx);
+    const base = [serviceEvidence('tuiChannel')];
+    if (channel === undefined) {
+        return CHANNEL_FEATURES.map(feature => degradedFeature(feature, base, 'channel-not-registered'));
+    }
+    const out = [];
+    try {
+        const snapshot = projectChannelSnapshot(channel);
+        out.push(liveFeature('host.channel.projection.snapshot', [
+            serviceEvidence('tuiChannel'),
+            methodEvidence('tuiChannel', 'version'),
+            probeEvidence('channel.projection.snapshot()', `projected ${snapshot.rows.length} row(s)`),
+        ]));
+    }
+    catch (error) {
+        out.push(degradedFeature('host.channel.projection.snapshot', base, errorText(error)));
+    }
+    try {
+        const state = projectChannelState(channel);
+        out.push(liveFeature('host.channel.state.snapshot', [
+            serviceEvidence('tuiChannel'),
+            methodEvidence('tuiChannel', 'version'),
+            probeEvidence('channel.state.snapshot()', `state version ${state.version}`),
+        ]));
+    }
+    catch (error) {
+        out.push(degradedFeature('host.channel.state.snapshot', base, errorText(error)));
+    }
+    try {
+        const rows = projectChannelRows(channel.rows);
+        out.push(liveFeature('host.channel.transcript.rows', [
+            serviceEvidence('tuiChannel'),
+            methodEvidence('tuiChannel', 'rows'),
+            probeEvidence('channel.transcript.rows()', `read ${rows.length} rendered row(s)`),
+        ]));
+    }
+    catch (error) {
+        out.push(degradedFeature('host.channel.transcript.rows', base, errorText(error)));
+    }
+    try {
+        const events = channel.traceEvents();
+        if (!Array.isArray(events)) {
+            throw new TypeError('tuiChannel.traceEvents() did not return an array');
+        }
+        out.push(liveFeature('host.channel.transcript.trace-events', [
+            serviceEvidence('tuiChannel'),
+            methodEvidence('tuiChannel', 'traceEvents'),
+            probeEvidence('channel.transcript.trace-events()', `read ${events.length} DSH session event(s)`),
+        ]));
+    }
+    catch (error) {
+        out.push(degradedFeature('host.channel.transcript.trace-events', base, errorText(error)));
+    }
+    // Subscribe is a real listener on the live Channel; it can be safely
+    // registered and disposed by the Kernel wrapper, but the driver does not
+    // auto-run it in verifyLive because the running TUI already owns it.
+    out.push(degradedFeature('host.channel.projection.subscribe', base, 'host.channel.projection.subscribe.live-probe'));
+    // Mutations and plugin invocations are not safely auto-reversible on a live
+    // TUI; they remain degraded until a dedicated replay channel proves them.
+    const emitted = new Set(out.map(lifecycle => lifecycle.capability));
+    for (const feature of CHANNEL_FEATURES) {
+        if (emitted.has(feature))
+            continue;
+        out.push(degradedFeature(feature, base, `${feature}.live-probe`));
+    }
+    return out;
+}
+function requireChannel(ctx) {
+    const channel = channelFor(ctx);
+    if (channel === undefined) {
+        throw new Error('dsh-tui: live TUI Channel is not registered for this composition root');
+    }
+    return channel;
+}
+/**
+ * Captures exactly one registered Channel for one mounted Host Port.  A port
+ * may wait until its first use because the Kernel can mount before React
+ * creates the channel, but it must never silently borrow a later replacement.
+ * Registration replacement and driver disposal revoke subscriptions, returned
+ * notification handles, and nested renderer capabilities together.
+ */
+function throwCleanupFailures(failures, message) {
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, message);
+}
+function createChannelPortLease(ctx, ownDriver, isDriverActive) {
+    let active = true;
+    let captured;
+    let releaseOwnerLease;
+    const cleanups = new Set();
+    const assertActive = () => {
+        if (!active || !isDriverActive())
+            throw new Error('dsh-tui: Channel driver has been disposed');
+        if (captured !== undefined && getTuiChannelRegistration(ctx) !== captured) {
+            dispose();
+            throw new Error('dsh-tui: Channel port lifetime has ended');
+        }
+    };
+    const dispose = () => {
+        if (!active)
+            return;
+        active = false;
+        const failures = [];
+        for (const cleanup of [...cleanups]) {
+            try {
+                cleanup();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        throwCleanupFailures(failures, 'dsh-tui: Channel port cleanup failed');
+    };
+    const own = (cleanup) => {
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            cleanups.delete(release);
+            cleanup();
+        };
+        if (active)
+            cleanups.add(release);
+        else
+            release();
+        return release;
+    };
+    const channel = () => {
+        assertActive();
+        const current = getTuiChannelRegistration(ctx);
+        if (current === undefined || current.channel === null || typeof current.channel !== 'object') {
+            throw new Error('dsh-tui: live TUI Channel is not registered for this composition root');
+        }
+        if (captured === undefined) {
+            captured = current;
+            // Registry authority alone is insufficient: a retained Port must also
+            // stop immediately when its live Channel owner releases.
+            releaseOwnerLease = onChannelOwnerDispose(current.channel, dispose);
+            own(() => { releaseOwnerLease?.(); releaseOwnerLease = undefined; });
+        }
+        if (captured !== current) {
+            dispose();
+            throw new Error('dsh-tui: Channel port lifetime has ended');
+        }
+        // Registering with an already released owner revokes synchronously.
+        assertActive();
+        return current.channel;
+    };
+    const unsubscribe = onTuiChannelRegistration(ctx, next => {
+        if (captured !== undefined && next !== captured) {
+            try {
+                dispose();
+            }
+            catch { /* notification is advisory; stale lease is still revoked */ }
+        }
+    });
+    ownDriver(() => {
+        const failures = [];
+        for (const cleanup of [unsubscribe, dispose]) {
+            try {
+                cleanup();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        throwCleanupFailures(failures, 'dsh-tui: Channel driver cleanup failed');
+    });
+    return { assertActive, channel, own, dispose };
+}
+function createProjectionPort(ctx, lease) {
+    let cachedUi;
+    return Object.freeze({
+        ui() {
+            const channel = lease.channel();
+            if (cachedUi === undefined) {
+                const uiLease = createChannelUiLease(() => {
+                    lease.assertActive();
+                    return true;
+                });
+                lease.own(() => uiLease.dispose());
+                cachedUi = createChannelUi(channel, adapterRuntimeFor(ctx).mode, uiLease);
+            }
+            return cachedUi;
+        },
+        snapshot() { return projectChannelSnapshot(lease.channel()); },
+        subscribe(listener) {
+            const channel = lease.channel();
+            const unsubscribe = channel.subscribe(() => { if (leaseIsActive(lease))
+                listener(); });
+            return lease.own(unsubscribe);
+        },
+    });
+}
+function leaseIsActive(lease) {
+    try {
+        lease.assertActive();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function createStatePort(lease) {
+    return Object.freeze({ snapshot: () => projectChannelState(lease.channel()) });
+}
+function createActionsPort(lease) {
+    const actions = () => createChannelActions(lease.channel(), CHANNEL_SPLIT_TOKEN);
+    return Object.freeze({
+        submit: text => actions().submit(text),
+        steer: text => actions().steer(text),
+        cancel: () => actions().cancel(),
+        interruptAndDeliver: texts => actions().interruptAndDeliver(texts),
+        clear: () => actions().clear(),
+        loadOlder: () => actions().loadOlder(),
+        notify: (text, options) => lease.own(actions().notify(text, options)),
+    });
+}
+function createPluginsPort(lease) {
+    const plugins = () => createChannelPlugins(lease.channel(), CHANNEL_SPLIT_TOKEN);
+    return Object.freeze({
+        async runExternalCommand(name, rawInput) {
+            const result = await plugins().runExternalCommand(name, rawInput);
+            lease.assertActive();
+            return result;
+        },
+        openPluginScene: id => plugins().openPluginScene(id),
+        closePluginScene: () => plugins().closePluginScene(),
+        settingsSections: () => plugins().settingsSections(),
+        subscribeSettingsSections(listener) {
+            const unsubscribe = plugins().subscribeSettingsSections(() => { if (leaseIsActive(lease))
+                listener(); });
+            return lease.own(unsubscribe);
+        },
+    });
+}
+function createTranscriptPort(lease) {
+    const transcript = () => createChannelTranscript(lease.channel(), CHANNEL_SPLIT_TOKEN);
+    return Object.freeze({ rows: () => transcript().rows(), traceEvents: () => transcript().traceEvents() });
+}
+function createChannelPort(ctx, own, isActive) {
+    const lease = createChannelPortLease(ctx, own, isActive);
+    return Object.freeze({
+        projection: createProjectionPort(ctx, lease),
+        actions: createActionsPort(lease),
+        state: createStatePort(lease),
+        plugins: createPluginsPort(lease),
+        transcript: createTranscriptPort(lease),
+    });
+}
+export const channelDriver = {
+    id: 'dsh-tui-channel',
+    upstreamFamily: 'dsh-tui',
+    capability: CAPABILITY,
+    mountEffectClass: 'read-only',
+    detect: detectChannelCapability,
+    verifyLive: verifyChannelLive,
+    async mount(context) {
+        const disposers = new Set();
+        let active = true;
+        return {
+            disposer: () => {
+                active = false;
+                const failures = [];
+                for (const dispose of [...disposers]) {
+                    try {
+                        dispose();
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                }
+                disposers.clear();
+                throwCleanupFailures(failures, 'dsh-tui: Channel driver cleanup failed');
+            },
+            ports: { channel: createChannelPort(context, dispose => { disposers.add(dispose); }, () => active) },
+        };
+    },
+};

package/lib/types/adapter/upstream/decisions-driver.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Upstream driver for the TUI DecisionEvents capability.
+ *
+ * The read-only dispatch-topology probe is real: it asks the host which
+ * decision event names are actually dispatched in this composition. The
+ * subscribe path is intentionally kept staged on the internal Host Port
+ * because plugin-side subscriptions must go through the mediated
+ * DecisionEvents API (which derives owner from the Cordis activation); the
+ * driver never fabricates a live subscribe probe.
+ */
+import type { Detection } from './detection.js';
+import type { UpstreamDriver } from './driver.js';
+export declare function detectDecisionsCapability(ctx: unknown): Detection;
+export declare const decisionsDriver: UpstreamDriver;
+//# sourceMappingURL=decisions-driver.d.ts.map

package/lib/types/adapter/upstream/decisions-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions-driver.d.ts","sourceRoot":"","sources":["../../../../src/adapter/upstream/decisions-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,gBAAgB,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,aAAa,CAAA;AA2BtE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CA+CjE;AAoDD,eAAO,MAAM,eAAe,EAAE,cAa7B,CAAA"}

package/lib/types/adapter/upstream/decisions-driver.js

@@ -0,0 +1,141 @@
+/**
+ * Upstream driver for the TUI DecisionEvents capability.
+ *
+ * The read-only dispatch-topology probe is real: it asks the host which
+ * decision event names are actually dispatched in this composition. The
+ * subscribe path is intentionally kept staged on the internal Host Port
+ * because plugin-side subscriptions must go through the mediated
+ * DecisionEvents API (which derives owner from the Cordis activation); the
+ * driver never fabricates a live subscribe probe.
+ */
+import { lifecycleFromDetection } from '../kernel/lifecycle.js';
+import { KERNEL_TUI_DECISION_EVENT_NAMES as TUI_DECISION_EVENT_NAMES } from '../kernel/contract-catalog.js';
+const CAPABILITY = 'host.decisions';
+function serviceEvidence(id) {
+    return { kind: 'service', id };
+}
+function methodEvidence(service, method) {
+    return { kind: 'method', id: `${service}:${method}` };
+}
+function probeEvidence(id, detail) {
+    return { kind: 'probe', id, detail };
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function decisionHost(ctx) {
+    return ctx?.get?.('tuiPluginHost');
+}
+export function detectDecisionsCapability(ctx) {
+    const host = decisionHost(ctx);
+    if (host === undefined) {
+        return { state: 'unsupported', reason: 'tuiPluginHost service is not mounted' };
+    }
+    const evidence = [serviceEvidence('tuiPluginHost')];
+    if (typeof host.probeDecisionEvents === 'function') {
+        evidence.push(methodEvidence('tuiPluginHost', 'probeDecisionEvents'));
+    }
+    else {
+        return { state: 'degraded', missing: ['tuiPluginHost.probeDecisionEvents()'], evidence };
+    }
+    if (typeof host.subscribeDecision === 'function') {
+        evidence.push(methodEvidence('tuiPluginHost', 'subscribeDecision'));
+    }
+    else {
+        return {
+            state: 'degraded',
+            missing: ['tuiPluginHost.subscribeDecision()'],
+            evidence,
+        };
+    }
+    try {
+        const available = host.probeDecisionEvents();
+        if (!Array.isArray(available))
+            throw new Error('probeDecisionEvents() did not return an array');
+        if (available.length === 0) {
+            return {
+                state: 'degraded',
+                missing: ['decision-dispatch-topology'],
+                evidence: [
+                    ...evidence,
+                    probeEvidence('tuiPluginHost.probeDecisionEvents()', 'no decision dispatch topology is currently mounted'),
+                ],
+            };
+        }
+        return {
+            state: 'supported',
+            evidence: [
+                ...evidence,
+                probeEvidence('tuiPluginHost.probeDecisionEvents()', `verified ${available.length}/${TUI_DECISION_EVENT_NAMES.length} decision events`),
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            state: 'degraded',
+            missing: ['tuiPluginHost.probeDecisionEvents()'],
+            evidence: [...evidence, probeEvidence('tuiPluginHost.probeDecisionEvents()', errorText(error))],
+        };
+    }
+}
+async function verifyDecisionsLive(ctx) {
+    const detection = detectDecisionsCapability(ctx);
+    if (detection.state !== 'supported') {
+        return TUI_DECISION_EVENT_NAMES.map(event => lifecycleFromDetection(`host.decisions.event:${event}`, {
+            state: 'degraded',
+            missing: ['decision-dispatch-topology'],
+            evidence: [serviceEvidence('tuiPluginHost')],
+        }));
+    }
+    const host = decisionHost(ctx);
+    const available = host.probeDecisionEvents();
+    return TUI_DECISION_EVENT_NAMES.map(event => {
+        const verified = Array.isArray(available) && available.includes(event);
+        const feature = `host.decisions.event:${event}`;
+        return verified
+            ? lifecycleFromDetection(feature, {
+                state: 'supported',
+                evidence: [
+                    serviceEvidence('tuiPluginHost'),
+                    probeEvidence(`decision:${event}`, `real dispatch topology verified for ${event}`),
+                ],
+            })
+            : lifecycleFromDetection(feature, {
+                state: 'degraded',
+                missing: [`decision-event:${event}`],
+                evidence: [serviceEvidence('tuiPluginHost')],
+            });
+    });
+}
+function createDecisionsPort(ctx) {
+    const host = decisionHost(ctx);
+    return Object.freeze({
+        probe() {
+            if (host === undefined)
+                return [];
+            try {
+                return [...host.probeDecisionEvents()];
+            }
+            catch {
+                return [];
+            }
+        },
+        subscribe() {
+            throw new Error('dsh-tui: host.decisions.subscribe is staged; plugin subscriptions must use the mediated DecisionEvents API');
+        },
+    });
+}
+export const decisionsDriver = {
+    id: 'dsh-tui-decisions',
+    upstreamFamily: 'dsh-tui',
+    capability: 'host.decisions',
+    mountEffectClass: 'read-only',
+    detect: detectDecisionsCapability,
+    verifyLive: verifyDecisionsLive,
+    async mount(context) {
+        return {
+            disposer: () => undefined,
+            ports: { decisions: createDecisionsPort(context) },
+        };
+    },
+};

package/lib/types/adapter/upstream/detection.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Structured upstream capability detection.
+ *
+ * This is the only shape a driver may return from detect(). It is deliberately
+ * not a boolean: the kernel needs to know *why* a capability is unavailable or
+ * only partially available so diagnostics and Host Descriptor publication stay
+ * honest.
+ */
+export interface DetectionEvidence {
+    readonly kind: 'service' | 'method' | 'version' | 'contract' | 'probe';
+    readonly id: string;
+    readonly detail?: string;
+}
+export type Detection = {
+    readonly state: 'supported';
+    readonly evidence: readonly DetectionEvidence[];
+} | {
+    readonly state: 'unsupported';
+    readonly reason: string;
+} | {
+    readonly state: 'degraded';
+    readonly missing: readonly string[];
+    readonly evidence?: readonly DetectionEvidence[];
+};
+export type DetectionState = Detection['state'];
+//# sourceMappingURL=detection.d.ts.map

package/lib/types/adapter/upstream/detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../../../src/adapter/upstream/detection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAA;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,MAAM,SAAS,GACjB;IACE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAChD,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACjD,CAAA;AAEL,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA"}

package/lib/types/adapter/upstream/detection.js

@@ -0,0 +1,9 @@
+/**
+ * Structured upstream capability detection.
+ *
+ * This is the only shape a driver may return from detect(). It is deliberately
+ * not a boolean: the kernel needs to know *why* a capability is unavailable or
+ * only partially available so diagnostics and Host Descriptor publication stay
+ * honest.
+ */
+export {};

package/lib/types/adapter/upstream/driver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Upstream driver contract.
+ *
+ * Upstream drivers are the only place allowed to import `@deepseek-ai/*`.
+ * Each driver translates one DSH capability into a host Port; it does not
+ * define protocols, manifest semantics, permission policy or Host Descriptor.
+ */
+import type { CapabilityLifecycle } from '../kernel/lifecycle.js';
+import type { HostEffectClass } from '../ports/owner.js';
+import type { Detection } from './detection.js';
+export interface UpstreamDriverMount {
+    readonly disposer: () => void;
+    /** Optional host ports mounted by this driver. Keys are the HostFacade
+     * port names (for example `workspace`, `scenes`, `settings`). */
+    readonly ports?: Readonly<Record<string, unknown>>;
+}
+export interface UpstreamDriver {
+    readonly id: string;
+    readonly upstreamFamily: string;
+    readonly capability: string;
+    /** Must return structured Detection, never a bare boolean. */
+    detect(context: unknown): Detection;
+    /**
+     * Optional synchronous evidence-based lifecycle projection. Drivers that
+     * cover several publishable contracts (for example the host-descriptor
+     * driver) use this instead of a single generic Detection so the Kernel can
+     * run `declared → staged → live` over all contracts in one place.
+     */
+    lifecycles?(context: unknown): readonly CapabilityLifecycle[];
+    /**
+     * Optional asynchronous live verification. This is where reversible probes
+     * live (temporary command registration, isolated storage file, temporary
+     * observer subscription). The Kernel calls it only outside passive shadow /
+     * real-service replay; the replay harness may call it on isolated mock
+     * context.
+     */
+    verifyLive?(context: unknown): Promise<readonly CapabilityLifecycle[]>;
+    /**
+     * Effect class produced by this driver's mount. The Kernel enforces the
+     * unified shadow policy before calling `mount`, so passive/replay production
+     * modes cannot obtain real effects through a driver mount.
+     */
+    readonly mountEffectClass: HostEffectClass;
+    /**
+     * Mount this driver into a kernel runtime. The kernel supplies Ports; the
+     * driver performs only translation and returns a disposal handle.
+     */
+    mount(context: unknown, kernelPorts: unknown): Promise<UpstreamDriverMount>;
+}
+//# sourceMappingURL=driver.d.ts.map

package/lib/types/adapter/upstream/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../../src/adapter/upstream/driver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;IAC7B;qEACiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,8DAA8D;IAC9D,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC;;;;;OAKG;IACH,UAAU,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,mBAAmB,EAAE,CAAA;IAC7D;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAA;IACtE;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAA;IAC1C;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAC5E"}