@stackstackstack/dsh-commands 0.1.5

package/lib/types/brand.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-commands' owned branded id: command lifecycle pairing across the
+ * session log, the wire admission response, and client-side flow pairing.
+ *
+ * The `Branded<B>` primitive lives in `@stackstackstack/dsh-brand`; this module
+ * is a pure type/constructor outlet (no cordis imports, no module
+ * augmentation) so wire and client programs can name the brand without
+ * loading the host plugin's Context merges — the `dsh-llm/brand` shape.
+ *
+ * @module @stackstackstack/dsh-commands/brand
+ */
+import type { Branded } from '@stackstackstack/dsh-brand';
+/**
+ * Pairs one command execution's `command/run`/`command/done` lifecycle
+ * records with each other and with the `command.execute` admission response.
+ * Minted by the executor, monotonic per service instance.
+ */
+export type CommandId = Branded<'CommandId'>;
+/**
+ * Brand a string as a {@link CommandId}.
+ * @param id - the executor-minted pairing id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CommandId(id: string): CommandId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,20 @@
+/**
+ * dsh-commands' owned branded id: command lifecycle pairing across the
+ * session log, the wire admission response, and client-side flow pairing.
+ *
+ * The `Branded<B>` primitive lives in `@stackstackstack/dsh-brand`; this module
+ * is a pure type/constructor outlet (no cordis imports, no module
+ * augmentation) so wire and client programs can name the brand without
+ * loading the host plugin's Context merges — the `dsh-llm/brand` shape.
+ *
+ * @module @stackstackstack/dsh-commands/brand
+ */
+/**
+ * Brand a string as a {@link CommandId}.
+ * @param id - the executor-minted pairing id.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CommandId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Plugin-owned human-command registry shared by interactive UI adapters.
+ * @module @stackstackstack/dsh-commands
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@stackstackstack/dsh-agent';
+import { TypertRemoteService } from '@stackstackstack/dsh-typert-protocol';
+import { CommandId } from './brand.ts';
+import type { CommandDescriptor, CommandExecution, CommandInputDescriptor, CommandResult } from './types.ts';
+export { CommandId } from './brand.ts';
+export type * from './types.ts';
+export declare const name = "commands";
+/** Invocation passed to one registered command handler. */
+export interface CommandInvocation {
+    /** Pairing id already written to this invocation's `command/run` event. */
+    readonly commandId: CommandId;
+    /** Exact agent whose UI received the command. */
+    readonly agent: Agent;
+    /** Exact text following the registered command name, including separator whitespace. */
+    readonly rawInput: string;
+    /** Cancellation signal owned by the dispatching UI request. */
+    readonly signal: AbortSignal;
+}
+/** Plugin-owned command registration. */
+export interface CommandDefinition {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Human-readable summary used in discovery UI. */
+    readonly description: string;
+    /** Optional free-form input hint advertised to capable clients. */
+    readonly input?: CommandInputDescriptor;
+    /**
+     * Whether `command/run` records `rawInput`. Defaults to true. A command
+     * whose domain event owns the payload sets this false to avoid duplicating
+     * that payload in the session log.
+     */
+    readonly recordInput?: boolean;
+    /** Execute against the receiving agent without sending the command to the model. */
+    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+}
+/** Syntactically valid slash command before registry resolution. */
+export interface ParsedCommand {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Exact text following the command name. */
+    readonly rawInput: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        commands: CommandRuntime;
+    }
+}
+/**
+ * Parse an exact slash command without normalizing its trailing input.
+ *
+ * @param line - Complete candidate command line.
+ * @returns The parsed command, or `undefined` when the line is not a command.
+ */
+export declare function parseCommand(line: string): ParsedCommand | undefined;
+/**
+ * Human-command registry. Plain-context definitions are global; definitions
+ * registered through a command-injected child of an agent context shadow
+ * globals for that agent.
+ */
+export declare class CommandRuntime extends TypertRemoteService {
+    private readonly layers;
+    /** Monotonic per-instance counter behind {@link mintCommandId}. */
+    private commandSeq;
+    /** Instance token keeping minted ids unique across process restarts over one resumed log. */
+    private readonly instanceToken;
+    constructor(ctx: Context);
+    /**
+     * Register a global or calling-agent-scoped command.
+     * @param definition - discovery metadata and direct UI handler.
+     * @returns the exact effect disposer that unregisters this definition.
+     */
+    register(definition: CommandDefinition): () => void;
+    /**
+     * List the effective immutable command descriptors for one agent.
+     * @param agent - exact receiving agent and scoped-layer key.
+     * @returns name-sorted descriptors after scoped shadowing.
+     */
+    list(agent: Agent): readonly CommandDescriptor[];
+    /**
+     * Resolve one effective command definition.
+     * @param agent - exact receiving agent and scoped-layer key.
+     * @param name - command name without a slash.
+     * @returns the scoped shadow or global definition.
+     */
+    find(agent: Agent, name: string): CommandDefinition | undefined;
+    /**
+     * Parse and execute a known command without sending it to the model.
+     *
+     * A resolved command's lifecycle is logged: `command/run` is appended
+     * before the handler is invoked and `command/done` after settlement (a
+     * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+     * log-only appends — no turn wraps them, and persistence drains them at
+     * ordinary checkpoints. Admission misses (syntax or unknown name) log
+     * nothing — they never entered a handler. A `command/run` append failure
+     * fails the execution loud; a `command/done` append failure on the
+     * handler-failure path is contained so the handler's own error stays the
+     * reported failure.
+     *
+     * @param agent - exact receiving agent.
+     * @param line - complete slash-command line.
+     * @param signal - cancellation signal owned by the UI request.
+     * @returns the settled execution (result + lifecycle pairing id), or
+     *   `undefined` when syntax or name does not resolve.
+     */
+    execute(agent: Agent, line: string, signal: AbortSignal): Promise<CommandExecution | undefined>;
+    /** Mint the next pairing id (monotonic; instance-token-prefixed so a resumed log never repeats one). */
+    private mintCommandId;
+    /**
+     * Append one log-only lifecycle event directly: no turn is opened for it and
+     * no flush is forced — persistence observes the eager `session/event` path
+     * and drains at ordinary checkpoints and teardown, like every other
+     * standalone plugin event.
+     */
+    private appendLifecycle;
+    /** Resolve global definitions followed by exact scoped shadows. */
+    private view;
+    /** Notify every registry observer without making UI refresh load-bearing. */
+    private notifyChange;
+}
+export default CommandRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,343 @@
+/**
+ * Plugin-owned human-command registry shared by interactive UI adapters.
+ * @module @stackstackstack/dsh-commands
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { NamedEntries, ScopedLayers } from '@stackstackstack/dsh-scope';
+import { TypertRemoteService, Remote } from '@stackstackstack/dsh-typert-protocol';
+import { CommandId } from "./brand.js";
+export { CommandId } from "./brand.js";
+export const name = 'commands';
+const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u;
+/** All command registrations owned by one global or scoped layer. */
+class CommandLayer {
+    commands;
+    /**
+     * Create one command layer with diagnostics specific to its ownership scope.
+     * @param scope - the scoped owner, or `undefined` for global registrations.
+     */
+    constructor(scope) {
+        this.commands = new NamedEntries(name => new Error(scope === undefined
+            ? `command "${name}" is already registered (for a per-agent variant, mount a command-injected plugin under that agent's \`agent.ctx\`)`
+            : `command "${name}" is already registered in this scope`));
+    }
+    /** @returns whether this layer owns no command registrations. */
+    isEmpty() {
+        return this.commands.isEmpty();
+    }
+}
+/**
+ * Parse an exact slash command without normalizing its trailing input.
+ *
+ * @param line - Complete candidate command line.
+ * @returns The parsed command, or `undefined` when the line is not a command.
+ */
+export function parseCommand(line) {
+    const match = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u.exec(line);
+    if (match === null)
+        return undefined;
+    const name = match[1];
+    /* v8 ignore next -- the first capture is required whenever the regular expression matches */
+    if (name === undefined)
+        return undefined;
+    return Object.freeze({ name, rawInput: line.slice(match[0].length) });
+}
+/** Convert arbitrary abort reasons to one stable rejected Error. */
+function abortError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    return new Error(typeof signal.reason === 'string' ? signal.reason : 'command aborted');
+}
+/** Render arbitrary thrown values without trusting their string coercion. */
+function renderThrown(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return '<unrenderable thrown value>';
+    }
+}
+/** Stop awaiting an uncooperative handler once its owning UI request aborts. */
+function withAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            signal.removeEventListener('abort', onAbort);
+            reject(abortError(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error instanceof Error
+                ? error
+                : new Error(`command handler rejected with a non-Error value: ${renderThrown(error)}`, { cause: error }));
+        });
+    });
+}
+/** Reject invalid command metadata before it can reach a UI protocol. */
+function normalizeDefinition(definition) {
+    if (!COMMAND_NAME.test(definition.name)) {
+        throw new TypeError(`command name "${definition.name}" must match ${String(COMMAND_NAME)}`);
+    }
+    if (typeof definition.description !== 'string') {
+        throw new TypeError(`command "${definition.name}" description must be a string`);
+    }
+    if (definition.description.trim().length === 0) {
+        throw new TypeError(`command "${definition.name}" description must not be empty`);
+    }
+    if (typeof definition.handler !== 'function') {
+        throw new TypeError(`command "${definition.name}" handler must be a function`);
+    }
+    const rawInput = definition.input;
+    let input;
+    if (rawInput !== undefined) {
+        if (typeof rawInput !== 'object' || rawInput === null || !('hint' in rawInput)
+            || typeof rawInput.hint !== 'string') {
+            throw new TypeError(`command "${definition.name}" input hint must be a string`);
+        }
+        if (rawInput.hint.trim().length === 0) {
+            throw new TypeError(`command "${definition.name}" input hint must not be empty`);
+        }
+        input = Object.freeze({ hint: rawInput.hint });
+    }
+    const normalized = Object.freeze({
+        name: definition.name,
+        description: definition.description,
+        ...input === undefined ? {} : { input },
+        ...definition.recordInput === undefined ? {} : { recordInput: definition.recordInput },
+        handler: definition.handler,
+    });
+    const descriptor = Object.freeze({
+        name: normalized.name,
+        description: normalized.description,
+        ...normalized.input === undefined ? {} : { input: normalized.input },
+    });
+    return { definition: normalized, descriptor };
+}
+/** Validate and detach an untrusted handler result at the registry boundary. */
+function normalizeResult(command, value) {
+    if (typeof value !== 'object' || value === null || !('kind' in value)) {
+        throw new TypeError(`command "${command}" handler must return a CommandResult`);
+    }
+    const result = value;
+    if (result.kind === 'success') {
+        if (result.text !== undefined && typeof result.text !== 'string') {
+            throw new TypeError(`command "${command}" success text must be a string when supplied`);
+        }
+        if (result.sourceEventSeq !== undefined
+            && (!Number.isSafeInteger(result.sourceEventSeq) || result.sourceEventSeq < 0)) {
+            throw new TypeError(`command "${command}" success sourceEventSeq must be a non-negative safe integer when supplied`);
+        }
+        return Object.freeze({
+            kind: 'success',
+            ...result.text === undefined ? {} : { text: result.text },
+            ...result.sourceEventSeq === undefined ? {} : { sourceEventSeq: result.sourceEventSeq },
+        });
+    }
+    if (result.kind === 'error') {
+        if (typeof result.text !== 'string' || result.text.trim().length === 0) {
+            throw new TypeError(`command "${command}" error text must be a non-empty string`);
+        }
+        return Object.freeze({ kind: 'error', text: result.text });
+    }
+    throw new TypeError(`command "${command}" returned unknown result kind "${String(result.kind)}"`);
+}
+/**
+ * Human-command registry. Plain-context definitions are global; definitions
+ * registered through a command-injected child of an agent context shadow
+ * globals for that agent.
+ */
+let CommandRuntime = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _execute_decorators;
+    return class CommandRuntime extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote];
+            _execute_decorators = [Remote];
+            __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _execute_decorators, { kind: "method", name: "execute", static: false, private: false, access: { has: obj => "execute" in obj, get: obj => obj.execute }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        layers = (__runInitializers(this, _instanceExtraInitializers), new ScopedLayers(scope => new CommandLayer(scope), () => { this.notifyChange(); }));
+        /** Monotonic per-instance counter behind {@link mintCommandId}. */
+        commandSeq = 0;
+        /** Instance token keeping minted ids unique across process restarts over one resumed log. */
+        instanceToken = crypto.randomUUID().slice(0, 8);
+        constructor(ctx) {
+            super(ctx, 'commands');
+        }
+        /**
+         * Register a global or calling-agent-scoped command.
+         * @param definition - discovery metadata and direct UI handler.
+         * @returns the exact effect disposer that unregisters this definition.
+         */
+        register(definition) {
+            const registered = normalizeDefinition(definition);
+            return this.layers.effect(this.ctx, layer => layer.commands.insert(registered.definition.name, registered), { label: 'commands.register()' });
+        }
+        /**
+         * List the effective immutable command descriptors for one agent.
+         * @param agent - exact receiving agent and scoped-layer key.
+         * @returns name-sorted descriptors after scoped shadowing.
+         */
+        list(agent) {
+            return Object.freeze([...this.view(agent).values()]
+                .map(command => command.descriptor)
+                // Names are unique in the effective view, so equality is impossible.
+                .sort((left, right) => left.name < right.name ? -1 : 1));
+        }
+        /**
+         * Resolve one effective command definition.
+         * @param agent - exact receiving agent and scoped-layer key.
+         * @param name - command name without a slash.
+         * @returns the scoped shadow or global definition.
+         */
+        find(agent, name) {
+            return this.view(agent).get(name)?.definition;
+        }
+        /**
+         * Parse and execute a known command without sending it to the model.
+         *
+         * A resolved command's lifecycle is logged: `command/run` is appended
+         * before the handler is invoked and `command/done` after settlement (a
+         * thrown or aborted handler settles as `kind: 'error'`). Both are direct
+         * log-only appends — no turn wraps them, and persistence drains them at
+         * ordinary checkpoints. Admission misses (syntax or unknown name) log
+         * nothing — they never entered a handler. A `command/run` append failure
+         * fails the execution loud; a `command/done` append failure on the
+         * handler-failure path is contained so the handler's own error stays the
+         * reported failure.
+         *
+         * @param agent - exact receiving agent.
+         * @param line - complete slash-command line.
+         * @param signal - cancellation signal owned by the UI request.
+         * @returns the settled execution (result + lifecycle pairing id), or
+         *   `undefined` when syntax or name does not resolve.
+         */
+        async execute(agent, line, signal) {
+            const parsed = parseCommand(line);
+            if (parsed === undefined)
+                return undefined;
+            const command = this.view(agent).get(parsed.name);
+            if (command === undefined)
+                return undefined;
+            if (signal.aborted)
+                throw abortError(signal);
+            const commandId = this.mintCommandId();
+            this.appendLifecycle(agent.session, 'command/run', {
+                commandId,
+                name: parsed.name,
+                ...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
+                source: { kind: 'user' },
+            });
+            const invocation = Object.freeze({ commandId, agent, rawInput: parsed.rawInput, signal });
+            let result;
+            try {
+                const output = command.definition.handler(invocation);
+                result = normalizeResult(parsed.name, await withAbort(Promise.resolve(output), signal));
+            }
+            catch (error) {
+                try {
+                    this.appendLifecycle(agent.session, 'command/done', {
+                        commandId, kind: 'error',
+                        text: error instanceof Error ? error.message : renderThrown(error),
+                    });
+                }
+                catch (appendError) {
+                    this.ctx.logger.warn(`command "${parsed.name}": command/done append failed: ${renderThrown(appendError)}`);
+                }
+                throw error;
+            }
+            this.appendLifecycle(agent.session, 'command/done', {
+                commandId, kind: result.kind,
+                ...result.text === undefined ? {} : { text: result.text },
+                ...result.kind === 'success' && result.sourceEventSeq !== undefined
+                    ? { sourceEventSeq: result.sourceEventSeq }
+                    : {},
+            });
+            return Object.freeze({ commandId, result });
+        }
+        /** Mint the next pairing id (monotonic; instance-token-prefixed so a resumed log never repeats one). */
+        mintCommandId() {
+            this.commandSeq += 1;
+            return CommandId(`cmd-${this.instanceToken}-${this.commandSeq}`);
+        }
+        /**
+         * Append one log-only lifecycle event directly: no turn is opened for it and
+         * no flush is forced — persistence observes the eager `session/event` path
+         * and drains at ordinary checkpoints and teardown, like every other
+         * standalone plugin event.
+         */
+        appendLifecycle(session, type, data) {
+            // Both admitted types are log-only (non-surface), but TypeScript does not
+            // reduce Session.append's conditional rest parameter through a generic
+            // type parameter. Preserve the proven two-argument call shape.
+            const appendLogOnly = session.append.bind(session);
+            return appendLogOnly(type, data);
+        }
+        /** Resolve global definitions followed by exact scoped shadows. */
+        view(agent) {
+            return this.layers.merge(agent, layer => layer.commands);
+        }
+        /** Notify every registry observer without making UI refresh load-bearing. */
+        notifyChange() {
+            // Cordis emit uses Array.map: one synchronous throw starves later listeners,
+            // and returned promises are discarded. Registry notifications are
+            // non-vetoing, so contain each callback independently.
+            for (const callback of this.ctx.events.dispatch('emit', ['commands/change'])) {
+                try {
+                    const returned = callback();
+                    void Promise.resolve(returned).catch((error) => {
+                        this.ctx.logger.warn(`commands/change listener rejected: ${renderThrown(error)}`);
+                    });
+                }
+                catch (error) {
+                    this.ctx.logger.warn(`commands/change listener threw: ${renderThrown(error)}`);
+                }
+            }
+        }
+    };
+})();
+export { CommandRuntime };
+export default CommandRuntime;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-commands`:
+ * command lifecycle events pair by commandId within one session log.
+ * @module @stackstackstack/dsh-commands/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "commands-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,60 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-commands`:
+ * command lifecycle events pair by commandId within one session log.
+ * @module @stackstackstack/dsh-commands/invariant
+ */
+const PACKAGE_NAME = '@stackstackstack/dsh-commands';
+/** Cordis companion plugin name. */
+export const name = 'commands-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Install pairing validation over loaded logs and newly appended lifecycle events. */
+const install = Object.assign((ctx, fail) => {
+    // Install-scoped so a dispose/re-register cycle re-sweeps from a clean slate.
+    const runIds = new WeakMap();
+    const validateEvent = (session, event) => {
+        if (event.type === 'command/run') {
+            const ids = runIds.get(session) ?? new Set();
+            if (ids.has(event.data.commandId)) {
+                fail(`command/run repeats commandId ${JSON.stringify(event.data.commandId)}`);
+            }
+            ids.add(event.data.commandId);
+            runIds.set(session, ids);
+            return;
+        }
+        if (event.type !== 'command/done')
+            return;
+        if (runIds.get(session)?.has(event.data.commandId) !== true) {
+            fail(`command/done ${JSON.stringify(event.data.commandId)} pairs no prior command/run in this log`);
+        }
+        const source = event.data.sourceEventSeq;
+        const sourceEvent = source === undefined ? undefined : session.events[source];
+        if (source !== undefined
+            && (event.data.kind !== 'success'
+                || !Number.isSafeInteger(source) || source < 0 || source >= event.seq
+                || sourceEvent?.seq !== source
+                || sourceEvent.type === 'command/run'
+                || sourceEvent.type === 'command/done')) {
+            fail(`command/done ${JSON.stringify(event.data.commandId)} has invalid sourceEventSeq ${String(source)}`);
+        }
+    };
+    for (const session of ctx.sessions.list()) {
+        for (const event of session.events)
+            validateEvent(session, event);
+    }
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        validateEvent(session, event);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map