@miadi/connector 0.1.19 → 0.1.20

package/dist/reading/markdown.js

@@ -0,0 +1,52 @@
+import { block, hash } from "./contract.js";
+/** UTF-16 string offsets outside code fences, retaining CRLF. No Markdown reserialization. */
+export function headings(markdown) {
+    let offset = 0, fence = null, fenceLength = 0;
+    const out = [];
+    for (const line of markdown.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        const f = line.match(/^ {0,3}(`{3,}|~{3,})/);
+        if (f) {
+            if (!fence) {
+                fence = f[1][0];
+                fenceLength = f[1].length;
+            }
+            else if (fence === f[1][0] && f[1].length >= fenceLength)
+                fence = null;
+        }
+        else if (!fence) {
+            const h = line.match(/^## ([^\r\n]+?)\s*#*\s*$/);
+            if (h)
+                out.push({ name: h[1].trim(), at: offset });
+        }
+        offset += line.length;
+    }
+    if (fence)
+        block("blocked_citations", "The base contains an unclosed Markdown fence. Ask the author to approve its repair before enrichment.");
+    return out;
+}
+export function insert(base, at, addition) {
+    const markdown = base.slice(0, at) + addition + base.slice(at);
+    return { markdown, diff: { operation: "insert", at, addition, base_sha256: hash(base), sha256: hash(markdown), bytes: Buffer.byteLength(markdown), retained: true } };
+}
+export function academic(base, s) {
+    const hs = headings(base), summary = hs.findIndex(h => h.name.toLowerCase() === "summary");
+    if (summary < 0 || hs.filter(h => h.name.toLowerCase() === "summary").length !== 1 || hs.some(h => /^(academic fields|academic field survey)$/i.test(h.name)))
+        block("blocked_citations", "A unique Summary and no existing Academic Fields are required; resolve the base with the author.");
+    const at = hs[summary + 1]?.at ?? base.length;
+    const fields = "\n\n## Academic Fields\n\n" + s.fields.map(f => `### ${f.name}\n\n${f.body}\n\nSource anchor: ${f.at_ms} ms (transcript). External literature: ${f.source_ids.map(id => `[${id}]`).join(", ")}.\n\nOpen question: ${f.question}\n\nLimit: ${f.limitation}\n`).join("\n") + "\n";
+    const first = insert(base, at, fields);
+    const sources = "\n\n## Reading Sources\n\n" + s.sources.map(x => `- [${x.id}] ${x.title}. ${x.url}\n  Retrieved excerpt checked; relevance to the inquiry is an agent interpretation. This receipt does not claim a full reading.\n`).join("\n");
+    const second = insert(first.markdown, first.markdown.length, sources);
+    return { markdown: second.markdown, diffs: [first.diff, second.diff] };
+}
+export function reflective(base, r, companion) {
+    let added = `\n\n## Reflective Methodology — AI-generated Ava–Mia Dialogue\n\nGenerated by ${r.model}; fictional agent voices reflecting on this survey. These words were not spoken in the recording or supplied by the author.\n\n`;
+    added += r.dialogue.map(d => `**${d.voice} (AI-generated):** ${d.text}\n`).join("\n");
+    added += `\n### Cross-field synthesis (interpretation)\n\n${r.synthesis}\n\n### Proposed methods and possible evidence\n\n`;
+    added += r.methods.map(m => `- Question: ${m.question}\n  Method (proposed): ${m.method}\n  Possible evidence: ${m.evidence}\n  Contradiction to test: ${m.contradiction}\n`).join("\n");
+    added += `\nHypothesis (untested): ${r.hypothesis}\n\n`;
+    if (companion)
+        added += `## Author-supplied Companion Dialogue\n\nSeparate contribution; supplied by ${companion.author}, originating tool ${companion.tool}, ${companion.supplied_at}. Alignment with video unknown. Exact supplied text follows.\n\n${companion.text}\n\n`;
+    const at = headings(base).find(h => h.name === "Reading Sources")?.at ?? base.length;
+    return insert(base, at, added);
+}

package/dist/reading/privacy.d.ts

@@ -0,0 +1,7 @@
+import type { ConnectorRecord } from "../records.js";
+/** Processing approval never grants other readers access to drafts or completion text. */
+export declare function readingOwner(record: ConnectorRecord, records: ConnectorRecord[]): string | undefined;
+export declare function canReadReading(record: ConnectorRecord, records: ConnectorRecord[], viewer: {
+    id: string;
+    api_tier?: string | null;
+}): boolean;

package/dist/reading/privacy.js

@@ -0,0 +1,14 @@
+/** Processing approval never grants other readers access to drafts or completion text. */
+export function readingOwner(record, records) {
+    if (record.body.reading || record.body.reading_import)
+        return record.actor.person_id;
+    if (record.kind === "session_completion_proposal") {
+        const parent = records.find(r => r.kind === "run_request" && (r.body.reading || r.body.reading_import) && (r.id === record.body.mission || record.refs.includes(r.id)));
+        return parent?.actor.person_id;
+    }
+    return undefined;
+}
+export function canReadReading(record, records, viewer) {
+    const owner = readingOwner(record, records);
+    return !owner || viewer.api_tier === "write" || owner === viewer.id;
+}

package/dist/reading/workflow.d.ts

@@ -0,0 +1,93 @@
+import { type Actor, type ConnectorRecord } from "../records.js";
+import { Ledger } from "../store.js";
+import { type Provider, type ReadingScope, type SourcePart, type BaseReview, type Survey, type Reflection } from "./contract.js";
+export interface ReviewBase {
+    id: string;
+    version: number;
+    markdown: string;
+    video_id: string;
+}
+export interface StageContext {
+    workflow_id: string;
+    video_id: string;
+    scope: ReadingScope;
+    idempotency_key: string;
+    transcript: SourcePart;
+    source_part_id: string;
+    base?: BaseReview;
+    survey?: Survey;
+}
+export interface ReadingAdapters {
+    /** Provider execution belongs to the runtime/shim. Every operation must replay a key without charging twice. */
+    providers: Record<"transcript" | "v1" | "academic" | "reflective", Provider & {
+        idempotent: true;
+    }>;
+    lookup(video: string): Promise<ReviewBase | null>;
+    acquire(context: Omit<StageContext, "transcript" | "source_part_id">): Promise<SourcePart | null>;
+    generateV1(context: StageContext): Promise<BaseReview>;
+    generateSurvey(context: StageContext): Promise<Survey>;
+    generateReflection(context: StageContext): Promise<Reflection>;
+    /** Read primary sources through a host-controlled allowlist; no source-directed credential or media forwarding. */
+    verifySource(source: Survey["sources"][number]): Promise<{
+        url: string;
+        text: string;
+        fetched_at: string;
+    }>;
+    /** True only after a real capability handshake for atomic compare-and-swap + durable idempotency. */
+    atomicImport: boolean;
+    importExact(input: {
+        video_id: string;
+        review_id: string | null;
+        expected_version: number;
+        expected_sha256: string;
+        markdown: string;
+        sha256: string;
+        idempotency_key: string;
+    }): Promise<{
+        id: string;
+        version: number;
+    }>;
+    readExact(id: string, version: number): Promise<ReviewBase>;
+}
+type Receipt = {
+    stage: string;
+    status: string;
+    attempt: number;
+    started_at: string;
+    completed_at: string;
+    workflow_id: string;
+    request_id: string;
+    video_id: string;
+    actor: Actor;
+    consent_scope: ReadingScope;
+    approval_state: string;
+    artifact_refs: string[];
+    sha256: string;
+    previous_sha256: string | null;
+    artifact: any;
+    next_action: string;
+};
+export type ReadingResult = {
+    workflow_id: string;
+    status: string;
+    next_action: string;
+    receipts: Receipt[];
+};
+/** One workflow per person and video; two concurrent releases cannot spend twice. */
+export declare function workflowId(actor: string, video: string, revisionOf?: string): string;
+export declare class ReadingWorkflow {
+    readonly stateDir: string;
+    readonly adapters: ReadingAdapters;
+    readonly ledger: Ledger<ConnectorRecord>;
+    constructor(stateDir: string, adapters: ReadingAdapters);
+    receipts(id: string): Receipt[];
+    private approved;
+    private source;
+    private locked;
+    private record;
+    private done;
+    private provider;
+    run(requestId: string, companion?: unknown): Promise<ReadingResult>;
+    importApproved(requestId: string): Promise<ReadingResult>;
+}
+export {};

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", "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,9 @@ export const RECORD_KINDS = [
     "research_artifact",
     "inquiry_episode_request",
     "session_steer_request",
+    // 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 +101,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

@@ -154,6 +154,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/server.js

@@ -16,7 +16,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { mcpAuthRouter, createOAuthMetadata, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 import { MiadiOAuthProvider, SCOPES, SCOPE_CONTRIBUTE, SCOPE_READ, emptyOAuthState } from "./oauth.js";
-import { reconcileInterrupted, registerApprovalRoutes } from "./approve.js";
+import { reconcileInterrupted, registerApprovalRoutes, registerProviderPolicyRoutes } from "./approve.js";
 import { DecisionTokens } from "./decisions.js";
 import { JsonFile, Ledger, ensureStateDir, statePaths } from "./store.js";
 import { registerTools } from "./tools.js";
@@ -92,6 +92,7 @@ export function createConnectorApp(config, deps) {
     // A run the connector was recording when it last stopped is failed now, so a person may run it again (#924).
     reconcileInterrupted(approvalDeps);
     registerApprovalRoutes(app, approvalDeps);
+    registerProviderPolicyRoutes(app, approvalDeps);
     const decisionTokens = new DecisionTokens(config.stateDir, config.decisionTokenTtl);
     const bearer = requireBearerAuth({
         verifier: provider,

package/dist/store.d.ts

@@ -17,6 +17,8 @@ export declare class Ledger<R extends {
     private cache;
     constructor(path: string);
     append(record: R): R;
+    /** A processing receipt is committed to disk before its dependent stage starts. */
+    appendDurable(record: R): R;
     all(): R[];
 }
 export declare function statePaths(dir: string): {

package/dist/store.js

@@ -10,7 +10,7 @@
  *                (observations, handoffs, proposals). Append-only: a record
  *                is never edited, a later record supersedes it.
  */
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, statSync, writeSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { readJsonSafe, writeJsonAtomic } from "@miadi/node-service-kit/json";
@@ -66,6 +66,23 @@ export class Ledger {
         appendFileSync(this.path, JSON.stringify(record) + "\n", { mode: 0o600 });
         return record;
     }
+    /** A processing receipt is committed to disk before its dependent stage starts. */
+    appendDurable(record) {
+        const fd = openSync(this.path, "a", 0o600);
+        try {
+            // Keep a torn crash tail separate from this record, as all() skips invalid lines.
+            const old = readFileSync(this.path);
+            const line = Buffer.from((old.length && old[old.length - 1] !== 10 ? "\n" : "") + JSON.stringify(record) + "\n");
+            let written = 0;
+            while (written < line.length)
+                written += writeSync(fd, line, written, line.length - written);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return record;
+    }
     all() {
         if (!existsSync(this.path))
             return [];