@popcomputer/structured-chat 0.1.0 → 0.2.0

package/dist/core/collect-stage.js

@@ -1,11 +1,14 @@
-import { Data, Effect, Either, Schema, unsafeCoerce } from "effect";
+import { cast, Data, Effect, Result, Schema, Struct } from "effect";
 import { StageNameSchema } from "./stage-name.js";
 import { ChatModelUnavailable, Instruction, runToolStep, StructuredChatModel, } from "./model.js";
 import { defineTool, InvalidToolCall, } from "./tool.js";
 import { defineToolSet } from "./tool-set.js";
 import { structuredDefinition, } from "./definition.js";
 /** Safe reason that a collect-stage model proposal was rejected. */
-export const InvalidCollectStageResponseReasonSchema = Schema.Literal("invalid_evidence", "invalid_repair");
+export const InvalidCollectStageResponseReasonSchema = Schema.Literals([
+    "invalid_evidence",
+    "invalid_repair",
+]);
 /** A collect-stage proposal was not grounded in a user message. */
 export class InvalidCollectStageResponse extends Schema.TaggedError()("InvalidCollectStageResponse", {
     stage: StageNameSchema,
@@ -16,14 +19,17 @@ export class InvalidCollectStageResponse extends Schema.TaggedError()("InvalidCo
 export class AnswerValidationRejected extends Data.TaggedError("AnswerValidationRejected") {
 }
 const collectStageRuntime = Symbol("@popcomputer/structured-chat/CollectStageRuntime");
+const collectStageInspection = Symbol("@popcomputer/structured-chat/CollectStageInspection");
 /** @internal Read the erased runtime from an authentic collect stage. */
 export const readCollectStageRuntime = (stage) => stage[collectStageRuntime];
+/** @internal Read trusted definition metadata from an authentic collect stage. */
+export const readCollectStageInspection = (stage) => stage[collectStageInspection];
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
 /** Define one deterministic schema-derived fact collection stage. */
 export const defineCollectStage = (definition) => {
     Schema.decodeSync(StageNameSchema)(definition.name);
-    const questionGuidanceSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000));
-    const questionEscapeSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100));
+    const questionGuidanceSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(2_000));
+    const questionEscapeSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(100));
     const questionPolicyBuilder = {};
     if (definition.questions?.guidance !== undefined) {
         questionPolicyBuilder.guidance = Schema.decodeSync(questionGuidanceSchema)(definition.questions.guidance);
@@ -34,7 +40,7 @@ export const defineCollectStage = (definition) => {
     const questions = questionPolicyBuilder;
     // SAFETY: definition.fields is the exact Fields mapping; Object.keys returns
     // only its enumerable string keys.
-    const fieldNames = unsafeCoerce(Object.keys(definition.fields));
+    const fieldNames = cast(Object.keys(definition.fields));
     if (fieldNames.length === 0) {
         throw new Error("Collect stages require at least one answer field");
     }
@@ -53,8 +59,8 @@ export const defineCollectStage = (definition) => {
     if (firstField === undefined) {
         throw new Error("Collect stages require at least one answer field");
     }
-    const fieldSchema = Schema.Literal(firstField, ...remainingFields);
-    const messageIndexSchema = Schema.Number.pipe(Schema.int(), Schema.between(0, 1_000_000));
+    const fieldSchema = Schema.Literals([firstField, ...remainingFields]);
+    const messageIndexSchema = Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 0, maximum: 1_000_000 }));
     const getAnswer = (field) => {
         const answer = definition.fields[field];
         if (answer === undefined) {
@@ -91,10 +97,10 @@ export const defineCollectStage = (definition) => {
     }
     const answerSchemaEntries = fieldNames.map((field) => [field, getAnswer(field).schema]);
     // SAFETY: every entry uses one exact Fields key and its corresponding schema.
-    const answerSchemas = unsafeCoerce(Object.fromEntries(answerSchemaEntries));
+    const answerSchemas = cast(Object.fromEntries(answerSchemaEntries));
     const rawAnswersSchema = Schema.Struct(answerSchemas);
-    const evidenceQuoteSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000));
-    const questionTextSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(500));
+    const evidenceQuoteSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(2_000));
+    const questionTextSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(500));
     const acceptedEvidenceSchema = Schema.Struct({
         messageIndex: messageIndexSchema,
         quote: evidenceQuoteSchema,
@@ -126,10 +132,10 @@ export const defineCollectStage = (definition) => {
     }
     const rawRepairSchema = remainingRepairSchemas.length === 0
         ? firstRepairSchema
-        : Schema.Union(firstRepairSchema, ...remainingRepairSchemas);
+        : Schema.Union([firstRepairSchema, ...remainingRepairSchemas]);
     // SAFETY: every dynamically generated member uses only AnyNoContext field
     // schemas and exact stage, field, and transition literals.
-    const repairSchema = rawRepairSchema;
+    const repairSchema = cast(rawRepairSchema);
     const acceptedFields = Object.fromEntries(fieldNames.map((field) => [
         field,
         Schema.Struct({
@@ -145,8 +151,8 @@ export const defineCollectStage = (definition) => {
         }),
     ]));
     const rawStateSchema = Schema.Struct({
-        accepted: Schema.partial(Schema.Struct(acceptedFields)),
-        asked: Schema.partial(Schema.Struct(askedFields)),
+        accepted: Schema.Struct(acceptedFields).mapFields(Struct.map(Schema.optional)),
+        asked: Schema.Struct(askedFields).mapFields(Struct.map(Schema.optional)),
     });
     const isValidState = (state) => {
         return fieldNames.every((field) => {
@@ -156,49 +162,61 @@ export const defineCollectStage = (definition) => {
                 hasOwn(state.asked, field));
         });
     };
-    const refinedStateSchema = rawStateSchema.pipe(Schema.filter(isValidState, {
+    const refinedStateSchema = rawStateSchema.check(Schema.makeFilter(isValidState, {
         description: "semantically valid collect-stage state",
     }));
     // SAFETY: rawAnswersSchema is created from every field's exact schema.
-    const answersSchema = unsafeCoerce(rawAnswersSchema);
+    const answersSchema = cast(rawAnswersSchema);
     // SAFETY: partial preserves the mapped accepted-answer types, while asked is
     // a record whose keys are restricted to the exact field literal union.
-    const stateSchema = unsafeCoerce(refinedStateSchema);
-    const initialState = Schema.validateSync(stateSchema)({
+    const stateSchema = cast(refinedStateSchema);
+    const initialState = Schema.decodeSync(Schema.toType(stateSchema))({
         accepted: {},
         asked: {},
     });
+    const inspectionFields = fieldNames.map((field) => {
+        const answer = getAnswer(field);
+        return {
+            field,
+            mode: answer.mode,
+            description: answer.description,
+            question: answer.question,
+            encodeValue: (value) => Schema.encodeUnknownEffect(answer.schema)(value, {
+                onExcessProperty: "error",
+            }),
+        };
+    });
     // SAFETY: when guards are omitted, Guards uses its readonly [] default; an
     // explicitly supplied tuple is returned unchanged.
-    const guards = definition.guards ?? unsafeCoerce([]);
+    const guards = definition.guards ?? cast([]);
     // SAFETY: every entry is built from one registered AnyNoContext answer
     // schema and adds only the model-wire null representation for absence.
     const proposalAnswerSchemaEntries = fieldNames.map((field) => {
         const answer = getAnswer(field);
         return [
             field,
-            Schema.NullOr(answer.schema).annotations({
+            Schema.NullOr(answer.schema).annotate({
                 description: `${answer.mode}: ${answer.description}`,
             }),
         ];
     });
     // SAFETY: each entry contains one registered field and its no-context schema.
-    const proposalAnswerSchemas = unsafeCoerce(Object.fromEntries(proposalAnswerSchemaEntries));
+    const proposalAnswerSchemas = cast(Object.fromEntries(proposalAnswerSchemaEntries));
     const rawProposalSchema = Schema.Struct({
         answers: Schema.Struct(proposalAnswerSchemas),
         evidence: Schema.Array(Schema.Struct({
             field: fieldSchema,
             quote: evidenceQuoteSchema,
-        })).pipe(Schema.maxItems(fieldNames.length)),
+        })).check(Schema.isMaxLength(fieldNames.length)),
         nextQuestion: Schema.NullOr(Schema.Struct({
             field: fieldSchema,
             text: questionTextSchema,
-            options: Schema.Array(Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100))).pipe(Schema.maxItems(20)),
+            options: Schema.Array(Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(100))).check(Schema.isMaxLength(20)),
         })),
     });
     // SAFETY: every answer field schema is constrained to AnyNoContext; the
     // generic mapped Struct cannot prove that fact after Object.fromEntries.
-    const ProposalSchema = rawProposalSchema;
+    const ProposalSchema = cast(rawProposalSchema);
     const submitAnswers = defineTool({
         name: "submit_answers",
         description: "Submit grounded answers from the conversation and optionally phrase the next adaptive question.",
@@ -314,11 +332,11 @@ export const defineCollectStage = (definition) => {
             // A selected label is later submitted as this answer's wire value,
             // so model-authored labels that cannot decode would dead-end the
             // user; fall back to the application-authored options instead.
-            const decodeLabel = Schema.decodeUnknownEither(getAnswer(pending.field).schema);
+            const decodeLabel = Schema.decodeUnknownResult(getAnswer(pending.field).schema);
             const validOptions = supplied.length < question.minimumOptions ||
                 supplied.length > question.maximumOptions ||
                 new Set(normalized).size !== normalized.length ||
-                supplied.some(({ label }) => Either.isLeft(decodeLabel(label)))
+                supplied.some(({ label }) => Result.isFailure(decodeLabel(label)))
                 ? undefined
                 : supplied;
             const selectedOptions = validOptions ??
@@ -339,8 +357,8 @@ export const defineCollectStage = (definition) => {
             options,
         };
         return questions.escape === undefined
-            ? unsafeCoerce(prompt)
-            : unsafeCoerce({ ...prompt, escape: { label: questions.escape } });
+            ? cast(prompt)
+            : cast({ ...prompt, escape: { label: questions.escape } });
     };
     const askPendingQuestion = (state, messages, adaptive) => {
         const pending = nextQuestion(state);
@@ -385,8 +403,8 @@ export const defineCollectStage = (definition) => {
             options: question._tag === "ChoiceQuestion" ? question.options : [],
         };
         return questions.escape === undefined
-            ? unsafeCoerce(prompt)
-            : unsafeCoerce({ ...prompt, escape: { label: questions.escape } });
+            ? cast(prompt)
+            : cast({ ...prompt, escape: { label: questions.escape } });
     };
     const validateAnswer = (field, value) => {
         const answer = getAnswer(field);
@@ -395,7 +413,7 @@ export const defineCollectStage = (definition) => {
         }
         // SAFETY: field selects the same answer definition whose schema parsed
         // value before validation, preserving that field's validator input.
-        const validation = unsafeCoerce(answer.validate);
+        const validation = cast(answer.validate);
         return validation(value).pipe(Effect.mapError((error) => new AnswerValidationRejected({
             stage: definition.name,
             field,
@@ -413,7 +431,7 @@ export const defineCollectStage = (definition) => {
         for (const repair of repairs) {
             // SAFETY: the field lookup below rejects names outside Fields before
             // any field-indexed operation runs.
-            const field = unsafeCoerce(repair.field);
+            const field = cast(repair.field);
             const answer = definition.fields[field];
             if (answer === undefined ||
                 seen.has(field) ||
@@ -547,7 +565,7 @@ export const defineCollectStage = (definition) => {
             };
             // SAFETY: accepted keys come only from fieldNames and every value was
             // decoded by that field's schema before insertion.
-            const merged = unsafeCoerce(runtimeMerged);
+            const merged = cast(runtimeMerged);
             if (isComplete(merged)) {
                 return {
                     state: merged,
@@ -577,7 +595,7 @@ export const defineCollectStage = (definition) => {
         // at the first failure. This keeps application Effects and the selected
         // retry question deterministic. Each validator came from the same
         // concrete Fields mapping used by the public conditional unions.
-        return execution;
+        return cast(execution);
     };
     const run = ({ state, messages, }) => {
         if (!isValidState(state) || !isGroundedInMessages(state, messages)) {
@@ -594,12 +612,12 @@ export const defineCollectStage = (definition) => {
                 error.reason === "invalid_response"), (error) => Effect.logWarning("Falling back to the trusted pending question").pipe(Effect.annotateLogs({
             stage: definition.name,
             errorTag: error._tag,
-        }), Effect.as(askPendingQuestion(state, messages, null)))));
+        }), Effect.as(askPendingQuestion(state, messages, null))), (error) => Effect.fail(error)));
     };
     // SAFETY: The chat runtime calls these erased operations only after the
     // generated state schema has parsed this exact collect-stage state. The
     // public lower-level run method already requires CollectStageState<Fields>.
-    const assumeParsedState = (state) => unsafeCoerce(state);
+    const assumeParsedState = (state) => cast(state);
     return structuredDefinition("collect_stage")({
         _tag: "CollectStage",
         name: definition.name,
@@ -609,7 +627,7 @@ export const defineCollectStage = (definition) => {
         stateSchema,
         initialState,
         guards,
-        parseState: (input) => Schema.decodeUnknown(stateSchema)(input, {
+        parseState: (input) => Schema.decodeUnknownEffect(stateSchema)(input, {
             onExcessProperty: "error",
         }),
         isComplete,
@@ -627,6 +645,9 @@ export const defineCollectStage = (definition) => {
                 },
         }),
         run,
+        [collectStageInspection]: {
+            fields: inspectionFields,
+        },
         [collectStageRuntime]: {
             initialState,
             stateSchema,

package/dist/core/command.d.ts

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 /** Opaque deterministic identity supplied to one command execution. */
-export declare const CommandIdSchema: Schema.brand<Schema.filter<typeof Schema.String>, "CommandId">;
+export declare const CommandIdSchema: Schema.brand<Schema.String, "CommandId">;
 /** Opaque deterministic identity supplied to one command execution. */
 export type CommandId = Schema.Schema.Type<typeof CommandIdSchema>;
 /** Inputs whose exact tuple identity defines one command attempt. */

package/dist/core/command.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 /** Opaque deterministic identity supplied to one command execution. */
-export const CommandIdSchema = Schema.String.pipe(Schema.pattern(/^cmd_[0-9a-f]{64}$/), Schema.brand("CommandId"));
+export const CommandIdSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^cmd_[0-9a-f]{64}$/)), Schema.brand("CommandId"));
 const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 /** Derive the stable idempotency key for one persisted command turn. */
 export const deriveCommandId = (input) => Effect.promise(async () => {

package/dist/core/debug-protocol.d.ts

@@ -0,0 +1,126 @@
+import { Effect, Schema } from "effect";
+import type { ChatDefinition, ChatReply, ChatStageTuple } from "./chat.js";
+import { type InspectChatStateOptions, type InvalidChatDebugProjection } from "./debug.js";
+import { presentChatReply, type InvalidChatPresentation, type PresentChatReplyOptions } from "./protocol.js";
+type BrowserPresentableTurn = Parameters<typeof presentChatReply>[0]["turn"];
+type DebugChatTurn<Name extends string, Version extends number, Stages extends ChatStageTuple> = ChatReply<Name, Version, Stages>["turn"] & BrowserPresentableTurn;
+type DebugChatReply<Name extends string, Version extends number, Stages extends ChatStageTuple> = Omit<ChatReply<Name, Version, Stages>, "turn"> & {
+    readonly sessionId: string;
+    readonly turn: DebugChatTurn<Name, Version, Stages>;
+};
+/** Explicit opt-in browser response carrying one debug state projection. */
+export declare const StructuredChatDebugTurnResponseSchema: Schema.Struct<{
+    readonly debug: Schema.Struct<{
+        readonly schemaVersion: Schema.Literal<1>;
+        readonly chat: Schema.Struct<{
+            readonly name: Schema.Trimmed;
+            readonly version: Schema.Number;
+        }>;
+        readonly status: Schema.Literals<readonly ["active", "complete"]>;
+        readonly currentStage: Schema.Struct<{
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly kind: Schema.Literals<readonly ["collect", "tool", "command"]>;
+        }>;
+        readonly stages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly satisfiedFields: Schema.Natural;
+            readonly totalFields: Schema.Natural;
+            readonly fields: Schema.$Array<Schema.Struct<{
+                readonly field: Schema.String;
+                readonly mode: Schema.Literals<readonly ["semantic", "explicit", "confirmed"]>;
+                readonly description: Schema.String;
+                readonly question: Schema.Union<readonly [Schema.Struct<{
+                    readonly _tag: Schema.Literal<"FixedQuestion">;
+                    readonly text: Schema.String;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"AdaptiveQuestion">;
+                    readonly goal: Schema.String;
+                    readonly fallback: Schema.String;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"AdaptiveChoiceQuestion">;
+                    readonly prompt: Schema.String;
+                    readonly minimumOptions: Schema.Natural;
+                    readonly maximumOptions: Schema.Natural;
+                    readonly fallbackOptions: Schema.$Array<Schema.String>;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"ChoiceQuestion">;
+                    readonly text: Schema.String;
+                    readonly options: Schema.$Array<Schema.Struct<{
+                        readonly label: Schema.String;
+                    }>>;
+                }>]>;
+                readonly state: Schema.Union<readonly [Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Missing">;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Asked">;
+                    readonly issuedQuestion: Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly text: Schema.String;
+                    }>;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Accepted">;
+                    readonly value: Schema.Codec<import("./json-value.js").JsonValue, import("./json-value.js").JsonValue, never, never>;
+                    readonly evidence: Schema.NullOr<Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly quote: Schema.String;
+                    }>>;
+                    readonly issuedQuestion: Schema.NullOr<Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly text: Schema.String;
+                    }>>;
+                }>]>;
+            }>>;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"CollectStage">;
+        }>, Schema.Struct<{
+            readonly tools: Schema.$Array<Schema.Trimmed>;
+            readonly afterExecution: Schema.Literals<readonly ["stay", "complete"]>;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"ToolStage">;
+        }>, Schema.Struct<{
+            readonly command: Schema.Trimmed;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"CommandStage">;
+        }>]>>;
+    }>;
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly session: Schema.optional<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly revision: Schema.Trimmed;
+    }>>;
+    readonly message: Schema.Struct<{
+        readonly role: Schema.Literal<"assistant">;
+        readonly content: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"text">;
+            readonly text: Schema.Trimmed;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"data">;
+            readonly name: Schema.Trimmed;
+            readonly data: Schema.Unknown;
+        }>]>>;
+    }>;
+}>;
+/** Explicit opt-in browser response carrying one debug state projection. */
+export type StructuredChatDebugTurnResponse = Schema.Schema.Type<typeof StructuredChatDebugTurnResponseSchema>;
+/** Presentation and state-inspection policies for one debug chat reply. */
+export interface PresentChatDebugReplyOptions<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly presentation?: PresentChatReplyOptions<DebugChatTurn<Name, Version, Stages>>;
+    readonly inspection?: InspectChatStateOptions;
+}
+/**
+ * Project one persisted reply into the explicit debug browser protocol.
+ *
+ * Applications must select this presenter deliberately and should authorize
+ * its endpoint independently from whether a debug panel is visually mounted.
+ */
+export declare const presentChatDebugReply: <const Name extends string, const Version extends number, const Stages extends ChatStageTuple>(chat: ChatDefinition<Name, Version, Stages>, reply: DebugChatReply<Name, Version, Stages>, options?: PresentChatDebugReplyOptions<Name, Version, Stages>) => Effect.Effect<StructuredChatDebugTurnResponse, InvalidChatPresentation | InvalidChatDebugProjection>;
+export {};

package/dist/core/debug-protocol.js

@@ -0,0 +1,19 @@
+import { Effect, Schema } from "effect";
+import { inspectChatState, StructuredChatDebugSnapshotSchema, } from "./debug.js";
+import { presentChatReply, StructuredChatTurnResponseSchema, } from "./protocol.js";
+/** Explicit opt-in browser response carrying one debug state projection. */
+export const StructuredChatDebugTurnResponseSchema = Schema.Struct({
+    ...StructuredChatTurnResponseSchema.fields,
+    debug: StructuredChatDebugSnapshotSchema,
+});
+/**
+ * Project one persisted reply into the explicit debug browser protocol.
+ *
+ * Applications must select this presenter deliberately and should authorize
+ * its endpoint independently from whether a debug panel is visually mounted.
+ */
+export const presentChatDebugReply = (chat, reply, options = {}) => Effect.gen(function* () {
+    const response = yield* presentChatReply(reply, options.presentation);
+    const debug = yield* inspectChatState(chat, reply.turn.state, options.inspection);
+    return { ...response, debug };
+});

package/dist/core/debug.d.ts

@@ -0,0 +1,103 @@
+import { Effect, Schema } from "effect";
+import { type ChatDefinition, type ChatStageTuple, type ChatState } from "./chat.js";
+/** Runtime schema for one JSON-safe structured-chat debug snapshot. */
+export declare const StructuredChatDebugSnapshotSchema: Schema.Struct<{
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly chat: Schema.Struct<{
+        readonly name: Schema.Trimmed;
+        readonly version: Schema.Number;
+    }>;
+    readonly status: Schema.Literals<readonly ["active", "complete"]>;
+    readonly currentStage: Schema.Struct<{
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly kind: Schema.Literals<readonly ["collect", "tool", "command"]>;
+    }>;
+    readonly stages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly satisfiedFields: Schema.Natural;
+        readonly totalFields: Schema.Natural;
+        readonly fields: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly mode: Schema.Literals<readonly ["semantic", "explicit", "confirmed"]>;
+            readonly description: Schema.String;
+            readonly question: Schema.Union<readonly [Schema.Struct<{
+                readonly _tag: Schema.Literal<"FixedQuestion">;
+                readonly text: Schema.String;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"AdaptiveQuestion">;
+                readonly goal: Schema.String;
+                readonly fallback: Schema.String;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"AdaptiveChoiceQuestion">;
+                readonly prompt: Schema.String;
+                readonly minimumOptions: Schema.Natural;
+                readonly maximumOptions: Schema.Natural;
+                readonly fallbackOptions: Schema.$Array<Schema.String>;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"ChoiceQuestion">;
+                readonly text: Schema.String;
+                readonly options: Schema.$Array<Schema.Struct<{
+                    readonly label: Schema.String;
+                }>>;
+            }>]>;
+            readonly state: Schema.Union<readonly [Schema.Struct<{
+                readonly _tag: Schema.Literal<"Missing">;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"Asked">;
+                readonly issuedQuestion: Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly text: Schema.String;
+                }>;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"Accepted">;
+                readonly value: Schema.Codec<import("./json-value.js").JsonValue, import("./json-value.js").JsonValue, never, never>;
+                readonly evidence: Schema.NullOr<Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly quote: Schema.String;
+                }>>;
+                readonly issuedQuestion: Schema.NullOr<Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly text: Schema.String;
+                }>>;
+            }>]>;
+        }>>;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"CollectStage">;
+    }>, Schema.Struct<{
+        readonly tools: Schema.$Array<Schema.Trimmed>;
+        readonly afterExecution: Schema.Literals<readonly ["stay", "complete"]>;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"ToolStage">;
+    }>, Schema.Struct<{
+        readonly command: Schema.Trimmed;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"CommandStage">;
+    }>]>>;
+}>;
+/** JSON-safe read model rendered by a structured-chat debug inspector. */
+export type StructuredChatDebugSnapshot = Schema.Schema.Type<typeof StructuredChatDebugSnapshotSchema>;
+/** Controls sensitive provenance included in a structured-chat debug snapshot. */
+export interface InspectChatStateOptions {
+    readonly evidence?: "include" | "omit";
+}
+declare const InvalidChatDebugProjection_base: Schema.Class<InvalidChatDebugProjection, Schema.TaggedStruct<"InvalidChatDebugProjection", {
+    readonly reason: Schema.Literals<readonly ["invalid_options", "invalid_state", "invalid_answer_value", "invalid_snapshot"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A chat state or answer could not be projected into safe debug JSON. */
+export declare class InvalidChatDebugProjection extends InvalidChatDebugProjection_base {
+}
+/**
+ * Project one trusted chat definition and Type-side state into browser-safe
+ * inspector data without exposing choice values or raw Effect schemas.
+ */
+export declare const inspectChatState: <const Name extends string, const Version extends number, const Stages extends ChatStageTuple>(chat: ChatDefinition<Name, Version, Stages>, state: ChatState<Name, Version, Stages>, options?: InspectChatStateOptions) => Effect.Effect<StructuredChatDebugSnapshot, InvalidChatDebugProjection>;
+export {};