@popcomputer/structured-chat 0.1.0 → 0.2.0

package/dist/core/answer.d.ts

@@ -1,14 +1,14 @@
 import { Effect, Schema } from "effect";
 import type { ChoiceQuestion, FixedQuestion, QuestionDefinition, QuestionDefinitionContract } from "./question.js";
 /** How strongly a collect-stage answer must be grounded in user messages. */
-export declare const AnswerModeSchema: Schema.Literal<["semantic", "explicit", "confirmed"]>;
+export declare const AnswerModeSchema: Schema.Literals<readonly ["semantic", "explicit", "confirmed"]>;
 /** How strongly a collect-stage answer must be grounded in user messages. */
 export type AnswerMode = Schema.Schema.Type<typeof AnswerModeSchema>;
 /** Minimum runtime shape retained for every collect-stage answer. */
 export interface AnswerDefinitionContract {
     readonly _tag: "AnswerDefinition";
     readonly mode: AnswerMode;
-    readonly schema: Schema.Schema.AnyNoContext;
+    readonly schema: Schema.ConstraintCodec<unknown, unknown>;
     readonly description: string;
     readonly question: QuestionDefinitionContract;
     readonly validate?: (value: never) => Effect.Effect<void, unknown, unknown>;
@@ -20,16 +20,16 @@ export interface AnswerDefinitionContract {
     };
 }
 /** One typed fact required by a collect stage. */
-export interface AnswerDefinition<Mode extends AnswerMode, ValueSchema extends Schema.Schema.AnyNoContext, Error = never, Requirements = never> extends AnswerDefinitionContract {
+export interface AnswerDefinition<Mode extends AnswerMode, ValueSchema extends Schema.ConstraintCodec<unknown, unknown>, Error = never, Requirements = never> extends AnswerDefinitionContract {
     readonly mode: Mode;
     readonly schema: ValueSchema;
-    readonly question: QuestionDefinition<Schema.Schema.Type<ValueSchema>>;
-    readonly validate?: (value: Schema.Schema.Type<ValueSchema>) => Effect.Effect<void, Error, Requirements>;
+    readonly question: QuestionDefinition<ValueSchema["Type"]>;
+    readonly validate?: (value: ValueSchema["Type"]) => Effect.Effect<void, Error, Requirements>;
     readonly reject?: {
-        readonly ask: FixedQuestion | ChoiceQuestion<Schema.Schema.Type<ValueSchema>>;
+        readonly ask: FixedQuestion | ChoiceQuestion<ValueSchema["Type"]>;
     };
     readonly escape?: {
-        readonly value: Schema.Schema.Type<ValueSchema>;
+        readonly value: ValueSchema["Type"];
     };
 }
 interface DefineAnswerBase<Value> {
@@ -58,12 +58,12 @@ export interface DefineValidatedAnswerInput<Value, Error, Requirements> extends
 }
 /** Configuration shared by all answer grounding modes. */
 export type DefineAnswerInput<Value, Error = never, Requirements = never> = DefineUnvalidatedAnswerInput<Value> | DefineValidatedAnswerInput<Value, Error, Requirements>;
-declare function semantic<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"semantic", ValueSchema, never, never>;
-declare function semantic<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"semantic", ValueSchema, Error, Requirements>;
-declare function explicit<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"explicit", ValueSchema, never, never>;
-declare function explicit<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"explicit", ValueSchema, Error, Requirements>;
-declare function confirmed<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"confirmed", ValueSchema, never, never>;
-declare function confirmed<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"confirmed", ValueSchema, Error, Requirements>;
+declare function semantic<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<ValueSchema["Type"]>): AnswerDefinition<"semantic", ValueSchema, never, never>;
+declare function semantic<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<ValueSchema["Type"], Error, Requirements>): AnswerDefinition<"semantic", ValueSchema, Error, Requirements>;
+declare function explicit<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<ValueSchema["Type"]>): AnswerDefinition<"explicit", ValueSchema, never, never>;
+declare function explicit<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<ValueSchema["Type"], Error, Requirements>): AnswerDefinition<"explicit", ValueSchema, Error, Requirements>;
+declare function confirmed<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<ValueSchema["Type"]>): AnswerDefinition<"confirmed", ValueSchema, never, never>;
+declare function confirmed<ValueSchema extends Schema.ConstraintCodec<unknown, unknown>, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<ValueSchema["Type"], Error, Requirements>): AnswerDefinition<"confirmed", ValueSchema, Error, Requirements>;
 /** Constructors for semantic, explicit, and explicitly confirmed facts. */
 export declare const Answer: {
     readonly semantic: typeof semantic;

package/dist/core/answer.js

@@ -1,7 +1,11 @@
 import { Effect, Schema } from "effect";
 /** How strongly a collect-stage answer must be grounded in user messages. */
-export const AnswerModeSchema = Schema.Literal("semantic", "explicit", "confirmed");
-const AnswerDescriptionSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(1_000));
+export const AnswerModeSchema = Schema.Literals([
+    "semantic",
+    "explicit",
+    "confirmed",
+]);
+const AnswerDescriptionSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(1_000));
 const defineAnswer = (mode, schema, input) => {
     if (input.ask._tag === "ChoiceQuestion") {
         for (const option of input.ask.options) {
@@ -27,18 +31,23 @@ const defineAnswer = (mode, schema, input) => {
         description: Schema.decodeSync(AnswerDescriptionSchema)(input.description),
         question: input.ask,
     };
-    const withEscape = input.escape === undefined
-        ? base
-        : {
-            ...base,
-            escape: {
-                value: Schema.validateSync(schema)(input.escape.value),
-            },
-        };
+    if (input.escape === undefined) {
+        return input.validate === undefined
+            ? base
+            : {
+                ...base,
+                validate: input.validate,
+                reject: input.reject,
+            };
+    }
+    const escape = {
+        value: Schema.decodeSync(Schema.toType(schema))(input.escape.value),
+    };
     return input.validate === undefined
-        ? withEscape
+        ? { ...base, escape }
         : {
-            ...withEscape,
+            ...base,
+            escape,
             validate: input.validate,
             reject: input.reject,
         };

package/dist/core/chat.d.ts

@@ -1,5 +1,4 @@
 import { Effect, Schema } from "effect";
-import type * as ParseResult from "effect/ParseResult";
 import type { AcceptedAnswer, CollectAnswers, CollectStage, CollectStageDefinitionContract, CollectStagePrompt, CollectStageState } from "./collect-stage.js";
 import { type UntrustedMessage } from "./model.js";
 import { type CommandStage, type CommandStageDefinitionContract, type ToolStage, type ToolStageDefinitionContract } from "./stage.js";
@@ -7,17 +6,15 @@ import type { ToolSetExecution } from "./tool-set.js";
 import type { StandardRepair } from "./repair.js";
 import { ChatSessionConflict, ChatSessionStore, InvalidChatSession, type ChatSessionStoreUnavailable } from "./session.js";
 /** Stable machine-facing name for one structured chat definition. */
-export declare const ChatNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+export declare const ChatNameSchema: Schema.Trimmed;
 /** Positive persisted-state version for one structured chat definition. */
-export declare const ChatVersionSchema: Schema.filter<Schema.filter<typeof Schema.Number>>;
+export declare const ChatVersionSchema: Schema.Number;
 /** Safe reason that a server-owned chat transition was rejected. */
-export declare const InvalidChatTransitionReasonSchema: Schema.Literal<["already_complete", "invalid_state"]>;
-declare const InvalidChatTransition_base: Schema.TaggedErrorClass<InvalidChatTransition, "InvalidChatTransition", {
-    readonly _tag: Schema.tag<"InvalidChatTransition">;
-} & {
-    chat: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
-    reason: Schema.Literal<["already_complete", "invalid_state"]>;
-}>;
+export declare const InvalidChatTransitionReasonSchema: Schema.Literals<readonly ["already_complete", "invalid_state"]>;
+declare const InvalidChatTransition_base: Schema.Class<InvalidChatTransition, Schema.TaggedStruct<"InvalidChatTransition", {
+    readonly chat: Schema.Trimmed;
+    readonly reason: Schema.Literals<readonly ["already_complete", "invalid_state"]>;
+}>, import("effect/Cause").YieldableError>;
 /** A server-owned chat state cannot perform the requested transition. */
 export declare class InvalidChatTransition extends InvalidChatTransition_base {
 }
@@ -50,12 +47,12 @@ export interface ChatState<Name extends string, Version extends number, Stages e
     };
 }
 type ChatQuestion<Stage> = Stage extends CollectStage<infer _Name, infer Fields, infer _Guards> ? CollectStagePrompt<Fields> : never;
-type ChatToolExecution<Stage> = Stage extends ToolStage<infer _Name, infer Tools, infer _Guards> ? ToolSetExecution<Tools> : Stage extends CommandStage<infer _Name, infer _Command, infer _Guards> ? Extract<Effect.Effect.Success<ReturnType<Stage["run"]>>, object> : never;
+type ChatToolExecution<Stage> = Stage extends ToolStage<infer _Name, infer Tools, infer _Guards> ? ToolSetExecution<Tools> : Stage extends CommandStage<infer _Name, infer _Command, infer _Guards> ? Extract<Effect.Success<ReturnType<Stage["run"]>>, object> : never;
 type StageEffect<Stage> = Stage extends CollectStage<infer _CollectName, infer _Fields, infer _CollectGuards> ? ReturnType<Stage["run"]> : Stage extends ToolStage<infer _ToolName, infer _Tools, infer _ToolGuards> ? ReturnType<Stage["run"]> : Stage extends CommandStage<infer _CommandName, infer _Command, infer _CommandGuards> ? ReturnType<Stage["run"]> : never;
 /** Failure union produced by any stage in one chat. */
-export type ChatError<Stages extends ChatStageTuple> = InvalidChatTransition | Effect.Effect.Error<StageEffect<Stages[number]>>;
+export type ChatError<Stages extends ChatStageTuple> = InvalidChatTransition | Effect.Error<StageEffect<Stages[number]>>;
 /** Effect service union required by any stage in one chat. */
-export type ChatRequirements<Stages extends ChatStageTuple> = Effect.Effect.Context<StageEffect<Stages[number]>>;
+export type ChatRequirements<Stages extends ChatStageTuple> = Effect.Services<StageEffect<Stages[number]>>;
 /** Question, ongoing tool result, or terminal result emitted by one turn. */
 export type ChatTurn<Name extends string, Version extends number, Stages extends ChatStageTuple> = {
     readonly _tag: "Question";
@@ -100,12 +97,12 @@ export interface ChatDefinition<Name extends string, Version extends number, Sta
     readonly version: Version;
     readonly stages: Stages;
     readonly repair: StandardRepair | undefined;
-    readonly stateSchema: Schema.Schema<ChatState<Name, Version, Stages>, unknown, never>;
+    readonly stateSchema: Schema.Codec<ChatState<Name, Version, Stages>, unknown>;
     readonly initialState: ChatState<Name, Version, Stages>;
     /** Read one accepted value together with its supporting transcript data. */
     readonly getAcceptedAnswer: <Stage extends ChatCollectStage<Stages>, Field extends keyof CollectFields<Stage> & string>(state: ChatState<Name, Version, Stages>, stage: Stage, field: Field) => AcceptedAnswer<CollectAnswers<CollectFields<Stage>>[Field]> | undefined;
     /** Strictly parse persisted server-owned chat state. */
-    readonly parseState: (input: Schema.Schema.Encoded<Schema.Schema<ChatState<Name, Version, Stages>, unknown, never>>) => Effect.Effect<ChatState<Name, Version, Stages>, ParseResult.ParseError>;
+    readonly parseState: (input: Schema.Codec.Encoded<Schema.Codec<ChatState<Name, Version, Stages>, unknown>>) => Effect.Effect<ChatState<Name, Version, Stages>, Schema.SchemaError>;
     /** Run the active stage and any immediately reachable tool stage. */
     readonly run: (input: {
         readonly state: ChatState<Name, Version, Stages>;

package/dist/core/chat.js

@@ -1,4 +1,4 @@
-import { Effect, Schema, unsafeCoerce } from "effect";
+import { cast, Effect, Schema } from "effect";
 import { readCollectStageRuntime } from "./collect-stage.js";
 import { countUntrustedMessageCharacters, UntrustedMessageSchema, } from "./model.js";
 import { readCommandStageRuntime, readToolStageRuntime, } from "./stage.js";
@@ -7,11 +7,14 @@ import { deriveCommandId } from "./command.js";
 import { defineTool } from "./tool.js";
 import { ChatSessionConflict, ChatSessionIdSchema, ChatSessionNamespaceSchema, ChatSessionReplacementSchema, ChatSessionRevisionSchema, ChatSessionSnapshotSchema, ChatSessionStore, InvalidChatSession, } from "./session.js";
 /** Stable machine-facing name for one structured chat definition. */
-export const ChatNameSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));
+export const ChatNameSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(100), Schema.isPattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));
 /** Positive persisted-state version for one structured chat definition. */
-export const ChatVersionSchema = Schema.Number.pipe(Schema.int(), Schema.between(1, 2_147_483_647));
+export const ChatVersionSchema = Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 2_147_483_647 }));
 /** Safe reason that a server-owned chat transition was rejected. */
-export const InvalidChatTransitionReasonSchema = Schema.Literal("already_complete", "invalid_state");
+export const InvalidChatTransitionReasonSchema = Schema.Literals([
+    "already_complete",
+    "invalid_state",
+]);
 /** A server-owned chat state cannot perform the requested transition. */
 export class InvalidChatTransition extends Schema.TaggedError()("InvalidChatTransition", {
     chat: ChatNameSchema,
@@ -90,9 +93,9 @@ export const defineChat = (definition) => {
         }
         const correctionSchema = remainingSchemas.length === 0
             ? firstSchema
-            : Schema.Union(firstSchema, ...remainingSchemas);
+            : Schema.Union([firstSchema, ...remainingSchemas]);
         const input = Schema.Struct({
-            corrections: Schema.NonEmptyArray(correctionSchema).pipe(Schema.maxItems(repair.maximumCorrections)),
+            corrections: Schema.NonEmptyArray(correctionSchema).check(Schema.isMaxLength(repair.maximumCorrections)),
         });
         return defineTool({
             name: repairToolName,
@@ -164,8 +167,11 @@ export const defineChat = (definition) => {
     const baseStateFields = {
         schemaVersion: Schema.Literal(definition.version),
         chat: Schema.Literal(definition.name),
-        stage: Schema.Number.pipe(Schema.int(), Schema.between(0, definition.stages.length - 1)),
-        status: Schema.Literal("active", "complete"),
+        stage: Schema.Number.check(Schema.isInt(), Schema.isBetween({
+            minimum: 0,
+            maximum: definition.stages.length - 1,
+        })),
+        status: Schema.Literals(["active", "complete"]),
         stages: Schema.Struct(stateFields),
     };
     const rawStateSchema = repair === undefined
@@ -173,18 +179,21 @@ export const defineChat = (definition) => {
         : Schema.Struct({
             ...baseStateFields,
             repair: Schema.Struct({
-                pendingStages: Schema.Array(Schema.Number.pipe(Schema.int(), Schema.between(0, finalStageIndex - 1))).pipe(Schema.maxItems(20)),
+                pendingStages: Schema.Array(Schema.Number.check(Schema.isInt(), Schema.isBetween({
+                    minimum: 0,
+                    maximum: finalStageIndex - 1,
+                }))).check(Schema.isMaxLength(20)),
             }),
         });
     // SAFETY: the conditional repair field is erased only for applying the
     // shared semantic predicate; stateSchema below restores the public type.
-    const runtimeStateSchema = unsafeCoerce(rawStateSchema);
-    const refinedStateSchema = runtimeStateSchema.pipe(Schema.filter((state) => isValidRuntimeState(unsafeCoerce(state)), {
+    const runtimeStateSchema = cast(rawStateSchema);
+    const refinedStateSchema = runtimeStateSchema.check(Schema.makeFilter((state) => isValidRuntimeState(cast(state)), {
         description: "semantically valid structured-chat state",
     }));
     // SAFETY: stage state fields are taken directly from the concrete collect
     // stages, and the remaining envelope fields are exact literals or bounds.
-    const stateSchema = unsafeCoerce(refinedStateSchema);
+    const stateSchema = cast(refinedStateSchema);
     const baseInitialState = {
         schemaVersion: definition.version,
         chat: definition.name,
@@ -195,7 +204,7 @@ export const defineChat = (definition) => {
     const initialStateInput = repair === undefined
         ? baseInitialState
         : { ...baseInitialState, repair: { pendingStages: [] } };
-    const initialState = Schema.validateSync(stateSchema)(initialStateInput);
+    const initialState = Schema.decodeUnknownSync(Schema.toType(stateSchema))(initialStateInput);
     const isGroundedInMessages = (state, messages) => definition.stages.every((stage) => {
         if (stage._tag !== "CollectStage") {
             return true;
@@ -279,7 +288,7 @@ export const defineChat = (definition) => {
                     }
                     // SAFETY: planWith used the generated repair tool schema, and this
                     // branch is selected by that tool's unique literal name.
-                    const proposal = unsafeCoerce(call.arguments);
+                    const proposal = cast(call.arguments);
                     return applyConversationRepairs(state, messages, proposal.corrections).pipe(Effect.flatMap((repairedState) => Effect.suspend(() => runTrustedRuntime(repairedState, messages, commandContext, false))));
                 }));
             }
@@ -348,14 +357,14 @@ export const defineChat = (definition) => {
     const run = (input) => {
         // SAFETY: ChatState is generated from the same stage tuple as the sealed
         // runtime state contract; only generic correlations are erased here.
-        const runtimeState = unsafeCoerce(input.state);
+        const runtimeState = cast(input.state);
         const runtime = runCheckedRuntime(runtimeState, input.messages);
         // SAFETY: runtime dispatch follows the exact Stages tuple and each stage
         // retains its own parsing, errors, dependencies, and output constructor.
-        return unsafeCoerce(runtime);
+        return cast(runtime);
     };
     const reply = (input) => Effect.gen(function* () {
-        const parsedInput = yield* Schema.decodeUnknown(ChatReplyBoundaryInputSchema)(input, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_input")));
+        const parsedInput = yield* Schema.decodeUnknownEffect(ChatReplyBoundaryInputSchema)(input, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_input")));
         const store = yield* ChatSessionStore;
         const scope = {
             namespace: parsedInput.namespace ?? "",
@@ -371,7 +380,7 @@ export const defineChat = (definition) => {
         }));
         const snapshot = loaded === null
             ? null
-            : yield* Schema.decodeUnknown(ChatSessionSnapshotSchema)(loaded, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_snapshot")));
+            : yield* Schema.decodeUnknownEffect(ChatSessionSnapshotSchema)(loaded, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_snapshot")));
         if ((snapshot === null &&
             parsedInput.expectedRevision !== undefined) ||
             (snapshot !== null &&
@@ -380,12 +389,12 @@ export const defineChat = (definition) => {
         }
         const state = snapshot === null
             ? initialState
-            : yield* Schema.decodeUnknown(stateSchema)(snapshot.state, {
+            : yield* Schema.decodeUnknownEffect(stateSchema)(snapshot.state, {
                 onExcessProperty: "error",
             }).pipe(Effect.mapError(() => invalidSession("invalid_state")));
         const previousMessages = snapshot?.messages ?? [];
         // SAFETY: stateSchema decoded this definition's exact state envelope.
-        const runtimeState = unsafeCoerce(state);
+        const runtimeState = cast(state);
         if (!isGroundedInMessages(runtimeState, previousMessages)) {
             return yield* Effect.fail(invalidSession("invalid_state"));
         }
@@ -393,7 +402,7 @@ export const defineChat = (definition) => {
             maximumPersistedMessages) {
             return yield* Effect.fail(invalidSession("history_limit"));
         }
-        const userMessage = yield* Schema.decodeUnknown(UntrustedMessageSchema)({ role: "user", content: parsedInput.message }, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_input")));
+        const userMessage = yield* Schema.decodeUnknownEffect(UntrustedMessageSchema)({ role: "user", content: parsedInput.message }, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_input")));
         const messages = [...previousMessages, userMessage];
         const commandContext = finalStage?._tag === "CommandStage"
             ? {
@@ -414,7 +423,7 @@ export const defineChat = (definition) => {
             snapshot !== null &&
             state.status === "active" &&
             state.stage === finalStageIndex);
-        const turn = yield* unsafeCoerce(trustedTurn);
+        const turn = yield* cast(trustedTurn);
         const toolModelContext = turn._tag === "Question"
             ? undefined
             : readToolExecutionModelContext(turn.result);
@@ -438,7 +447,7 @@ export const defineChat = (definition) => {
         if (persistedMessages.length > maximumPersistedMessages) {
             return yield* Effect.fail(invalidSession("history_limit"));
         }
-        const encodedState = yield* Schema.encodeUnknown(stateSchema)(turn.state, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_state")));
+        const encodedState = yield* Schema.encodeUnknownEffect(stateSchema)(turn.state, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_state")));
         const replaced = yield* store
             .replace({
             ...scope,
@@ -456,7 +465,7 @@ export const defineChat = (definition) => {
                 status: turn.state.status,
             },
         }));
-        const replacement = yield* Schema.decodeUnknown(ChatSessionReplacementSchema)(replaced, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_replacement")));
+        const replacement = yield* Schema.decodeUnknownEffect(ChatSessionReplacementSchema)(replaced, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidSession("invalid_replacement")));
         return {
             revision: replacement.revision,
             turn,
@@ -477,11 +486,11 @@ export const defineChat = (definition) => {
             }
             // SAFETY: Stage is restricted to this chat's concrete collect stages,
             // Field is restricted to its field keys, and state uses the same tuple.
-            const runtimeState = unsafeCoerce(state);
+            const runtimeState = cast(state);
             const accepted = runtimeState.stages[stage.name]?.accepted[field];
-            return unsafeCoerce(accepted);
+            return cast(accepted);
         },
-        parseState: (input) => Schema.decodeUnknown(stateSchema)(input, {
+        parseState: (input) => Schema.decodeUnknownEffect(stateSchema)(input, {
             onExcessProperty: "error",
         }),
         run,

package/dist/core/collect-stage.d.ts

@@ -1,19 +1,16 @@
 import { Effect, Schema } from "effect";
-import type * as ParseResult from "effect/ParseResult";
 import type { AnswerDefinition, AnswerDefinitionContract, AnswerMode } from "./answer.js";
 import { ChatModelUnavailable, StructuredChatModel, type UnsupportedModelToolSchema, type UntrustedMessage } from "./model.js";
 import type { ModelGuardError, ModelGuardRequirements, ModelGuardTuple } from "./model-guard.js";
 import { InvalidToolCall, type InvalidToolProjection } from "./tool.js";
-import type { AdaptiveChoiceQuestion, ChoiceQuestion, QuestionChoice } from "./question.js";
+import type { AdaptiveChoiceQuestion, ChoiceQuestion, QuestionDefinitionContract, QuestionChoice } from "./question.js";
 import { type StructuredDefinition } from "./definition.js";
 /** Safe reason that a collect-stage model proposal was rejected. */
-export declare const InvalidCollectStageResponseReasonSchema: Schema.Literal<["invalid_evidence", "invalid_repair"]>;
-declare const InvalidCollectStageResponse_base: Schema.TaggedErrorClass<InvalidCollectStageResponse, "InvalidCollectStageResponse", {
-    readonly _tag: Schema.tag<"InvalidCollectStageResponse">;
-} & {
-    stage: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
-    reason: Schema.Literal<["invalid_evidence", "invalid_repair"]>;
-}>;
+export declare const InvalidCollectStageResponseReasonSchema: Schema.Literals<readonly ["invalid_evidence", "invalid_repair"]>;
+declare const InvalidCollectStageResponse_base: Schema.Class<InvalidCollectStageResponse, Schema.TaggedStruct<"InvalidCollectStageResponse", {
+    readonly stage: Schema.Trimmed;
+    readonly reason: Schema.Literals<readonly ["invalid_evidence", "invalid_repair"]>;
+}>, import("effect/Cause").YieldableError>;
 /** A collect-stage proposal was not grounded in a user message. */
 export declare class InvalidCollectStageResponse extends InvalidCollectStageResponse_base {
 }
@@ -104,7 +101,7 @@ export interface CollectStageTurn<Fields extends AnswerFields> {
     readonly complete: boolean;
     readonly question: CollectStagePrompt<Fields> | undefined;
 }
-type RuntimeAnswerValue = Schema.Schema.Type<Schema.Schema.AnyNoContext>;
+type RuntimeAnswerValue = Schema.Schema.Type<Schema.Codec<unknown, unknown>>;
 type RuntimeAcceptedAnswer = AcceptedAnswer<RuntimeAnswerValue>;
 interface RuntimeCollectStageState {
     readonly accepted: Readonly<Partial<Record<string, RuntimeAcceptedAnswer>>>;
@@ -139,27 +136,43 @@ interface RuntimeCollectRepairResult {
 /** @internal Erased collect-stage behavior consumed by the chat runtime. */
 export interface CollectStageRuntime {
     readonly initialState: RuntimeCollectStageState;
-    readonly stateSchema: Schema.Schema.AnyNoContext;
+    readonly stateSchema: Schema.Codec<unknown, unknown>;
     readonly isInitial: (state: RuntimeCollectStageState) => boolean;
     readonly isValid: (state: RuntimeCollectStageState) => boolean;
     readonly isGroundedInMessages: (state: RuntimeCollectStageState, messages: ReadonlyArray<UntrustedMessage>) => boolean;
     readonly isComplete: (state: RuntimeCollectStageState) => boolean;
-    readonly repairSchema: Schema.Schema.AnyNoContext;
+    readonly repairSchema: Schema.Codec<unknown, unknown>;
     readonly applyRepairs: (state: RuntimeCollectStageState, messages: ReadonlyArray<UntrustedMessage>, repairs: ReadonlyArray<RuntimeCollectRepair>) => Effect.Effect<RuntimeCollectRepairResult, unknown, unknown>;
     readonly run: (input: {
         readonly state: RuntimeCollectStageState;
         readonly messages: ReadonlyArray<UntrustedMessage>;
     }) => Effect.Effect<RuntimeCollectStageTurn, unknown, unknown>;
 }
+/** @internal One definition-ordered field exposed to trusted projections. */
+export interface CollectStageInspectionField {
+    readonly field: string;
+    readonly mode: AnswerMode;
+    readonly description: string;
+    readonly question: QuestionDefinitionContract;
+    readonly encodeValue: (value: RuntimeAnswerValue) => Effect.Effect<unknown, Schema.SchemaError>;
+}
+/** @internal Read-only collect-stage metadata used by trusted projections. */
+export interface CollectStageInspection {
+    readonly fields: ReadonlyArray<CollectStageInspectionField>;
+}
 declare const collectStageRuntime: unique symbol;
+declare const collectStageInspection: unique symbol;
 /** Minimum sealed collect-stage shape accepted by a chat definition. */
 export interface CollectStageDefinitionContract extends StructuredDefinition<"collect_stage"> {
     readonly _tag: "CollectStage";
     readonly name: string;
     readonly [collectStageRuntime]: CollectStageRuntime;
+    readonly [collectStageInspection]: CollectStageInspection;
 }
 /** @internal Read the erased runtime from an authentic collect stage. */
 export declare const readCollectStageRuntime: (stage: CollectStageDefinitionContract) => CollectStageRuntime;
+/** @internal Read trusted definition metadata from an authentic collect stage. */
+export declare const readCollectStageInspection: (stage: CollectStageDefinitionContract) => CollectStageInspection;
 /** Shared conversational policy for questions in one collect stage. */
 export interface CollectQuestionPolicy {
     /** Trusted style guidance applied to every adaptive question in this stage. */
@@ -180,12 +193,12 @@ export interface CollectStage<Name extends string, Fields extends AnswerFields,
     readonly name: Name;
     readonly fields: Fields;
     readonly questions: CollectQuestionPolicy;
-    readonly answersSchema: Schema.Schema<CollectAnswers<Fields>, unknown, never>;
-    readonly stateSchema: Schema.Schema<CollectStageState<Fields>, unknown, never>;
+    readonly answersSchema: Schema.Codec<CollectAnswers<Fields>, unknown>;
+    readonly stateSchema: Schema.Codec<CollectStageState<Fields>, unknown>;
     readonly initialState: CollectStageState<Fields>;
     readonly guards: Guards;
     /** Strictly parse persisted or client-returned stage state. */
-    readonly parseState: (input: Schema.Schema.Encoded<Schema.Schema<CollectStageState<Fields>, unknown, never>>) => Effect.Effect<CollectStageState<Fields>, ParseResult.ParseError>;
+    readonly parseState: (input: Schema.Codec.Encoded<Schema.Codec<CollectStageState<Fields>, unknown>>) => Effect.Effect<CollectStageState<Fields>, Schema.SchemaError>;
     /** Test whether every schema-defined answer has been populated. */
     readonly isComplete: (state: CollectStageState<Fields>) => boolean;
     /** Select the first missing question in schema declaration order. */