@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/compat/settings.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type Schema from '@deepseek-ai/schemastery';
+/** New Cordis configs wrap editable fields; old hosts pass plain values. */
+export type RuntimeConfig<T> = {
+    [K in keyof T]: T[K] | {
+        get(): T[K];
+    };
+};
+/** Declare only UI preferences as live fields, never the agent/session route. */
+export declare function editableConfig<T>(schema: Schema<T>, keys: readonly (keyof T)[]): Schema<T, RuntimeConfig<T>>;
+/** Settings forms use the Config owner's Loader ID, not the plugin name. */
+export declare function resolveSettingsNamespace(ctx: Context, schema: Pick<Schema, 'dict'>): string;
+/** Snapshot at an operation boundary; retain the host refs for later updates. */
+export declare function configValues<T extends object>(config: RuntimeConfig<T>): T;
+interface SettingsScope<T> {
+    get(): T;
+    watch(callback: (next: T) => void): () => void;
+}
+/**
+ * 0.1.7 owns settings in Config; older hosts still own registered scopes.
+ * Pass the Config owner's context, and dispose watch with the consumer's lifecycle.
+ */
+export declare function createSettingsScope<T>(ctx: Context, service: unknown, ns: string, schema: Schema<T>, current: () => T): SettingsScope<T> & {
+    legacy: boolean;
+};
+/** New settings forms expose values through describe(), not get(). */
+export declare function settingsValue(settings: {
+    get?(ns: string): unknown;
+    describe(): readonly {
+        ns: string;
+        value?: unknown;
+    }[];
+}, ns: string): unknown;
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/dsh-adapter/compat/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,MAAM,MAAM,0BAA0B,CAAA;AAElD,4EAA4E;AAC5E,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG;QAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE;CAAE,CAAA;AAEzE,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAM5G;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAU3F;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAO1E;AAED,UAAU,aAAa,CAAC,CAAC;IACvB,GAAG,IAAI,CAAC,CAAA;IACR,KAAK,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CAC/C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,MAAM,CAAC,GACf,aAAa,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAgBxC;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,QAAQ,EAAE;IACtC,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,QAAQ,IAAI,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACvD,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAEtB"}

package/lib/types/dsh-adapter/compat/settings.js

@@ -0,0 +1,57 @@
+/** Declare only UI preferences as live fields, never the agent/session route. */
+export function editableConfig(schema, keys) {
+    for (const key of keys) {
+        const field = schema.dict?.[String(key)];
+        if (field !== undefined && typeof field.volatile === 'function')
+            schema.dict[String(key)] = field.volatile();
+    }
+    return schema;
+}
+/** Settings forms use the Config owner's Loader ID, not the plugin name. */
+export function resolveSettingsNamespace(ctx, schema) {
+    const settings = ctx.get('settings');
+    if (!settings || typeof settings.register === 'function')
+        return 'dsh-tui';
+    if (!Object.values(schema.dict ?? {}).some(field => field.meta.volatile === true)) {
+        throw new Error('dsh-tui: profile-backed settings require @deepseek-ai/schemastery >= 3.18.3 with volatile Config support. Update DSH and reinstall the current profile dependencies before starting the TUI.');
+    }
+    const owner = ctx.fiber;
+    const ns = owner.entry?.options.id;
+    if (!ns)
+        throw new Error('dsh-tui: profile-backed settings require a Loader entry for the Config owner.');
+    return ns;
+}
+/** Snapshot at an operation boundary; retain the host refs for later updates. */
+export function configValues(config) {
+    return Object.fromEntries(Object.entries(config).map(([key, value]) => [
+        key,
+        value !== null && typeof value === 'object' && 'get' in value && typeof value.get === 'function'
+            ? value.get()
+            : value,
+    ]));
+}
+/**
+ * 0.1.7 owns settings in Config; older hosts still own registered scopes.
+ * Pass the Config owner's context, and dispose watch with the consumer's lifecycle.
+ */
+export function createSettingsScope(ctx, service, ns, schema, current) {
+    const settings = service;
+    if (typeof settings.register === 'function') {
+        const scope = settings.register(ns, schema);
+        return { legacy: true, get: () => scope.get(), watch: callback => scope.watch(callback) };
+    }
+    return {
+        legacy: false,
+        get: current,
+        watch(callback) {
+            // The event is absent from the old framework's type map. Cordis owns
+            // listener disposal and emits it only to the updated plugin fiber.
+            const events = ctx;
+            return events.on('loader/volatile-update', () => callback(current()));
+        },
+    };
+}
+/** New settings forms expose values through describe(), not get(). */
+export function settingsValue(settings, ns) {
+    return typeof settings.get === 'function' ? settings.get(ns) : settings.describe().find(row => row.ns === ns)?.value;
+}

package/lib/types/dsh-adapter/compat/shell.d.ts

@@ -0,0 +1,25 @@
+/** Foreground shell seam across the legacy run() and 0.1.7 execute() APIs. */
+export interface ShellRequest {
+    command: string;
+    workdir?: string;
+    timeoutMs: number;
+}
+export interface ShellResult {
+    stdout: {
+        text: string;
+    };
+    stderr: {
+        text: string;
+    };
+    timedOut: boolean;
+}
+export interface ForegroundShell {
+    resolve(request: ShellRequest): unknown;
+    run?(spec: unknown): Promise<ShellResult>;
+    execute?(spec: unknown): Promise<{
+        result(): Promise<ShellResult>;
+    }>;
+}
+/** Resolve through the host so workspace, timeout and sandbox policy survive. */
+export declare function runForegroundShell(shell: ForegroundShell, request: ShellRequest): Promise<ShellResult>;
+//# sourceMappingURL=shell.d.ts.map

package/lib/types/dsh-adapter/compat/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/shell.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAA;IACvC,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACzC,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAA;CACrE;AAED,iFAAiF;AACjF,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ5G"}

package/lib/types/dsh-adapter/compat/shell.js

@@ -0,0 +1,11 @@
+/** Resolve through the host so workspace, timeout and sandbox policy survive. */
+export async function runForegroundShell(shell, request) {
+    const spec = shell.resolve(request);
+    if (typeof shell.execute === 'function') {
+        const execution = await shell.execute(spec);
+        return execution.result();
+    }
+    if (typeof shell.run === 'function')
+        return shell.run(spec);
+    throw new Error('dsh-tui: shell provides neither execute() nor run()');
+}

package/lib/types/dsh-adapter/component-identity.d.ts

@@ -0,0 +1,33 @@
+/** Verified Component identity bound to one Cordis activation owner. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ComponentManifest, PluginManifest } from '../adapter/standard/types.js';
+export type ComponentIdentityErrorCode = 'COMPONENT_NOT_ADMITTED' | 'COMPONENT_ALREADY_ADMITTED';
+export declare class ComponentIdentityError extends Error {
+    readonly code: ComponentIdentityErrorCode;
+    constructor(code: ComponentIdentityErrorCode, message: string);
+}
+export interface VerifiedComponentIdentity {
+    readonly componentId: string;
+    readonly version: string;
+    readonly facet: 'host';
+    readonly activationId: string;
+    readonly manifest: PluginManifest;
+    readonly projection: ComponentManifest;
+}
+/** Activation ids are host-issued opaque values. Keep them bounded and free
+ * of control characters because the same value is written to the effect
+ * ledger and used as a grant principal selector. */
+export declare const ACTIVATION_ID_MAX_LENGTH = 128;
+export declare function bindComponentIdentity(context: Context, manifest: PluginManifest, projection: ComponentManifest, activationId?: string): VerifiedComponentIdentity;
+export declare function componentIdentityOf(context: Context): VerifiedComponentIdentity | undefined;
+export declare function requireComponentIdentity(context: Context): VerifiedComponentIdentity;
+export declare function declaresPermission(identity: VerifiedComponentIdentity, permission: string, actualScope: string): boolean;
+export declare function declaresCommand(identity: VerifiedComponentIdentity, commandId: string): boolean;
+export declare function declaresObserverScope(identity: VerifiedComponentIdentity, actualScope: string): boolean;
+export declare function requiresDecisionEvents(identity: VerifiedComponentIdentity): boolean;
+/** Whether admission negotiated the protocol that backs a mediated runtime
+ * capability.  Permissions alone are not a capability grant: a plugin must
+ * explicitly require the corresponding contract before the host can expose
+ * its calls. */
+export declare function requiresContract(identity: VerifiedComponentIdentity, apiVersion: string, kind: string): boolean;
+//# sourceMappingURL=component-identity.d.ts.map

package/lib/types/dsh-adapter/component-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-identity.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/component-identity.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAGxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAIrF,MAAM,MAAM,0BAA0B,GAAG,wBAAwB,GAAG,4BAA4B,CAAA;AAEhG,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,0BAA0B;gBAAhC,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM;CAIvE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;CACvC;AAED;;oDAEoD;AACpD,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAqB3C,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,cAAc,EACxB,UAAU,EAAE,iBAAiB,EAC7B,YAAY,GAAE,MAAqB,GAClC,yBAAyB,CAyB3B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,yBAAyB,GAAG,SAAS,CAM3F;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,yBAAyB,CASpF;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,yBAAyB,EACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAQT;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAE/F;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,yBAAyB,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAUvG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAEnF;AAED;;;gBAGgB;AAChB,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,yBAAyB,EACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAGT"}

package/lib/types/dsh-adapter/component-identity.js

@@ -0,0 +1,108 @@
+/** Verified Component identity bound to one Cordis activation owner. */
+import { randomUUID } from 'node:crypto';
+import { normalizePermissionScope, scopeCovers } from '../adapter/standard/permission-scope.js';
+import { activationFiber, bindCallerEffect } from './host-access.js';
+export class ComponentIdentityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ComponentIdentityError';
+    }
+}
+/** Activation ids are host-issued opaque values. Keep them bounded and free
+ * of control characters because the same value is written to the effect
+ * ledger and used as a grant principal selector. */
+export const ACTIVATION_ID_MAX_LENGTH = 128;
+function validateActivationId(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > ACTIVATION_ID_MAX_LENGTH
+        || /[\x00-\x1f\x7f-\x9f]/u.test(value)) {
+        throw new ComponentIdentityError('COMPONENT_NOT_ADMITTED', `activationId must be a non-empty control-free string of at most ${ACTIVATION_ID_MAX_LENGTH} characters`);
+    }
+    return value;
+}
+const identities = new WeakMap();
+function ownerKey(context) {
+    const fiber = activationFiber(context);
+    if (fiber !== undefined)
+        return fiber;
+    throw new ComponentIdentityError('COMPONENT_NOT_ADMITTED', 'a Component activation requires an owning Cordis fiber');
+}
+export function bindComponentIdentity(context, manifest, projection, activationId = randomUUID()) {
+    const key = ownerKey(context);
+    if (identities.has(key)) {
+        throw new ComponentIdentityError('COMPONENT_ALREADY_ADMITTED', 'this activation already has a verified Component identity');
+    }
+    const identity = Object.freeze({
+        componentId: projection.metadata.name,
+        version: projection.metadata.version,
+        facet: 'host',
+        activationId: validateActivationId(activationId),
+        manifest,
+        projection,
+    });
+    identities.set(key, identity);
+    const release = () => {
+        if (identities.get(key) === identity)
+            identities.delete(key);
+    };
+    if (!bindCallerEffect(context, release)) {
+        identities.delete(key);
+        throw new ComponentIdentityError('COMPONENT_NOT_ADMITTED', 'cannot bind Component identity to an inactive activation');
+    }
+    return identity;
+}
+export function componentIdentityOf(context) {
+    try {
+        return identities.get(ownerKey(context));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function requireComponentIdentity(context) {
+    const identity = componentIdentityOf(context);
+    if (identity === undefined) {
+        throw new ComponentIdentityError('COMPONENT_NOT_ADMITTED', 'the calling activation has no verified dsh-plugin.json Component identity');
+    }
+    return identity;
+}
+export function declaresPermission(identity, permission, actualScope) {
+    const actual = normalizePermissionScope(permission, actualScope, identity.componentId);
+    if (actual === undefined)
+        return false;
+    return identity.manifest.permissions.some(request => {
+        if (request.name !== permission)
+            return false;
+        const declared = normalizePermissionScope(permission, request.scope, identity.componentId);
+        return declared !== undefined && scopeCovers(declared, actual);
+    });
+}
+export function declaresCommand(identity, commandId) {
+    return identity.manifest.contributes.commands.some(command => command.id === commandId);
+}
+export function declaresObserverScope(identity, actualScope) {
+    const actual = normalizePermissionScope('messages.observe.read', actualScope, identity.componentId);
+    if (actual === undefined)
+        return false;
+    return identity.manifest.subscriptions.some(subscription => {
+        if (typeof subscription === 'string')
+            return subscription === 'messages.observe';
+        if (subscription.apiVersion !== 'messages.dsh/v1alpha1' || subscription.kind !== 'MessageObserver')
+            return false;
+        if (subscription.scope === undefined)
+            return true;
+        const declared = normalizePermissionScope('messages.observe.read', subscription.scope, identity.componentId);
+        return declared !== undefined && scopeCovers(declared, actual);
+    });
+}
+export function requiresDecisionEvents(identity) {
+    return requiresContract(identity, 'tui.dsh/v1alpha1', 'DecisionEvents');
+}
+/** Whether admission negotiated the protocol that backs a mediated runtime
+ * capability.  Permissions alone are not a capability grant: a plugin must
+ * explicitly require the corresponding contract before the host can expose
+ * its calls. */
+export function requiresContract(identity, apiVersion, kind) {
+    return identity.manifest.requires.contracts.some(requirement => requirement.apiVersion === apiVersion && requirement.kind === kind);
+}

package/lib/types/dsh-adapter/contract.d.ts

@@ -0,0 +1,91 @@
+/** Primary validated upstream line (newest). */
+export declare const UPSTREAM_VALIDATED_VERSION = "0.1.7-rc.2";
+/**
+ * Explicitly supported upstream prerelease lines, oldest first.
+ *
+ * 0.1.7-rc.2 = primary continuous-CI line; 0.1.7-rc.1 = previous 0.1.7
+ * build (mapped compatibility); 0.1.5-rc.1/alpha.2/alpha.1 = mapped
+ * compatibility lines (source-checked when the primary line moves);
+ * 0.1.3-alpha.2 = compatibility line (the only 0.1.3 build on npm);
+ * 0.1.2-rc.1 = previous family (full CI coverage); 0.1.2-alpha.3–alpha.5 =
+ * mapped compatibility lines; 0.1.1-rc.1/rc.2 = compatibility lines
+ * (install- and type-level compatibility); 0.1.0-rc.7/rc.8 = full CI
+ * coverage; 0.1.0-rc.6 = legacy line (install- and type-level
+ * compatibility, feature surface may lack later additions — new features
+ * must degrade gracefully there).
+ * The peer range in package.json is deliberately wider than this list: an
+ * install on an older or newer line is allowed but reports drift at boot.
+ */
+export declare const UPSTREAM_VALIDATED_VERSIONS: readonly ["0.1.0-rc.6", "0.1.0-rc.7", "0.1.0-rc.8", "0.1.1-rc.1", "0.1.1-rc.2", "0.1.2-alpha.3", "0.1.2-alpha.4", "0.1.2-alpha.5", "0.1.2-rc.1", "0.1.3-alpha.2", "0.1.5-alpha.1", "0.1.5-alpha.2", "0.1.5-rc.1", "0.1.7-rc.1", "0.1.7-rc.2"];
+/**
+ * Framework packages version on their own lines; the contract validates
+ * their MAJOR (breaking surface), not the harness prerelease number.
+ */
+export declare const UPSTREAM_FRAMEWORK_MAJORS: Record<string, number>;
+/** Official packages the adapter consumes at runtime or as types. */
+export declare const UPSTREAM_BLESSED_PACKAGES: readonly ["@deepseek-ai/cordis", "@deepseek-ai/schemastery", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-agent-preset-registry", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-ptc-runtime-node", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-cordis-host-runner", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@deepseek-ai/dsh-persona", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-storage", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-workspace", "@deepseek-ai/dsh-web-app", "@deepseek-ai/dsh-system-prompt", "@deepseek-ai/dsh-terminal", "@deepseek-ai/dsh-terminal-bash", "@deepseek-ai/dsh-tool-ask-user", "@deepseek-ai/dsh-tool-bash-persistent", "@deepseek-ai/dsh-tool-cordis", "@deepseek-ai/dsh-tool-subagent", "@deepseek-ai/dsh-user-approval", "@deepseek-ai/dsh-user-questions"];
+export interface UpstreamDriftEntry {
+    package: string;
+    installed: string | undefined;
+    validated: string;
+}
+/** Supported upstream prerelease channels in ascending precedence order. */
+export type UpstreamPrereleaseChannel = 'alpha' | 'beta' | 'rc';
+/** A parsed upstream prerelease version, e.g. `0.1.2-alpha.1` → `[0, 1, 2, 'alpha', 1]`. */
+export type UpstreamVersionTuple = readonly [number, number, number, UpstreamPrereleaseChannel, number];
+/** Parse an upstream prerelease version; undefined when unparseable. */
+export declare function parseUpstreamVersion(version: string | undefined): UpstreamVersionTuple | undefined;
+/** Order two parsed versions: negative/positive/zero as a `<`/`>`/`=`. */
+export declare function compareVersions(a: UpstreamVersionTuple, b: UpstreamVersionTuple): number;
+/** Human-readable summary of the exact validated prerelease lines. */
+export declare const UPSTREAM_VALIDATED_LABEL: string;
+export declare function installedUpstreamVersions(): Record<string, string | undefined>;
+/**
+ * The installed upstream version of one blessed package, parsed; undefined
+ * when missing or not on a supported `x.y.z-(alpha|beta|rc).n` line. Feature gates
+ * compare this against the line a behavior was introduced on, so the
+ * adapter degrades on older installs instead of calling APIs they do not
+ * have.
+ */
+export declare function installedUpstreamVersion(packageName: string): UpstreamVersionTuple | undefined;
+/**
+ * Whether the installed version of `packageName` is at or beyond `minimum`
+ * (a literal like `'0.1.0-rc.8'`). Unparseable or older installs return
+ * false so features introduced on the minimum line degrade gracefully.
+ */
+export declare function installedMeetsVersion(packageName: string, minimum: string): boolean;
+/**
+ * The distinct installed prerelease versions across the blessed harness
+ * packages (framework packages excluded). One entry = coherent install;
+ * several = a mixed tree, which the per-package drift check cannot see.
+ * Empty when nothing (or no harness package) is installed.
+ */
+export declare function installedUpstreamLines(installedVersions?: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * Report every blessed package whose installed version is NOT one of the
+ * validated release lines. Empty array = the running install matches the
+ * contract.
+ */
+export declare function upstreamDrift(installedVersions?: Readonly<Record<string, string | undefined>>): UpstreamDriftEntry[];
+/**
+ * Classification of a drifted install for the one-line boot notice:
+ * `newer` / `older` — every drifted harness package sits on a single
+ * parseable version off one end of the validated window; `mixed` — several
+ * distinct versions coexist (unstable tree); `broken` — something is
+ * missing or unparseable and wording cannot get more specific.
+ */
+export type UpstreamDriftKind = 'newer' | 'older' | 'mixed' | 'broken';
+/** Merged drift verdict consumed by the logo header notice (LogoV2). */
+export interface UpstreamDriftSummary {
+    kind: UpstreamDriftKind;
+    /** Distinct installed versions among drifted packages ('missing' for absent ones). */
+    versions: string[];
+}
+/**
+ * Collapse {@link upstreamDrift} into a single summary for the boot notice:
+ * undefined when the install matches the contract. Only harness prerelease packages
+ * decide newer/older/mixed; a framework-only drift (e.g. a cordis major
+ * bump) reports `broken`, since its version line is not comparable.
+ */
+export declare function upstreamDriftSummary(installedVersions?: Readonly<Record<string, string | undefined>>): UpstreamDriftSummary | undefined;
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/dsh-adapter/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAkBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,+OAgB9B,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,o8BA+B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAUD,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,CAAA;AAEvG,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAKlG;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAQxF;AAkBD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAA6D,CAAA;AAYlG,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,MAAM,EAAE,CAQV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,kBAAkB,EAAE,CAuBtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,oBAAoB,GAAG,SAAS,CA0BlC"}