@kontourai/survey 3.0.0 → 4.0.0

package/dist/src/review-session-file.js

@@ -0,0 +1,320 @@
+/**
+ * Shared session-file persistence for the local review writers
+ * (`survey-review-console` and `survey-review-mcp`).
+ *
+ * Every write goes through {@link updateReviewSessionFile}, which takes one
+ * exclusive lock file next to the session, re-reads the session inside the
+ * lock, applies the caller's change, writes a uniquely named temp file and
+ * renames it into place. Both writers must use this helper: a lock that only
+ * one of them takes still races with the other (kontourai/survey#281).
+ */
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { open, readdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { defaultReviewSessionName } from "./review-workbench/review-queue-session.js";
+export class ReviewSessionFileLockTimeoutError extends Error {
+    constructor(lockPath, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for session lock ${lockPath}`);
+        this.name = "ReviewSessionFileLockTimeoutError";
+    }
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_MS = 30_000;
+/** A lock file that is still empty this long after creation was left by an acquirer that died between create and write. */
+const EMPTY_LOCK_STALE_MS = 1_000;
+/** The break mutex is held for a few milliseconds; older means its holder died mid-break. */
+const BREAK_MUTEX_STALE_MS = 5_000;
+const RETRY_MIN_MS = 10;
+const RETRY_MAX_MS = 50;
+export function reviewSessionLockPath(sessionPath) {
+    return `${sessionPath}.lock`;
+}
+export async function readReviewSessionFile(sessionPath) {
+    return JSON.parse(await readFile(sessionPath, "utf8"));
+}
+/**
+ * Opaque revision token for an event log: a digest of its serialized form.
+ * An event count is not enough, because the log is regenerated from session
+ * state and a changed decision keeps the count while changing the content.
+ */
+export function reviewSessionRevision(events) {
+    return createHash("sha256").update(JSON.stringify(events)).digest("hex").slice(0, 32);
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * An identity for the process currently running as `pid`: its start time, as
+ * the OS reports it. A pid can be reused after its holder dies, so a live pid
+ * only proves the holder is alive when the start time also matches the one
+ * the holder recorded (kontourai/survey#298). Linux reads `/proc/<pid>/stat`
+ * field 22 (start time in clock ticks since boot); elsewhere `ps -o lstart=`
+ * (one-second resolution), rendered in UTC with the C locale so every reader
+ * spells the same instant the same way whatever its own TZ or locale. Resolves `undefined` when the platform offers
+ * neither or the process is gone, which leaves the pid-only rule in force.
+ */
+async function processStartIdentity(pid) {
+    if (process.platform === "linux") {
+        try {
+            const procStat = await readFile(`/proc/${pid}/stat`, "utf8");
+            // Fields after the parenthesized command name, which may contain spaces.
+            const fields = procStat.slice(procStat.lastIndexOf(")") + 2).split(" ");
+            const startTicks = fields[19];
+            return startTicks ? `linux-starttime:${startTicks}` : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === "win32")
+        return undefined;
+    return new Promise((resolveIdentity) => {
+        execFile("ps", ["-o", "lstart=", "-p", String(pid)], { env: { ...process.env, LC_ALL: "C", TZ: "UTC" }, timeout: 2_000 }, (error, stdout) => {
+            const started = error ? "" : stdout.trim().replace(/\s+/g, " ");
+            resolveIdentity(started ? `ps-lstart:${started}` : undefined);
+        });
+    });
+}
+let ownStartIdentity;
+/**
+ * A lock is stale only when we can show its holder is gone, never merely
+ * because it is old. Liveness is authoritative whenever the lock carries a
+ * usable pid: a holder that is alive but slow (age past `staleMs`) is NOT
+ * stale — age alone used to be enough to break it, which let a live-but-slow
+ * holder's lock be removed out from under it (kontourai/survey#281 review:
+ * 135 double-hold events in 60 rounds of the reviewer's stress test). We
+ * deliberately do not add a hard age ceiling that overrides a live pid: with
+ * the default timeoutMs (10s) well under the default staleMs (30s), a waiter
+ * simply times out with {@link ReviewSessionFileLockTimeoutError} against a
+ * live holder that never releases in time, which is a loud, safe failure
+ * mode rather than a silent double-hold. A genuinely wedged holder (hung
+ * forever) requires an operator to remove the lock file by hand; that is the
+ * accepted cost of "never remove a live lock" actually holding.
+ *
+ * The age rule is kept only as the fallback for a lock we cannot judge by
+ * liveness: no pid field (unknown-PID); a live pid whose current start time
+ * differs from the one the holder recorded, i.e. the holder died and its pid
+ * was reused by an unrelated process (kontourai/survey#298); or, since the lock carries no host
+ * identity, a pid from another host/container sharing this volume (`isPidAlive`
+ * is meaningless there, in either direction — the residual this repo has
+ * always accepted for that case).
+ */
+async function lockIsStale(lockPath, staleMs) {
+    try {
+        const info = await stat(lockPath);
+        const age = Date.now() - info.mtimeMs;
+        const raw = await readFile(lockPath, "utf8");
+        if (raw.trim() === "")
+            return age > EMPTY_LOCK_STALE_MS;
+        const holder = JSON.parse(raw);
+        if (typeof holder.pid === "number") {
+            if (!isPidAlive(holder.pid))
+                return true;
+            if (typeof holder.startIdentity !== "string")
+                return false;
+            const current = await processStartIdentity(holder.pid);
+            // Unknown now (or never recorded): trust liveness, as before.
+            if (current === undefined || current === holder.startIdentity)
+                return false;
+        }
+        return age > staleMs;
+    }
+    catch {
+        // Vanished (released) or half-written by a live acquirer: not stale.
+        return false;
+    }
+}
+/**
+ * Remove a stale lock without ever removing a live one.
+ *
+ * Breakers serialize on a separate `<lock>.break` mutex and re-judge the lock
+ * inside it. While a breaker holds the mutex, the lock file can only change if
+ * its owner releases it, and {@link lockIsStale} only calls a lock stale once
+ * its holder is provably dead (or, lacking a usable pid, sufficiently old), so
+ * the file the breaker removes is the one it judged stale. The earlier
+ * rename-aside scheme let two waiters that both judged the same lock stale
+ * each remove it, the second removing the first's fresh lock
+ * (kontourai/survey#281 review). A holder that is merely alive-but-slow is
+ * never broken, by construction, no matter its age (see {@link lockIsStale}).
+ * Residual (accepted): a breaker that dies inside the few-millisecond break
+ * section leaves a mutex that is removed after BREAK_MUTEX_STALE_MS, and pid
+ * liveness means nothing across hosts or containers that share the session
+ * volume (the age rule is the only signal available there, and it is a
+ * pre-existing limitation, not one this fix introduces).
+ */
+async function breakStaleLock(lockPath, staleMs) {
+    const breakPath = `${lockPath}.break`;
+    try {
+        await (await open(breakPath, "wx")).close();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        try {
+            if (Date.now() - (await stat(breakPath)).mtimeMs > BREAK_MUTEX_STALE_MS) {
+                await rm(breakPath, { force: true });
+            }
+        }
+        catch {
+            // Released meanwhile.
+        }
+        return;
+    }
+    try {
+        if (await lockIsStale(lockPath, staleMs)) {
+            await rm(lockPath, { force: true });
+        }
+    }
+    finally {
+        await rm(breakPath, { force: true });
+    }
+}
+/**
+ * Acquire the exclusive session lock. Resolves with a release function.
+ * Exported so tests can hold the lock and observe that writers wait for it.
+ */
+export async function acquireReviewSessionFileLock(sessionPath, options = {}) {
+    const lockPath = reviewSessionLockPath(sessionPath);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + timeoutMs;
+    const token = randomUUID();
+    ownStartIdentity ??= processStartIdentity(process.pid);
+    const startIdentity = await ownStartIdentity;
+    for (;;) {
+        try {
+            const handle = await open(lockPath, "wx");
+            try {
+                await handle.writeFile(JSON.stringify({ pid: process.pid, ...(startIdentity ? { startIdentity } : {}), token, acquiredAt: new Date().toISOString() }));
+            }
+            finally {
+                await handle.close();
+            }
+            return async () => {
+                // Only remove the lock if it is still ours (a stale-lock breaker may
+                // have replaced it after we were presumed dead).
+                try {
+                    const holder = JSON.parse(await readFile(lockPath, "utf8"));
+                    if (holder.token === token)
+                        await rm(lockPath, { force: true });
+                }
+                catch {
+                    // Already gone.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        if (await lockIsStale(lockPath, staleMs)) {
+            await breakStaleLock(lockPath, staleMs);
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new ReviewSessionFileLockTimeoutError(lockPath, timeoutMs);
+        }
+        const delay = RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS));
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, delay));
+    }
+}
+function tempFilePattern(sessionPath) {
+    const escaped = basename(sessionPath).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^${escaped}\\.\\d+\\.[0-9a-f-]{36}\\.tmp$`);
+}
+/**
+ * Remove temp files a crashed writer left between write and rename. Called
+ * only while holding the lock, when no other writer can have a temp file in
+ * flight, so every match is an orphan.
+ */
+async function removeOrphanTempFiles(sessionPath) {
+    const pattern = tempFilePattern(sessionPath);
+    let entries;
+    try {
+        entries = await readdir(dirname(sessionPath));
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries.filter((entry) => pattern.test(entry)).map((entry) => rm(join(dirname(sessionPath), entry), { force: true })));
+}
+async function writeReviewSessionFileAtomic(sessionPath, content) {
+    const tmp = `${sessionPath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(tmp, "wx");
+        try {
+            await handle.writeFile(JSON.stringify(content, null, 2), "utf8");
+            // Durable before it becomes visible: a crash after the rename must not
+            // leave a renamed but empty or partial session file.
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, sessionPath);
+    }
+    catch (error) {
+        await rm(tmp, { force: true });
+        throw error;
+    }
+}
+/**
+ * Locked read-modify-write of a session file. `mutate` receives the content
+ * read inside the lock and returns the content to write, or `undefined` to
+ * leave the file untouched. Whatever `mutate` throws propagates after the lock
+ * is released.
+ */
+export async function updateReviewSessionFile(sessionPath, mutate, options = {}) {
+    const release = await acquireReviewSessionFileLock(sessionPath, options);
+    try {
+        await removeOrphanTempFiles(sessionPath);
+        const current = await readReviewSessionFile(sessionPath);
+        const { next, result } = await mutate(current);
+        if (next !== undefined) {
+            await writeReviewSessionFileAtomic(sessionPath, next);
+        }
+        return result;
+    }
+    finally {
+        await release();
+    }
+}
+/**
+ * The session name the stored log is recorded under: the name its events
+ * already carry, else the stored ReviewSession's name, else `fallback` (the
+ * writer's own default). Appended events are renamed into it so one log never mixes names.
+ */
+export function storedReviewSessionName(content, fallback = defaultReviewSessionName) {
+    const fromEvents = content.events[0]?.spec.sessionName;
+    if (fromEvents)
+        return fromEvents;
+    const session = content.session;
+    return typeof session?.metadata?.name === "string" ? session.metadata.name : fallback;
+}
+/**
+ * Append events to the stored log, renumbering them after the stored events
+ * and renaming them into the stored session. The stored log is never
+ * rewritten, so decision reversals and note changes stay on record.
+ */
+export function appendReviewSessionEvents(content, appended) {
+    const sessionName = storedReviewSessionName(content);
+    const start = content.events.length;
+    const renumbered = [...appended]
+        .sort((left, right) => left.spec.sequence - right.spec.sequence)
+        .map((event, index) => {
+        const sequence = start + index + 1;
+        return {
+            ...event,
+            metadata: { ...event.metadata, name: `${sessionName}-${String(sequence).padStart(4, "0")}-${event.spec.eventType}` },
+            spec: { ...event.spec, sessionName, sequence },
+        };
+    });
+    return [...content.events, ...renumbered];
+}

package/dist/src/review-workbench/edited-value.d.ts

@@ -0,0 +1,70 @@
+import type { ReviewItem, ReviewValueDescriptor } from "../review-resource.js";
+/**
+ * Result of checking an inline edit (`data.workbenchEditedValue` on an
+ * `accept-proposed` decision event) against the ReviewItem it edits.
+ *
+ * - `ok: true` — the edit is allowed; `value` is the value to store. When
+ *   `convertedFromText` is true, the stored edit was descriptor-typed text
+ *   written by an older workbench (for example `"42"` on a number field) and
+ *   `value` is its typed form (`42`).
+ * - `ok: false` — the edit must be refused: the item is not editable, or the
+ *   value does not satisfy the item's `valueDescriptor`.
+ */
+export type EditedValueCheck = {
+    readonly ok: true;
+    readonly value: unknown;
+    readonly convertedFromText: boolean;
+} | {
+    readonly ok: false;
+    readonly code: "edited-value-not-editable" | "edited-value-type-mismatch";
+    readonly message: string;
+};
+/**
+ * True for a `YYYY-MM-DD` string naming a real calendar day. The Y/M/D must
+ * round-trip through a UTC date, so an impossible day such as `2026-02-31`
+ * (which `Date.parse` silently rolls over to March) is refused.
+ */
+export declare function isIsoCalendarDate(value: string): boolean;
+/**
+ * Parses number-field editor text, or returns `undefined` when it is not a
+ * plain decimal or would not survive storage as a JSON number exactly.
+ *
+ * Integer-only text (no `.` and no exponent) is checked by
+ * `Number.isSafeInteger` instead of the digit count: every safe integer
+ * (|value| ≤ 2^53−1, i.e. up to 9007199254740991, 16 digits) round-trips
+ * through a JSON number exactly, so the 15-significant-digit rule would
+ * wrongly refuse `9007199254740991` while accepting some 15-digit values
+ * that are actually less precise. `9007199254740993` is refused: it is
+ * outside the safe range and `Number(...)` rounds it to `9007199254740992`,
+ * a different integer than the text named.
+ *
+ * A fractional value (has `.` or an exponent) keeps the 15-significant-digit
+ * rule: `Number.isSafeInteger` does not apply to it, and IEEE 754 doubles
+ * only guarantee exactness up to 15 significant decimal digits, so anything
+ * longer is refused rather than silently rounded. A value that overflows to
+ * Infinity is refused. `-0` is stored as `0` (JSON has no negative zero).
+ */
+export declare function parsePlainDecimal(text: string): number | undefined;
+/**
+ * Converts a reviewer's editor text to the JSON type the item's descriptor
+ * declares, using the same parsing rules the workbench's `validateProposedValue`
+ * checks. Returns `undefined` when the text does not parse for that type. With
+ * no descriptor, or a type that has no single-line form (string, array, object),
+ * the text is returned unchanged.
+ */
+export declare function editedValueFromEditorText(descriptor: ReviewValueDescriptor | undefined, text: string): unknown;
+/**
+ * Checks an inline edit carried by an `accept-proposed` decision against the
+ * item's `editable` flag and `valueDescriptor`. This is the server-side
+ * counterpart of the browser editor's validation (kontourai/survey#278): the
+ * apply boundary must not trust an edit the workbench would never have let a
+ * reviewer make.
+ *
+ * Legacy sessions: workbenches before this check stored every edit as the
+ * editor's text, so a number or boolean edit arrives as `"42"` / `"true"`. Such
+ * text (and date/enum text with surrounding whitespace, which the old editor
+ * accepted and stored untrimmed) is converted to its typed value when it parses
+ * cleanly under the workbench's own rules (`convertedFromText: true`, reported as a warning by the
+ * apply derivation); text that does not parse is refused.
+ */
+export declare function checkEditedValueForItem(item: ReviewItem, value: unknown): EditedValueCheck;

package/dist/src/review-workbench/edited-value.js

@@ -0,0 +1,147 @@
+const isoDatePattern = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * True for a `YYYY-MM-DD` string naming a real calendar day. The Y/M/D must
+ * round-trip through a UTC date, so an impossible day such as `2026-02-31`
+ * (which `Date.parse` silently rolls over to March) is refused.
+ */
+export function isIsoCalendarDate(value) {
+    const match = isoDatePattern.exec(value);
+    if (!match)
+        return false;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+// Plain decimal only: optional minus, no leading zeros, optional fraction and
+// exponent. Refuses hex/binary/octal forms, "Infinity", "+1", ".5" and "007".
+const plainDecimalPattern = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+/** A JSON number keeps at most 15 significant decimal digits exactly (IEEE 754 double). */
+const maxSignificantDigits = 15;
+/**
+ * Parses number-field editor text, or returns `undefined` when it is not a
+ * plain decimal or would not survive storage as a JSON number exactly.
+ *
+ * Integer-only text (no `.` and no exponent) is checked by
+ * `Number.isSafeInteger` instead of the digit count: every safe integer
+ * (|value| ≤ 2^53−1, i.e. up to 9007199254740991, 16 digits) round-trips
+ * through a JSON number exactly, so the 15-significant-digit rule would
+ * wrongly refuse `9007199254740991` while accepting some 15-digit values
+ * that are actually less precise. `9007199254740993` is refused: it is
+ * outside the safe range and `Number(...)` rounds it to `9007199254740992`,
+ * a different integer than the text named.
+ *
+ * A fractional value (has `.` or an exponent) keeps the 15-significant-digit
+ * rule: `Number.isSafeInteger` does not apply to it, and IEEE 754 doubles
+ * only guarantee exactness up to 15 significant decimal digits, so anything
+ * longer is refused rather than silently rounded. A value that overflows to
+ * Infinity is refused. `-0` is stored as `0` (JSON has no negative zero).
+ */
+export function parsePlainDecimal(text) {
+    const match = plainDecimalPattern.exec(text);
+    if (!match)
+        return undefined;
+    const isIntegerOnly = match[2] === undefined && match[3] === undefined;
+    if (isIntegerOnly) {
+        const parsed = Number(text);
+        if (!Number.isSafeInteger(parsed))
+            return undefined;
+        return parsed === 0 ? 0 : parsed;
+    }
+    const digits = `${match[1]}${(match[2] ?? "").slice(1)}`.replace(/^0+/, "").replace(/0+$/, "");
+    if (digits.length > maxSignificantDigits)
+        return undefined;
+    const parsed = Number(text);
+    if (!Number.isFinite(parsed))
+        return undefined;
+    return parsed === 0 ? 0 : parsed;
+}
+/**
+ * Converts a reviewer's editor text to the JSON type the item's descriptor
+ * declares, using the same parsing rules the workbench's `validateProposedValue`
+ * checks. Returns `undefined` when the text does not parse for that type. With
+ * no descriptor, or a type that has no single-line form (string, array, object),
+ * the text is returned unchanged.
+ */
+export function editedValueFromEditorText(descriptor, text) {
+    if (!descriptor)
+        return text;
+    const trimmed = text.trim();
+    switch (descriptor.type) {
+        case "number":
+            return parsePlainDecimal(trimmed);
+        case "boolean":
+            return trimmed === "true" ? true : trimmed === "false" ? false : undefined;
+        case "date":
+            return isIsoCalendarDate(trimmed) ? trimmed : undefined;
+        case "enum": {
+            const allowed = descriptor.enumValues ?? [];
+            return allowed.length === 0 || allowed.includes(trimmed) ? trimmed : undefined;
+        }
+        default:
+            return text;
+    }
+}
+function valueMatchesDescriptor(descriptor, value) {
+    switch (descriptor.type) {
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "date":
+            return typeof value === "string" && isIsoCalendarDate(value);
+        case "enum": {
+            if (typeof value !== "string")
+                return false;
+            const allowed = descriptor.enumValues ?? [];
+            return allowed.length === 0 || allowed.includes(value);
+        }
+        case "string":
+            return typeof value === "string";
+        default:
+            // array/object: the workbench has no typed editor for these, so Survey
+            // declares no constraint on the edit's shape.
+            return true;
+    }
+}
+/**
+ * Checks an inline edit carried by an `accept-proposed` decision against the
+ * item's `editable` flag and `valueDescriptor`. This is the server-side
+ * counterpart of the browser editor's validation (kontourai/survey#278): the
+ * apply boundary must not trust an edit the workbench would never have let a
+ * reviewer make.
+ *
+ * Legacy sessions: workbenches before this check stored every edit as the
+ * editor's text, so a number or boolean edit arrives as `"42"` / `"true"`. Such
+ * text (and date/enum text with surrounding whitespace, which the old editor
+ * accepted and stored untrimmed) is converted to its typed value when it parses
+ * cleanly under the workbench's own rules (`convertedFromText: true`, reported as a warning by the
+ * apply derivation); text that does not parse is refused.
+ */
+export function checkEditedValueForItem(item, value) {
+    const itemName = item.metadata.name;
+    if (item.spec.editable === false) {
+        return {
+            ok: false,
+            code: "edited-value-not-editable",
+            message: `ReviewItem ${itemName} is not editable (spec.editable: false), but the decision carries an edited value.`,
+        };
+    }
+    const descriptor = item.spec.valueDescriptor;
+    if (!descriptor || valueMatchesDescriptor(descriptor, value)) {
+        return { ok: true, value, convertedFromText: false };
+    }
+    if (typeof value === "string") {
+        const converted = editedValueFromEditorText(descriptor, value);
+        if (converted !== undefined) {
+            return { ok: true, value: converted, convertedFromText: true };
+        }
+    }
+    const allowed = descriptor.type === "enum" && descriptor.enumValues?.length
+        ? ` (one of: ${descriptor.enumValues.join(", ")})`
+        : "";
+    return {
+        ok: false,
+        code: "edited-value-type-mismatch",
+        message: `ReviewItem ${itemName} declares value type ${descriptor.type}${allowed}, but the decision carries edited value ${JSON.stringify(value)}.`,
+    };
+}

package/dist/src/review-workbench/review-presentation.d.ts

@@ -1,4 +1,5 @@
 import { type ReviewCandidate, type ReviewItem } from "../review-resource.js";
+import type { InterpretationAnswerImpact, InterpretationReadingKind } from "../types.js";
 import { type ReviewWorkbenchResult } from "./review-workbench.js";
 export interface ReviewPresentationAdapter {
     readonly labelForTarget?: (target: string, context: ReviewItemPresentationContext) => string | undefined;
@@ -61,6 +62,49 @@ export interface ReviewResultPresentation {
     readonly reviewItemLink?: ReviewPresentationLink;
     readonly traceRefs: readonly ReviewTraceRef[];
 }
+/**
+ * Structural input for {@link buildInterpretationReadingPresentation}: either
+ * a Survey `Interpretation` record (`id`) or the entry Survey projects onto a
+ * claim at `metadata.survey.interpretations[]` (`interpretationId`). Kind and
+ * impact arrive as plain strings when read back from projected metadata.
+ */
+export interface InterpretationReadingSource {
+    readonly id?: string;
+    readonly interpretationId?: string;
+    readonly readingKind?: string;
+    readonly answerImpact?: string;
+    readonly ruleLocator: string;
+    readonly reading: string;
+    readonly actor: string;
+    readonly recordedAt: string;
+}
+export interface InterpretationReadingPresentation {
+    readonly interpretationId: string;
+    readonly readingKind: InterpretationReadingKind;
+    readonly kindLabel: string;
+    readonly answerImpact?: InterpretationAnswerImpact;
+    readonly answerImpactLabel?: string;
+    readonly reading: string;
+    readonly actor: string;
+    readonly recordedAt: string;
+    readonly ruleLocator: string;
+    /**
+     * Always `"authored-judgment"`. This is DERIVED from the record type, not a
+     * stored flag: every Interpretation reading is a producer-authored reading
+     * by contract (CONTEXT.md "Interpretation Record"), never a machine-observed
+     * fact. Renderers must present readings under this marking, visually
+     * distinct from machine-observed values — the StatementBadge / ADR 0003 §4
+     * discipline (blending the two is the defect class of #247).
+     */
+    readonly provenance: "authored-judgment";
+    readonly provenanceLabel: string;
+}
+/**
+ * Presents one interpretation reading as authored judgment. Fails closed on
+ * unknown reading-kind / answer-impact vocabulary rather than rendering an
+ * authored record under a label nothing derived.
+ */
+export declare function buildInterpretationReadingPresentation(source: InterpretationReadingSource): InterpretationReadingPresentation;
 export declare function buildReviewItemPresentation(item: ReviewItem, adapter?: ReviewPresentationAdapter): ReviewItemPresentation;
 export declare function buildReviewCandidatePresentation(item: ReviewItem, candidate: ReviewCandidate, adapter?: ReviewPresentationAdapter, targetLabel?: string): ReviewCandidatePresentation;
 export declare function buildReviewResultPresentation(result: ReviewWorkbenchResult, item: ReviewItem | undefined, adapter?: ReviewPresentationAdapter): ReviewResultPresentation;

package/dist/src/review-workbench/review-presentation.js

@@ -1,5 +1,54 @@
 import { findSoleCandidateById } from "../review-resource.js";
 import { formatValue } from "./review-surface-preview.js";
+const INTERPRETATION_KIND_LABELS = {
+    "policy-standard": "Policy-standard reading",
+    gleaned: "Gleaned from results",
+    answerImpact: "Answer impact",
+};
+const ANSWER_IMPACT_LABELS = {
+    supported: "Supported the answer",
+    narrowed: "Narrowed the answer",
+    "accepted-risk": "Accepted as a risk",
+};
+/**
+ * Presents one interpretation reading as authored judgment. Fails closed on
+ * unknown reading-kind / answer-impact vocabulary rather than rendering an
+ * authored record under a label nothing derived.
+ */
+export function buildInterpretationReadingPresentation(source) {
+    const interpretationId = source.interpretationId ?? source.id;
+    if (!interpretationId) {
+        throw new Error("Interpretation reading presentation requires an id or interpretationId.");
+    }
+    const readingKind = (source.readingKind ?? "policy-standard");
+    const kindLabel = INTERPRETATION_KIND_LABELS[readingKind];
+    if (!kindLabel) {
+        throw new Error(`Interpretation ${interpretationId} has unknown readingKind ${String(source.readingKind)}`);
+    }
+    const answerImpact = source.answerImpact;
+    const answerImpactLabel = answerImpact === undefined ? undefined : ANSWER_IMPACT_LABELS[answerImpact];
+    if (answerImpact !== undefined && !answerImpactLabel) {
+        throw new Error(`Interpretation ${interpretationId} has unknown answerImpact ${String(source.answerImpact)}`);
+    }
+    if (readingKind === "answerImpact" && answerImpact === undefined) {
+        throw new Error(`Interpretation ${interpretationId} readingKind answerImpact requires an answerImpact value`);
+    }
+    if (readingKind !== "answerImpact" && answerImpact !== undefined) {
+        throw new Error(`Interpretation ${interpretationId} sets answerImpact but readingKind is ${readingKind}`);
+    }
+    return {
+        interpretationId,
+        readingKind,
+        kindLabel,
+        ...(answerImpact !== undefined ? { answerImpact, answerImpactLabel } : {}),
+        reading: source.reading,
+        actor: source.actor,
+        recordedAt: source.recordedAt,
+        ruleLocator: source.ruleLocator,
+        provenance: "authored-judgment",
+        provenanceLabel: "Authored judgment",
+    };
+}
 export function buildReviewItemPresentation(item, adapter = {}) {
     const context = { item };
     const targetLabel = adapter.labelForTarget?.(item.spec.target, context) ?? humanizeIdentifier(item.spec.target);

package/dist/src/review-workbench/review-queue-session.js

@@ -1,5 +1,6 @@
 import { publicDirectoryReviewItemExample, reviewWorkbenchQueueExamples } from "./review-workbench-data.js";
 import { assertReviewResolutionConsistency } from "../producer-discipline.js";
+import { checkEditedValueForItem } from "./edited-value.js";
 import { assertSoleCandidateId, reviewResourceApiVersion, } from "../../src/review-resource.js";
 export const reviewWorkbenchSessionStorageKey = "kontourai.survey.review-workbench.session-events.v1";
 export const defaultReviewSessionName = "review-workbench-session";
@@ -368,7 +369,13 @@ export function replayReviewSessionEvents(startState, events) {
             const editedValuesByItemName = { ...session.editedValuesByItemName };
             const attemptEvidenceIdsByItemName = { ...session.attemptEvidenceIdsByItemName };
             if (decision === "accept-proposed" && editedValue !== undefined) {
-                editedValuesByItemName[itemName] = editedValue;
+                // Legacy sessions stored typed edits as editor text ("42"); store the
+                // descriptor-typed value so effectiveValue is 42. An edit the item does
+                // not allow is left as carried: validated replay refuses it before this
+                // point (kontourai/survey#278).
+                const item = session.items.find((entry) => entry.metadata.name === itemName);
+                const check = item ? checkEditedValueForItem(item, editedValue) : undefined;
+                editedValuesByItemName[itemName] = check?.ok ? check.value : editedValue;
             }
             else {
                 delete editedValuesByItemName[itemName];