@gentbajko/slopify 3.16.0 → 3.18.0

package/dist/slices/rebuild/runtime-agent-review.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { externalReviewWaitMs } from "../reviews/external-model.js";
+import { openExternalReview } from "../reviews/external-repo.js";
+import { externalReviewByFingerprint } from "../reviews/external-rows.js";
+import { reviewStages } from "../reviews/model.js";
+import { nextAttempt, reviewOutcome } from "../reviews/outcome.js";
+import { latestVerdict, saveVerdict } from "../reviews/repo.js";
+import { exportSnapshot } from "./runtime-export-inputs.js";
+import { publishResult } from "./runtime-publication.js";
+import { reviewMaterial } from "./runtime-review.js";
+// What `recipe-reviews.ts` saves for a review an external agent answers, by position.
+const valuesSchema = z.tuple([
+    z.enum(reviewStages),
+    z.string(),
+    z.array(z.tuple([z.string(), z.unknown()])),
+    z.string(),
+    z.enum(["flag", "redo"]),
+    z.number().int().nonnegative(),
+]);
+// A review no model answers: the step saves what a reviewer would be shown and waits for an
+// agent's verdict through MCP. Waiting is not "held": the stage's other reviews still open
+// theirs in the same pass, and `agentReviewHold` keeps the runner from claiming it again.
+export async function executeAgentReviewRecipe(deps, context, piece) {
+    if (deps.db
+        .prepare("SELECT state FROM revision_work_pieces WHERE id=? AND work_id=?")
+        .get(piece.id, context.work.workId)?.state === "done")
+        return "done";
+    if (!context.maySubmit(piece.id))
+        return "held";
+    const values = piece.input.kind === "local" ? valuesSchema.safeParse(piece.input.values) : undefined;
+    if (values === undefined || !values.success)
+        throw new Error("Slopify hit an internal error (a review step was set up wrongly). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
+    const [stage, itemKey, , prompt, mode, retries] = values.data;
+    const projectId = context.work.projectId;
+    const known = externalReviewByFingerprint(deps.db, projectId, piece.fingerprint);
+    if (known === undefined || known.state === "superseded" || known.state === "canceled") {
+        const material = reviewMaterial(deps, context, exportSnapshot(deps, context, piece), stage, itemKey, prompt);
+        const now = deps.clock.now();
+        openExternalReview(deps.db, {
+            id: deps.ids.next(),
+            projectId,
+            revisionId: context.work.revisionId,
+            workId: context.work.workId,
+            pieceId: piece.id,
+            workKey: piece.key,
+            itemKey,
+            stage,
+            itemFingerprint: material.itemFingerprint,
+            reviewFingerprint: piece.fingerprint,
+            material: {
+                request: material.request,
+                images: material.images.map((image) => ({ stored: image.stored, name: image.name })),
+            },
+            waitingSince: now.toISOString(),
+            deadlineAt: new Date(now.getTime() + externalReviewWaitMs).toISOString(),
+        });
+        context.emit({ type: "project.updated", projectId });
+        return "waiting";
+    }
+    const autoPassed = known.state === "auto-passed";
+    const verdict = autoPassed ? { passed: true, reasons: [] } : known.verdict;
+    if (known.state === "waiting" || verdict === null)
+        return "waiting";
+    const attempt = nextAttempt(latestVerdict(deps.db, projectId, itemKey), known.itemFingerprint);
+    const outcome = autoPassed
+        ? "auto-passed"
+        : reviewOutcome({ passed: verdict.passed, mode, attempt, retries });
+    const saved = saveVerdict(deps.db, {
+        id: deps.ids.next(),
+        projectId,
+        revisionId: context.work.revisionId,
+        itemKey,
+        stage,
+        itemFingerprint: known.itemFingerprint,
+        reviewFingerprint: piece.fingerprint,
+        passed: verdict.passed,
+        reasons: verdict.reasons,
+        outcome,
+        attempt,
+        action: null,
+        actionAt: null,
+        redoState: outcome === "redo" ? "pending" : null,
+        redoError: null,
+        answeredBy: autoPassed ? "nobody" : (known.answeredBy ?? "agent"),
+        actionBy: null,
+        createdAt: deps.clock.now().toISOString(),
+    });
+    await publishResult(deps, context, piece, [], {
+        verdictId: saved.id,
+        passed: saved.passed,
+        reasons: saved.reasons,
+        outcome: saved.outcome,
+        attempt: saved.attempt,
+    });
+    if (saved.outcome === "flagged")
+        context.emit({
+            type: "review.flagged",
+            projectId,
+            verdictId: saved.id,
+            stage: saved.stage,
+            itemKey: saved.itemKey,
+            ...(saved.reasons[0] === undefined ? {} : { reason: saved.reasons[0] }),
+            ...(saved.answeredBy === "agent" ? { byAgent: true } : {}),
+        });
+    return "done";
+}
+// A stage whose only unfinished steps are reviews waiting for an agent is not claimed again
+// until one is answered (or passes at its deadline); anything else lets it run.
+export function agentReviewHold(deps, work) {
+    const open = deps.db
+        .prepare(`SELECT e.id AS review FROM revision_work_pieces p
+       LEFT JOIN external_reviews e ON e.work_id=p.work_id AND e.piece_id=p.id
+         AND e.review_fingerprint=p.fingerprint AND e.state='waiting'
+       WHERE p.work_id=? AND p.state!='done' AND p.work_key NOT LIKE 'article:continuation:%'`)
+        .all(work.workId)
+        .map((row) => z.object({ review: z.string().nullable() }).parse(row).review);
+    const waiting = open.flatMap((id) => (id === null ? [] : [id]));
+    return open.length > 0 && waiting.length === open.length
+        ? { kind: "held", checkpointIds: waiting.map((id) => `agent-review:${id}`) }
+        : { kind: "eligible" };
+}

package/dist/slices/rebuild/runtime-export-inputs.js

@@ -30,6 +30,15 @@ export async function revisionAudio(deps, context, view,
 // the shorts' pick) reads the plain ones, which it waits for. An uploaded narration has no
 // levelled join: only the master reaches it.
 options = {}) {
+    return narrationAudio({
+        paths: deps.paths,
+        measure: (path) => deps.measureAudio?.(path, context.signal) ??
+            probeDurationMs(deps.ffmpeg, path, context.signal, deps.log),
+    }, view, options);
+}
+// The narration's parts in their order on the export timeline: the version's selected, ready
+// intro, body and outro, each measured when its length was never recorded.
+export async function narrationAudio(deps, view, options = {}) {
     const config = view.revision.config;
     if (config.sources.audio === "off")
         return [];
@@ -46,10 +55,8 @@ options = {}) {
             throw new Error(`The levelled ${segment === "body" ? "narration" : segment} isn't finished yet, so the sound can't be exported at an even volume. Let the Narration stage finish (Resume, or Try again on it), then retry this stage; or turn off Level the volume in Edit project → Pauses and volume.`);
         if (row === undefined)
             return undefined;
-        const path = outputPath(deps.paths, context.work.projectId, row.output.path);
-        const duration = row.output.durationMs ??
-            (await (deps.measureAudio?.(path, context.signal) ??
-                probeDurationMs(deps.ffmpeg, path, context.signal, deps.log)));
+        const path = outputPath(deps.paths, view.revision.projectId, row.output.path);
+        const duration = row.output.durationMs ?? (await deps.measure(path));
         if (!Number.isFinite(duration) || duration <= 0)
             throw new Error("Slopify couldn't read the length of the narration audio, so the file may be damaged or empty. Regenerate the narration (or upload your audio file again in Edit project → Narration), then Try again.");
         return { path, seconds: duration / 1000 };
@@ -57,14 +64,22 @@ options = {}) {
     const body = await input("audio_body");
     if (body === undefined)
         throw new Error("The narration audio isn't finished yet. Let the Narration stage finish (Resume, or Try again on it), then retry this stage.");
-    return audioTimeline({
+    return narrationTimeline(config, {
         body,
-        intro: config.sources.audio === "generate" && config.intro !== undefined
-            ? await input("audio_intro")
-            : undefined,
-        outro: config.sources.audio === "generate" && config.outro !== undefined
-            ? await input("audio_outro")
-            : undefined,
+        intro: speaksPart(config, "intro") ? await input("audio_intro") : undefined,
+        outro: speaksPart(config, "outro") ? await input("audio_outro") : undefined,
+    });
+}
+// Only generated narration has a spoken intro and outro.
+export function speaksPart(config, part) {
+    return config.sources.audio === "generate" && config[part] !== undefined;
+}
+// The narration in its order on the export timeline, the clock the word timing is on.
+export function narrationTimeline(config, parts) {
+    return audioTimeline({
+        body: parts.body,
+        intro: speaksPart(config, "intro") ? parts.intro : undefined,
+        outro: speaksPart(config, "outro") ? parts.outro : undefined,
         gapSeconds: config.silenceGapSeconds,
         edgeSeconds: config.edgeSilenceSeconds,
     }, config.sources.video === "off" ? 1 / 48000 : 1 / 30);

package/dist/slices/rebuild/runtime-review.js

@@ -93,6 +93,8 @@ export async function executeReviewRecipe(deps, context, providers, piece) {
         actionAt: null,
         redoState: outcome === "redo" ? "pending" : null,
         redoError: null,
+        answeredBy: "model",
+        actionBy: null,
         createdAt: deps.clock.now().toISOString(),
     });
     await publishResult(deps, context, piece, [], {
@@ -138,7 +140,7 @@ function spokenText(deps, snapshot) {
     }
     return plainText(snapshot.view.articleMarkdown ?? "");
 }
-function reviewMaterial(deps, context, snapshot, stage, itemKey, prompt) {
+export function reviewMaterial(deps, context, snapshot, stage, itemKey, prompt) {
     const { view } = snapshot;
     const recipes = snapshot.plan.recipes;
     const config = view.revision.config;
@@ -197,11 +199,18 @@ function reviewMaterial(deps, context, snapshot, stage, itemKey, prompt) {
                 images: [
                     {
                         path: path(image),
+                        stored: image.output.path,
                         name: stage === "images" ? "the image to review" : "the thumbnail to review",
                     },
                     ...(reference === undefined
                         ? []
-                        : [{ path: path(reference), name: "the establishing image it must match" }]),
+                        : [
+                            {
+                                path: path(reference),
+                                stored: reference.output.path,
+                                name: "the establishing image it must match",
+                            },
+                        ]),
                 ],
                 itemFingerprint: image.fingerprint,
             };
@@ -255,6 +264,7 @@ function reviewMaterial(deps, context, snapshot, stage, itemKey, prompt) {
                 request: request([{ label: "Title of the short", text: title }], names),
                 images: stills.map((row, index) => ({
                     path: path(row),
+                    stored: row.output.path,
                     name: names[index] ?? "an image of the short",
                 })),
                 itemFingerprint: render.fingerprint,

package/dist/slices/rebuild/runtime-run.js

@@ -1,3 +1,4 @@
+import { executeAgentReviewRecipe } from "./runtime-agent-review.js";
 import { executeAnimateRecipe } from "./runtime-animate.js";
 import { executeDocumentRecipe } from "./runtime-document.js";
 import { executeExportRecipe } from "./runtime-export.js";
@@ -12,6 +13,7 @@ import { executeYoutubeRecipe } from "./runtime-youtube.js";
 import { workPieces } from "./work-records.js";
 export async function runRevisionInvocation(deps, context, providers) {
     const pieces = workPieces(deps.db, context.work.workId).filter((piece) => !piece.key.startsWith("article:continuation:"));
+    let waiting = false;
     for (const piece of pieces) {
         if (piece.state === "done")
             continue;
@@ -34,7 +36,9 @@ export async function runRevisionInvocation(deps, context, providers) {
                     : piece.key.startsWith("document:")
                         ? await executeDocumentRecipe(deps, context, piece)
                         : piece.key.startsWith("review:")
-                            ? await executeReviewRecipe(deps, context, providers, piece)
+                            ? piece.input.kind === "local" && piece.input.operation === "review-agent-v1"
+                                ? await executeAgentReviewRecipe(deps, context, piece)
+                                : await executeReviewRecipe(deps, context, providers, piece)
                             : piece.key.startsWith("voices:")
                                 ? await executeVoicesRecipe(deps, context, piece)
                                 : piece.key.startsWith("youtube:")
@@ -48,6 +52,11 @@ export async function runRevisionInvocation(deps, context, providers) {
                                                 piece.input.kind === "image"
                                                 ? await executeProviderRecipe(deps, context, providers, piece)
                                                 : await executeLocalRecipe(deps, context, piece);
+            // An agent's review waits without stopping the stage's other pieces.
+            if (outcome === "waiting") {
+                waiting = true;
+                continue;
+            }
             if (outcome === "held")
                 return outcome;
         }
@@ -74,7 +83,7 @@ export async function runRevisionInvocation(deps, context, providers) {
     deps.db
         .prepare("UPDATE revision_work_pieces SET state='done' WHERE work_id=? AND result_json IS NOT NULL")
         .run(context.work.workId);
-    return "done";
+    return waiting ? "held" : "done";
 }
 function startLocalTime(deps, context) {
     const id = deps.ids.next();

package/dist/slices/rebuild/runtime-store.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { stageKinds, stageStates } from "../../kernel/pipeline.js";
 import { optionalDeps } from "../../kernel/runner/graph.js";
+import { admittedStates, parkedKinds } from "../admission/admitted-work.js";
 import { sourceOf } from "../admission/model.js";
 import { usesShorts, usesYoutubeDescription } from "../admission/rules.js";
 import { reviewsNarration } from "../reviews/rules.js";
@@ -138,7 +139,7 @@ export function executionStandings(deps, projectId, derived) {
     if (view === undefined)
         return [];
     const work = derived ?? executionStages(deps, projectId);
-    return stageKinds.map((kind) => {
+    const standings = stageKinds.map((kind) => {
         const source = sourceOf(view.revision.config.sources, kind);
         const group = work
             .filter((entry) => entry.kind === kind)
@@ -174,8 +175,17 @@ export function executionStandings(deps, projectId, derived) {
                     ? "provided"
                     : "done"
                 : "pending";
-        return state === "pending" && retryAt !== null ? { kind, state, retryAt } : { kind, state };
+        return state === "pending" && retryAt !== null
+            ? { kind, state, source, retryAt }
+            : { kind, state, source };
     });
+    const admitted = admittedStates(deps.db, projectId);
+    const parked = parkedKinds(deps.db, projectId);
+    return standings.map((stage) => ({
+        ...stage,
+        ...(admitted.has(`${stage.kind}:${stage.state}`) ? { admitted: true } : {}),
+        ...(parked.has(stage.kind) ? { parked: true } : {}),
+    }));
 }
 // A finished piece whose request was planned under this fingerprint: a placeholder is planned
 // under the logical fingerprint, the finished piece carries the one its request resolved to.
@@ -216,7 +226,9 @@ export function projectStandings(deps, projectId) {
                 .get(entry.work.workId);
             return total + fraction(progress?.progress_current, progress?.progress_total);
         }, 0);
-        // A failed step, or else one waiting to run again, says why on the stage row.
+        // A failed step, or else one waiting to run again, says why on the stage row. A failed
+        // stage keeps the moment it failed: needs_attention tells a narration retry started after
+        // the failure (still going) from one started before it (spent) by it.
         const failed = all.find((work) => work.state === "failed") ??
             (stage.retryAt === undefined || stage.retryAt === null
                 ? undefined
@@ -227,8 +239,23 @@ export function projectStandings(deps, projectId) {
                 .prepare("SELECT failure_reason,failure_kind FROM revision_work WHERE id=?")
                 .get(failed.work.workId);
         deps.db
-            .prepare("UPDATE stages SET state=?,failure_reason=?,failure_kind=?,retry_at=?,progress_current=?,progress_total=?,finished_at=CASE WHEN ?='done' THEN ? ELSE NULL END WHERE project_id=? AND kind=?")
-            .run(stage.state, textOf(failure?.failure_reason), textOf(failure?.failure_kind), stage.retryAt ?? null, invocations.length === 0 ? null : current, invocations.length === 0 ? null : invocations.length, stage.state, deps.clock.now().toISOString(), projectId, stage.kind);
+            .prepare(`UPDATE stages SET state=:state,failure_reason=:reason,failure_kind=:kind,retry_at=:retryAt,
+           progress_current=:current,progress_total=:total,
+           finished_at=CASE WHEN :state='done' THEN :now
+             WHEN :state='failed' THEN CASE WHEN state='failed' AND finished_at IS NOT NULL THEN finished_at ELSE :now END
+             ELSE NULL END
+         WHERE project_id=:projectId AND kind=:stage`)
+            .run({
+            state: stage.state,
+            reason: textOf(failure?.failure_reason),
+            kind: textOf(failure?.failure_kind),
+            retryAt: stage.retryAt ?? null,
+            current: invocations.length === 0 ? null : current,
+            total: invocations.length === 0 ? null : invocations.length,
+            now: deps.clock.now().toISOString(),
+            projectId,
+            stage: stage.kind,
+        });
     }
     settleScheduleRunsForProject(deps.db, projectId, deps.clock.now().toISOString());
     return work;

package/dist/slices/reruns/index.js

@@ -2,7 +2,8 @@ import { rmSync } from "node:fs";
 import { z } from "zod";
 import { transact } from "../../kernel/db/tx.js";
 import { allPiecesOf, deletePiece, deletePieces, setPiece, } from "../../kernel/runner/piece-repo.js";
-import { projectById, resetStage, stagesOf } from "../admission/repo.js";
+import { projectById, stagesOf } from "../admission/repo.js";
+import { resetStage } from "../admission/stage-writes.js";
 import { storeArticleText } from "../article/store.js";
 import { currentRevisionId } from "../revisions/repo.js";
 import { outputPath } from "../storage/layout.js";

package/dist/slices/research/run.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { transact } from "../../kernel/db/tx.js";
 import { isProviderError } from "../../kernel/ports/model.js";
 import { insertPiece, piecesOf, setPiece } from "../../kernel/runner/piece-repo.js";
-import { projectById, setStageProgress } from "../admission/repo.js";
+import { projectById } from "../admission/repo.js";
+import { setStageProgress } from "../admission/stage-writes.js";
 import { storeText } from "../storage/staging.js";
 import { noTokens, plusUsage } from "../telemetry/model.js";
 import { researchDocuments } from "./documents.js";

package/dist/slices/reviews/external-model.js

@@ -0,0 +1,21 @@
+// ceiling: the owner's number. An hourly agent routine answers well inside two hours; a run
+// with no agent at all still finishes the same evening.
+export const externalReviewWaitMs = 2 * 60 * 60 * 1000;
+// `canceled`: Cancel closed it while it waited; taken up again, its step asks it once more.
+export const externalReviewStates = [
+    "waiting",
+    "answered",
+    "auto-passed",
+    "superseded",
+    "canceled",
+];
+// Why a review takes no verdict, one sentence per standing: what get_external_review explains,
+// and what a refused verdict says after "The verdict wasn't saved."
+export const closedReviewSentences = {
+    answered: "This review was already answered, so it takes no other verdict. Call needs_attention to see what is waiting now.",
+    "auto-passed": "This review passed at its 2-hour deadline with no verdict, so it takes none now. Call needs_attention to see what is waiting now.",
+    superseded: "This review was replaced: its item was made again or edited, and the new one waits for its own verdict. Call needs_attention to see it.",
+    "replaced-pending": "This review was replaced: its item was made again or edited, so it takes no verdict, and no new review waits for it yet. One opens once the new item is made; an edit saved but not continued makes none until the run is continued. There is nothing to answer here: call needs_attention to see what is waiting now.",
+    canceled: "This review's run was canceled, so nothing waits on it and it takes no verdict: a canceled run's reviews never pass. Call needs_attention to see what is waiting now.",
+    trashed: "This review's project is in the Trash, so nothing waits on it and it takes no verdict. Restore the project in Settings → Backup & storage → Trash; the review then waits for its verdict again.",
+};

package/dist/slices/reviews/external-release.js

@@ -0,0 +1,38 @@
+import { causedBy } from "../../kernel/errors.js";
+import { reviewItemName } from "../notifications/rules.js";
+import { revisionById } from "../revisions/repo.js";
+import { settleExternalReviews } from "./external-repo.js";
+function itemName(db, review) {
+    const revision = revisionById(db, review.projectId, review.revisionId);
+    return reviewItemName(review.itemKey, revision?.content.imageOrder ?? []);
+}
+// At boot and every few seconds: each review past its deadline passes, says so, and the run
+// goes on. The deadline is a row, so a restart in between loses nothing. Each passed review is
+// announced and woken on its own: one that throws is logged, and the others still go on (the
+// passing itself is already saved).
+export function releaseDueReviews(deps) {
+    const passed = settleExternalReviews(deps.db, deps.now());
+    for (const review of passed) {
+        try {
+            deps.emit(review.projectId, {
+                type: "review.auto-passed",
+                projectId: review.projectId,
+                reviewId: review.id,
+                stage: review.stage,
+                itemKey: review.itemKey,
+                item: itemName(deps.db, review),
+                revisionId: review.revisionId,
+                workId: review.workId,
+            });
+            deps.emit(review.projectId, { type: "project.updated", projectId: review.projectId });
+            deps.tick(review.projectId);
+        }
+        catch (error) {
+            deps.log.write("error", "review.deadline", {
+                projectId: review.projectId,
+                detail: `Review ${review.id} passed at its deadline, but announcing it or waking the run failed: ${causedBy(error)}`,
+            });
+        }
+    }
+    return passed.length;
+}

package/dist/slices/reviews/external-repo.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { liveProject } from "../admission/repo.js";
+import { externalReviewByFingerprint, externalReviewById } from "./external-rows.js";
+import { liveWork, reviewStanding, wantedBy } from "./external-waiting.js";
+import { reviewStages } from "./model.js";
+// A step asked again for the same review keeps its row; one whose earlier wait was superseded
+// or canceled waits again from now.
+export function openExternalReview(db, input) {
+    db.prepare(`INSERT INTO external_reviews(id,project_id,revision_id,work_id,piece_id,work_key,item_key,stage,item_fingerprint,review_fingerprint,material,state,waiting_since,deadline_at)
+     VALUES (?,?,?,?,?,?,?,?,?,?,?,'waiting',?,?)
+     ON CONFLICT(project_id,review_fingerprint) DO UPDATE SET revision_id=excluded.revision_id,
+       work_id=excluded.work_id,piece_id=excluded.piece_id,work_key=excluded.work_key,
+       item_fingerprint=excluded.item_fingerprint,material=excluded.material,state='waiting',
+       waiting_since=excluded.waiting_since,deadline_at=excluded.deadline_at,verdict=NULL,
+       answered_by=NULL,answered_at=NULL
+     WHERE external_reviews.state IN ('superseded','canceled')`).run(input.id, input.projectId, input.revisionId, input.workId, input.pieceId, input.workKey, input.itemKey, input.stage, input.itemFingerprint, input.reviewFingerprint, JSON.stringify(input.material), input.waitingSince, input.deadlineAt);
+    const saved = externalReviewByFingerprint(db, input.projectId, input.reviewFingerprint);
+    if (saved === undefined)
+        throw new Error("Slopify hit an internal error (an external review could not be saved). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
+    return saved;
+}
+// Cancel stops a run's reviews waiting. Retried, its step asks again (`openExternalReview`) and
+// each review waits its whole two hours from then, not from before the cancel.
+export function stopWaitingReviews(db, projectId) {
+    db.prepare("UPDATE external_reviews SET state='canceled' WHERE project_id=? AND state='waiting'").run(projectId);
+}
+// The step that waited ended its stage as held, which parks the work (`finishWork`); a settled
+// review lets it be claimed again while the current version still wants it. A restart also
+// held the work's unfinished pieces (`recoverWork`), so the ones never submitted are allowed
+// again, as boot does for work it keeps (`recoverCheckpointWork`). A paused project stays put:
+// the runner claims nothing for it until Resume.
+function releaseParkedWork(db, projectId, id) {
+    const parked = `(SELECT e.work_id FROM external_reviews e WHERE e.project_id=? AND e.id=? AND ${wantedBy("e")})`;
+    const released = db
+        .prepare(`UPDATE revision_work SET dispatch_state='allowed' WHERE state='pending' AND dispatch_state='held' AND id=${parked}`)
+        .run(projectId, id);
+    if (Number(released.changes) === 0)
+        return;
+    db.prepare(`UPDATE revision_work_pieces SET state='pending',dispatch_state='allowed'
+     WHERE work_id=${parked} AND state='held' AND submitted_at IS NULL AND continuation IS NULL`).run(projectId, id);
+}
+// The first verdict saved wins: read and answered in one transaction, so two agents answering
+// at once cannot both succeed. A review whose item was just replaced is superseded here rather
+// than at the next settle, a project in the Trash takes no verdict until it is restored, and a
+// canceled run's review takes none at all.
+export function answerExternalReview(db, input) {
+    return transact(db, () => {
+        const review = externalReviewById(db, input.projectId, input.id);
+        if (review === undefined)
+            return { ok: false, reason: "not-found" };
+        const standing = reviewStanding(db, review);
+        if (standing === "trashed")
+            return { ok: false, reason: "trashed" };
+        if (standing === "superseded" || standing === "replaced-pending")
+            db.prepare("UPDATE external_reviews SET state='superseded' WHERE project_id=? AND id=? AND state='waiting'").run(input.projectId, input.id);
+        if (standing !== "waiting")
+            return { ok: false, reason: standing, value: review };
+        db.prepare("UPDATE external_reviews SET state='answered', verdict=?, answered_by=?, answered_at=? WHERE project_id=? AND id=?").run(JSON.stringify(input.verdict), input.by, input.at, input.projectId, input.id);
+        releaseParkedWork(db, input.projectId, input.id);
+        return {
+            ok: true,
+            value: {
+                ...review,
+                state: "answered",
+                verdict: input.verdict,
+                answeredBy: input.by,
+                answeredAt: input.at,
+            },
+        };
+    });
+}
+const dueRow = z.object({
+    id: z.string(),
+    project_id: z.string(),
+    revision_id: z.string(),
+    work_id: z.string(),
+    stage: z.enum(reviewStages),
+    item_key: z.string(),
+});
+// Replaced reviews stop waiting; waiting ones past their deadline pass without review. A
+// paused project's review passes too (nothing runs until Resume); a canceled run's never does,
+// nor one of a project in the Trash (it waits on, and passes once restored).
+// Read by plain columns only: a review whose stored material can't be read back still passes,
+// and never holds up the others.
+export function settleExternalReviews(db, now) {
+    const at = now.toISOString();
+    return transact(db, () => {
+        db.prepare(`UPDATE external_reviews SET state='superseded' WHERE state='waiting' AND NOT ${wantedBy("external_reviews")}`).run();
+        const due = db
+            .prepare(`SELECT e.id, e.project_id, e.revision_id, e.work_id, e.stage, e.item_key FROM external_reviews e
+         WHERE e.state='waiting' AND e.deadline_at<=? AND ${liveWork("e")} AND ${liveProject("e", "project_id")}
+         ORDER BY e.waiting_since, e.rowid`)
+            .all(at)
+            .map((value) => dueRow.parse(value));
+        return due.map((row) => {
+            db.prepare("UPDATE external_reviews SET state='auto-passed', answered_at=? WHERE id=? AND state='waiting'").run(at, row.id);
+            releaseParkedWork(db, row.project_id, row.id);
+            return {
+                id: row.id,
+                projectId: row.project_id,
+                revisionId: row.revision_id,
+                workId: row.work_id,
+                stage: row.stage,
+                itemKey: row.item_key,
+            };
+        });
+    });
+}

package/dist/slices/reviews/external-rows.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { actors } from "../agents/model.js";
+import { externalReviewStates } from "./external-model.js";
+import { reviewStages } from "./model.js";
+const materialSchema = z.object({
+    request: z.object({
+        stage: z.enum(reviewStages),
+        instruction: z.string(),
+        sections: z.array(z.object({ label: z.string(), text: z.string() })),
+        images: z.array(z.string()),
+    }),
+    images: z.array(z.object({ stored: z.string(), name: z.string() })),
+});
+const verdictSchema = z.object({ passed: z.boolean(), reasons: z.array(z.string()) });
+const rowSchema = z.object({
+    id: z.string(),
+    project_id: z.string(),
+    revision_id: z.string(),
+    work_id: z.string(),
+    piece_id: z.string(),
+    work_key: z.string(),
+    item_key: z.string(),
+    stage: z.enum(reviewStages),
+    item_fingerprint: z.string(),
+    review_fingerprint: z.string(),
+    material: z.string(),
+    state: z.enum(externalReviewStates),
+    waiting_since: z.string(),
+    deadline_at: z.string(),
+    verdict: z.string().nullable(),
+    answered_by: z.enum(actors).nullable(),
+    answered_at: z.string().nullable(),
+});
+// One stored review as the slice speaks of it; throws for a row that can't be read back.
+export function externalReviewOf(value) {
+    const row = rowSchema.parse(value);
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        revisionId: row.revision_id,
+        workId: row.work_id,
+        pieceId: row.piece_id,
+        workKey: row.work_key,
+        itemKey: row.item_key,
+        stage: row.stage,
+        itemFingerprint: row.item_fingerprint,
+        reviewFingerprint: row.review_fingerprint,
+        material: materialSchema.parse(JSON.parse(row.material)),
+        state: row.state,
+        waitingSince: row.waiting_since,
+        deadlineAt: row.deadline_at,
+        verdict: row.verdict === null ? null : verdictSchema.parse(JSON.parse(row.verdict)),
+        answeredBy: row.answered_by,
+        answeredAt: row.answered_at,
+    };
+}
+export function externalReviewByFingerprint(db, projectId, reviewFingerprint) {
+    const row = db
+        .prepare("SELECT * FROM external_reviews WHERE project_id=? AND review_fingerprint=?")
+        .get(projectId, reviewFingerprint);
+    return row === undefined ? undefined : externalReviewOf(row);
+}
+export function externalReviewById(db, projectId, id) {
+    const row = db
+        .prepare("SELECT * FROM external_reviews WHERE project_id=? AND id=?")
+        .get(projectId, id);
+    return row === undefined ? undefined : externalReviewOf(row);
+}