run-dmcp 0.9.0 → 0.10.0

package/dist/reader/turnReader.js

@@ -65,6 +65,22 @@
  * still-unanswered questions. `attemptsPerTransport` gives one rung its own
  * retry budget before the ladder gives up on it and moves on.
  */
+/**
+ * The words of a source as a range citation numbers them: each maximal run
+ * of non-whitespace, numbered from 1. Exported so a caller that shows its
+ * model numbered words builds that numbering from the same function the
+ * rebuild uses -- two numberings that disagree by one word would cite the
+ * wrong span without any error. Lexical only: punctuation stays on its word
+ * and nothing is split by what it means (hard rule 4).
+ */
+export function sourceWords(text) {
+    const words = [];
+    for (const match of text.matchAll(/\S+/g)) {
+        const start = match.index ?? 0;
+        words.push({ index: words.length + 1, word: match[0], start, end: start + match[0].length });
+    }
+    return words;
+}
 /**
  * Construction-time validation, in the same voice as `validateMechanics`
  * (resolve.ts) and `validateMigrations` (src/db/schema.ts): every check
@@ -75,7 +91,7 @@
  * own declared `answerKeys` must be unconstructable, which is why
  * `safeDefault` membership is checked here rather than trusted.
  */
-function validateQuestions(questions) {
+export function validateQuestions(questions) {
     const seenIds = new Set();
     for (const question of questions) {
         const id = question?.id;
@@ -106,6 +122,18 @@ function validateQuestions(questions) {
         }
     }
 }
+/** A citation names its source by id, so two sources sharing one make a
+ *  citation ambiguous. Checked everywhere sources are handed over: `read()`
+ *  (which rejects), `verifyAnswers`, and the MCP verbs over it. Until
+ *  2026-09-27 `read()` let the last duplicate win silently. */
+export function validateSourceIds(sources) {
+    const seen = new Set();
+    for (const source of sources) {
+        if (seen.has(source.id))
+            throw new Error(`duplicate source id '${source.id}'`);
+        seen.add(source.id);
+    }
+}
 function validateAttemptsPerTransport(attemptsPerTransport) {
     if (!Number.isInteger(attemptsPerTransport) || attemptsPerTransport < 1) {
         throw new Error(`createTurnReader: 'attemptsPerTransport' must be an integer >= 1, got ${JSON.stringify(attemptsPerTransport)}`);
@@ -145,37 +173,81 @@ export function createTurnReader(params) {
  * (`String.prototype.includes`, no case folding, no trimming, no fuzzy
  * matching) inside that source's text. An offer that fails two conjuncts is
  * rejected either way -- which reason it carries is a reporting detail, not
- * a difference in whether it counts. Returns the first failing reason, or
- * `null` when the citation is accepted -- see the module doc comment's
- * rule-4 discussion for why this literal presence test does not become the
- * pattern-matching-meaning it is built beside.
+ * a difference in whether it counts. Returns the accepted citation, or the
+ * first failing reason -- see the module doc comment's rule-4 discussion for
+ * why this literal presence test does not become the pattern-matching-meaning
+ * it is built beside.
+ *
+ * A RANGE (issue #35) is rebuilt into a quote first, then held to the same
+ * rule -- which a rebuilt quote always passes, being a slice of the source.
+ * Its own conjuncts: both ends integers with 1 <= from <= to
+ * (`invalid-range`), and `from` naming a real word (`range-start-past-end`).
+ * A `to` past the last word is CLAMPED to it, not rejected: the span cites
+ * what is there plus nothing. Dropping those instead was the recorded
+ * failure -- short sources overshoot most, and in the consumer that hit it
+ * a whole class of four-word intents was never once ruled.
+ *
+ * A citation that names no span at all -- absent, `{}`, or a source alone
+ * -- is `missing-citation`, reported before any of the above. A null field
+ * counts as absent throughout.
  *
  * Defensive against a citation that is missing entirely or missing a field
  * -- a transport is caller-supplied code this module does not control at
  * runtime, and a malformed citation must still be rejected mechanically
  * rather than throwing out of this function and aborting the whole read.
  */
-function checkCitation(citation, sourcesById) {
-    const sourceId = citation?.sourceId;
-    const quote = citation?.quote;
+export function resolveCitation(citation, sourcesById) {
+    const record = (typeof citation === "object" && citation !== null ? citation : {});
+    const sourceId = record.sourceId;
+    // Nothing that could name a span at all -- no citation, `{}`, or a source
+    // with neither a quote nor a range. Distinct from `empty-quote` because a
+    // reader chasing a quoting problem here would be chasing nothing.
+    // null is absent: models emit `"from": null` for a field they did not use.
+    const given = (v) => v !== undefined && v !== null;
+    if (!given(record.quote) && !given(record.from) && !given(record.to)) {
+        return { reason: "missing-citation" };
+    }
+    if (given(record.from) || given(record.to)) {
+        const { from, to } = record;
+        if (typeof sourceId !== "string")
+            return { reason: "unknown-source-id" };
+        const source = sourcesById.get(sourceId);
+        if (!source)
+            return { reason: "unknown-source-id" };
+        if (!Number.isInteger(from) || !Number.isInteger(to) || from < 1 || from > to) {
+            return { reason: "invalid-range" };
+        }
+        const words = sourceWords(source.text);
+        if (from > words.length)
+            return { reason: "range-start-past-end" };
+        const end = Math.min(to, words.length);
+        const quote = source.text.slice(words[from - 1].start, words[end - 1].end);
+        return { citation: { sourceId, quote, range: { from: from, to: end } } };
+    }
+    const quote = record.quote;
     if (typeof quote !== "string" || quote.length === 0) {
-        return "empty-quote";
+        return { reason: "empty-quote" };
     }
     if (typeof sourceId !== "string") {
-        return "unknown-source-id";
+        return { reason: "unknown-source-id" };
     }
     const source = sourcesById.get(sourceId);
     if (!source) {
-        return "unknown-source-id";
+        return { reason: "unknown-source-id" };
     }
     if (!source.text.includes(quote)) {
-        return "quote-not-in-source";
+        return { reason: "quote-not-in-source" };
     }
-    return null;
+    return { citation: { sourceId, quote } };
 }
 /**
- * Runs the fallback ladder for one `read()` call. `accepted` accumulates
- * across rungs, keyed by `questionId` -- once a question is in this map its
+ * The per-read bookkeeping every offer goes through, whichever rung (or, for
+ * `verifyAnswers`, whichever caller) produced it. There is exactly one path
+ * from "an offer" to "accepted" or "a rejected row with a reason", and this
+ * is it -- so the ladder and a one-shot verification cannot disagree about
+ * what counts.
+ *
+ * `accepted` is keyed by `questionId` -- once a question is in this map its
  * answer is FINAL for this read: the next rung's request omits it (rule 4,
  * "questions already answered validly are NOT re-asked"), and any further
  * offer for it from any rung -- including a non-compliant transport that
@@ -186,103 +258,185 @@ function checkCitation(citation, sourcesById) {
  * both are the same check, `accepted.has(questionId)`, evaluated at the
  * moment each offer is processed.
  */
-async function runLadder(questions, transports, attemptsPerTransport, sources) {
+function createTally(questions, sources) {
     const questionsById = new Map(questions.map((q) => [q.id, q]));
     const sourcesById = new Map(sources.map((s) => [s.id, s]));
     const accepted = new Map();
     const rejectedByQuestion = new Map();
+    const askedByQuestion = new Map();
     const unmatched = [];
-    function reject(reason, rung, offer) {
+    function reject(reason, rung, offer, questionId) {
         const row = { reason, rung, offer };
-        const question = questionsById.get(offer.questionId);
-        if (!question) {
+        if (questionId === null || !questionsById.has(questionId)) {
             unmatched.push(row);
             return;
         }
-        const existing = rejectedByQuestion.get(offer.questionId);
+        const existing = rejectedByQuestion.get(questionId);
         if (existing) {
             existing.push(row);
         }
         else {
-            rejectedByQuestion.set(offer.questionId, [row]);
+            rejectedByQuestion.set(questionId, [row]);
         }
     }
+    return {
+        remaining() {
+            return questions.filter((q) => !accepted.has(q.id));
+        },
+        asked(rung, asked) {
+            for (const q of asked) {
+                const rungs = askedByQuestion.get(q.id);
+                if (rungs)
+                    rungs.push(rung);
+                else
+                    askedByQuestion.set(q.id, [rung]);
+            }
+        },
+        offer(rung, offer) {
+            // A transport is caller code: an entry may not be an object at all.
+            // That is a row, never a throw that loses every other offer in the list.
+            if (typeof offer !== "object" || offer === null || typeof offer.questionId !== "string") {
+                reject("malformed-offer", rung, offer, null);
+                return;
+            }
+            const question = questionsById.get(offer.questionId);
+            if (!question) {
+                reject("unknown-question", rung, offer, null);
+                return;
+            }
+            if (accepted.has(offer.questionId)) {
+                reject("duplicate-answer", rung, offer, offer.questionId);
+                return;
+            }
+            if (!question.answerKeys.includes(offer.answerKey)) {
+                // Coercion to keys that ACTUALLY exist -- exact membership or
+                // nothing (rule 2). No fuzzy match, no case fold, no "nearest key".
+                reject("unknown-answer-key", rung, offer, offer.questionId);
+                return;
+            }
+            const cited = resolveCitation(offer.citation, sourcesById);
+            if ("reason" in cited) {
+                reject(cited.reason, rung, offer, offer.questionId);
+                return;
+            }
+            accepted.set(offer.questionId, { answerKey: offer.answerKey, rung, citation: cited.citation, offer });
+        },
+        answers() {
+            return questions.map((question) => {
+                const rejected = rejectedByQuestion.get(question.id) ?? [];
+                const askedOfRungs = askedByQuestion.get(question.id) ?? [];
+                const win = accepted.get(question.id);
+                if (win) {
+                    return {
+                        questionId: question.id,
+                        answerKey: win.answerKey,
+                        fromSafeDefault: false,
+                        answeredByRung: win.rung,
+                        citation: win.citation,
+                        acceptedOffer: win.offer,
+                        askedOfRungs,
+                        rejected,
+                    };
+                }
+                // Every rung that could answer this question was exhausted (or none
+                // were ever registered) -- the caller's own declared safe direction,
+                // never the engine's guess (rule 3).
+                return {
+                    questionId: question.id,
+                    answerKey: question.safeDefault,
+                    fromSafeDefault: true,
+                    answeredByRung: null,
+                    citation: null,
+                    acceptedOffer: null,
+                    askedOfRungs,
+                    rejected,
+                };
+            });
+        },
+        unmatched() {
+            return unmatched;
+        },
+    };
+}
+/**
+ * Runs the fallback ladder for one `read()` call, recording what each rung
+ * that was called came back as (issue #36) alongside the answers.
+ */
+async function runLadder(questions, transports, attemptsPerTransport, sources) {
+    validateSourceIds(sources);
+    const tally = createTally(questions, sources);
+    const rungs = [];
     for (let rung = 0; rung < transports.length; rung++) {
-        const remaining = questions.filter((q) => !accepted.has(q.id));
+        const remaining = tally.remaining();
         if (remaining.length === 0)
             break; // every question already answered -- nothing left for any further rung
         const transport = transports[rung];
+        const attempts = [];
         let answers = null;
+        tally.asked(rung, remaining);
         for (let attempt = 0; attempt < attemptsPerTransport; attempt++) {
             try {
                 const result = await transport({ questions: remaining, sources });
                 if (Array.isArray(result)) {
+                    attempts.push({ outcome: "answered", offers: result.length });
                     answers = result;
                     break;
                 }
                 // Unusable output -- treated identically to a throw: retry within
                 // this rung's budget, then fall through to the next rung.
+                attempts.push({ outcome: "not-a-list" });
             }
-            catch {
+            catch (error) {
                 // Threw or rejected -- retry within this rung's budget, then fall
-                // through to the next rung. The engine does not distinguish WHY a
-                // rung failed; it only advances.
+                // through to the next rung. What was thrown is recorded as given;
+                // the engine does not interpret it.
+                attempts.push({ outcome: "threw", error: String(error) });
             }
         }
+        rungs.push({ rung, asked: remaining.map((q) => q.id), attempts });
         if (answers === null)
             continue; // rung exhausted; the next rung sees the same `remaining` set
-        for (const offer of answers) {
-            const question = questionsById.get(offer.questionId);
-            if (!question) {
-                reject("unknown-question", rung, offer);
-                continue;
-            }
-            if (accepted.has(offer.questionId)) {
-                reject("duplicate-answer", rung, offer);
-                continue;
-            }
-            if (!question.answerKeys.includes(offer.answerKey)) {
-                // Coercion to keys that ACTUALLY exist -- exact membership or
-                // nothing (rule 2). No fuzzy match, no case fold, no "nearest key".
-                reject("unknown-answer-key", rung, offer);
-                continue;
-            }
-            const citationProblem = checkCitation(offer.citation, sourcesById);
-            if (citationProblem) {
-                reject(citationProblem, rung, offer);
-                continue;
-            }
-            accepted.set(offer.questionId, {
-                answerKey: offer.answerKey,
-                rung,
-                citation: { sourceId: offer.citation.sourceId, quote: offer.citation.quote },
-            });
-        }
+        for (const offer of answers)
+            tally.offer(rung, offer);
     }
-    const answersOut = questions.map((question) => {
-        const rejected = rejectedByQuestion.get(question.id) ?? [];
-        const win = accepted.get(question.id);
-        if (win) {
-            return {
-                questionId: question.id,
-                answerKey: win.answerKey,
-                fromSafeDefault: false,
-                answeredByRung: win.rung,
-                citation: win.citation,
-                rejected,
-            };
-        }
-        // Every rung that could answer this question was exhausted (or none
-        // were ever registered) -- the caller's own declared safe direction,
-        // never the engine's guess (rule 3).
-        return {
-            questionId: question.id,
-            answerKey: question.safeDefault,
-            fromSafeDefault: true,
-            answeredByRung: null,
-            citation: null,
-            rejected,
-        };
-    });
-    return { answers: answersOut, unmatched };
+    return { answers: tally.answers(), unmatched: tally.unmatched(), rungs };
+}
+/**
+ * Verifies one list of answers a caller's own model produced, by the same
+ * rule a `read()` applies to a rung's offers (GitHub issue #39: intent in,
+ * ruling out, with the ruling model outside the engine). For a caller that
+ * cannot hand the engine a transport -- a client reaching it over MCP, whose
+ * model runs on its own side -- this is the second of the verb's two steps:
+ * the caller builds the request and gets it answered; the engine verifies the
+ * answers and returns the ruling. It never infers anything itself.
+ *
+ * The result is exactly what `createTurnReader({ questions, transports: [t]
+ * }).read(sources)` returns when `t` resolves to `offers`, and both refuse
+ * duplicate source ids: the offers are rung
+ * 0, asked every question, and go through the one tally every rung's offers
+ * go through, so the verb and the library cannot disagree about what counts.
+ * Synchronous, because there is nothing to wait for.
+ *
+ * The question set is validated as `createTurnReader` validates it. A
+ * non-list `offers` throws rather than reading as "no offers": at this
+ * boundary the CALLER parsed its model's reply, so a non-list is the caller's
+ * bug, not a rung failure to record. Individual malformed entries inside the
+ * list are still rows (`malformed-offer`), as on the ladder.
+ */
+export function verifyAnswers(params) {
+    validateQuestions(params.questions);
+    validateSourceIds(params.sources);
+    if (!Array.isArray(params.offers)) {
+        throw new Error(`verifyAnswers: offers must be a list of answers, got ${JSON.stringify(params.offers)}`);
+    }
+    const tally = createTally(params.questions, params.sources);
+    const asked = tally.remaining();
+    tally.asked(0, asked);
+    for (const offer of params.offers)
+        tally.offer(0, offer);
+    return {
+        answers: tally.answers(),
+        unmatched: tally.unmatched(),
+        rungs: [{ rung: 0, asked: asked.map((q) => q.id), attempts: [{ outcome: "answered", offers: params.offers.length }] }],
+    };
 }

package/dist/register/conditions.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type DeclaredRules } from "../timeline/declared.js";
+/**
+ * `conditions_at` (GitHub issue #41): a game's DECLARED conditions evaluated
+ * at `t` -- which hold, and each clause's observed value. Registered only
+ * when a server was given declared rules (createCoreMcpServer's `rules`, or
+ * the application's DMCP_RULES_FILE); a server with none has nothing to
+ * evaluate and serves no such tool, the same silence `resolve` keeps when no
+ * mechanics are registered.
+ *
+ * With `for`, it is one principal's condition list: the conditions declared
+ * for it, in declared order, from the same data that gates the declared
+ * mechanics. Rows, never a verdict -- `holds` compares a stored value to a
+ * declared one; what that means is the caller's.
+ */
+export declare function registerConditionTools(server: McpServer, rules: DeclaredRules): void;

package/dist/register/conditions.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+import { evaluateConditions } from "../timeline/declared.js";
+const log = createLogger("conditions");
+/**
+ * `conditions_at` (GitHub issue #41): a game's DECLARED conditions evaluated
+ * at `t` -- which hold, and each clause's observed value. Registered only
+ * when a server was given declared rules (createCoreMcpServer's `rules`, or
+ * the application's DMCP_RULES_FILE); a server with none has nothing to
+ * evaluate and serves no such tool, the same silence `resolve` keeps when no
+ * mechanics are registered.
+ *
+ * With `for`, it is one principal's condition list: the conditions declared
+ * for it, in declared order, from the same data that gates the declared
+ * mechanics. Rows, never a verdict -- `holds` compares a stored value to a
+ * declared one; what that means is the caller's.
+ */
+export function registerConditionTools(server, rules) {
+    server.registerTool("conditions_at", {
+        description: "Evaluate this server's declared conditions for a game at t: each condition, whether it holds, and every " +
+            "clause's observed value against its declared threshold. Pass `for` to get one principal's condition list " +
+            "-- the conditions declared for it, in order, each with its declared 'then' -- from the same data that gates " +
+            "the declared mechanics. A structural comparison of stored facts, never a verdict about the game.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: z.number().finite().describe("An opaque ordinal on this game's declared time axis."),
+            for: z.string().max(200).optional().describe("Only the conditions declared for this principal."),
+            parameters: z
+                .record(z.string().max(200), z.union([z.string().max(1000), z.number(), z.null()]))
+                .optional()
+                .describe("Values for conditions that take {param} operands. A condition needing one not given is reported with missingParameter, and does not hold."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t, for: principal, parameters }) => {
+        try {
+            const rows = evaluateConditions({ gameId, t, rules, parameters, ...(principal !== undefined ? { for: principal } : {}) });
+            return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+        }
+        catch (error) {
+            log.error("conditions_at failed", { gameId, t, error: error.message });
+            return { content: [{ type: "text", text: JSON.stringify({ error: error.message }) }], isError: true };
+        }
+    });
+}

package/dist/register/reader.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerReaderTools(server: McpServer): void;

package/dist/register/reader.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { LIMITS } from "../utils/validation.js";
+import { createLogger } from "../utils/logger.js";
+import { sourceWords, validateQuestions, validateSourceIds, verifyAnswers, } from "../reader/turnReader.js";
+const log = createLogger("reader");
+/**
+ * The turn reader as two MCP verbs (GitHub issue #39: intent in, ruling out),
+ * for a caller whose ruling MODEL runs on its own side of the wire -- a
+ * client-side principal, a person typing, anything that cannot hand the engine a
+ * transport function. The engine owns the call shape and the verification;
+ * it never runs, names or configures a model (src/reader/turnReader.ts's
+ * header, and noVendorTransports.test.ts beside it):
+ *
+ *   1. `prepare_reading` -- the caller's own request (closed-key questions and
+ *      the sources an answer may cite), validated exactly as
+ *      `createTurnReader` validates it, handed back with every source's words
+ *      numbered as a range citation counts them. A bad question set is
+ *      refused here, before a model call is spent on it.
+ *   2. `verify_reading` -- the caller's model's answers, verified by the same
+ *      tally the library's ladder runs (`verifyAnswers`): the citation rule,
+ *      ranges and their clamp, the safe defaults, and a reason for every
+ *      discarded offer.
+ *
+ * Stateless: neither verb reads or writes a game. The request travels with
+ * each call rather than being stored between them, so nothing here is a
+ * second copy of a caller's question set that could drift from the first.
+ * Everything the caller sends is opaque to the engine except the literal
+ * checks the reader already makes (hard rule 4).
+ */
+const questionSchema = () => z.object({
+    id: z.string().max(100).describe("The question's id; answers name it as questionId."),
+    prompt: z.string().max(LIMITS.CONTENT_MAX).describe("The caller's question text. Opaque to the engine."),
+    answerKeys: z
+        .array(z.string().max(LIMITS.NAME_MAX))
+        .max(200)
+        .describe("The CLOSED set of keys an answer may take."),
+    safeDefault: z
+        .string()
+        .max(LIMITS.NAME_MAX)
+        .describe("The key a question falls to when no answer is accepted. Must be one of answerKeys."),
+});
+const sourceSchema = () => z.object({
+    id: z.string().max(100).describe("The source's id; a citation names it as sourceId."),
+    text: z.string().max(LIMITS.CONTENT_MAX).describe("The text a citation must come from, byte for byte."),
+});
+const requestShape = () => ({
+    questions: z.array(questionSchema()).max(100).describe("The caller's closed-key questions."),
+    sources: z.array(sourceSchema()).max(100).describe("Every source an answer may cite."),
+});
+/** A scalar of any JSON type, bounded where it is a string. */
+const looseLeaf = () => z.union([z.string().max(LIMITS.NAME_MAX), z.number(), z.boolean(), z.null()]);
+function fail(tool, error) {
+    log.error(`${tool} refused`, { error: error.message });
+    return {
+        content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+        isError: true,
+    };
+}
+export function registerReaderTools(server) {
+    server.registerTool("prepare_reading", {
+        description: "Step 1 of ruling free text against closed keys with your own model. Validates your request -- " +
+            "closed-key questions and the sources an answer may cite -- exactly as the engine's turn reader does, " +
+            "and returns it with every source's words numbered from 1. Show your model the numbered words and let " +
+            "it cite {sourceId, from, to} instead of retyping a quote: a range cannot misquote. Then send its " +
+            "answers to verify_reading. The engine never runs or chooses a model.",
+        inputSchema: requestShape(),
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ questions, sources }) => {
+        try {
+            validateQuestions(questions);
+            validateSourceIds(sources);
+            const numbered = sources.map((s) => ({
+                id: s.id,
+                text: s.text,
+                words: sourceWords(s.text).map((w) => ({ index: w.index, word: w.word })),
+            }));
+            return { content: [{ type: "text", text: JSON.stringify({ questions, sources: numbered }, null, 2) }] };
+        }
+        catch (error) {
+            return fail("prepare_reading", error);
+        }
+    });
+    server.registerTool("verify_reading", {
+        description: "Step 2: your model's answers in, a ruling out. Each answer is {questionId, answerKey, citation}, where " +
+            "citation is {sourceId, from, to} (a word range from prepare_reading's numbering) or {sourceId, quote} " +
+            "(byte-exact). An answer counts only if its key is one of that question's answerKeys and its citation " +
+            "names text really in that source; a range ending past a source's last word ends at it. Every question " +
+            "gets exactly one answer: the accepted one, or its safeDefault. Every discarded answer is returned with " +
+            "the reason it was discarded. Send the same questions and sources you prepared.",
+        inputSchema: {
+            ...requestShape(),
+            offers: z
+                .array(
+            // Every leaf admits the wrong type on purpose: a model that writes
+            // "from": "3" or a numeric key has made an answer the reader
+            // rejects as a row with a reason, and refusing the whole call on
+            // schema validation would lose every other answer beside it --
+            // the same failure a `[null]` in a transport's list once caused.
+            z.union([
+                z.object({
+                    questionId: looseLeaf().optional(),
+                    answerKey: looseLeaf().optional(),
+                    citation: z
+                        .object({
+                        sourceId: looseLeaf().optional(),
+                        quote: z.union([z.string().max(LIMITS.CONTENT_MAX), z.number(), z.null()]).optional(),
+                        from: looseLeaf().optional(),
+                        to: looseLeaf().optional(),
+                    })
+                        .nullable()
+                        .optional(),
+                }),
+                // An entry that is not an answer at all -- a model's stray
+                // null or string -- becomes a `malformed-offer` row.
+                looseLeaf(),
+            ]))
+                .max(1000)
+                .describe("Your model's answers, as parsed from its reply. An answer with a wrong or missing field is a rejected " +
+                "row with a reason, not a refused call."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ questions, sources, offers }) => {
+        try {
+            const ruling = verifyAnswers({ questions, sources, offers: offers });
+            return { content: [{ type: "text", text: JSON.stringify(ruling, null, 2) }] };
+        }
+        catch (error) {
+            return fail("verify_reading", error);
+        }
+    });
+}

package/dist/register/render.js

@@ -32,11 +32,16 @@ export function registerRenderTools(server, renderer) {
                 .finite()
                 .describe("An opaque ordinal on this game's declared time axis -- never a datetime, and never an index " +
                 "into units you might later re-cut."),
+            entityIds: z
+                .array(z.string().max(100))
+                .max(10000)
+                .optional()
+                .describe("Scope the read to these entities -- a selection you built, such as what one character perceives. Omitted: every entity. An empty list: none. An id not alive at t is simply absent."),
         },
         annotations: ANNOTATIONS.READ_ONLY,
-    }, async ({ gameId, t }) => {
+    }, async ({ gameId, t, entityIds }) => {
         try {
-            const rendered = renderer.render({ gameId, t });
+            const rendered = renderer.render({ gameId, t, entityIds });
             return { content: [{ type: "text", text: JSON.stringify(rendered, null, 2) }] };
         }
         catch (error) {

package/dist/register/resolve.js

@@ -45,11 +45,17 @@ export function registerResolveTools(server, resolver) {
                 .optional()
                 .describe("Facts this proposal declares it depends on, verified BEFORE the mechanic is dispatched. A caller's " +
                 "own declared precondition -- the engine only reports whether it holds, never why it should."),
+            actor: z
+                .string()
+                .max(100)
+                .optional()
+                .describe("The entity proposing. If the game has declared a turn order, a proposal from anyone not due at the " +
+                "current t is refused (out-of-turn) before the mechanic runs. Omit for the world's own mechanics."),
         },
         annotations: ANNOTATIONS.UPDATE,
-    }, async ({ gameId, mechanic, parameters, expects }) => {
+    }, async ({ gameId, mechanic, parameters, expects, actor }) => {
         try {
-            const outcome = resolver.resolve({ gameId, mechanic, parameters, expects });
+            const outcome = resolver.resolve({ gameId, mechanic, parameters, expects, actor });
             return { content: [{ type: "text", text: JSON.stringify(outcome, null, 2) }] };
         }
         catch (error) {