@gridlock/orchestrator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intelligence Cycle and gridlock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/AgentRoute.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Agent Route Resolver — maps command types to agent roles (#855).
+ *
+ * Engine-level utility. Produces a pure data object describing which
+ * agent role a command should target. The product layer (e.g. CliRunner)
+ * interprets the route and wires execution through AgentOrchestrator.
+ *
+ * This keeps the engine free of platform-layer dependencies while
+ * providing a canonical mapping from command verbs to agent roles.
+ */
+/** Context scope determining what knowledge an agent receives. */
+export type ContextScope = 'character' | 'advisor' | 'controller';
+/** Resolved agent route for a command. */
+export interface AgentRoute {
+    /** Agent definition key (character id, 'sage', 'c-controller'). */
+    role: string;
+    /** Unique agent identifier for the request. */
+    agentId: string;
+    /** Knowledge scope to apply when building context. */
+    contextScope: ContextScope;
+    /** What to do when agent resolution fails. */
+    fallbackMode: 'deterministic';
+}
+/** Minimal game state needed by the route resolver. */
+interface RouteGameState {
+    case: {
+        characters: Array<{
+            id: string;
+            name: string;
+        }>;
+    };
+}
+/**
+ * Resolve command verb + args to an agent route.
+ * Returns null for commands that don't map to an agent role.
+ */
+export declare function resolveAgentRoute(verb: string, args: string[], gameState: RouteGameState): AgentRoute | null;
+/**
+ * Resolve the C controller agent route.
+ * Called from phase-transition logic, not from command dispatch.
+ */
+export declare function resolveControllerRoute(): AgentRoute;
+export {};
+//# sourceMappingURL=AgentRoute.d.ts.map

package/dist/AgentRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRoute.d.ts","sourceRoot":"","sources":["../src/AgentRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AAElE,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,YAAY,EAAE,YAAY,CAAC;IAC3B,8CAA8C;IAC9C,YAAY,EAAE,eAAe,CAAC;CAC/B;AAED,uDAAuD;AACvD,UAAU,cAAc;IACtB,IAAI,EAAE;QAAE,UAAU,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,cAAc,GACxB,UAAU,GAAG,IAAI,CA+BnB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,UAAU,CAOnD"}

package/dist/AgentRoute.js

@@ -0,0 +1,54 @@
+/**
+ * Agent Route Resolver — maps command types to agent roles (#855).
+ *
+ * Engine-level utility. Produces a pure data object describing which
+ * agent role a command should target. The product layer (e.g. CliRunner)
+ * interprets the route and wires execution through AgentOrchestrator.
+ *
+ * This keeps the engine free of platform-layer dependencies while
+ * providing a canonical mapping from command verbs to agent roles.
+ */
+/**
+ * Resolve command verb + args to an agent route.
+ * Returns null for commands that don't map to an agent role.
+ */
+export function resolveAgentRoute(verb, args, gameState) {
+    const v = verb.toLowerCase();
+    if (v === 'talk') {
+        // Parse "talk to <id> [message]" — target is first arg after optional "to"
+        const target = (args[0]?.toLowerCase() === 'to' ? args[1] : args[0])?.toLowerCase();
+        if (!target)
+            return null;
+        const character = gameState.case.characters.find(c => c.id === target || c.name.toLowerCase() === target);
+        if (!character)
+            return null;
+        return {
+            role: character.id,
+            agentId: character.id,
+            contextScope: 'character',
+            fallbackMode: 'deterministic',
+        };
+    }
+    if (v === 'sage') {
+        return {
+            role: 'sage',
+            agentId: 'sage',
+            contextScope: 'advisor',
+            fallbackMode: 'deterministic',
+        };
+    }
+    return null;
+}
+/**
+ * Resolve the C controller agent route.
+ * Called from phase-transition logic, not from command dispatch.
+ */
+export function resolveControllerRoute() {
+    return {
+        role: 'c-controller',
+        agentId: 'c-controller',
+        contextScope: 'controller',
+        fallbackMode: 'deterministic',
+    };
+}
+//# sourceMappingURL=AgentRoute.js.map

package/dist/AgentRoute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRoute.js","sourceRoot":"","sources":["../src/AgentRoute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,IAAc,EACd,SAAyB;IAEzB,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAE7B,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;QACjB,2EAA2E;QAC3E,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;QACpF,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAEzB,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAC9C,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CACxD,CAAC;QACF,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAE5B,OAAO;YACL,IAAI,EAAE,SAAS,CAAC,EAAE;YAClB,OAAO,EAAE,SAAS,CAAC,EAAE;YACrB,YAAY,EAAE,WAAW;YACzB,YAAY,EAAE,eAAe;SAC9B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;QACjB,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,MAAM;YACf,YAAY,EAAE,SAAS;YACvB,YAAY,EAAE,eAAe;SAC9B,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,cAAc;QACvB,YAAY,EAAE,YAAY;QAC1B,YAAY,EAAE,eAAe;KAC9B,CAAC;AACJ,CAAC"}

package/dist/CommandRegistry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * CommandRegistry — generic, extensible command dispatch for the game engine.
+ *
+ * Engine-level primitive. The Orchestrator owns one instance; product layers
+ * (TIC, or any future game) register their commands at startup via
+ * `register()`. The Orchestrator calls `dispatch()` in processCommand().
+ *
+ * This is the Core-Configure pattern applied to command routing:
+ *   - Engine provides: registry, dispatch, help generation, metadata queries
+ *   - Product provides: command verbs, handlers, help text, categories
+ */
+/** Function that executes when a command is dispatched. */
+export type CommandFn = (args: string[]) => string | Promise<string>;
+/** Metadata for a registered command. */
+export interface CommandRegistration {
+    /** The handler function — called with parsed args on dispatch. */
+    handler: CommandFn;
+    /**
+     * Whether this command mutates game state (triggers stateVersion increment,
+     * auto-save, milestone checks). Default: false.
+     */
+    mutating?: boolean;
+    /** Help text entry for this command. */
+    help?: CommandHelp;
+}
+/** Help entry for a single command. */
+export interface CommandHelp {
+    /** Usage text shown in help output, e.g. "talk to <id> [message]" */
+    usage: string;
+    /** Short description, e.g. "Interview a contact" */
+    description: string;
+    /** Category for grouping in help output, e.g. "Collection" */
+    category: string;
+}
+/**
+ * Generic command registry with plugin architecture.
+ *
+ * Commands are registered by verb (case-insensitive). Dispatch looks up the
+ * verb and calls the handler. Unknown verbs return a configurable fallback.
+ */
+export declare class CommandRegistry {
+    private commands;
+    /**
+     * Register a command handler for a verb.
+     * Overwrites any previous registration for the same verb.
+     */
+    register(verb: string, registration: CommandRegistration): void;
+    /**
+     * Register multiple commands at once.
+     */
+    registerAll(entries: Record<string, CommandRegistration>): void;
+    /** Check whether a verb is registered. */
+    has(verb: string): boolean;
+    /** Get registration metadata for a verb (or undefined). */
+    get(verb: string): CommandRegistration | undefined;
+    /** Whether the command mutates game state. */
+    isMutating(verb: string): boolean;
+    /** Dispatch a command. Returns the handler's response or a fallback for unknown verbs. */
+    dispatch(verb: string, args: string[]): Promise<string>;
+    /** All registered verbs. */
+    verbs(): string[];
+    /**
+     * Generate help text grouped by category.
+     * Categories are rendered in insertion order.
+     */
+    generateHelp(title?: string): string;
+}
+//# sourceMappingURL=CommandRegistry.d.ts.map

package/dist/CommandRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRegistry.d.ts","sourceRoot":"","sources":["../src/CommandRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAErE,yCAAyC;AACzC,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,wCAAwC;IACxC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA0C;IAE1D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,mBAAmB,GAAG,IAAI;IAI/D;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,IAAI;IAM/D,0CAA0C;IAC1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,2DAA2D;IAC3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIlD,8CAA8C;IAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,0FAA0F;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ7D,4BAA4B;IAC5B,KAAK,IAAI,MAAM,EAAE;IAIjB;;;OAGG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;CAyBrC"}

package/dist/CommandRegistry.js

@@ -0,0 +1,87 @@
+/**
+ * CommandRegistry — generic, extensible command dispatch for the game engine.
+ *
+ * Engine-level primitive. The Orchestrator owns one instance; product layers
+ * (TIC, or any future game) register their commands at startup via
+ * `register()`. The Orchestrator calls `dispatch()` in processCommand().
+ *
+ * This is the Core-Configure pattern applied to command routing:
+ *   - Engine provides: registry, dispatch, help generation, metadata queries
+ *   - Product provides: command verbs, handlers, help text, categories
+ */
+/**
+ * Generic command registry with plugin architecture.
+ *
+ * Commands are registered by verb (case-insensitive). Dispatch looks up the
+ * verb and calls the handler. Unknown verbs return a configurable fallback.
+ */
+export class CommandRegistry {
+    commands = new Map();
+    /**
+     * Register a command handler for a verb.
+     * Overwrites any previous registration for the same verb.
+     */
+    register(verb, registration) {
+        this.commands.set(verb.toLowerCase(), registration);
+    }
+    /**
+     * Register multiple commands at once.
+     */
+    registerAll(entries) {
+        for (const [verb, reg] of Object.entries(entries)) {
+            this.register(verb, reg);
+        }
+    }
+    /** Check whether a verb is registered. */
+    has(verb) {
+        return this.commands.has(verb.toLowerCase());
+    }
+    /** Get registration metadata for a verb (or undefined). */
+    get(verb) {
+        return this.commands.get(verb.toLowerCase());
+    }
+    /** Whether the command mutates game state. */
+    isMutating(verb) {
+        return this.commands.get(verb.toLowerCase())?.mutating ?? false;
+    }
+    /** Dispatch a command. Returns the handler's response or a fallback for unknown verbs. */
+    async dispatch(verb, args) {
+        const reg = this.commands.get(verb.toLowerCase());
+        if (!reg) {
+            return `Unknown command: "${verb}". Type 'help' for a list of commands.`;
+        }
+        return reg.handler(args);
+    }
+    /** All registered verbs. */
+    verbs() {
+        return Array.from(this.commands.keys());
+    }
+    /**
+     * Generate help text grouped by category.
+     * Categories are rendered in insertion order.
+     */
+    generateHelp(title) {
+        const categories = new Map();
+        for (const reg of this.commands.values()) {
+            if (!reg.help)
+                continue;
+            const cat = reg.help.category;
+            if (!categories.has(cat))
+                categories.set(cat, []);
+            categories.get(cat).push(reg.help);
+        }
+        const lines = [];
+        if (title) {
+            lines.push(title, '');
+        }
+        for (const [category, entries] of categories) {
+            lines.push(`[${category}]`);
+            for (const entry of entries) {
+                lines.push(`  ${entry.usage.padEnd(28)}— ${entry.description}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n').trimEnd();
+    }
+}
+//# sourceMappingURL=CommandRegistry.js.map

package/dist/CommandRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRegistry.js","sourceRoot":"","sources":["../src/CommandRegistry.ts"],"names":[],"mappings":"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"}

package/dist/ContextFactory.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Engine-generic ContextFactory — builds typed context objects for handler
+ * modules without coupling to the concrete Orchestrator class.
+ *
+ * Only engine-generic context builders live here:
+ *   - `collection()` — for CollectionHandlers (talk, examine, collect)
+ *   - `rice()` — for RiceHandlers (empathize, gift, flatter, challenge)
+ *
+ * TIC-specific context builders (`accusation()`, `sage()`) stay in TIC's
+ * own ContextFactory because they depend on TIC-only source interfaces
+ * (AccusationSource → AnalystWorkspace, SageSource → SageAnalyst).
+ *
+ * ## Parameterisation
+ *
+ * The factory is generic over `TState` (defaults to `EngineState`). Product
+ * layers that extend the engine state (e.g. TIC's `GameState`) can bind
+ * their state type when constructing the factory, and the context objects
+ * will carry the narrowed type through to handlers.
+ *
+ * MS-28 #1116 — Step 5.3 — Engine-generic types boundary.
+ */
+import type { EngineState, CollectionSource, RiceSource, DomainInteractionState, RiceGuidanceProvider } from './types.js';
+/**
+ * Context passed to engine-generic collection handlers.
+ *
+ * Contains state, interaction access, LLM hooks, and optional narrative
+ * dispatch / RICE guidance providers. No product-specific fields.
+ */
+export interface EngineCollectionContext<TState = EngineState> {
+    gameState: TState;
+    notifications: string[];
+    getInteractionState: (playerId: string, characterId: string) => DomainInteractionState;
+    getLLMResponse: (character: any, message: string) => Promise<string>;
+    summarizeDialogue: (character: any, message: string, response: string) => Promise<string | null>;
+    onCharacterDialogue?: (character: any, responseText: string) => void;
+    getRiceGuidance?: RiceGuidanceProvider;
+}
+/**
+ * Context passed to engine-generic RICE handlers.
+ *
+ * Minimal shape — state, notifications, and interaction state access.
+ */
+export interface EngineRiceContext<TState = EngineState> {
+    gameState: TState;
+    notifications: string[];
+    getInteractionState: (playerId: string, characterId: string) => DomainInteractionState;
+}
+/**
+ * Engine-generic context factory.
+ *
+ * Builds `EngineCollectionContext` and `EngineRiceContext` from a host that
+ * implements the corresponding source interfaces. Product layers can extend
+ * this class to add product-specific context builders (TIC adds
+ * `accusation()` and `sage()`).
+ */
+export declare class EngineContextFactory<TState = EngineState> {
+    protected readonly source: CollectionSource<TState> & RiceSource<TState>;
+    constructor(source: CollectionSource<TState> & RiceSource<TState>);
+    collection(): EngineCollectionContext<TState>;
+    rice(): EngineRiceContext<TState>;
+}
+//# sourceMappingURL=ContextFactory.d.ts.map

package/dist/ContextFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextFactory.d.ts","sourceRoot":"","sources":["../src/ContextFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAUpB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,MAAM,GAAG,WAAW;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,sBAAsB,CAAC;IACvF,cAAc,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,iBAAiB,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACjG,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,eAAe,CAAC,EAAE,oBAAoB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,GAAG,WAAW;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,sBAAsB,CAAC;CACxF;AAMD;;;;;;;GAOG;AACH,qBAAa,oBAAoB,CAAC,MAAM,GAAG,WAAW;IAElD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;gBAArD,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAG1E,UAAU,IAAI,uBAAuB,CAAC,MAAM,CAAC;IAa7C,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC;CAQlC"}

package/dist/ContextFactory.js

@@ -0,0 +1,59 @@
+/**
+ * Engine-generic ContextFactory — builds typed context objects for handler
+ * modules without coupling to the concrete Orchestrator class.
+ *
+ * Only engine-generic context builders live here:
+ *   - `collection()` — for CollectionHandlers (talk, examine, collect)
+ *   - `rice()` — for RiceHandlers (empathize, gift, flatter, challenge)
+ *
+ * TIC-specific context builders (`accusation()`, `sage()`) stay in TIC's
+ * own ContextFactory because they depend on TIC-only source interfaces
+ * (AccusationSource → AnalystWorkspace, SageSource → SageAnalyst).
+ *
+ * ## Parameterisation
+ *
+ * The factory is generic over `TState` (defaults to `EngineState`). Product
+ * layers that extend the engine state (e.g. TIC's `GameState`) can bind
+ * their state type when constructing the factory, and the context objects
+ * will carry the narrowed type through to handlers.
+ *
+ * MS-28 #1116 — Step 5.3 — Engine-generic types boundary.
+ */
+// ---------------------------------------------------------------------------
+// EngineContextFactory
+// ---------------------------------------------------------------------------
+/**
+ * Engine-generic context factory.
+ *
+ * Builds `EngineCollectionContext` and `EngineRiceContext` from a host that
+ * implements the corresponding source interfaces. Product layers can extend
+ * this class to add product-specific context builders (TIC adds
+ * `accusation()` and `sage()`).
+ */
+export class EngineContextFactory {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    collection() {
+        const s = this.source;
+        return {
+            gameState: s.getGameState(),
+            notifications: s.getNotifications(),
+            getInteractionState: s.getInteractionState.bind(s),
+            getLLMResponse: s._getLLMResponse.bind(s),
+            summarizeDialogue: s._summarizeDialogue.bind(s),
+            onCharacterDialogue: s._onCharacterDialogue?.bind(s),
+            getRiceGuidance: s._getRiceGuidance,
+        };
+    }
+    rice() {
+        const s = this.source;
+        return {
+            gameState: s.getGameState(),
+            notifications: s.getNotifications(),
+            getInteractionState: s.getInteractionState.bind(s),
+        };
+    }
+}
+//# sourceMappingURL=ContextFactory.js.map

package/dist/ContextFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextFactory.js","sourceRoot":"","sources":["../src/ContextFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA6CH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAoB;IAEV;IADrB,YACqB,MAAqD;QAArD,WAAM,GAAN,MAAM,CAA+C;IACvE,CAAC;IAEJ,UAAU;QACR,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,OAAO;YACL,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE;YAC3B,aAAa,EAAE,CAAC,CAAC,gBAAgB,EAAE;YACnC,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;YAClD,cAAc,EAAE,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;YACzC,iBAAiB,EAAE,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;YAC/C,mBAAmB,EAAE,CAAC,CAAC,oBAAoB,EAAE,IAAI,CAAC,CAAC,CAAC;YACpD,eAAe,EAAE,CAAC,CAAC,gBAAgB;SACpC,CAAC;IACJ,CAAC;IAED,IAAI;QACF,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,OAAO;YACL,SAAS,EAAE,CAAC,CAAC,YAAY,EAAE;YAC3B,aAAa,EAAE,CAAC,CAAC,gBAAgB,EAAE;YACnC,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC;SACnD,CAAC;IACJ,CAAC;CACF"}

package/dist/DialogueGate.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Dialogue Gate — generic gated dialogue with unlock bands and disclosure ceilings.
+ *
+ * Engine-generic: maps a numeric cooperation score (0–10) to a disclosure
+ * posture via configurable threshold bands. The unlock mechanism (e.g.
+ * RICE in TIC) is product-specific — the gate just reads a numeric score
+ * and determines how open an entity is.
+ *
+ * No TIC vocabulary: no suspects, crimes, cases, investigations.
+ *
+ * See issue #718.
+ */
+/** A named disclosure posture — controls how much an entity will reveal. */
+export type PostureName = string;
+/**
+ * A threshold band definition — maps a score range to a posture.
+ * Bands are evaluated in order; the first band whose `maxExclusive`
+ * exceeds the score wins. The last band is the catch-all.
+ */
+export interface ThresholdBand {
+    /** Posture name for this band (e.g. 'locked', 'guarded', 'open'). */
+    readonly posture: PostureName;
+    /** Upper bound (exclusive). Scores < maxExclusive fall into this band. */
+    readonly maxExclusive: number;
+}
+/**
+ * A disclosure ceiling — maximum revelation level an entity will reach
+ * at a given posture. Ceilings constrain what information can be
+ * disclosed even if the entity is willing to talk.
+ */
+export interface DisclosureCeiling {
+    /** Posture this ceiling applies to. */
+    readonly posture: PostureName;
+    /** Topics or categories that are forbidden at this posture. */
+    readonly forbiddenTopics: readonly string[];
+    /** Maximum verbosity level (0–1 normalized). */
+    readonly maxVerbosity: number;
+}
+/**
+ * Configuration for a DialogueGate instance.
+ * Products provide their own bands and ceilings.
+ */
+export interface DialogueGateConfig {
+    /**
+     * Ordered threshold bands. Must be sorted ascending by maxExclusive.
+     * The last band's maxExclusive should be +Infinity (catch-all).
+     */
+    readonly bands: readonly ThresholdBand[];
+    /** Optional disclosure ceilings per posture. */
+    readonly ceilings?: readonly DisclosureCeiling[];
+}
+/**
+ * Result of evaluating a cooperation score against the gate.
+ */
+export interface GateResult {
+    /** The resolved posture name. */
+    readonly posture: PostureName;
+    /** The band index (0-based) that matched. */
+    readonly bandIndex: number;
+    /** Whether the entity is in the lowest (most locked) band. */
+    readonly isLocked: boolean;
+    /** Whether the entity is in the highest (most open) band. */
+    readonly isFullyOpen: boolean;
+    /** Applicable disclosure ceiling, if configured. */
+    readonly ceiling: DisclosureCeiling | undefined;
+}
+/**
+ * Whether an entity meets a minimum cooperation threshold for interaction.
+ */
+export interface ThresholdCheck {
+    /** Whether the score meets or exceeds the threshold. */
+    readonly passes: boolean;
+    /** The current score. */
+    readonly score: number;
+    /** The required threshold. */
+    readonly threshold: number;
+    /** The shortfall (0 if passes). */
+    readonly deficit: number;
+}
+/**
+ * Default TIC-style bands on a 0–10 scale:
+ *   locked:      [0, 3)
+ *   guarded:     [3, 6)
+ *   cooperative: [6, 8)
+ *   open:        [8, +Inf)
+ */
+export declare const DEFAULT_BANDS: readonly ThresholdBand[];
+/**
+ * Evaluates a cooperation score against a gate configuration.
+ *
+ * @param score - Numeric cooperation/openness score (typically 0–10).
+ * @param config - Gate configuration with threshold bands and optional ceilings.
+ * @returns The gate evaluation result.
+ */
+export declare function evaluateGate(score: number, config: DialogueGateConfig): GateResult;
+/**
+ * Checks whether a cooperation score meets a minimum threshold.
+ *
+ * @param score - Current cooperation score.
+ * @param threshold - Minimum required score.
+ * @returns Threshold check result.
+ */
+export declare function checkThreshold(score: number, threshold: number): ThresholdCheck;
+/**
+ * Convenience: evaluates gate using the default TIC-style bands.
+ */
+export declare function evaluateDefaultGate(score: number): GateResult;
+/**
+ * Creates a gate configuration from simple posture-threshold pairs.
+ *
+ * Example:
+ *   createGateConfig(['locked', 3], ['guarded', 6], ['cooperative', 8], ['open', Infinity])
+ *
+ * is equivalent to the DEFAULT_BANDS constant.
+ */
+export declare function createGateConfig(...entries: Array<[posture: PostureName, maxExclusive: number]>): DialogueGateConfig;
+//# sourceMappingURL=DialogueGate.d.ts.map

package/dist/DialogueGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DialogueGate.d.ts","sourceRoot":"","sources":["../src/DialogueGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,aAAa,EAKxC,CAAC;AAMX;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,UAAU,CAyBlF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc,CAQ/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAE7D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,OAAO,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,GAC9D,kBAAkB,CAWpB"}

package/dist/DialogueGate.js

@@ -0,0 +1,101 @@
+/**
+ * Dialogue Gate — generic gated dialogue with unlock bands and disclosure ceilings.
+ *
+ * Engine-generic: maps a numeric cooperation score (0–10) to a disclosure
+ * posture via configurable threshold bands. The unlock mechanism (e.g.
+ * RICE in TIC) is product-specific — the gate just reads a numeric score
+ * and determines how open an entity is.
+ *
+ * No TIC vocabulary: no suspects, crimes, cases, investigations.
+ *
+ * See issue #718.
+ */
+// ---------------------------------------------------------------------------
+// Default bands (TIC defaults — products can override)
+// ---------------------------------------------------------------------------
+/**
+ * Default TIC-style bands on a 0–10 scale:
+ *   locked:      [0, 3)
+ *   guarded:     [3, 6)
+ *   cooperative: [6, 8)
+ *   open:        [8, +Inf)
+ */
+export const DEFAULT_BANDS = [
+    { posture: 'locked', maxExclusive: 3 },
+    { posture: 'guarded', maxExclusive: 6 },
+    { posture: 'cooperative', maxExclusive: 8 },
+    { posture: 'open', maxExclusive: Infinity },
+];
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Evaluates a cooperation score against a gate configuration.
+ *
+ * @param score - Numeric cooperation/openness score (typically 0–10).
+ * @param config - Gate configuration with threshold bands and optional ceilings.
+ * @returns The gate evaluation result.
+ */
+export function evaluateGate(score, config) {
+    const { bands, ceilings } = config;
+    if (bands.length === 0) {
+        throw new Error('DialogueGate: bands array must not be empty.');
+    }
+    let matchedIndex = bands.length - 1; // default to last band
+    for (let i = 0; i < bands.length; i++) {
+        if (score < bands[i].maxExclusive) {
+            matchedIndex = i;
+            break;
+        }
+    }
+    const matched = bands[matchedIndex];
+    const ceiling = ceilings?.find(c => c.posture === matched.posture);
+    return {
+        posture: matched.posture,
+        bandIndex: matchedIndex,
+        isLocked: matchedIndex === 0,
+        isFullyOpen: matchedIndex === bands.length - 1,
+        ceiling,
+    };
+}
+/**
+ * Checks whether a cooperation score meets a minimum threshold.
+ *
+ * @param score - Current cooperation score.
+ * @param threshold - Minimum required score.
+ * @returns Threshold check result.
+ */
+export function checkThreshold(score, threshold) {
+    const passes = score >= threshold;
+    return {
+        passes,
+        score,
+        threshold,
+        deficit: passes ? 0 : threshold - score,
+    };
+}
+/**
+ * Convenience: evaluates gate using the default TIC-style bands.
+ */
+export function evaluateDefaultGate(score) {
+    return evaluateGate(score, { bands: DEFAULT_BANDS });
+}
+/**
+ * Creates a gate configuration from simple posture-threshold pairs.
+ *
+ * Example:
+ *   createGateConfig(['locked', 3], ['guarded', 6], ['cooperative', 8], ['open', Infinity])
+ *
+ * is equivalent to the DEFAULT_BANDS constant.
+ */
+export function createGateConfig(...entries) {
+    if (entries.length === 0) {
+        throw new Error('DialogueGate: at least one band entry is required.');
+    }
+    const bands = entries.map(([posture, maxExclusive]) => ({
+        posture,
+        maxExclusive,
+    }));
+    return { bands };
+}
+//# sourceMappingURL=DialogueGate.js.map

package/dist/DialogueGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DialogueGate.js","sourceRoot":"","sources":["../src/DialogueGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA+EH,8EAA8E;AAC9E,uDAAuD;AACvD,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAA6B;IACrD,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC,EAAE;IACtC,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,EAAE;IACvC,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC,EAAE;IAC3C,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE;CACnC,CAAC;AAEX,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,MAA0B;IACpE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAEnC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,IAAI,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,uBAAuB;IAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;YAClC,YAAY,GAAG,CAAC,CAAC;YACjB,MAAM;QACR,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnE,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,YAAY;QACvB,QAAQ,EAAE,YAAY,KAAK,CAAC;QAC5B,WAAW,EAAE,YAAY,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;QAC9C,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,SAAiB;IAC7D,MAAM,MAAM,GAAG,KAAK,IAAI,SAAS,CAAC;IAClC,OAAO;QACL,MAAM;QACN,KAAK;QACL,SAAS;QACT,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,KAAK;KACxC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,YAAY,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAG,OAA4D;IAE/D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,KAAK,GAAoB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;QACvE,OAAO;QACP,YAAY;KACb,CAAC,CAAC,CAAC;IAEJ,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC"}