loopforge 3.7.1 → 3.8.1

package/dist/mcp/session.d.ts

@@ -13,7 +13,8 @@
  * SessionManager → RoundDriver → RoundCoordinator path.
  */
 import type { GateActionDescriptor } from "../protocol.js";
-import type { ExternalContextProvider, LoopTerminalSink, SelfEvaluation } from "../protocol.js";
+import type { ExternalContextProvider, LoopTerminalSink } from "../protocol.js";
+import type { ActiveContractView } from "../round-contract.js";
 import type { LoopStore } from "../loop-store.js";
 import type { PolicyMetricsSnapshot } from "../policy-metrics.js";
 import type { SessionStateStore } from "../storage.js";
@@ -94,41 +95,40 @@ export declare class SessionManager implements SessionRegistry {
      *  canonicalized action hash — if the action changed, the match fails and
      *  the old approval expires automatically. */
     resolveGate(sessionId: string, gateId: string, approved: boolean, note?: string): Record<string, unknown>;
-    /** Compile the current round context exactly once per derivation path.
-     *  v3.0.1: prefer the round-boundary compile cached on the session (the
-     *  artifact's deterministic roundId guards against stale reuse); fall
-     *  back to a read-only compile (persistLineage: false) that never writes
-     *  the vault. Single derivation — shared by the projection view and the
-     *  subgoal_updates preflight so they can never disagree. */
+    /** The compile context for this round.
+     *
+     *  v3.8.1: delegates to the SHARED implementation in round-lifecycle.ts —
+     *  the runtime's submission boundary reads the same context (the sub-goal
+     *  reference space is exactly the compiled set the prompt carried), and two
+     *  copies would let the projection and the boundary disagree about it. */
     private compileContext;
-    /** v3.7.1: pre-advance referential check for subgoal_updates. The
-     *  reference space is the SAME derivation the agent saw in its prompt
-     *  (the compiled sub_goals of the current round) plus this payload's own
-     *  emerged items (a sub-goal may be created and transitioned in one
-     *  round). Unknown IDs, terminal references, and illegal migrations
-     *  return evaluation_invalid before anything mutates. Compile failure
-     *  fails open (the shape checks above stay strict). */
-    preflightSubGoalUpdates(sessionId: string, roundId: string, updates: import("../protocol.js").SubGoalUpdate[], emerged: string[]): Array<{
-        field: string;
-        reason: string;
-        detail: string;
-    }>;
     /** Typed cognitive state projection for an active session. Derived on
      *  demand — zero persistence. Null when nothing meaningful exists yet. */
     getProjection(sessionId: string): Record<string, unknown> | null;
+    /** v3.8: Read-only per-round "why" view over committed facts. Never
+     *  rebuilds history and never writes. */
+    getExplain(loopId: string, round?: number): Record<string, unknown>;
     /** Read-only end-of-loop audit (verification view). Never writes. */
     getAudit(loopId: string): Record<string, unknown> | null;
     /** v3.5: The ACTIVE Round Contract governing the session's next round —
      *  derived from the committed :feedback evals (the SAME adapter + walker
      *  the verification gate uses; display-only, zero persistence). Null when
      *  nothing is active (whole-task round). */
-    getActiveContract(sessionId: string): import("../protocol.js").RoundContract | null;
+    getActiveContract(sessionId: string): ActiveContractView | null;
     /** v2.12: Policy metrics that survive restarts — vault-derived round
      *  statistics (A4 port) folded with this process's live observations.
      *  Non-durable fields (evidence, vault errors) come from live only. */
     getPolicyMetrics(loopId: string): PolicyMetricsSnapshot;
-    /** Get loop health for a loop (in-memory or vault).
-     *  Computes goal alignment, constraint integrity, drift, strategy stability. */
+    /** Get machine facts about a loop (in-memory or vault).
+     *
+     *  v3.8.1: this view used to report `goal_alignment`, `drift_detected`,
+     *  `strategy_stability` and `task_continuity`. Every one was a
+     *  text-similarity verdict rather than a fact, and two were degenerate in
+     *  THIS method specifically: `task_continuity` was pinned to 1.0 because the
+     *  request was built with `round: 1`, so `getPreviousRound(loopId, 0)`
+     *  returned null and the code took its hardcoded `?? 1` branch; and
+     *  `strategy_stability` was a literal `true`. What remains is counted
+     *  directly from committed round flags. */
     getHealth(loopId: string): Record<string, unknown> | null;
     /** Core cycle: extract self-eval → record feedback → check stop → compile next.
      *  The lease + per-session queue wrap the RoundLifecycle state machine.
@@ -138,7 +138,23 @@ export declare class SessionManager implements SessionRegistry {
      *    (from the last start/next/resume response). Anchors the submission so a
      *    stale or duplicate submission is not processed against a later round.
      *    Optional for library callers — when absent the anchor check is skipped. */
-    advance(sessionId: string, output: string, preExtractedEval?: SelfEvaluation, roundId?: string): Promise<AdvanceResult>;
+    /** \`submission\` is the RAW evaluation payload, not a built one.
+     *
+     *  v3.8.1: this method used to carry a partial copy of the submission
+     *  boundary (an object check plus core-field validation) while the MCP tool
+     *  handler carried the rest — one rule, three copies, across two layers.
+     *  The boundary now lives entirely in the runtime
+     *  (`RoundLifecycle.submissionBoundary`), so every caller — this manager, a
+     *  library user, a future CLI command — gets the same strictness. */
+    /** \`submission\` is the RAW evaluation payload, not a built one.
+     *
+     *  v3.8.1: this method used to carry a partial copy of the submission
+     *  boundary (an object check plus core-field validation) while the MCP tool
+     *  handler carried the rest — one rule, three copies, across two layers.
+     *  The whole boundary now runs HERE, before the queue and before the lease
+     *  heartbeat, so every caller of the public API gets it and a rejected
+     *  payload leaves nothing durable behind. */
+    advance(sessionId: string, output: string, submission?: unknown, roundId?: string): Promise<AdvanceResult>;
     /** Replay timeline for a session — creates ReplayBackend from the stored backend. */
     replayTimeline(sessionId: string): Record<string, unknown>[] | null;
     /** v3.3.1: Replay a loop straight from the vault — no in-memory session

package/dist/mcp/session.d.ts.map

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

package/dist/mcp/session.js

@@ -15,18 +15,17 @@
 import { randomUUID } from "node:crypto";
 import { LoopForgeEngine } from "../engine.js";
 import { canonicalizeGateAction, deriveGate, preflightStructuredGate, } from "../cognitive-governance.js";
-import { makeGateDecision, Mode } from "../protocol.js";
+import { makeGateDecision } from "../protocol.js";
 import { buildLoopProjection } from "../loop-projection.js";
 import { deriveCognitiveFacts } from "../cognitive-facts.js";
+import { NO_IN_FLIGHT_ROUND, deriveRoundFacts } from "../round-facts.js";
 import { listVerifiedClaims } from "../evidence-claims.js";
 import { buildAudit } from "../audit.js";
-import { checkLoopHealth, deriveSubGoalId, validateSubGoalUpdates } from "../loop-compiler.js";
-import { committedRoundsFromEntries } from "../committed-round.js";
-import { contractRoundEvaluations, deriveActiveRoundContract, } from "../round-contract.js";
+import { buildExplain } from "../explain.js";
+import { CHECK_CONTRACT_ITEMS_UNVERIFIED } from "../verification-gate.js";
+import { readOnlyRounds } from "../committed-round.js";
 import { getPolicy, validateLoopId } from "../policy.js";
 import { isRecord } from "../token-utils.js";
-import { buildSelfEvaluation, validateCoreSelfEvaluation, } from "../self-eval.js";
-import { makeLoopCompileRequest } from "../protocol.js";
 import { ReplayBackend } from "../replay.js";
 import { FileLoopStore, queryLoopEntries } from "../loop-store.js";
 import { makeRoundId, prepareRoundTransaction } from "../round-transaction.js";
@@ -36,6 +35,7 @@ import { policyMetrics, derivePolicyMetrics, mergePolicyMetrics, } from "../poli
 import { SessionLeaseConflictError, VaultSessionStateStore, } from "../storage.js";
 import { StorageCorruptionError } from "../loop-store.js";
 import { RoundLifecycle, buildLoopRequest } from "./round-lifecycle.js";
+import { activeContractOf, compileSessionContext, validateSubmission, } from "./submission-boundary.js";
 // ── SessionManager ─────────────────────────────────────────────────────────
 export class SessionManager {
     sessions = new Map();
@@ -193,7 +193,6 @@ export class SessionManager {
             maxRounds, successTrajectory: [], status: "running", createdAt: Date.now(),
             consecutiveRejections: 0,
             lastRejectionCheck: "",
-            driftClarificationStreak: 0,
             backtrackSkippedFiles: [],
             backtrackSkippedFingerprints: {},
             evidenceBaseline: [],
@@ -235,7 +234,6 @@ export class SessionManager {
             // v1.13: Enforcement gate state
             consecutiveRejections: 0,
             lastRejectionCheck: "",
-            driftClarificationStreak: 0,
             backtrackSkippedFiles: [],
             backtrackSkippedFingerprints: {},
             evidenceBaseline,
@@ -509,12 +507,22 @@ export class SessionManager {
     checkGate(sessionId, roundId, action) {
         const session = this.sessions.get(sessionId);
         if (!session) {
-            return { error: `session not found: ${sessionId}` };
+            return {
+                error: "session_not_found",
+                errorMessage: `session not found: ${sessionId}`,
+                sessionId,
+            };
         }
         const expectedRoundId = session.roundSnapshot?.roundId
             ?? makeRoundId(session.loopId, session.currentRound);
         if (expectedRoundId !== roundId) {
-            return { error: "roundId does not match the current round — re-run loopforge_gate_check with the roundId from the latest response" };
+            return {
+                error: "round_id_mismatch",
+                errorMessage: "roundId does not match the current round — re-run loopforge_gate_check " +
+                    "with the roundId from the latest response",
+                sessionId,
+                roundId,
+            };
         }
         const verdict = preflightStructuredGate(action);
         if (verdict.kind === "user") {
@@ -561,8 +569,13 @@ export class SessionManager {
                 return lineage.session_id === sessionId;
             });
             loopId = persistedEntry?.loop_id;
-            if (!loopId)
-                return { error: `session not found: ${sessionId}` };
+            if (!loopId) {
+                return {
+                    error: "session_not_found",
+                    errorMessage: `session not found: ${sessionId}`,
+                    sessionId,
+                };
+            }
             const claimed = this.claimSessionEntry(loopId);
             if (!claimed) {
                 return { ...this.leaseConflictResult(loopId, persistedEntry) };
@@ -573,14 +586,23 @@ export class SessionManager {
                 ? lineage.current_round
                 : 0;
         }
-        if (!loopId)
-            return { error: `session not found: ${sessionId}` };
+        if (!loopId) {
+            return {
+                error: "session_not_found",
+                errorMessage: `session not found: ${sessionId}`,
+                sessionId,
+            };
+        }
         try {
             const prefix = `loop:${loopId}:gate:`;
             const opened = queryLoopEntries(this.loopStore, loopId, { prefix })
                 .find((entry) => entry.task_type === "gate_opened" && entry.gate_id === gateId);
             if (!opened) {
-                return { error: `no gate_opened record for gate ${gateId} — the gate may have expired or was never recorded` };
+                return {
+                    error: "state_unavailable",
+                    errorMessage: `no gate_opened record for gate ${gateId} — the gate may have ` +
+                        "expired or was never recorded",
+                };
             }
             const actionText = typeof opened.gate_action === "string" ? opened.gate_action : "";
             const openedLineage = isRecord(opened.loop_lineage) ? opened.loop_lineage : {};
@@ -604,7 +626,11 @@ export class SessionManager {
                     descriptor = JSON.parse(actionText);
                 }
                 catch {
-                    return { error: `gate ${gateId} has a corrupted structured action — re-run loopforge_gate_check` };
+                    return {
+                        error: "state_unavailable",
+                        errorMessage: `gate ${gateId} has a corrupted structured action — ` +
+                            "re-run loopforge_gate_check",
+                    };
                 }
                 const verdict = preflightStructuredGate(descriptor);
                 matchedId = verdict.gateId;
@@ -619,10 +645,18 @@ export class SessionManager {
                 userScope = derived.gate.blockedScope ?? [];
             }
             if (matchedId !== gateId) {
-                return { error: "gateId does not match the recorded action — the action changed, old approvals expire" };
+                return {
+                    error: "invalid_argument",
+                    errorMessage: "gateId does not match the recorded action — the action changed, " +
+                        "old approvals expire",
+                };
             }
             if (!userKind) {
-                return { error: "agent gates are resolved by submitting the required evidence, not by user approval" };
+                return {
+                    error: "invalid_argument",
+                    errorMessage: "agent gates are resolved by submitting the required evidence, " +
+                        "not by user approval",
+                };
             }
             const decision = makeGateDecision({
                 gateId,
@@ -658,77 +692,14 @@ export class SessionManager {
         }
     }
     // ── v2.12: Typed projection + audit ────────────────────────────────────
-    /** Compile the current round context exactly once per derivation path.
-     *  v3.0.1: prefer the round-boundary compile cached on the session (the
-     *  artifact's deterministic roundId guards against stale reuse); fall
-     *  back to a read-only compile (persistLineage: false) that never writes
-     *  the vault. Single derivation — shared by the projection view and the
-     *  subgoal_updates preflight so they can never disagree. */
+    /** The compile context for this round.
+     *
+     *  v3.8.1: delegates to the SHARED implementation in round-lifecycle.ts —
+     *  the runtime's submission boundary reads the same context (the sub-goal
+     *  reference space is exactly the compiled set the prompt carried), and two
+     *  copies would let the projection and the boundary disagree about it. */
     compileContext(session) {
-        const cached = session.lastCompileResponse;
-        const expectedRoundId = session.roundSnapshot?.roundId
-            ?? makeRoundId(session.loopId, session.currentRound);
-        if (cached?.prompt_artifact && cached.prompt_artifact.roundId === expectedRoundId) {
-            return cached;
-        }
-        try {
-            const request = {
-                task: session.task,
-                mode: Mode.LOOP_COMPILE,
-                feedback: null,
-                skill_name: null,
-                task_id: null,
-                loop_id: session.loopId,
-                round: session.currentRound,
-                max_rounds: session.maxRounds,
-                verification_flags: [],
-            };
-            const compiled = session.engine.invokeLoopCompile(request, undefined, { persistLineage: false });
-            return compiled.response ?? null;
-        }
-        catch {
-            return null; // projection/preflight degrades gracefully
-        }
-    }
-    /** v3.7.1: pre-advance referential check for subgoal_updates. The
-     *  reference space is the SAME derivation the agent saw in its prompt
-     *  (the compiled sub_goals of the current round) plus this payload's own
-     *  emerged items (a sub-goal may be created and transitioned in one
-     *  round). Unknown IDs, terminal references, and illegal migrations
-     *  return evaluation_invalid before anything mutates. Compile failure
-     *  fails open (the shape checks above stay strict). */
-    preflightSubGoalUpdates(sessionId, roundId, updates, emerged) {
-        if (updates.length === 0)
-            return [];
-        const session = this.sessions.get(sessionId);
-        if (!session)
-            return [];
-        const expectedRoundId = session.roundSnapshot?.roundId
-            ?? makeRoundId(session.loopId, session.currentRound);
-        if (expectedRoundId !== roundId)
-            return []; // stale/foreign submission — advance handles it
-        const response = this.compileContext(session);
-        if (!response?.sub_goals)
-            return []; // fail open: cannot observe
-        const known = [...response.sub_goals];
-        for (const desc of emerged) {
-            const id = deriveSubGoalId(desc);
-            if (!known.some((sg) => sg.id === id)) {
-                known.push({
-                    id,
-                    description: desc.trim(),
-                    status: "pending",
-                    declared_at_round: session.currentRound,
-                    status_changed_at_round: session.currentRound,
-                    priority: known.length,
-                });
-            }
-        }
-        return validateSubGoalUpdates(known, updates).map((error) => ({
-            field: "subgoal_updates",
-            reason: error.reason,
-            detail: `${error.reason.replace(/_/g, " ")}: ${error.id}`,
-        }));
+        return compileSessionContext(session);
     }
     /** Typed cognitive state projection for an active session. Derived on
      *  demand — zero persistence. Null when nothing meaningful exists yet. */
@@ -743,14 +714,43 @@ export class SessionManager {
         ];
         const compileResponse = this.compileContext(session);
         const openGates = this.lifecycle.listOpenGateDescriptions(session.loopId);
+        // v3.8: the projection reads the WHOLE committed history. The old
+        // `beforeRound: session.currentRound` bound is only correct while the loop
+        // is running, where currentRound is always one past the last committed
+        // round; a stop / terminate / max_rounds leaves currentRound ON the round
+        // it just committed, so the bound silently dropped the loop's final round
+        // and the projection disagreed with audit and explain about it.
+        // v3.8.1: one window, one decode, one derivation. The contract facts come
+        // from the same `deriveRoundFacts` the compile path calls, so the prompt
+        // and the projection cannot tell different stories about what the machine
+        // verified.
+        const rounds = readOnlyRounds(entries);
         const projection = buildLoopProjection(deriveCognitiveFacts({
             compileResponse,
-            rounds: committedRoundsFromEntries(entries, session.currentRound),
+            rounds,
+            facts: deriveRoundFacts({
+                rounds,
+                currentRound: (rounds[rounds.length - 1]?.round ?? 0) + 1,
+                inFlight: NO_IN_FLIGHT_ROUND,
+                subGoals: compileResponse?.sub_goals ?? [],
+                commands: getPolicy().evidence.commands ?? [],
+            }),
             verifiedClaims: listVerifiedClaims(entries, session.loopId),
             openGates,
         }));
         return projection ? { ...projection } : null;
     }
+    /** v3.8: Read-only per-round "why" view over committed facts. Never
+     *  rebuilds history and never writes. */
+    getExplain(loopId, round) {
+        validateLoopId(loopId);
+        const prefix = `loop:${loopId}:`;
+        const entries = [
+            ...queryLoopEntries(this.loopStore, loopId, { prefix }),
+            ...queryLoopEntries(this.loopStore, loopId, { prefix, feedbackOnly: true }),
+        ];
+        return buildExplain(loopId, entries, round);
+    }
     /** Read-only end-of-loop audit (verification view). Never writes. */
     getAudit(loopId) {
         validateLoopId(loopId);
@@ -767,7 +767,7 @@ export class SessionManager {
         // Zero committed decisions → nothing to audit. Returning null lets the
         // tools layer report "no audit data" instead of the external auditor
         // solemnly passing a loop that never ran (or a mistyped loopId).
-        const hasCommittedDecision = committedRoundsFromEntries(entries).length > 0;
+        const hasCommittedDecision = readOnlyRounds(entries).length > 0;
         if (!hasCommittedDecision)
             return null;
         const audit = buildAudit(loopId, entries, this.loopStore);
@@ -781,12 +781,8 @@ export class SessionManager {
         const session = this.sessions.get(sessionId);
         if (!session)
             return null;
-        const prefix = `loop:${session.loopId}:`;
-        const entries = [
-            ...queryLoopEntries(this.loopStore, session.loopId, { prefix }),
-            ...queryLoopEntries(this.loopStore, session.loopId, { prefix, feedbackOnly: true }),
-        ];
-        return deriveActiveRoundContract(contractRoundEvaluations(committedRoundsFromEntries(entries, session.currentRound)));
+        // One derivation, shared with the submission boundary.
+        return activeContractOf(this.loopStore, session);
     }
     /** v2.12: Policy metrics that survive restarts — vault-derived round
      *  statistics (A4 port) folded with this process's live observations.
@@ -808,48 +804,35 @@ export class SessionManager {
             return live;
         return mergePolicyMetrics(derived, live);
     }
-    /** Get loop health for a loop (in-memory or vault).
-     *  Computes goal alignment, constraint integrity, drift, strategy stability. */
+    /** Get machine facts about a loop (in-memory or vault).
+     *
+     *  v3.8.1: this view used to report `goal_alignment`, `drift_detected`,
+     *  `strategy_stability` and `task_continuity`. Every one was a
+     *  text-similarity verdict rather than a fact, and two were degenerate in
+     *  THIS method specifically: `task_continuity` was pinned to 1.0 because the
+     *  request was built with `round: 1`, so `getPreviousRound(loopId, 0)`
+     *  returned null and the code took its hardcoded `?? 1` branch; and
+     *  `strategy_stability` was a literal `true`. What remains is counted
+     *  directly from committed round flags. */
     getHealth(loopId) {
-        // Find the task — check in-memory sessions first, then vault
-        let task = "";
-        let goalId = loopId;
-        for (const s of this.sessions.values()) {
-            if (s.loopId === loopId) {
-                task = s.task;
-                if (s.engine.state?.task_id) {
-                    goalId = s.engine.state.task_id;
-                }
-                break;
-            }
-        }
-        // Fall back to vault for task
-        if (!task) {
-            const sessionEntry = this.findSessionEntry(loopId);
-            if (sessionEntry) {
-                task = sessionEntry.task ?? "";
-            }
-        }
-        if (!task)
-            return null;
-        // Hydrate vault context
         const engine = new LoopForgeEngine(this.loopStore);
-        const vaultContext = engine.hydrateLoopContext(loopId);
-        // Build a minimal request for health check
-        const request = makeLoopCompileRequest({
-            task,
-            loop_id: loopId,
-            goal_id: goalId,
-            round: 1, // round doesn't matter for health check
-        });
-        const health = checkLoopHealth(loopId, request, vaultContext);
+        const context = engine.hydrateLoopContext(loopId);
+        // No hydratable context at all → unknown loop. A started-but-uncommitted
+        // loop DOES have a context (the compile persists a lineage entry), so it
+        // still gets a view — with zeros — exactly as it did before.
+        if (!context)
+            return null;
+        const entries = Array.isArray(context.results) ? context.results : [];
+        const views = readOnlyRounds(entries);
+        const roundsWithUnverifiedItems = views.filter((view) => view.verificationFlags.some((flag) => flag.check === CHECK_CONTRACT_ITEMS_UNVERIFIED)).length;
         return {
             loopId,
-            goal_alignment: health.goal_alignment,
-            constraint_integrity: health.constraint_integrity,
-            drift_detected: health.drift_detected,
-            strategy_stability: health.strategy_stability,
-            task_continuity: health.task_continuity,
+            committed_rounds: views.length,
+            rounds_with_unverified_items: roundsWithUnverifiedItems,
+            // The policy value the enforcement gate escalates on. The streak itself
+            // is derived in the gate — re-deriving it here would be a second
+            // implementation of the same rule, which is what this release removes.
+            unverified_streak_limit: getPolicy().engine.unverified_claim_streak_limit,
             policy_metrics: this.getPolicyMetrics(loopId),
         };
     }
@@ -861,34 +844,36 @@ export class SessionManager {
      *    (from the last start/next/resume response). Anchors the submission so a
      *    stale or duplicate submission is not processed against a later round.
      *    Optional for library callers — when absent the anchor check is skipped. */
-    async advance(sessionId, output, preExtractedEval, roundId) {
-        const current = this.sessions.get(sessionId);
-        if (current && (current.status === "running" || current.status === "stalled")) {
-            const rawEvaluation = preExtractedEval;
-            if (!isRecord(rawEvaluation)) {
-                return {
-                    sessionId,
-                    round: current.currentRound,
-                    roundId: current.roundSnapshot?.roundId
-                        ?? makeRoundId(current.loopId, current.currentRound),
-                    prompt: null,
-                    stopReason: "evaluation_invalid",
-                    stopDetail: "A structured evaluation object is required. Resubmit the same roundId with success, output_summary, constraint_violations, and should_continue.",
-                };
-            }
-            const validation = validateCoreSelfEvaluation(rawEvaluation);
-            if (validation.missing.length > 0 || validation.invalid.length > 0) {
-                return {
-                    sessionId,
-                    round: current.currentRound,
-                    roundId: current.roundSnapshot?.roundId
-                        ?? makeRoundId(current.loopId, current.currentRound),
-                    prompt: null,
-                    stopReason: "evaluation_invalid",
-                    stopDetail: "The structured evaluation has missing or invalid core fields. Correct it and resubmit the same roundId.",
-                };
-            }
-            preExtractedEval = buildSelfEvaluation(rawEvaluation);
+    /** \`submission\` is the RAW evaluation payload, not a built one.
+     *
+     *  v3.8.1: this method used to carry a partial copy of the submission
+     *  boundary (an object check plus core-field validation) while the MCP tool
+     *  handler carried the rest — one rule, three copies, across two layers.
+     *  The boundary now lives entirely in the runtime
+     *  (`RoundLifecycle.submissionBoundary`), so every caller — this manager, a
+     *  library user, a future CLI command — gets the same strictness. */
+    /** \`submission\` is the RAW evaluation payload, not a built one.
+     *
+     *  v3.8.1: this method used to carry a partial copy of the submission
+     *  boundary (an object check plus core-field validation) while the MCP tool
+     *  handler carried the rest — one rule, three copies, across two layers.
+     *  The whole boundary now runs HERE, before the queue and before the lease
+     *  heartbeat, so every caller of the public API gets it and a rejected
+     *  payload leaves nothing durable behind. */
+    async advance(sessionId, output, submission, roundId) {
+        // Judged before the session is even resolved: a malformed evaluation is a
+        // payload defect whatever the session's state. See submission-boundary.ts.
+        const boundary = validateSubmission(this.loopStore, this.sessions.get(sessionId), submission);
+        if (!boundary.ok) {
+            return {
+                sessionId,
+                round: this.sessions.get(sessionId)?.currentRound ?? 0,
+                ...(roundId !== undefined ? { roundId } : {}),
+                prompt: null,
+                stopReason: boundary.submissionError.code,
+                stopDetail: boundary.stopDetail,
+                submissionError: boundary.submissionError,
+            };
         }
         return this.withSessionQueue(sessionId, async () => {
             const session = this.sessions.get(sessionId);
@@ -897,7 +882,7 @@ export class SessionManager {
                 return this.leaseConflictResult(session.loopId, this.findSessionEntry(session.loopId));
             }
             try {
-                return await this.lifecycle.advance(sessionId, output, preExtractedEval, roundId);
+                return await this.lifecycle.advance(sessionId, output, boundary.evaluation, roundId);
             }
             catch (error) {
                 if (error instanceof SessionLeaseConflictError) {