@fungi.computer/shiitake-extensions 0.0.2 → 0.1.1

package/dist/question/contract.d.ts

@@ -1,249 +1,407 @@
 import * as Schema from "effect/Schema";
 /** A decision question: first option is recommended, free text belongs to the host. */
 export declare const Question: Schema.Struct<{
+    /** Identity used to associate this question with its answer. */
     readonly id: Schema.String;
+    /** Short label shown above the question. */
     readonly header: Schema.String;
+    /** Decision presented to the person. */
     readonly question: Schema.String;
+    /** Offered choices, with the recommended choice first. */
     readonly options: Schema.$Array<Schema.Struct<{
+        /** Choice label returned in an answer's selection. */
         readonly label: Schema.String;
+        /** Explanation of the choice's trade-off. */
         readonly description: Schema.String;
     }>>;
+    /** Whether the person may select more than one offered choice. */
     readonly multiple: Schema.optionalKey<Schema.Boolean>;
 }>;
+/** Bounded question set with distinct question identities. */
 export declare const Questions: Schema.$Array<Schema.Struct<{
+    /** Identity used to associate this question with its answer. */
     readonly id: Schema.String;
+    /** Short label shown above the question. */
     readonly header: Schema.String;
+    /** Decision presented to the person. */
     readonly question: Schema.String;
+    /** Offered choices, with the recommended choice first. */
     readonly options: Schema.$Array<Schema.Struct<{
+        /** Choice label returned in an answer's selection. */
         readonly label: Schema.String;
+        /** Explanation of the choice's trade-off. */
         readonly description: Schema.String;
     }>>;
+    /** Whether the person may select more than one offered choice. */
     readonly multiple: Schema.optionalKey<Schema.Boolean>;
 }>>;
+/** One decoded decision question. */
 export type Question = Schema.Schema.Type<typeof Question>;
 /** The complete question data shared by ordinary Session clients. */
 export declare const OpenAsk: Schema.Struct<{
+    /** Durable identity of the open ask. */
     readonly askId: Schema.String;
+    /** Decisions awaiting the person's answers. */
     readonly questions: Schema.$Array<Schema.Struct<{
+        /** Identity used to associate this question with its answer. */
         readonly id: Schema.String;
+        /** Short label shown above the question. */
         readonly header: Schema.String;
+        /** Decision presented to the person. */
         readonly question: Schema.String;
+        /** Offered choices, with the recommended choice first. */
         readonly options: Schema.$Array<Schema.Struct<{
+            /** Choice label returned in an answer's selection. */
             readonly label: Schema.String;
+            /** Explanation of the choice's trade-off. */
             readonly description: Schema.String;
         }>>;
+        /** Whether the person may select more than one offered choice. */
         readonly multiple: Schema.optionalKey<Schema.Boolean>;
     }>>;
+    /** Whether the ask is live in a turn or parked for later. */
     readonly status: Schema.Literals<readonly ["live", "parked"]>;
+    /** Creation timestamp. */
     readonly createdAt: Schema.Number;
+    /** Expiry timestamp, or null when none is set. */
     readonly expiresAt: Schema.NullOr<Schema.Number>;
 }>;
+/** One live or parked ask visible to Session clients. */
 export type OpenAsk = Schema.Schema.Type<typeof OpenAsk>;
+/** Bounded set of open asks projected into the Session. */
 export declare const AskProjection: Schema.Struct<{
+    /** Currently visible live and parked asks. */
     readonly asks: Schema.$Array<Schema.Struct<{
+        /** Durable identity of the open ask. */
         readonly askId: Schema.String;
+        /** Decisions awaiting the person's answers. */
         readonly questions: Schema.$Array<Schema.Struct<{
+            /** Identity used to associate this question with its answer. */
             readonly id: Schema.String;
+            /** Short label shown above the question. */
             readonly header: Schema.String;
+            /** Decision presented to the person. */
             readonly question: Schema.String;
+            /** Offered choices, with the recommended choice first. */
             readonly options: Schema.$Array<Schema.Struct<{
+                /** Choice label returned in an answer's selection. */
                 readonly label: Schema.String;
+                /** Explanation of the choice's trade-off. */
                 readonly description: Schema.String;
             }>>;
+            /** Whether the person may select more than one offered choice. */
             readonly multiple: Schema.optionalKey<Schema.Boolean>;
         }>>;
+        /** Whether the ask is live in a turn or parked for later. */
         readonly status: Schema.Literals<readonly ["live", "parked"]>;
+        /** Creation timestamp. */
         readonly createdAt: Schema.Number;
+        /** Expiry timestamp, or null when none is set. */
         readonly expiresAt: Schema.NullOr<Schema.Number>;
     }>>;
 }>;
 /** Stable identity for a human command and its retry. */
 export declare const RequestId: Schema.String;
+/** Answers keyed by question id, with selected choices and optional free text. */
 export declare const Answers: Schema.$Record<Schema.String, Schema.Struct<{
+    /** Labels of the offered choices selected by the person. */
     readonly selected: Schema.$Array<Schema.String>;
+    /** Optional free-text answer supplied by the person. */
     readonly text: Schema.optionalKey<Schema.String>;
 }>>;
+/** Decoded answers indexed by question identity. */
 export type Answers = Schema.Schema.Type<typeof Answers>;
+/** Idempotent human submission of a complete answer set. */
 export declare const AnswerInput: Schema.Struct<{
+    /** Ask being answered. */
     readonly askId: Schema.String;
+    /** Stable identity shared by this command and its retries. */
     readonly requestId: Schema.String;
+    /** Answers to the ask's question set. */
     readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+        /** Labels of the offered choices selected by the person. */
         readonly selected: Schema.$Array<Schema.String>;
+        /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
     }>>;
 }>;
+/** Decoded human answer submission. */
 export type AnswerInput = Schema.Schema.Type<typeof AnswerInput>;
+/** Idempotent human refusal to answer an ask. */
 export declare const DeclineInput: Schema.Struct<{
+    /** Ask being declined. */
     readonly askId: Schema.String;
+    /** Stable identity shared by this command and its retries. */
     readonly requestId: Schema.String;
+    /** Optional explanation for declining. */
     readonly note: Schema.optionalKey<Schema.String>;
 }>;
+/** Decoded human decline submission. */
 export type DeclineInput = Schema.Schema.Type<typeof DeclineInput>;
 /** Terminal question outcomes, shared by human replies and model withdrawal. */
 export declare const ClosedStatus: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
+/** Admission, already-closed state, or absence returned to a human reply. */
 export declare const HumanResult: Schema.Union<readonly [Schema.Struct<{
+    /** Reply was accepted. */
     readonly result: Schema.Literal<"accepted">;
+    /** Whether the reply resumed its turn or became a follow-up. */
     readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
 }>, Schema.Struct<{
+    /** Ask had already reached a terminal state. */
     readonly result: Schema.Literal<"closed">;
+    /** Terminal state that prevented another answer. */
     readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
 }>, Schema.Struct<{
+    /** No ask with this identity exists. */
     readonly result: Schema.Literal<"not_found">;
 }>]>;
+/** Decoded outcome of a human answer or decline. */
 export type HumanResult = Schema.Schema.Type<typeof HumanResult>;
 /** The ordinary /answer conversation carries its draft between typed steps. */
 export declare const AnswerFlowInput: Schema.Union<readonly [Schema.Struct<{
+    /** Encoded selection supplied by the human control. */
     readonly selection: Schema.String;
     readonly askId: Schema.String;
     readonly requestId: Schema.String;
     readonly index: Schema.Number;
     readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+        /** Labels of the offered choices selected by the person. */
         readonly selected: Schema.$Array<Schema.String>;
+        /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
     }>>;
+    /** Multiple-choice selection step. */
     readonly stage: Schema.Literal<"multiple">;
 }>, Schema.Struct<{
+    /** Encoded selection supplied by the human control. */
     readonly selection: Schema.String;
     readonly askId: Schema.String;
     readonly requestId: Schema.String;
     readonly index: Schema.Number;
     readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+        /** Labels of the offered choices selected by the person. */
         readonly selected: Schema.$Array<Schema.String>;
+        /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
     }>>;
+    /** Single-choice selection step. */
     readonly stage: Schema.Literal<"selection">;
 }>, Schema.Struct<{
+    /** Offered choices retained while entering free text. */
     readonly selected: Schema.$Array<Schema.String>;
+    /** Free-text answer supplied by the person. */
     readonly text: Schema.String;
     readonly askId: Schema.String;
     readonly requestId: Schema.String;
     readonly index: Schema.Number;
     readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+        /** Labels of the offered choices selected by the person. */
         readonly selected: Schema.$Array<Schema.String>;
+        /** Optional free-text answer supplied by the person. */
         readonly text: Schema.optionalKey<Schema.String>;
     }>>;
+    /** Free-text answer step. */
     readonly stage: Schema.Literal<"text">;
 }>, Schema.Struct<{
+    /** Ask whose answer conversation should be opened. */
     readonly askId: Schema.String;
 }>, Schema.Struct<{}>]>;
 /** Human reads and the ordinary projection slot; model operations belong to the host. */
 export declare const questionContract: {
+    /** Stable extension identity. */
     readonly id: string & import("effect/Brand").Brand<"ExtensionId">;
+    /** Human question controls admitted by the Session owner. */
     readonly commands: {
+        /** Advance the server-owned answer conversation. */
         readonly answerFlow: {
+            /** The Session owns its asks and replies. */
             readonly scope: "session";
+            /** Decode the current answer-draft step. */
             readonly input: Schema.Union<readonly [Schema.Struct<{
+                /** Encoded selection supplied by the human control. */
                 readonly selection: Schema.String;
                 readonly askId: Schema.String;
                 readonly requestId: Schema.String;
                 readonly index: Schema.Number;
                 readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    /** Labels of the offered choices selected by the person. */
                     readonly selected: Schema.$Array<Schema.String>;
+                    /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
                 }>>;
+                /** Multiple-choice selection step. */
                 readonly stage: Schema.Literal<"multiple">;
             }>, Schema.Struct<{
+                /** Encoded selection supplied by the human control. */
                 readonly selection: Schema.String;
                 readonly askId: Schema.String;
                 readonly requestId: Schema.String;
                 readonly index: Schema.Number;
                 readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    /** Labels of the offered choices selected by the person. */
                     readonly selected: Schema.$Array<Schema.String>;
+                    /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
                 }>>;
+                /** Single-choice selection step. */
                 readonly stage: Schema.Literal<"selection">;
             }>, Schema.Struct<{
+                /** Offered choices retained while entering free text. */
                 readonly selected: Schema.$Array<Schema.String>;
+                /** Free-text answer supplied by the person. */
                 readonly text: Schema.String;
                 readonly askId: Schema.String;
                 readonly requestId: Schema.String;
                 readonly index: Schema.Number;
                 readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    /** Labels of the offered choices selected by the person. */
                     readonly selected: Schema.$Array<Schema.String>;
+                    /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
                 }>>;
+                /** Free-text answer step. */
                 readonly stage: Schema.Literal<"text">;
             }>, Schema.Struct<{
+                /** Ask whose answer conversation should be opened. */
                 readonly askId: Schema.String;
             }>, Schema.Struct<{}>]>;
+            /** Return the next human conversation step. */
             readonly output: Schema.declare<import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1, import("@fungi.computer/whistle/catalog").WhistleCatalogStepV1>;
         };
+        /** Submit a person's completed answers. */
         readonly answer: {
+            /** The Session owns this ask. */
             readonly scope: "session";
+            /** Decode the answer submission. */
             readonly input: Schema.Struct<{
+                /** Ask being answered. */
                 readonly askId: Schema.String;
+                /** Stable identity shared by this command and its retries. */
                 readonly requestId: Schema.String;
+                /** Answers to the ask's question set. */
                 readonly answers: Schema.$Record<Schema.String, Schema.Struct<{
+                    /** Labels of the offered choices selected by the person. */
                     readonly selected: Schema.$Array<Schema.String>;
+                    /** Optional free-text answer supplied by the person. */
                     readonly text: Schema.optionalKey<Schema.String>;
                 }>>;
             }>;
+            /** Return admission or the ask's terminal state. */
             readonly output: Schema.Union<readonly [Schema.Struct<{
+                /** Reply was accepted. */
                 readonly result: Schema.Literal<"accepted">;
+                /** Whether the reply resumed its turn or became a follow-up. */
                 readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
             }>, Schema.Struct<{
+                /** Ask had already reached a terminal state. */
                 readonly result: Schema.Literal<"closed">;
+                /** Terminal state that prevented another answer. */
                 readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
             }>, Schema.Struct<{
+                /** No ask with this identity exists. */
                 readonly result: Schema.Literal<"not_found">;
             }>]>;
         };
+        /** Decline an ask with an optional note. */
         readonly decline: {
+            /** The Session owns this ask. */
             readonly scope: "session";
+            /** Decode the decline submission. */
             readonly input: Schema.Struct<{
+                /** Ask being declined. */
                 readonly askId: Schema.String;
+                /** Stable identity shared by this command and its retries. */
                 readonly requestId: Schema.String;
+                /** Optional explanation for declining. */
                 readonly note: Schema.optionalKey<Schema.String>;
             }>;
+            /** Return admission or the ask's terminal state. */
             readonly output: Schema.Union<readonly [Schema.Struct<{
+                /** Reply was accepted. */
                 readonly result: Schema.Literal<"accepted">;
+                /** Whether the reply resumed its turn or became a follow-up. */
                 readonly via: Schema.Literals<readonly ["in_turn", "follow_up"]>;
             }>, Schema.Struct<{
+                /** Ask had already reached a terminal state. */
                 readonly result: Schema.Literal<"closed">;
+                /** Terminal state that prevented another answer. */
                 readonly status: Schema.Literals<readonly ["answered", "declined", "withdrawn", "expired", "cancelled", "undeliverable"]>;
             }>, Schema.Struct<{
+                /** No ask with this identity exists. */
                 readonly result: Schema.Literal<"not_found">;
             }>]>;
         };
+        /** Read the Session's open asks. */
         readonly list: {
+            /** The Session owns the ask collection. */
             readonly scope: "session";
+            /** No additional arguments are required. */
             readonly input: Schema.Struct<{}>;
+            /** Decode the currently visible asks. */
             readonly output: Schema.Struct<{
+                /** Currently visible live and parked asks. */
                 readonly asks: Schema.$Array<Schema.Struct<{
+                    /** Durable identity of the open ask. */
                     readonly askId: Schema.String;
+                    /** Decisions awaiting the person's answers. */
                     readonly questions: Schema.$Array<Schema.Struct<{
+                        /** Identity used to associate this question with its answer. */
                         readonly id: Schema.String;
+                        /** Short label shown above the question. */
                         readonly header: Schema.String;
+                        /** Decision presented to the person. */
                         readonly question: Schema.String;
+                        /** Offered choices, with the recommended choice first. */
                         readonly options: Schema.$Array<Schema.Struct<{
+                            /** Choice label returned in an answer's selection. */
                             readonly label: Schema.String;
+                            /** Explanation of the choice's trade-off. */
                             readonly description: Schema.String;
                         }>>;
+                        /** Whether the person may select more than one offered choice. */
                         readonly multiple: Schema.optionalKey<Schema.Boolean>;
                     }>>;
+                    /** Whether the ask is live in a turn or parked for later. */
                     readonly status: Schema.Literals<readonly ["live", "parked"]>;
+                    /** Creation timestamp. */
                     readonly createdAt: Schema.Number;
+                    /** Expiry timestamp, or null when none is set. */
                     readonly expiresAt: Schema.NullOr<Schema.Number>;
                 }>>;
             }>;
         };
     };
+    /** Open asks visible to Session clients. */
     readonly projection: {
+        /** Decoder for projected asks. */
         readonly schema: Schema.Struct<{
+            /** Currently visible live and parked asks. */
             readonly asks: Schema.$Array<Schema.Struct<{
+                /** Durable identity of the open ask. */
                 readonly askId: Schema.String;
+                /** Decisions awaiting the person's answers. */
                 readonly questions: Schema.$Array<Schema.Struct<{
+                    /** Identity used to associate this question with its answer. */
                     readonly id: Schema.String;
+                    /** Short label shown above the question. */
                     readonly header: Schema.String;
+                    /** Decision presented to the person. */
                     readonly question: Schema.String;
+                    /** Offered choices, with the recommended choice first. */
                     readonly options: Schema.$Array<Schema.Struct<{
+                        /** Choice label returned in an answer's selection. */
                         readonly label: Schema.String;
+                        /** Explanation of the choice's trade-off. */
                         readonly description: Schema.String;
                     }>>;
+                    /** Whether the person may select more than one offered choice. */
                     readonly multiple: Schema.optionalKey<Schema.Boolean>;
                 }>>;
+                /** Whether the ask is live in a turn or parked for later. */
                 readonly status: Schema.Literals<readonly ["live", "parked"]>;
+                /** Creation timestamp. */
                 readonly createdAt: Schema.Number;
+                /** Expiry timestamp, or null when none is set. */
                 readonly expiresAt: Schema.NullOr<Schema.Number>;
             }>>;
         }>;

package/dist/question/contract.js

@@ -4,18 +4,29 @@ import { CatalogStep } from "../internal/catalog.js";
 const text = (maximum) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maximum), Schema.isPattern(/\S/u));
 /** A decision question: first option is recommended, free text belongs to the host. */
 export const Question = Schema.Struct({
+    /** Identity used to associate this question with its answer. */
     id: text(32).check(Schema.isPattern(/^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$/u)),
+    /** Short label shown above the question. */
     header: text(12),
+    /** Decision presented to the person. */
     question: text(1_000),
-    options: Schema.Array(Schema.Struct({ label: text(60), description: text(300) })).check(Schema.isMinLength(2), Schema.isMaxLength(4), Schema.makeFilter((options) => new Set(options.map((option) => option.label)).size ===
+    /** Offered choices, with the recommended choice first. */
+    options: Schema.Array(Schema.Struct({
+        /** Choice label returned in an answer's selection. */
+        label: text(60),
+        /** Explanation of the choice's trade-off. */
+        description: text(300),
+    })).check(Schema.isMinLength(2), Schema.isMaxLength(4), Schema.makeFilter((options) => new Set(options.map((option) => option.label)).size ===
         options.length || "Option labels must be unique", {
         representation: {
             id: "botanical/ask/unique-option-labels",
             payload: null,
         },
     })),
+    /** Whether the person may select more than one offered choice. */
     multiple: Schema.optionalKey(Schema.Boolean),
 });
+/** Bounded question set with distinct question identities. */
 export const Questions = Schema.Array(Question).check(Schema.isMinLength(1), Schema.isMaxLength(4), Schema.makeFilter((questions) => new Set(questions.map((question) => question.id)).size ===
     questions.length || "Question ids must be unique", {
     representation: {
@@ -25,29 +36,47 @@ export const Questions = Schema.Array(Question).check(Schema.isMinLength(1), Sch
 }));
 /** The complete question data shared by ordinary Session clients. */
 export const OpenAsk = Schema.Struct({
+    /** Durable identity of the open ask. */
     askId: Schema.String,
+    /** Decisions awaiting the person's answers. */
     questions: Questions,
+    /** Whether the ask is live in a turn or parked for later. */
     status: Schema.Literals(["live", "parked"]),
+    /** Creation timestamp. */
     createdAt: Schema.Number,
+    /** Expiry timestamp, or null when none is set. */
     expiresAt: Schema.NullOr(Schema.Number),
 });
+/** Bounded set of open asks projected into the Session. */
 export const AskProjection = Schema.Struct({
+    /** Currently visible live and parked asks. */
     asks: Schema.Array(OpenAsk).check(Schema.isMaxLength(4)),
 });
 /** Stable identity for a human command and its retry. */
 export const RequestId = text(256);
+/** Answers keyed by question id, with selected choices and optional free text. */
 export const Answers = Schema.Record(Question.fields.id, Schema.Struct({
+    /** Labels of the offered choices selected by the person. */
     selected: Schema.Array(text(60)).check(Schema.isMaxLength(4)),
+    /** Optional free-text answer supplied by the person. */
     text: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(4_000))),
 }));
+/** Idempotent human submission of a complete answer set. */
 export const AnswerInput = Schema.Struct({
+    /** Ask being answered. */
     askId: text(256),
+    /** Stable identity shared by this command and its retries. */
     requestId: RequestId,
+    /** Answers to the ask's question set. */
     answers: Answers,
 });
+/** Idempotent human refusal to answer an ask. */
 export const DeclineInput = Schema.Struct({
+    /** Ask being declined. */
     askId: text(256),
+    /** Stable identity shared by this command and its retries. */
     requestId: RequestId,
+    /** Optional explanation for declining. */
     note: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(4_000))),
 });
 /** Terminal question outcomes, shared by human replies and model withdrawal. */
@@ -59,56 +88,112 @@ export const ClosedStatus = Schema.Literals([
     "cancelled",
     "undeliverable",
 ]);
+/** Admission, already-closed state, or absence returned to a human reply. */
 export const HumanResult = Schema.Union([
     Schema.Struct({
+        /** Reply was accepted. */
         result: Schema.Literal("accepted"),
+        /** Whether the reply resumed its turn or became a follow-up. */
         via: Schema.Literals(["in_turn", "follow_up"]),
     }),
     Schema.Struct({
+        /** Ask had already reached a terminal state. */
         result: Schema.Literal("closed"),
+        /** Terminal state that prevented another answer. */
         status: ClosedStatus,
     }),
-    Schema.Struct({ result: Schema.Literal("not_found") }),
+    Schema.Struct({
+        /** No ask with this identity exists. */
+        result: Schema.Literal("not_found"),
+    }),
 ]);
 const answerStep = {
+    /** Ask whose answer draft is being edited. */
     askId: AnswerInput.fields.askId,
+    /** Identity of the eventual answer command. */
     requestId: RequestId,
+    /** Zero-based question being edited. */
     index: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 0, maximum: 3 })),
+    /** Answers accumulated by preceding conversation steps. */
     answers: Answers,
 };
 /** The ordinary /answer conversation carries its draft between typed steps. */
 export const AnswerFlowInput = Schema.Union([
     Schema.Struct({
+        /** Multiple-choice selection step. */
         stage: Schema.Literal("multiple"),
         ...answerStep,
+        /** Encoded selection supplied by the human control. */
         selection: Schema.String.check(Schema.isMaxLength(1_000)),
     }),
     Schema.Struct({
+        /** Single-choice selection step. */
         stage: Schema.Literal("selection"),
         ...answerStep,
+        /** Encoded selection supplied by the human control. */
         selection: Schema.String.check(Schema.isMaxLength(1_000)),
     }),
     Schema.Struct({
+        /** Free-text answer step. */
         stage: Schema.Literal("text"),
         ...answerStep,
+        /** Offered choices retained while entering free text. */
         selected: Answers.value.fields.selected,
+        /** Free-text answer supplied by the person. */
         text: Schema.String.check(Schema.isMaxLength(4_000)),
     }),
-    Schema.Struct({ askId: AnswerInput.fields.askId }),
+    Schema.Struct({
+        /** Ask whose answer conversation should be opened. */
+        askId: AnswerInput.fields.askId,
+    }),
     Schema.Struct({}),
 ]);
 /** Human reads and the ordinary projection slot; model operations belong to the host. */
 export const questionContract = {
+    /** Stable extension identity. */
     id: ExtensionId.make("botanical-session-question"),
+    /** Human question controls admitted by the Session owner. */
     commands: {
+        /** Advance the server-owned answer conversation. */
         answerFlow: {
+            /** The Session owns its asks and replies. */
             scope: "session",
+            /** Decode the current answer-draft step. */
             input: AnswerFlowInput,
+            /** Return the next human conversation step. */
             output: CatalogStep,
         },
-        answer: { scope: "session", input: AnswerInput, output: HumanResult },
-        decline: { scope: "session", input: DeclineInput, output: HumanResult },
-        list: { scope: "session", input: Schema.Struct({}), output: AskProjection },
+        /** Submit a person's completed answers. */
+        answer: {
+            /** The Session owns this ask. */
+            scope: "session",
+            /** Decode the answer submission. */
+            input: AnswerInput,
+            /** Return admission or the ask's terminal state. */
+            output: HumanResult,
+        },
+        /** Decline an ask with an optional note. */
+        decline: {
+            /** The Session owns this ask. */
+            scope: "session",
+            /** Decode the decline submission. */
+            input: DeclineInput,
+            /** Return admission or the ask's terminal state. */
+            output: HumanResult,
+        },
+        /** Read the Session's open asks. */
+        list: {
+            /** The Session owns the ask collection. */
+            scope: "session",
+            /** No additional arguments are required. */
+            input: Schema.Struct({}),
+            /** Decode the currently visible asks. */
+            output: AskProjection,
+        },
+    },
+    /** Open asks visible to Session clients. */
+    projection: {
+        /** Decoder for projected asks. */
+        schema: AskProjection,
     },
-    projection: { schema: AskProjection },
 };