@miadi/connector 0.1.19 → 0.1.21

package/dist/reading/workflow.js

@@ -0,0 +1,325 @@
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, fsyncSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { current } from "../records.js";
+import { Ledger } from "../store.js";
+import { contentHash } from "../revisions.js";
+import { academic, reflective, insert } from "./markdown.js";
+import { baseReview, block, canonicalVideo, hash, ReadingBlocked, readingScope, sourcePart, suppliedDialogue, survey, reflection } from "./contract.js";
+/** One workflow per person and video; two concurrent releases cannot spend twice. */
+export function workflowId(actor, video, revisionOf) { return `reading:${hash(`${actor}:${video}${revisionOf ? `:${revisionOf}` : ""}`).slice(0, 32)}`; }
+export class ReadingWorkflow {
+    stateDir;
+    adapters;
+    ledger;
+    constructor(stateDir, adapters) {
+        this.stateDir = stateDir;
+        this.adapters = adapters;
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        this.ledger = new Ledger(join(stateDir, "ledger.jsonl"));
+    }
+    receipts(id) {
+        return this.ledger.all().filter(r => r.kind === "observation" && r.body.reading && r.body.reading.workflow_id === id).map(r => r.body.reading);
+    }
+    approved(requestId) {
+        const r = current(this.ledger.all()).find(x => x.id === requestId);
+        if (!r || r.kind !== "run_request" || r.approval_state !== "approved")
+            block("blocked_permission", "Approve the bounded reading request through the connector decision door.");
+        if (r.completion_receipt?.instructions)
+            block("blocked_permission", "Approval carries changes: reconcile them in a revised typed scope before execution.");
+        return r;
+    }
+    source(request) {
+        const scope = readingScope.parse(request.body.reading);
+        if (scope.max_cost_usd > 0 && !scope.budget_approval_ref)
+            block("blocked_permission", "A nonzero provider budget needs a separate budget approval reference.");
+        if (scope.max_cost_usd > 0) {
+            const b = this.approved(scope.budget_approval_ref);
+            const parsed = z.object({ source_intent: z.string(), max_cost_usd: z.number().finite().min(0), providers: z.array(z.string()).min(1) }).strict().safeParse(b.body.reading_budget);
+            if (!parsed.success || parsed.data.source_intent !== scope.source_intent || parsed.data.max_cost_usd < scope.max_cost_usd || scope.providers.some(p => !parsed.data.providers.includes(p)) || b.actor.person_id !== request.actor.person_id)
+                block("blocked_permission", "The separate approved budget must name this source, person, providers and finite ceiling.");
+        }
+        const source = current(this.ledger.all()).find(r => r.id === scope.source_intent);
+        if (!source || source.kind !== "source_intent" || source.actor.person_id !== request.actor.person_id || source.state !== "ready" || source.body.readiness !== "released_for_review")
+            block("withheld", "The source owner must explicitly release this source; registration or uploading does not start work.");
+        const video = canonicalVideo(String(source.body.video_id));
+        if (scope.revision_of) {
+            const previous = this.done(scope.revision_of, "registration");
+            const priorRequest = current(this.ledger.all()).find(r => r.kind === "run_request" && r.body.workflow_id === scope.revision_of && r.actor.person_id === request.actor.person_id && r.approval_state === "approved" && r.body.reading?.source_intent === scope.source_intent);
+            if ((!previous && !priorRequest) || (previous && (previous.actor.person_id !== request.actor.person_id || previous.video_id !== video)) || this.done(scope.revision_of, "import"))
+                block("blocked_permission", "A revision must name this author's unimported prior workflow for the same video.");
+        }
+        return { scope, source, video, id: workflowId(request.actor.person_id, video, scope.revision_of) };
+    }
+    async locked(id, fn) {
+        const root = join(this.stateDir, "reading-locks");
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        const file = join(root, hash(id));
+        // Serialize every acquisition/recovery, including the dead-owner check and replacement.
+        // A crash in this tiny critical section fails closed; it is never stolen on a timer.
+        const acquiring = `${file}.acquiring`;
+        try {
+            mkdirSync(acquiring, { mode: 0o700 });
+        }
+        catch {
+            return block("failed_retryable", `Acquisition is in progress. If its worker crashed, inspect and recover ${acquiring} before retrying.`);
+        }
+        try {
+            try {
+                mkdirSync(file, { mode: 0o700 });
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                // No time-based stealing: a slow provider must never become a second writer.
+                let pid;
+                try {
+                    pid = Number(readFileSync(join(file, "pid"), "utf8"));
+                }
+                catch {
+                    return block("failed_retryable", "Workflow lock is initializing; retry, or inspect its owner after a crash.");
+                }
+                if (!Number.isSafeInteger(pid) || pid <= 0)
+                    block("failed_retryable", "Inspect the invalid workflow lock owner.");
+                try {
+                    process.kill(pid, 0);
+                    return block("failed_retryable", "Another worker holds this video; read its receipts.");
+                }
+                catch (e) {
+                    if (e.code !== "ESRCH")
+                        throw e;
+                }
+                // The acquisition mutex prevents two recoverers from moving a new active lock.
+                const stale = `${file}.dead-${randomUUID()}`;
+                try {
+                    renameSync(file, stale);
+                }
+                catch {
+                    return block("failed_retryable", "Another worker recovered this lock; retry.");
+                }
+                rmSync(stale, { recursive: true });
+                mkdirSync(file, { mode: 0o700 });
+            }
+            writeFileSync(join(file, "pid"), String(process.pid), { mode: 0o600 });
+        }
+        finally {
+            rmSync(acquiring, { recursive: true });
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            rmSync(file, { recursive: true });
+        }
+    }
+    record(request, scope, id, video, stage, status, artifact, next_action = "") {
+        const previous = this.receipts(id), at = new Date().toISOString();
+        const starts = previous.filter(r => r.stage === stage && r.status === "started");
+        const attempt = status === "started" ? starts.length + 1 : starts.length || 1;
+        const started = status === "started" ? at : starts.at(-1)?.started_at ?? at;
+        const receipt = { stage, status, attempt, started_at: started, completed_at: at, workflow_id: id, request_id: request.id, video_id: video, actor: request.actor, consent_scope: scope, approval_state: "approved_bounded_processing", artifact_refs: [], sha256: hash(JSON.stringify(artifact)), previous_sha256: previous.at(-1)?.sha256 ?? null, artifact, next_action };
+        const record = { id: `observation:${randomUUID()}`, kind: "observation", actor: request.actor, created_at: at, circle: "continuity", claim_category: "observed", refs: [request.id, `https://youtu.be/${video}`], evidence_refs: [], body: { reading: receipt } };
+        receipt.artifact_refs = [record.id];
+        this.ledger.appendDurable(record);
+        // Persist a new ledger directory entry too, before a downstream call.
+        const fd = openSync(this.stateDir, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return receipt;
+    }
+    done(id, stage) { return this.receipts(id).find(r => r.stage === stage && r.status === "completed"); }
+    provider(scope, id, stage) {
+        const p = this.adapters.providers[stage];
+        if (!p || !p.available)
+            block(stage === "transcript" ? "blocked_transcript" : "blocked_permission", `Configure and verify an available ${stage} provider; no fallback was called.`);
+        if (!p.idempotent || !scope.providers.includes(p.id) || (p.external && !scope.allow_external_processing) || (p.media && !scope.allow_media_access))
+            block("blocked_permission", `Authorize provider ${p.id}, its media/external access and durable retry contract first.`);
+        if (!Number.isFinite(p.max_cost_usd) || p.max_cost_usd < 0)
+            block("blocked_permission", "Provider must declare a finite maximum cost.");
+        const reservations = this.receipts(id).filter(r => r.status === "reserved");
+        const spent = reservations.reduce((s, r) => s + r.artifact.max_cost_usd, 0);
+        if (!reservations.some(r => r.stage === stage) && spent + p.max_cost_usd > scope.max_cost_usd)
+            block("blocked_permission", `The ${stage} provider exceeds the approved total budget; request a separate budget.`);
+        const old = reservations.find(r => r.stage === stage);
+        if (old && (old.artifact.id !== p.id || old.artifact.method !== p.method || old.artifact.max_cost_usd !== p.max_cost_usd))
+            block("blocked_permission", "Provider settings changed after reservation; reconcile the prior operation before retry.");
+        return p;
+    }
+    async run(requestId, companion) {
+        const request = this.approved(requestId), { scope, video, id } = this.source(request);
+        const approvedCompanion = request.body.reading_companion;
+        if (companion !== undefined && hash(JSON.stringify(companion)) !== hash(JSON.stringify(approvedCompanion ?? null)))
+            block("blocked_permission", "The companion text must be part of the author's approved reading request.");
+        companion = approvedCompanion;
+        return this.locked(workflowId(request.actor.person_id, video), async () => {
+            let stage = "registration";
+            const result = (status, next_action) => ({ workflow_id: id, status, next_action, receipts: this.receipts(id) });
+            try {
+                const registration = this.done(id, "registration");
+                if (registration && registration.artifact.request_id !== requestId)
+                    return result("duplicate_video", "This video already has a bounded workflow. Resume its original request.");
+                if (registration && registration.artifact.request_hash !== contentHash(request))
+                    return result(registration.artifact.request_id === requestId ? "blocked_permission" : "duplicate_video", "This video already has a bounded workflow. Resume its original request; a changed grant cannot overwrite its receipts.");
+                if (!registration)
+                    this.record(request, scope, id, video, stage, "completed", { request_hash: contentHash(request), request_id: requestId, video_id: video, kind: scope.kind });
+                let context = { workflow_id: id, video_id: video, scope, idempotency_key: "", transcript: undefined, source_part_id: "" };
+                const execute = async (name, fn, validate) => {
+                    stage = name;
+                    const done = this.done(id, name);
+                    if (done)
+                        return done.artifact;
+                    // Source release is rechecked at every new stage.
+                    this.source(this.approved(requestId));
+                    const p = this.provider(scope, id, name);
+                    if (!this.receipts(id).some(r => r.stage === name && r.status === "reserved"))
+                        this.record(request, scope, id, video, name, "reserved", p);
+                    this.record(request, scope, id, video, name, "started", { provider: p.id, method: p.method });
+                    const output = validate(await fn({ ...context, idempotency_key: `${id}:${name}` }));
+                    return this.record(request, scope, id, video, name, "completed", output).artifact;
+                };
+                const oldTranscript = scope.revision_of ? this.done(scope.revision_of, "transcript") : undefined;
+                if (!this.done(id, "transcript") && oldTranscript && oldTranscript.artifact.language === scope.language && oldTranscript.artifact.rights === scope.rights && scope.providers.includes(oldTranscript.artifact.provider)) {
+                    this.record(request, scope, id, video, "transcript", "completed", { ...oldTranscript.artifact, reused_from: oldTranscript.artifact_refs });
+                }
+                const transcript = await execute("transcript", c => this.adapters.acquire(c), x => {
+                    if (x === null)
+                        block("blocked_transcript", "No authorized captions or working local transcript. Supply exact transcript/caption bytes with provenance and retry; no paid fallback ran.");
+                    const part = sourcePart.parse(x);
+                    if (!part.text.trim() || part.video_id !== video || part.channel !== "video" || part.language !== scope.language || part.provider !== this.adapters.providers.transcript.id || part.rights !== scope.rights || /\b(summary|key points)\b/i.test(part.kind))
+                        block("blocked_transcript", "Video transcript provenance, language, rights or channel does not match this grant.");
+                    if (part.segments.some((s, i) => s.end_ms < s.start_ms || (i > 0 && s.start_ms < part.segments[i - 1].start_ms)))
+                        block("blocked_transcript", "Transcript has invalid or unordered timecodes.");
+                    if (part.timestamp_granularity !== "none" && !part.segments.length)
+                        block("blocked_transcript", "Claimed timestamp granularity needs actual segments.");
+                    return { ...part, sha256: hash(part.text), source_part_id: `source_part:${hash(`${video}:${part.provider}:${scope.language}:${hash(part.text)}`)}`, stored_at: new Date().toISOString(), normalized_sha256: part.normalized_text ? hash(part.normalized_text) : null };
+                });
+                context = { ...context, transcript, source_part_id: transcript.source_part_id };
+                stage = "lookup";
+                if (!this.done(id, "lookup")) {
+                    const base = await this.adapters.lookup(video);
+                    if (base && (base.video_id !== video || !Number.isSafeInteger(base.version) || base.version < 1 || !base.markdown))
+                        block("blocked_permission", "Review lookup returned an invalid or ambiguous base; resolve it before generating.");
+                    this.record(request, scope, id, video, "lookup", "completed", { base });
+                }
+                const base = this.done(id, "lookup").artifact.base;
+                const validateBase = (x) => {
+                    const b = baseReview.parse(x);
+                    for (const c of b.claims) {
+                        if (c.category === "transcript_supported" && (c.at_ms === undefined || !transcript.segments.some((s) => c.at_ms >= s.start_ms && c.at_ms <= s.end_ms)))
+                            block("blocked_transcript", "A source claim lacks an archived transcript timecode.");
+                        if (c.category === "visually_evidenced" && !c.visual_receipt)
+                            block("blocked_transcript", "A visual claim requires a separately inspected visual evidence receipt.");
+                    }
+                    return b;
+                };
+                const priorV1 = scope.revision_of && !base && transcript.reused_from ? this.done(scope.revision_of, "v1") : undefined;
+                if (priorV1 && !this.done(id, "v1"))
+                    this.record(request, scope, id, video, "v1", "completed", { ...priorV1.artifact, reused_from: priorV1.artifact_refs });
+                const v1 = base ? { markdown: base.markdown, claims: [{ category: "inference", claim: "Existing review reused verbatim; its claims have not been independently verified." }], model: "existing_review" } : await execute("v1", c => this.adapters.generateV1(c), validateBase);
+                if (base && !this.done(id, "v1"))
+                    this.record(request, scope, id, video, "v1", "completed", { ...v1, reused: true, review_id: base.id, version: base.version });
+                context.base = v1;
+                const academicResult = await execute("academic", c => this.adapters.generateSurvey(c), asyncIdentity);
+                // Verification is its own resumable stage, before any V2 is accepted.
+                stage = "citations";
+                this.source(this.approved(requestId));
+                let checked = this.done(id, "citations")?.artifact;
+                if (!checked) {
+                    const parsed = survey.parse(academicResult);
+                    if (parsed.fields.length > scope.max_fields || new Set(parsed.sources.map(s => s.id)).size !== parsed.sources.length)
+                        block("blocked_citations", "Field limit exceeded or duplicate source identifiers.");
+                    const verified = [];
+                    const normalize = (s) => s.replace(/\s+/g, " ").trim().toLowerCase();
+                    for (const source of parsed.sources) {
+                        const proof = await this.adapters.verifySource(source);
+                        if (proof.url !== source.url || !Number.isFinite(Date.parse(proof.fetched_at)) || !normalize(proof.text) || !normalize(source.excerpt) || !normalize(proof.text).includes(normalize(source.excerpt)))
+                            block("blocked_citations", `Source ${source.id} could not be verified against retrieved text. Correct or remove it, then request a new bounded candidate.`);
+                        verified.push({ id: source.id, url: source.url, fetched_at: proof.fetched_at, sha256: hash(proof.text), excerpt_sha256: hash(source.excerpt), claim: source.claim, status: "retrieved_excerpt", full_reading: false });
+                    }
+                    for (const field of parsed.fields) {
+                        if (field.body.trim().split(/\s+/).length > scope.max_field_words || !transcript.segments.some((s) => field.at_ms >= s.start_ms && field.at_ms <= s.end_ms) || field.source_ids.some(id => !verified.some(v => v.id === id)))
+                            block("blocked_citations", "Field length, timestamp or citation does not meet the authorized survey contract.");
+                    }
+                    checked = this.record(request, scope, id, video, stage, "completed", { survey: parsed, verified }).artifact;
+                }
+                context.survey = checked.survey;
+                stage = "v2";
+                this.source(this.approved(requestId));
+                const v2 = this.done(id, "v2")?.artifact ?? this.record(request, scope, id, video, stage, "completed", academic(v1.markdown, checked.survey)).artifact;
+                const reflectionResult = await execute("reflective", c => this.adapters.generateReflection(c), x => {
+                    const r = reflection.parse(x);
+                    if (new Set(r.dialogue.map(d => d.voice)).size !== 2)
+                        block("blocked_citations", "Reflective stage must contain both labelled generated voices.");
+                    return r;
+                });
+                stage = "v3";
+                this.source(this.approved(requestId));
+                const supplied = companion === undefined ? undefined : suppliedDialogue.parse(companion);
+                const prior = this.done(id, "v3");
+                if (prior && hash(JSON.stringify(supplied ?? null)) !== prior.artifact.companion_sha256)
+                    block("blocked_permission", "A later companion is a new attributed contribution; the immutable candidate cannot be overwritten.");
+                if (!prior) {
+                    const v3 = reflective(v2.markdown, reflectionResult, supplied);
+                    const manifest = { workflow_id: id, video_id: video, source_part_id: transcript.source_part_id, transcript_sha256: transcript.sha256, transcript_receipt: this.done(id, "transcript").artifact_refs, language: transcript.language, rights: transcript.rights, locator: transcript.locator, provider: transcript.provider, fetched_at: transcript.fetched_at, timestamp_granularity: transcript.timestamp_granularity, alignment_status: transcript.alignment_status, speaker_status: transcript.speaker_status, claim_categories: v1.claims, sources: checked.verified, base, companion: supplied ?? null, gates: ["editorial_import", "publication", "deep_diver", "chronicle", "cultural_reuse"] };
+                    const manifestText = `\n\n## Processing Provenance\n\nTranscript archived before generation. Source transcript supports spoken content; visual evidence is separate. Unknown speakers and channel synchronization remain uncertain.\n\n\`\`\`json\n${JSON.stringify(manifest, null, 2)}\n\`\`\`\n`;
+                    const final = insert(v3.markdown, v3.markdown.length, manifestText);
+                    this.record(request, scope, id, video, stage, "completed", { markdown: final.markdown, sha256: hash(final.markdown), bytes: Buffer.byteLength(final.markdown), diffs: [...v2.diffs, v3.diff, final.diff], manifest, companion_sha256: hash(JSON.stringify(supplied ?? null)), expected_version: base?.version ?? 0, expected_sha256: hash(base?.markdown ?? ""), review_id: base?.id ?? null });
+                }
+                const imported = this.done(id, "import");
+                return imported ? result("imported", "Public review import was read back exactly. Deep Diver, Chronicle and further publication/reuse remain separate gates.") : result("awaiting_editorial_decision", "Inspect V1/V2/V3, the insertion diff and manifest. Approve the exact candidate hash and base in a separate editorial request; import is a public release.");
+            }
+            catch (e) {
+                const blocked = e instanceof ReadingBlocked ? e : new ReadingBlocked(stage === "transcript" ? "blocked_transcript" : stage === "academic" || stage === "citations" ? "blocked_citations" : "failed_retryable", "Stage failed or returned malformed data. Inspect the adapter; retry the same request and idempotency key after repair.");
+                this.record(request, scope, id, video, stage, blocked.status, { error_type: e instanceof Error ? e.name : "unknown" }, blocked.next_action);
+                return result(blocked.status, blocked.next_action);
+            }
+        });
+    }
+    async importApproved(requestId) {
+        const request = this.approved(requestId), approval = request.body.reading_import;
+        if (!approval || typeof approval.workflow_id !== "string" || !/^reading:[a-f\d]{32}$/.test(approval.workflow_id))
+            block("blocked_permission", "An editorial request must name one staged workflow and exact candidate/base hashes.");
+        const id = approval.workflow_id;
+        const stagedOwner = this.done(id, "registration");
+        if (!stagedOwner)
+            block("blocked_permission", "Workflow is unavailable.");
+        return this.locked(workflowId(stagedOwner.actor.person_id, stagedOwner.video_id), async () => {
+            const staged = this.done(id, "v3"), registration = this.done(id, "registration");
+            if (!staged || !registration || staged.actor.person_id !== request.actor.person_id)
+                block("blocked_permission", "Only the source owner can request this candidate's editorial import.");
+            const candidate = staged.artifact, scope = staged.consent_scope, video = staged.video_id;
+            // Recheck the original bounded grant and current source release before sharing anything.
+            this.source(this.approved(registration.artifact.request_id));
+            if (approval.sha256 !== candidate.sha256 || approval.expected_version !== candidate.expected_version || approval.expected_sha256 !== candidate.expected_sha256 || approval.public_release !== true)
+                block("blocked_permission", "Approve the exact candidate and base, explicitly including public release.");
+            if (this.done(id, "import"))
+                return { workflow_id: id, status: "imported", next_action: "Already imported and verified; nothing was written again.", receipts: this.receipts(id) };
+            if (!this.adapters.atomicImport)
+                block("blocked_permission", "Review service lacks verified atomic conditional import and idempotency. Apply the v0 owner prompt; never fall back to the legacy import API.");
+            const intent = this.done(id, "import_intent");
+            // Persist the approved exact write ahead of the remote call; a lost response replays the same key.
+            if (!intent)
+                this.record(request, scope, id, video, "import_intent", "completed", { sha256: candidate.sha256, approval: request.id });
+            this.record(request, scope, id, video, "import", "started", { candidate_sha256: candidate.sha256 });
+            try {
+                const receipt = await this.adapters.importExact({ video_id: video, review_id: candidate.review_id, expected_version: candidate.expected_version, expected_sha256: candidate.expected_sha256, markdown: candidate.markdown, sha256: candidate.sha256, idempotency_key: `${id}:import:${candidate.sha256}` });
+                const back = await this.adapters.readExact(receipt.id, receipt.version);
+                if (back.id !== receipt.id || (candidate.review_id && back.id !== candidate.review_id) || back.video_id !== video || back.version !== candidate.expected_version + 1 || hash(back.markdown) !== candidate.sha256)
+                    block("failed_retryable", "Import read-back mismatch; reconcile the idempotency receipt before any further write.");
+                this.record(request, scope, id, video, "import", "completed", { ...receipt, sha256: hash(back.markdown), bytes: Buffer.byteLength(back.markdown), editorial_approval: request.id, publication: "explicitly_approved", deep_diver: "not_requested", chronicle: "not_requested" });
+            }
+            catch (e) {
+                const b = e instanceof ReadingBlocked ? e : new ReadingBlocked("failed_retryable", "Remote import outcome is uncertain. Replay the same durable operation key; never send a legacy write.");
+                this.record(request, scope, id, video, "import", b.status, { candidate_sha256: candidate.sha256 }, b.next_action);
+                throw b;
+            }
+            return { workflow_id: id, status: "imported", next_action: "Exact public import verified. Deep Diver and Chronicle require separate author decisions.", receipts: this.receipts(id) };
+        });
+    }
+}
+const asyncIdentity = (x) => survey.parse(x);

package/dist/records.d.ts

@@ -36,7 +36,7 @@ export declare const DOMAINS: readonly ["creative", "ceremonial", "engineering"]
 /** #815 "claim category": what kind of statement a record makes. */
 export declare const CLAIM_CATEGORIES: readonly ["observed", "hypothesis", "desired_future", "fiction", "verified_implementation"];
 export type ClaimCategory = (typeof CLAIM_CATEGORIES)[number];
-export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request", "session_steer_request"];
+export declare const RECORD_KINDS: readonly ["observation", "inquiry", "link", "work_proposal", "run_request", "handoff", "source_intent", "review_operation_request", "deep_diver_request", "review_episode_link_request", "calendar_event_draft", "session_completion_proposal", "research_artifact", "inquiry_episode_request", "session_steer_request", "steering_revocation", "provider_choice", "provider_policy"];
 export type RecordKind = (typeof RECORD_KINDS)[number];
 /** #816 handoff states. */
 export declare const HANDOFF_STATES: readonly ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];

package/dist/records.js

@@ -61,6 +61,11 @@ export const RECORD_KINDS = [
     "research_artifact",
     "inquiry_episode_request",
     "session_steer_request",
+    // A person stops a run's steering, or one steer still waiting at the runtime (jgwill/Miadi#930).
+    "steering_revocation",
+    // A requester's own per-mission provider choice and provider policy, made on the connector's pages (jgwill/Miadi#926).
+    "provider_choice",
+    "provider_policy",
 ];
 /** #816 handoff states. */
 export const HANDOFF_STATES = ["pending", "blocked", "ready", "in_progress", "completed", "withdrawn"];
@@ -98,6 +103,7 @@ export function current(records) {
                 approval_state: r.approval_state ?? base.approval_state,
                 next_action: r.next_action ?? base.next_action,
                 completion_receipt: r.completion_receipt ?? base.completion_receipt,
+                ...(base.kind === "source_intent" && r.kind === "source_intent" && r.body.source_readiness_transition === true ? { body: { ...base.body, readiness: r.body.readiness } } : {}),
                 history: [...(base.history ?? []), r.id],
             });
             continue;

package/dist/request-state.js

@@ -29,7 +29,12 @@ const OUTCOME_WORDS = {
     marked_ready: "marked ready for Deep Diver",
     decided: "recorded",
     nothing_to_run: "nothing to run",
-    accepted: "accepted by the session",
+    accepted: "typed into an idle session, which turned busy; its delivery says whether the model read it",
+    queued_at_runtime: "handed to the session's inbox, on its way to the model",
+    delivered_to_agent_context: "delivered: the model has it",
+    acknowledged: "delivered, and the agent said so",
+    behavior_adjusted: "delivered, and the agent's next action shows it",
+    expired: "expired before the model read it",
     submitted: "typed into the session, acceptance unconfirmed",
     failed: "failed",
 };
@@ -154,6 +159,9 @@ function projectCore(record, ctx = {}) {
         if (ctx.queue?.state === "cancelled" || ctx.queue?.state === "stale") {
             outstanding.push(`The factory intake set the brief aside (${ctx.queue.state}), so nothing is running for it.`);
         }
+        if (ctx.queue?.state === "refused") {
+            outstanding.push(`${ctx.queue.note ?? "The factory runner refused to launch it."} Nothing is running for it.`);
+        }
         const lines = [...decisionLines(decision), outcomeWord ? `Outcome: ${outcomeWord}.` : "Outcome: queued for the factory intake."];
         if (delivered)
             lines.push("Delivered to an agent session.");

package/dist/research-digest.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a shelf report is, read from its own Markdown, for a shelf a person can look through: its
+ * title, its opening, how long it is, what is inside, how many sources it cites. Everything here is
+ * computed from the file; nothing is summarised or invented. jgwill/Miadi#879.
+ */
+export interface ReportDigest {
+    title: string;
+    /** The document names itself; otherwise the title is its folder's name. */
+    titled: boolean;
+    /** The report's first paragraph of prose, without Markdown marks. */
+    excerpt?: string;
+    words: number;
+    minutes: number;
+    /** Its `##` and `###` headings, in order. */
+    headings: string[];
+    sections: number;
+    /** Distinct web addresses it cites. */
+    sources: number;
+}
+/** `jacqueline-m-quinless-…-261029-0e1f…` → `jacqueline m quinless …`: the date and uuid a folder name ends in are not its name. */
+export declare function folderTitle(name: string): string;
+export declare function digestReport(markdown: string, folder: string): ReportDigest;
+/**
+ * The text as the page shows it. A stray fence would turn the rest of a report into one code box, so
+ * a fence with no close in reach is left out of the display. The file itself is never changed.
+ */
+export declare function readableMarkdown(markdown: string): {
+    markdown: string;
+    repaired: boolean;
+};

package/dist/research-digest.js

@@ -0,0 +1,104 @@
+/**
+ * What a shelf report is, read from its own Markdown, for a shelf a person can look through: its
+ * title, its opening, how long it is, what is inside, how many sources it cites. Everything here is
+ * computed from the file; nothing is summarised or invented. jgwill/Miadi#879.
+ */
+const WORDS_PER_MINUTE = 230;
+const MAX_HEADINGS = 6;
+const MAX_EXCERPT = 280;
+/** A stray fence must not swallow a report: a block longer than this is not treated as code. */
+const MAX_FENCE_LINES = 60;
+const MAX_TITLE = 100;
+/** `jacqueline-m-quinless-…-261029-0e1f…` → `jacqueline m quinless …`: the date and uuid a folder name ends in are not its name. */
+export function folderTitle(name) {
+    const bare = name
+        .replace(/^ep\d+[-_]/i, "")
+        .replace(/-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, "")
+        .replace(/-\d{6,10}(-[0-9a-f]{6,})?$/i, "")
+        .replace(/[-_]+/g, " ")
+        .trim();
+    return bare ? bare[0].toUpperCase() + bare.slice(1) : name;
+}
+function plain(text) {
+    return text
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+        .replace(/[`*_~]+/g, "")
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** The lines outside fenced code, with a fence left alone when no close comes within reach. */
+function outsideFences(lines) {
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const open = /^(```|~~~)/.exec(lines[i]);
+        if (!open) {
+            out.push(lines[i]);
+            continue;
+        }
+        const close = lines.slice(i + 1, i + 1 + MAX_FENCE_LINES).findIndex((l) => l.trimEnd() === open[1]);
+        if (close < 0)
+            continue;
+        i += close + 1;
+    }
+    return out;
+}
+/** A heading that is a prompt, a command or a chat fragment is not the document's name. */
+const nameable = (t) => t.length > 0 && t.length <= MAX_TITLE && !/^@/.test(t) && !/\s--[a-z]/.test(t) && !/^(hey|hi|ok|okay|so|please|can you|could you)\b/i.test(t);
+/** How a document was made is not what it is about. */
+const PROVENANCE = /^(parent vessel|inquiry vessel|author role|mission|seed for|for the author's review|rendered from|status:|date:|woven to|generated)\b|\/(srv|workspace|a\/src|home)\/|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+export function digestReport(markdown, folder) {
+    const clean = outsideFences(markdown.replace(/^---\n[\s\S]*?\n---\n/, "").split("\n"));
+    const body = clean.join("\n");
+    const h1 = clean.find((l) => /^#\s+\S/.test(l));
+    const h1Text = h1 ? plain(h1.replace(/^#\s+/, "")) : "";
+    const headings = clean.filter((l) => /^#{2,3}\s+\S/.test(l)).map((l) => plain(l.replace(/^#+\s+/, "")));
+    let excerpt;
+    for (const block of body.split(/\n\s*\n/)) {
+        const t = block.trim();
+        if (!t || /^(#|\||>|[-*+]\s|\d+\.\s|!\[|<|---|===)/.test(t))
+            continue;
+        const p = plain(t);
+        if (p.split(" ").length < 8 || PROVENANCE.test(p))
+            continue;
+        excerpt = p.length > MAX_EXCERPT ? `${p.slice(0, MAX_EXCERPT).replace(/\s+\S*$/, "")}…` : p;
+        break;
+    }
+    const words = plain(body.replace(/^#+\s+/gm, "")).split(" ").filter(Boolean).length;
+    const titled = nameable(h1Text);
+    return {
+        title: titled ? h1Text : folderTitle(folder),
+        titled,
+        ...(excerpt ? { excerpt } : {}),
+        words,
+        minutes: Math.max(1, Math.round(words / WORDS_PER_MINUTE)),
+        headings: headings.slice(0, MAX_HEADINGS),
+        sections: headings.length,
+        sources: new Set(markdown.match(/https?:\/\/[^\s)\]>"']+/g) ?? []).size,
+    };
+}
+/**
+ * The text as the page shows it. A stray fence would turn the rest of a report into one code box, so
+ * a fence with no close in reach is left out of the display. The file itself is never changed.
+ */
+export function readableMarkdown(markdown) {
+    const lines = markdown.split("\n");
+    const out = [];
+    let repaired = false;
+    for (let i = 0; i < lines.length; i++) {
+        const open = /^(```|~~~)/.exec(lines[i]);
+        if (!open) {
+            out.push(lines[i]);
+            continue;
+        }
+        const close = lines.slice(i + 1, i + 1 + MAX_FENCE_LINES).findIndex((l) => l.trimEnd() === open[1]);
+        if (close < 0) {
+            repaired = true;
+            continue;
+        }
+        out.push(...lines.slice(i, i + close + 2));
+        i += close + 1;
+    }
+    return { markdown: out.join("\n"), repaired };
+}