@with-logic/elwood 0.1.3 → 0.2.0

package/dist/core/questions/notification-errors.js

@@ -0,0 +1,45 @@
+/** Finish independent question notifications before surfacing observer failures (PRD §4). */
+export class QuestionObserverFailure extends Error {
+    originalError;
+    constructor(originalError) {
+        super("A question lifecycle observer failed.");
+        this.name = "QuestionObserverFailure";
+        this.originalError = originalError;
+    }
+}
+/** Synchronous, nested scopes retain only the first known notification failure. */
+export class QuestionNotificationErrors {
+    depth = 0;
+    failure;
+    run(operation) {
+        this.depth += 1;
+        let failure;
+        let result;
+        try {
+            result = operation();
+        }
+        finally {
+            this.depth -= 1;
+            if (this.depth === 0) {
+                failure = this.failure;
+                this.failure = undefined;
+            }
+        }
+        // A primary operation exception bypasses this point after resetting the batch.
+        if (failure)
+            throw failure;
+        return result;
+    }
+    /** Capture only known registry notification operations, never arbitrary work. */
+    capture(operation) {
+        this.run(() => {
+            try {
+                operation();
+            }
+            catch (error) {
+                this.failure ??= new QuestionObserverFailure(error);
+            }
+        });
+    }
+}
+//# sourceMappingURL=notification-errors.js.map

package/dist/core/questions/notification-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-errors.js","sourceRoot":"","sources":["../../../src/core/questions/notification-errors.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACvC,aAAa,CAAU;IAChC,YAAY,aAAsB;QAChC,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,0BAA0B;IAC7B,KAAK,GAAG,CAAC,CAAC;IACV,OAAO,CAAsC;IAErD,GAAG,CAAI,SAAkB;QACvB,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAChB,IAAI,OAA4C,CAAC;QACjD,IAAI,MAAS,CAAC;QACd,IAAI,CAAC;YACH,MAAM,GAAG,SAAS,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;YAChB,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;gBACvB,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,+EAA+E;QAC/E,IAAI,OAAO;YAAE,MAAM,OAAO,CAAC;QAC3B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,SAAqB;QAC3B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE;YACZ,IAAI,CAAC;gBACH,SAAS,EAAE,CAAC;YACd,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,OAAO,KAAK,IAAI,uBAAuB,CAAC,KAAK,CAAC,CAAC;YACtD,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/core/questions/observers.d.ts

@@ -0,0 +1,17 @@
+/** Contain session question notifications and diagnose once (PRD §5.4, §5.10). */
+import type { ElwoodActivityEvent, ElwoodAgentKind } from "../activity/index.ts";
+import type { ElwoodWarningEvent } from "../types.ts";
+import type { QuestionEmitter } from "./dispatch.ts";
+export type QuestionObservationEmitter = QuestionEmitter & {
+    observeErrors<T>(onError: (error: unknown) => void, operation: () => T, retainOnOverflow?: boolean): T;
+    emit(event: "warning", payload: ElwoodWarningEvent): void;
+    emit(event: "activity", payload: ElwoodActivityEvent): void;
+};
+type QuestionNotifier = QuestionEmitter & {
+    reportFailure(): void;
+};
+/** Deliver question/activity pairs with contained failures (PRD §§5.4, 5.10).
+ * Preserve the first failed phase and defer synchronous diagnostics until both events finish. */
+export declare function observeQuestionNotifications(emitter: QuestionObservationEmitter, elwoodSessionId: string, agent: ElwoodAgentKind): QuestionNotifier;
+export {};
+//# sourceMappingURL=observers.d.ts.map

package/dist/core/questions/observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.d.ts","sourceRoot":"","sources":["../../../src/core/questions/observers.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG;IACzD,aAAa,CAAC,CAAC,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACjC,SAAS,EAAE,MAAM,CAAC,EAClB,gBAAgB,CAAC,EAAE,OAAO,GACzB,CAAC,CAAC;IACL,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC7D,CAAC;AACF,KAAK,gBAAgB,GAAG,eAAe,GAAG;IAAE,aAAa,IAAI,IAAI,CAAA;CAAE,CAAC;AAGpE;iGACiG;AACjG,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,0BAA0B,EACnC,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,eAAe,GACrB,gBAAgB,CAuDlB"}

package/dist/core/questions/observers.js

@@ -0,0 +1,57 @@
+import { emitSessionWarnings } from "../warnings/session.js";
+/** Deliver question/activity pairs with contained failures (PRD §§5.4, 5.10).
+ * Preserve the first failed phase and defer synchronous diagnostics until both events finish. */
+export function observeQuestionNotifications(emitter, elwoodSessionId, agent) {
+    let failedPhase;
+    let delivering = false;
+    let reported = false;
+    function report() {
+        if (failedPhase === undefined || reported)
+            return;
+        reported = true;
+        const warning = Object.freeze({
+            elwoodSessionId,
+            agent,
+            source: "lifecycle",
+            code: "question_observer_failed",
+            severity: "warning",
+            message: "A question notification failed; native question ownership was preserved.",
+            phase: failedPhase,
+            raw: `question_observer_failed phase=${failedPhase}`,
+        });
+        emitter.observeErrors(() => {
+            /* Diagnostic failures must not recursively warn. */
+        }, () => emitSessionWarnings([warning], {
+            warning: (event) => emitter.emit("warning", event),
+            activity: (event) => emitter.emit("activity", event),
+        }));
+    }
+    function fail(phase) {
+        failedPhase ??= phase;
+        if (!delivering)
+            report();
+    }
+    const failures = { question: () => fail("question"), activity: () => fail("activity") };
+    return {
+        reportFailure() {
+            fail("question");
+        },
+        emit(...[event, payload]) {
+            // QuestionDispatch always follows each typed event with its activity mirror.
+            // Synchronous diagnostics wait for that pair; late rejections report directly.
+            if (event === "question")
+                delivering = true;
+            emitter.observeErrors(failures[event], () => {
+                if (event === "question")
+                    emitter.emit(event, payload);
+                else
+                    emitter.emit(event, payload);
+            }, true);
+            if (event === "activity") {
+                delivering = false;
+                report();
+            }
+        },
+    };
+}
+//# sourceMappingURL=observers.js.map

package/dist/core/questions/observers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.js","sourceRoot":"","sources":["../../../src/core/questions/observers.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAiB7D;iGACiG;AACjG,MAAM,UAAU,4BAA4B,CAC1C,OAAmC,EACnC,eAAuB,EACvB,KAAsB;IAEtB,IAAI,WAA+D,CAAC;IACpE,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,SAAS,MAAM;QACb,IAAI,WAAW,KAAK,SAAS,IAAI,QAAQ;YAAE,OAAO;QAClD,QAAQ,GAAG,IAAI,CAAC;QAChB,MAAM,OAAO,GAAkC,MAAM,CAAC,MAAM,CAAC;YAC3D,eAAe;YACf,KAAK;YACL,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,SAAS;YACnB,OAAO,EAAE,0EAA0E;YACnF,KAAK,EAAE,WAAW;YAClB,GAAG,EAAE,kCAAkC,WAAW,EAAE;SACrD,CAAC,CAAC;QACH,OAAO,CAAC,aAAa,CACnB,GAAG,EAAE;YACH,oDAAoD;QACtD,CAAC,EACD,GAAG,EAAE,CACH,mBAAmB,CAAC,CAAC,OAAO,CAAC,EAAE;YAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC;YAClD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC;SACrD,CAAC,CACL,CAAC;IACJ,CAAC;IACD,SAAS,IAAI,CAAC,KAA6C;QACzD,WAAW,KAAK,KAAK,CAAC;QACtB,IAAI,CAAC,UAAU;YAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IACD,MAAM,QAAQ,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;IACxF,OAAO;QACL,aAAa;YACX,IAAI,CAAC,UAAU,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAW;YAChC,6EAA6E;YAC7E,+EAA+E;YAC/E,IAAI,KAAK,KAAK,UAAU;gBAAE,UAAU,GAAG,IAAI,CAAC;YAC5C,OAAO,CAAC,aAAa,CACnB,QAAQ,CAAC,KAAK,CAAC,EACf,GAAG,EAAE;gBACH,IAAI,KAAK,KAAK,UAAU;oBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;;oBAClD,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACpC,CAAC,EACD,IAAI,CACL,CAAC;YACF,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzB,UAAU,GAAG,KAAK,CAAC;gBACnB,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/questions/registry.d.ts

@@ -0,0 +1,35 @@
+/** Immutable request identities and native lifecycle edges (PRD §5.10). */
+import type { ElwoodAgentKind } from "../activity/index.ts";
+import { type QuestionEmitter } from "./dispatch.ts";
+import type { ElwoodQuestionEvent, ElwoodQuestionRequest, QuestionCloseReason, QuestionDefinition } from "./types.ts";
+export type { QuestionEmitter } from "./dispatch.ts";
+export declare class QuestionRegistry {
+    private readonly entries;
+    private readonly byNativeKey;
+    private readonly publishingNativeKeys;
+    private readonly dispatch;
+    private stopped;
+    readonly agent: ElwoodAgentKind;
+    private readonly elwoodSessionId;
+    constructor(agent: ElwoodAgentKind, elwoodSessionId: string, emitter: QuestionEmitter);
+    /** Includes retired requests until their native ownership is released. */
+    hasPending(): boolean;
+    list(): readonly ElwoodQuestionRequest[];
+    get(requestId: string): ElwoodQuestionRequest | undefined;
+    /** Retired identities remain available for authoritative native-close correlation. */
+    find(nativeKey: string): ElwoodQuestionRequest | undefined;
+    /** A retired request keeps its native reservation without answer authority. */
+    isRetired(nativeKey: string): boolean;
+    keyFor(requestId: string): string | undefined;
+    /** Mirrors retain identity; changed native authority retires its previous request. */
+    publish(nativeKey: string, delivery: ElwoodQuestionRequest["delivery"], questions: readonly QuestionDefinition[]): ElwoodQuestionRequest | undefined;
+    private publishRequest;
+    /** Close the API request while retaining native ownership until native closure. */
+    retireUnconfirmed(requestId: string): void;
+    close(requestId: string, reason: QuestionCloseReason): void;
+    clear(reason: QuestionCloseReason): void;
+    shutdown(): void;
+    onEvent(listener: (event: ElwoodQuestionEvent) => void): () => void;
+    private emit;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/questions/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/core/questions/registry.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAQrD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAqB;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAC7B,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;IAKrF,0EAA0E;IAC1E,UAAU,IAAI,OAAO;IAGrB,IAAI,IAAI,SAAS,qBAAqB,EAAE;IAKxC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAIzD,sFAAsF;IACtF,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAG1D,+EAA+E;IAC/E,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAGrC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAG7C,sFAAsF;IACtF,OAAO,CACL,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,qBAAqB,CAAC,UAAU,CAAC,EAC3C,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,qBAAqB,GAAG,SAAS;IAgBpC,OAAO,CAAC,cAAc;IAqDtB,mFAAmF;IACnF,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAY1C,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAc3D,KAAK,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAaxC,QAAQ,IAAI,IAAI;IAKhB,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,MAAM,IAAI;IAGnE,OAAO,CAAC,IAAI;CAGb"}

package/dist/core/questions/registry.js

@@ -0,0 +1,158 @@
+/** Immutable request identities and native lifecycle edges (PRD §5.10). */
+import { randomUUID } from "node:crypto";
+import { eventWithAgent, requestWithAgent } from "./correlation.js";
+import { QuestionDispatch } from "./dispatch.js";
+export class QuestionRegistry {
+    entries = new Map();
+    byNativeKey = new Map();
+    publishingNativeKeys = new Set();
+    dispatch;
+    stopped = false;
+    agent;
+    elwoodSessionId;
+    constructor(agent, elwoodSessionId, emitter) {
+        this.agent = agent;
+        this.elwoodSessionId = elwoodSessionId;
+        this.dispatch = new QuestionDispatch(emitter);
+    }
+    /** Includes retired requests until their native ownership is released. */
+    hasPending() {
+        return this.entries.size > 0;
+    }
+    list() {
+        return Object.freeze([...this.entries.values()].filter((entry) => entry.answerable).map((entry) => entry.request));
+    }
+    get(requestId) {
+        const entry = this.entries.get(requestId);
+        return entry?.answerable ? entry.request : undefined;
+    }
+    /** Retired identities remain available for authoritative native-close correlation. */
+    find(nativeKey) {
+        return this.byNativeKey.get(nativeKey)?.request;
+    }
+    /** A retired request keeps its native reservation without answer authority. */
+    isRetired(nativeKey) {
+        return this.byNativeKey.get(nativeKey)?.answerable === false;
+    }
+    keyFor(requestId) {
+        return this.entries.get(requestId)?.nativeKey;
+    }
+    /** Mirrors retain identity; changed native authority retires its previous request. */
+    publish(nativeKey, delivery, questions) {
+        // A replacement closes before raising: reentrant publication of the same key
+        // must not install an entry that the outer replacement would orphan in the index.
+        if (this.stopped ||
+            this.publishingNativeKeys.has(nativeKey) ||
+            this.byNativeKey.get(nativeKey)?.answerable === false)
+            return undefined;
+        this.publishingNativeKeys.add(nativeKey);
+        try {
+            return this.publishRequest(nativeKey, delivery, questions);
+        }
+        finally {
+            this.publishingNativeKeys.delete(nativeKey);
+        }
+    }
+    publishRequest(nativeKey, delivery, questions) {
+        const signature = JSON.stringify([delivery, questions]);
+        const existing = this.byNativeKey.get(nativeKey);
+        // Definition serialization can invoke getters that retire the active request.
+        if (existing?.answerable === false)
+            return undefined;
+        if (existing?.signature === signature)
+            return existing.request;
+        let failure;
+        let failed = false;
+        if (existing) {
+            try {
+                this.close(existing.request.id, "unavailable");
+            }
+            catch (error) {
+                failure = error;
+                failed = true;
+            }
+        }
+        if (this.stopped) {
+            if (failed)
+                throw failure;
+            return undefined;
+        }
+        const request = requestWithAgent(this.agent, {
+            id: randomUUID(),
+            delivery,
+            questions: Object.freeze(questions.map((question) => Object.freeze({
+                ...question,
+                id: randomUUID(),
+                options: Object.freeze(question.options.map((option) => Object.freeze({ ...option, id: randomUUID() }))),
+            }))),
+        });
+        const entry = { nativeKey, signature, request, answerable: true };
+        this.entries.set(request.id, entry);
+        this.byNativeKey.set(nativeKey, entry);
+        try {
+            this.emit(eventWithAgent(request, { elwoodSessionId: this.elwoodSessionId, phase: "raised" }));
+        }
+        catch (error) {
+            if (!failed)
+                failure = error;
+            failed = true;
+        }
+        if (failed)
+            throw failure;
+        return request;
+    }
+    /** Close the API request while retaining native ownership until native closure. */
+    retireUnconfirmed(requestId) {
+        const entry = this.entries.get(requestId);
+        if (!entry?.answerable)
+            return;
+        entry.answerable = false;
+        this.emit(eventWithAgent(entry.request, {
+            elwoodSessionId: this.elwoodSessionId,
+            phase: "closed",
+            reason: "unavailable",
+        }));
+    }
+    close(requestId, reason) {
+        const entry = this.entries.get(requestId);
+        if (!entry)
+            return;
+        this.entries.delete(requestId);
+        this.byNativeKey.delete(entry.nativeKey);
+        if (!entry.answerable)
+            return;
+        this.emit(eventWithAgent(entry.request, {
+            elwoodSessionId: this.elwoodSessionId,
+            phase: "closed",
+            reason,
+        }));
+    }
+    clear(reason) {
+        let failure;
+        let failed = false;
+        for (const requestId of [...this.entries.keys()]) {
+            try {
+                this.close(requestId, reason);
+            }
+            catch (error) {
+                if (!failed)
+                    failure = error;
+                failed = true;
+            }
+        }
+        if (failed)
+            throw failure;
+    }
+    shutdown() {
+        // Closure observers run synchronously; latch first so they cannot repopulate shutdown state.
+        this.stopped = true;
+        this.clear("unavailable");
+    }
+    onEvent(listener) {
+        return this.dispatch.onEvent(listener);
+    }
+    emit(event) {
+        this.dispatch.emit(event);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/questions/registry.js.map

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

package/dist/core/questions/transaction.d.ts

@@ -0,0 +1,23 @@
+/** Own one answer attempt until native acceptance or revocation (PRD §4). */
+import type { ElwoodTerminal } from "../../terminal/headless.ts";
+import type { QuestionAdapter } from "./adapter.ts";
+import type { QuestionRegistry } from "./registry.ts";
+import type { ElwoodQuestionAnswer, ElwoodQuestionAnswerOptions } from "./types.ts";
+export declare class QuestionTransaction {
+    private active;
+    private reservation;
+    private readonly registry;
+    private readonly terminal;
+    private readonly inputSignal;
+    private readonly closing;
+    constructor(registry: QuestionRegistry, terminal: ElwoodTerminal, inputSignal: () => AbortSignal, closing: AbortSignal);
+    busy(): boolean;
+    revoke(): void;
+    /** Resolves after adapter completion AND native answered closure; revocation, cancellation,
+     * deadline, or unconfirmed writes reject without permitting replay of uncertain input. */
+    run(adapter: QuestionAdapter | undefined, requestId: string, answers: readonly ElwoodQuestionAnswer[], options?: ElwoodQuestionAnswerOptions): Promise<void>;
+    private isBusy;
+    private releaseSettledReservation;
+    private operationSignal;
+}
+//# sourceMappingURL=transaction.d.ts.map

package/dist/core/questions/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/core/questions/transaction.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAIpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAGpF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,WAAW,CAAqE;IACxF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;gBAEpC,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,WAAW,EAC9B,OAAO,EAAE,WAAW;IAOtB,IAAI,IAAI,OAAO;IAGf,MAAM,IAAI,IAAI;IAGd;8FAC0F;IACpF,GAAG,CACP,OAAO,EAAE,eAAe,GAAG,SAAS,EACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,oBAAoB,EAAE,EACxC,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,IAAI,CAAC;IAkDhB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,yBAAyB;IAGjC,OAAO,CAAC,eAAe;CAgBxB"}

package/dist/core/questions/transaction.js

@@ -0,0 +1,97 @@
+import { QuestionAttempt } from "./attempt.js";
+import { questionAnswerFailed, questionError } from "./errors.js";
+import { questionInput } from "./input.js";
+import { questionTimeoutMs, validateQuestionAnswers } from "./validate.js";
+export class QuestionTransaction {
+    active;
+    reservation;
+    registry;
+    terminal;
+    inputSignal;
+    closing;
+    constructor(registry, terminal, inputSignal, closing) {
+        this.registry = registry;
+        this.terminal = terminal;
+        this.inputSignal = inputSignal;
+        this.closing = closing;
+    }
+    busy() {
+        return this.isBusy();
+    }
+    revoke() {
+        this.active?.abort(questionAnswerFailed());
+    }
+    /** Resolves after adapter completion AND native answered closure; revocation, cancellation,
+     * deadline, or unconfirmed writes reject without permitting replay of uncertain input. */
+    async run(adapter, requestId, answers, options) {
+        // Reject overlap before reading caller getters; the final check catches their reentry.
+        if (this.active)
+            throw questionAnswerFailed();
+        const request = this.registry.get(requestId);
+        if (!request)
+            throw questionError("question_not_found", "The native question request is no longer available.");
+        const timeoutMs = questionTimeoutMs(options);
+        const validated = validateQuestionAnswers(request, answers);
+        this.releaseSettledReservation();
+        const operation = new AbortController();
+        const signal = this.operationSignal(operation, options);
+        // Caller getters can reenter run() before this attempt installs its owner.
+        if (this.isBusy() || !adapter)
+            throw questionAnswerFailed();
+        this.active = operation;
+        const reservation = { requestId, inFlightWrites: 0 };
+        const attempt = new QuestionAttempt(request, operation, signal, this.registry, timeoutMs);
+        const io = questionInput(this.terminal, this.registry, request, signal, () => attempt.assertLive(), {
+            started: () => {
+                attempt.writeAttempted = true;
+                this.reservation = reservation;
+                reservation.inFlightWrites++;
+            },
+            settled: () => {
+                reservation.inFlightWrites--;
+                this.releaseSettledReservation();
+            },
+            failed: () => {
+                attempt.failureCategory = "terminal_write";
+            },
+        });
+        try {
+            await attempt.execute(adapter, validated, io);
+        }
+        catch {
+            throw attempt.failure();
+        }
+        finally {
+            attempt.dispose();
+            this.active = undefined;
+            this.releaseSettledReservation();
+        }
+    }
+    isBusy() {
+        const reservation = this.reservation;
+        // Retired requests retain native ownership without a second closed event.
+        return (this.active !== undefined ||
+            (reservation !== undefined &&
+                (reservation.inFlightWrites > 0 ||
+                    this.registry.keyFor(reservation.requestId) !== undefined)));
+    }
+    releaseSettledReservation() {
+        if (!this.isBusy())
+            this.reservation = undefined;
+    }
+    operationSignal(operation, options) {
+        try {
+            const callerSignal = options?.signal;
+            return AbortSignal.any([
+                operation.signal,
+                this.closing,
+                this.inputSignal(),
+                ...(callerSignal === undefined ? [] : [callerSignal]),
+            ]);
+        }
+        catch {
+            throw questionError("invalid_question_answer", "The question answer options are invalid.");
+        }
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/core/questions/transaction.js.map

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

package/dist/core/questions/types.d.ts

@@ -0,0 +1,62 @@
+/** Shared live native question contract (PRD §5.10). */
+import type { ElwoodAgentKind } from "../activity/index.ts";
+/** Option IDs belong to this live process and must not be reused after resume. */
+export type ElwoodQuestionOption = {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+};
+/** Question IDs belong to the current live process. */
+export type ElwoodQuestion = {
+    readonly id: string;
+    readonly prompt: string;
+    readonly header?: string;
+    readonly options: readonly ElwoodQuestionOption[];
+    readonly selection: "single" | "multiple" | "none";
+    /** Free text is forbidden, replaces choices, or accompanies choices, respectively. */
+    readonly textMode: "none" | "alternative" | "additional";
+    /** Whether the native question supports entering secret text. */
+    readonly supportsSecretInput: boolean;
+};
+/** Opaque request IDs are process-scoped; a new/resumed process creates new identities.
+ * Agent narrows the request's agent; the default distributes into one request type per agent. */
+export type ElwoodQuestionRequest<Agent extends ElwoodAgentKind = ElwoodAgentKind> = Agent extends ElwoodAgentKind ? {
+    readonly id: string;
+    readonly agent: Agent;
+    /** Blocking questions suspend native work; queued questions can coexist with native work. */
+    readonly delivery: "blocking" | "queued";
+    readonly questions: readonly ElwoodQuestion[];
+} : never;
+export type ElwoodQuestionAnswer = {
+    readonly questionId: string;
+    readonly optionIds?: readonly string[];
+    readonly text?: string;
+};
+export type ElwoodQuestionAnswerOptions = {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+};
+export type QuestionCloseReason = "answered" | "cancelled" | "unavailable";
+/** Agent narrows both envelope and nested request agents. The default distributes across
+ * agents and lifecycle phases, preserving agent identity and phase-specific fields in each branch. */
+export type ElwoodQuestionEvent<Agent extends ElwoodAgentKind = ElwoodAgentKind> = Agent extends ElwoodAgentKind ? {
+    readonly elwoodSessionId: string;
+    readonly agent: Agent;
+    readonly request: ElwoodQuestionRequest<Agent>;
+} & ({
+    readonly phase: "raised";
+} | {
+    readonly phase: "closed";
+    readonly reason: QuestionCloseReason;
+}) : never;
+export interface QuestionControls {
+    /** Discovery-ordered, deeply immutable point-in-time snapshot; retained snapshots do not update.
+     * Listing bypasses an active ergonomic turn. IDs expire with this live process. */
+    listQuestions(): Promise<readonly ElwoodQuestionRequest[]>;
+    answerQuestions(requestId: string, answers: readonly ElwoodQuestionAnswer[], options?: ElwoodQuestionAnswerOptions): Promise<void>;
+}
+/** Adapters supply native content; the registry generates request, question, and option IDs. */
+export type QuestionDefinition = Omit<ElwoodQuestion, "id" | "options"> & {
+    readonly options: readonly Omit<ElwoodQuestionOption, "id">[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/questions/types.d.ts.map

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

package/dist/core/questions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/questions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/questions/types.ts"],"names":[],"mappings":""}

package/dist/core/questions/validate.d.ts

@@ -0,0 +1,16 @@
+/** Validate a complete answer batch before native input (PRD §4). */
+import type { ElwoodQuestionAnswer, ElwoodQuestionAnswerOptions, ElwoodQuestionRequest } from "./types.ts";
+/** Entries follow request-question order; option indexes follow native option order. */
+export type ValidatedQuestionAnswer = {
+    readonly optionIndexes: readonly number[];
+    readonly text?: string;
+};
+/** Return a positive finite duration in milliseconds. The 20-second default bounds
+ * stalled native confirmation; callers can extend it for slower interfaces. */
+export declare function questionTimeoutMs(options?: ElwoodQuestionAnswerOptions): number;
+/** Require exactly one answer per question within its selection/text capabilities
+ * and one aggregate 8 MiB UTF-8-byte budget across the batch for question IDs, selected
+ * option IDs, and answer text; return native indexes in request-question order.
+ * The caller owns checking whether the request is still live. */
+export declare function validateQuestionAnswers(request: ElwoodQuestionRequest, answers: readonly ElwoodQuestionAnswer[]): readonly ValidatedQuestionAnswer[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/core/questions/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/core/questions/validate.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAIrE,OAAO,KAAK,EAEV,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAIF;+EAC+E;AAC/E,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,MAAM,CAM/E;AACD;;;iEAGiE;AACjE,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,SAAS,oBAAoB,EAAE,GACvC,SAAS,uBAAuB,EAAE,CA4BpC"}