@miadi/connector 0.1.18 → 0.1.20

package/dist/providers.js

@@ -4,9 +4,11 @@
  * The connector never assumes a provider works because a task text names one:
  * it reports what is installed on this host, what sign-in evidence exists (the
  * presence of the provider's own config directory — never its contents), and
- * applies an explicit preference order. Claude Code is never selected silently:
- * it requires an explicit request. When nothing safe is configured the answer
- * is `provider_unavailable` and the mission is left unstarted.
+ * applies an explicit preference order. Codex and Claude Code are never selected
+ * silently: each requires the request to name it, and Codex also needs the
+ * requester's own choice for that mission (provider-policy.ts, jgwill/Miadi#926).
+ * When nothing safe is configured the answer is `provider_unavailable` and the
+ * mission is left unstarted.
  *
  * No bearer token is read, logged or returned here. Version probes run the
  * provider's own `--version` with a short timeout.
@@ -15,9 +17,13 @@ import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-/** Preference order when a run request names no provider (jgwill/Miadi#893). */
+/**
+ * Preference order when a run request names no provider (jgwill/Miadi#893). Codex is never
+ * picked by default: a request names it, and it runs only on the requester's own choice for
+ * that mission or their own policy (provider-policy.ts, jgwill/Miadi#926).
+ */
 export const PROVIDERS = [
-    { id: "codex", cli: "codex", name: "Codex CLI", selectable_by_default: true, auth_evidence: [".codex"] },
+    { id: "codex", cli: "codex", name: "Codex CLI", selectable_by_default: false, auth_evidence: [".codex"] },
     { id: "pi", cli: "pi", name: "Pi coding agent", selectable_by_default: true, auth_evidence: [".pi", ".config/pi"] },
     { id: "copilot", cli: "copilot", name: "GitHub Copilot CLI", selectable_by_default: true, auth_evidence: [".copilot"] },
     { id: "claude", cli: "claude", name: "Claude Code", selectable_by_default: false, auth_evidence: [".claude"] },
@@ -59,8 +65,8 @@ export function discoverProviders(probe = {}, specs = PROVIDERS) {
 /**
  * Resolve the provider a run will ask the intake for. A requested provider must
  * be known and installed; with no request the first installed provider in the
- * preference order that may be selected by default wins — Claude Code only ever
- * by an explicit request.
+ * preference order that may be selected by default wins. Codex and Claude Code
+ * only ever by name; whether a named Codex may run is provider-policy.ts's answer.
  */
 export function resolveProvider(requested, found) {
     const installed = found.filter((p) => p.installed);

package/dist/queue-state.js

@@ -1,5 +1,5 @@
 /** Shared, read-only factory queue evidence for every request-state surface. */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 export function factoryDir(env = process.env) {
     // The factory's data folder, beside the connector's own /srv/miadi/connector: never a home directory (jgwill/Miadi#911).
@@ -18,6 +18,17 @@ export function readQueueState(record, dir = factoryDir()) {
         return { state: "delivered", file };
     if (existsSync(join(queue, "cancelled", file)))
         return { state: "cancelled", file };
+    if (existsSync(join(queue, "refused", file))) {
+        // The factory runner would not launch its provider (jgwill/Miadi#926): the reason it wrote beside the brief.
+        let why = "";
+        try {
+            why = readFileSync(join(queue, "refused", `${file}.why`), "utf8").trim().slice(0, 500);
+        }
+        catch {
+            /* no reason written */
+        }
+        return { state: "refused", file, note: `The factory runner refused to launch it${why ? `: ${why}` : "."}` };
+    }
     if (existsSync(join(queue, "stale", file)))
         return { state: "stale", file, note: "Its seat did not take it in time; the intake moved it aside." };
     return { state: record.approval_state === "approved" ? "missing" : "not_queued", file };

package/dist/reading/adapters.d.ts

@@ -0,0 +1,18 @@
+import { type ReadingScope } from "./contract.js";
+import type { ReadingAdapters, ReviewBase } from "./workflow.js";
+export declare function reviewAdapter(baseUrl: string, token: string | undefined, fetchImpl?: typeof fetch): {
+    lookup(video: string): Promise<ReviewBase | null>;
+    readExact: (id: string, version: number) => Promise<ReviewBase>;
+    atomicImport: boolean;
+    /** Future v0 contract; enable only from an authenticated live handshake, never a caller flag. */
+    discoverAtomicImport(): Promise<boolean>;
+    importExact(input: Parameters<ReadingAdapters["importExact"]>[0]): Promise<{
+        id: any;
+        version: any;
+    }>;
+    storeTranscript(id: string, text: string): Promise<any>;
+};
+/** Public literature GETs only: allowlisted HTTPS hosts, no credentials, redirects or private IPs. */
+export declare function literatureVerifier(hosts: string[], fetchImpl?: typeof fetch): ReadingAdapters["verifySource"];
+/** Human-readable factory task; its scope is data in the approved record, never shell interpolation. */
+export declare function readingTask(scope: ReadingScope): string;

package/dist/reading/adapters.js

@@ -0,0 +1,90 @@
+/** The real service adapter deliberately refuses the legacy unconditional import endpoint. */
+import { ReviewClient, reviewIdOf } from "../reviews.js";
+import { block, canonicalVideo } from "./contract.js";
+export function reviewAdapter(baseUrl, token, fetchImpl = fetch) {
+    const client = new ReviewClient(baseUrl, token, fetchImpl);
+    const request = async (path, init = {}) => {
+        const res = await fetchImpl(`${baseUrl}${path}`, { ...init, redirect: "error", signal: AbortSignal.timeout(30000), headers: { accept: "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...init.headers } });
+        if (res.status === 401 || res.status === 403)
+            block("blocked_permission", "Refresh the review service credential in its configured environment; do not paste it into chat.");
+        if (res.status === 409 || res.status === 412)
+            block("blocked_permission", "The review changed after staging. Rebase and obtain approval for a new candidate.");
+        if (!res.ok)
+            block("failed_retryable", `Review service answered ${res.status}; retry the same operation key after recovery.`);
+        return res.json();
+    };
+    const readExact = async (id, version) => {
+        if (reviewIdOf(id) !== id)
+            block("blocked_permission", "Review service returned an invalid review id.");
+        const body = await client.get(id, version);
+        if (!body || body.version?.version !== version)
+            block("failed_retryable", "Pinned review version is unavailable; fallback-to-latest is refused.");
+        const raw = await fetchImpl(`${baseUrl}/review/${id}/raw?v=${version}`, { redirect: "error", signal: AbortSignal.timeout(30000) });
+        if (!raw.ok)
+            block("failed_retryable", "Pinned raw Markdown could not be read.");
+        const markdown = await raw.text();
+        if (markdown !== body.version.markdown)
+            block("failed_retryable", "Raw and JSON Markdown differ; inspect the service before importing.");
+        return { id, version, markdown, video_id: canonicalVideo(body.video_id) };
+    };
+    return {
+        async lookup(video) {
+            if (!token)
+                block("blocked_permission", "Configure the review search token on the host before generating a potentially duplicate V1.");
+            const response = await request(`/api/reviews/search?${new URLSearchParams({ q: canonicalVideo(video), limit: "100" })}`);
+            const rows = response.reviews ?? response.results;
+            if (!Array.isArray(rows))
+                block("failed_retryable", "Review search returned malformed data; do not infer that no review exists.");
+            const matches = rows.filter(r => r.video_id === video);
+            if (matches.length > 1)
+                block("blocked_permission", "Multiple reviews exist for this video; the author must select the base.");
+            if (!matches.length)
+                return null;
+            if (!matches[0].latest_version)
+                block("failed_retryable", "Existing review is pending generation; no duplicate V1 will be generated.");
+            return readExact(matches[0].id, matches[0].latest_version);
+        },
+        readExact,
+        atomicImport: false,
+        /** Future v0 contract; enable only from an authenticated live handshake, never a caller flag. */
+        async discoverAtomicImport() {
+            const res = await fetchImpl(`${baseUrl}/api/reviews/capabilities`, { redirect: "error", signal: AbortSignal.timeout(15000), headers: token ? { authorization: `Bearer ${token}` } : {} });
+            if (!res.ok)
+                return false;
+            const c = await res.json();
+            return c.conditional_import === "sha256-cas-v1" && c.idempotency === "durable-transactional-v1" && c.publication === "explicit";
+        },
+        async importExact(input) {
+            // Kept on the real /import path, with a negotiated extension. Never send a legacy write.
+            if (!await this.discoverAtomicImport())
+                block("blocked_permission", "Atomic import is not implemented by the review service. Apply the v0 prompt first.");
+            const result = await request("/api/reviews/import", { method: "POST", headers: { "content-type": "application/json", "idempotency-key": input.idempotency_key }, body: JSON.stringify({ url: `https://youtu.be/${input.video_id}`, markdown: input.markdown, review_id: input.review_id, expected_version: input.expected_version, expected_sha256: input.expected_sha256, sha256: input.sha256, public_release: true, contract: "sha256-cas-v1" }) });
+            return { id: result.id, version: result.version };
+        },
+        async storeTranscript(id, text) {
+            // No generation-on-empty, trimming, or overwrite. Connector source-part remains canonical.
+            if (!text.trim() || reviewIdOf(id) !== id)
+                block("blocked_transcript", "An existing review id and nonempty exact transcript are required.");
+            return request(`/api/reviews/${id}/transcript`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ transcript: text, overwrite: false }) });
+        },
+    };
+}
+/** Public literature GETs only: allowlisted HTTPS hosts, no credentials, redirects or private IPs. */
+export function literatureVerifier(hosts, fetchImpl = fetch) {
+    return async (source) => {
+        const u = new URL(source.url);
+        if (u.protocol !== "https:" || u.username || u.password || u.port || !hosts.includes(u.hostname) || /^[\d.]+$/.test(u.hostname) || u.hostname.includes(":"))
+            block("blocked_citations", "Literature source is outside the host's public-source allowlist.");
+        const res = await fetchImpl(u, { redirect: "error", signal: AbortSignal.timeout(15000), headers: { accept: "text/plain, text/html, application/json" } });
+        if (!res.ok)
+            block("blocked_citations", "Public source could not be retrieved; no citation was marked verified.");
+        const text = await res.text();
+        if (Buffer.byteLength(text) > 2 * 1024 * 1024)
+            block("blocked_citations", "Public source exceeds the bounded verification size.");
+        return { url: source.url, text: text.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " "), fetched_at: new Date().toISOString() };
+    };
+}
+/** Human-readable factory task; its scope is data in the approved record, never shell interpolation. */
+export function readingTask(scope) {
+    return `Run the bounded transcript-first reading worker for THIS approved connector record:\nnode packages/connector/scripts/reading.mjs run <this-run-request-id>\nThe typed reading grant in this record is the only processing authority. Read packages/connector/scripts/READING.md.\nReturn stage receipts and staged V1/V2/V3 with hashes, insertion diff and provenance. Stop at editorial approval. No public import, Deep Diver, Chronicle, paid fallback or media upload beyond the grant.\nKind: ${scope.kind}; language: ${scope.language}; total provider ceiling USD ${scope.max_cost_usd}. Missing capabilities are explicit blockers, never permission to generate from memory.`;
+}

package/dist/reading/contract.d.ts

@@ -0,0 +1,153 @@
+/** Bounded reading contract. Product state lives in the connector ledger; providers stay injected. */
+import { z } from "zod";
+export declare const hash: (value: string) => string;
+export declare const readingScope: z.ZodObject<{
+    source_intent: z.ZodString;
+    revision_of: z.ZodOptional<z.ZodString>;
+    kind: z.ZodDefault<z.ZodEnum<{
+        "research-inquiry": "research-inquiry";
+        "ui-screenwalk": "ui-screenwalk";
+    }>>;
+    language: z.ZodString;
+    rights: z.ZodString;
+    providers: z.ZodArray<z.ZodString>;
+    max_cost_usd: z.ZodDefault<z.ZodNumber>;
+    budget_approval_ref: z.ZodOptional<z.ZodString>;
+    allow_media_access: z.ZodDefault<z.ZodBoolean>;
+    allow_external_processing: z.ZodDefault<z.ZodBoolean>;
+    max_field_words: z.ZodDefault<z.ZodNumber>;
+    max_fields: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type ReadingScope = z.infer<typeof readingScope>;
+export declare const sourcePart: z.ZodObject<{
+    video_id: z.ZodString;
+    kind: z.ZodEnum<{
+        captions: "captions";
+        verbatim_transcript: "verbatim_transcript";
+    }>;
+    channel: z.ZodEnum<{
+        video: "video";
+        commentary: "commentary";
+    }>;
+    text: z.ZodString;
+    normalized_text: z.ZodOptional<z.ZodString>;
+    language: z.ZodString;
+    locator: z.ZodString;
+    provider: z.ZodString;
+    caption_kind: z.ZodEnum<{
+        manual: "manual";
+        automatic: "automatic";
+        supplied: "supplied";
+        local_stt: "local_stt";
+    }>;
+    fetched_at: z.ZodString;
+    rights: z.ZodString;
+    timestamp_granularity: z.ZodEnum<{
+        none: "none";
+        word: "word";
+        segment: "segment";
+        turn: "turn";
+    }>;
+    alignment_status: z.ZodEnum<{
+        unknown: "unknown";
+        verified: "verified";
+    }>;
+    speaker_status: z.ZodEnum<{
+        unknown: "unknown";
+        verified: "verified";
+    }>;
+    segments: z.ZodArray<z.ZodObject<{
+        start_ms: z.ZodNumber;
+        end_ms: z.ZodNumber;
+        text: z.ZodString;
+        speaker: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SourcePart = z.infer<typeof sourcePart>;
+export interface Provider {
+    id: string;
+    available: boolean;
+    external: boolean;
+    media: boolean;
+    max_cost_usd: number;
+    method: string;
+}
+export declare const evidence: z.ZodObject<{
+    category: z.ZodEnum<{
+        transcript_supported: "transcript_supported";
+        visually_evidenced: "visually_evidenced";
+        inference: "inference";
+        open_question: "open_question";
+    }>;
+    claim: z.ZodString;
+    at_ms: z.ZodOptional<z.ZodNumber>;
+    visual_receipt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const baseReview: z.ZodObject<{
+    markdown: z.ZodString;
+    claims: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            transcript_supported: "transcript_supported";
+            visually_evidenced: "visually_evidenced";
+            inference: "inference";
+            open_question: "open_question";
+        }>;
+        claim: z.ZodString;
+        at_ms: z.ZodOptional<z.ZodNumber>;
+        visual_receipt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    model: z.ZodString;
+}, z.core.$strict>;
+export declare const survey: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        body: z.ZodString;
+        at_ms: z.ZodNumber;
+        question: z.ZodString;
+        limitation: z.ZodString;
+        source_ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        url: z.ZodString;
+        excerpt: z.ZodString;
+        claim: z.ZodString;
+    }, z.core.$strict>>;
+    model: z.ZodString;
+}, z.core.$strict>;
+export declare const reflection: z.ZodObject<{
+    dialogue: z.ZodArray<z.ZodObject<{
+        voice: z.ZodEnum<{
+            Ava: "Ava";
+            Mia: "Mia";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    synthesis: z.ZodString;
+    methods: z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        method: z.ZodString;
+        evidence: z.ZodString;
+        contradiction: z.ZodString;
+    }, z.core.$strict>>;
+    hypothesis: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strict>;
+export declare const suppliedDialogue: z.ZodObject<{
+    text: z.ZodString;
+    author: z.ZodString;
+    tool: z.ZodString;
+    supplied_at: z.ZodString;
+}, z.core.$strict>;
+export type BaseReview = z.infer<typeof baseReview>;
+export type Survey = z.infer<typeof survey>;
+export type Reflection = z.infer<typeof reflection>;
+export declare class ReadingBlocked extends Error {
+    readonly status: string;
+    readonly next_action: string;
+    constructor(status: string, next_action: string);
+}
+export declare function block(status: string, next: string): never;
+/** Recognise only real YouTube hosts and exact ids; never use URL-derived text as code. */
+export declare function canonicalVideo(input: string): string;

package/dist/reading/contract.js

@@ -0,0 +1,79 @@
+/** Bounded reading contract. Product state lives in the connector ledger; providers stay injected. */
+import { z } from "zod";
+import { createHash } from "node:crypto";
+export const hash = (value) => createHash("sha256").update(value).digest("hex");
+export const readingScope = z.object({
+    source_intent: z.string().regex(/^source_intent:[\da-f-]{36}$/i),
+    revision_of: z.string().regex(/^reading:[a-f\d]{32}$/).optional(),
+    kind: z.enum(["research-inquiry", "ui-screenwalk"]).default("research-inquiry"),
+    language: z.string().min(2).max(40),
+    rights: z.string().min(1).max(1000),
+    providers: z.array(z.string().min(1).max(100)).min(1).max(20),
+    max_cost_usd: z.number().finite().min(0).max(100).default(0),
+    budget_approval_ref: z.string().min(1).optional(),
+    allow_media_access: z.boolean().default(false),
+    allow_external_processing: z.boolean().default(false),
+    max_field_words: z.number().int().min(20).max(500).default(55),
+    max_fields: z.number().int().min(1).max(12).default(6),
+}).strict();
+export const sourcePart = z.object({
+    video_id: z.string().regex(/^[\w-]{11}$/),
+    kind: z.enum(["captions", "verbatim_transcript"]),
+    channel: z.enum(["video", "commentary"]),
+    text: z.string().min(1).max(800000),
+    normalized_text: z.string().max(800000).optional(),
+    language: z.string().min(2),
+    locator: z.string().min(1),
+    provider: z.string().min(1),
+    caption_kind: z.enum(["manual", "automatic", "supplied", "local_stt"]),
+    fetched_at: z.string().datetime(),
+    rights: z.string().min(1),
+    timestamp_granularity: z.enum(["word", "segment", "turn", "none"]),
+    alignment_status: z.enum(["unknown", "verified"]),
+    speaker_status: z.enum(["unknown", "verified"]),
+    segments: z.array(z.object({ start_ms: z.number().int().min(0), end_ms: z.number().int().min(0), text: z.string(), speaker: z.string().optional() }).strict()).max(50000),
+}).strict();
+export const evidence = z.object({
+    category: z.enum(["transcript_supported", "visually_evidenced", "inference", "open_question"]),
+    claim: z.string().min(1),
+    at_ms: z.number().int().min(0).optional(),
+    visual_receipt: z.string().min(1).optional(),
+}).strict();
+export const baseReview = z.object({ markdown: z.string().min(1).max(400000), claims: z.array(evidence).min(1), model: z.string().min(1) }).strict();
+export const survey = z.object({
+    fields: z.array(z.object({ name: z.string().min(1), body: z.string().min(1), at_ms: z.number().int().min(0), question: z.string().min(1), limitation: z.string().min(1), source_ids: z.array(z.string()).min(1) }).strict()).min(1),
+    sources: z.array(z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), title: z.string().trim().min(1), url: z.string().url(), excerpt: z.string().min(20).max(1000).refine(s => s.trim().length >= 20, "A verifiable excerpt needs meaningful text"), claim: z.string().trim().min(1) }).strict()).min(1),
+    model: z.string().min(1),
+}).strict();
+export const reflection = z.object({
+    dialogue: z.array(z.object({ voice: z.enum(["Ava", "Mia"]), text: z.string().min(1) }).strict()).min(2),
+    synthesis: z.string().min(40),
+    methods: z.array(z.object({ question: z.string().min(1), method: z.string().min(1), evidence: z.string().min(1), contradiction: z.string().min(1) }).strict()).min(1),
+    hypothesis: z.string().min(1), model: z.string().min(1),
+}).strict();
+export const suppliedDialogue = z.object({ text: z.string().min(1).max(200000), author: z.string().min(1), tool: z.string().min(1), supplied_at: z.string().datetime() }).strict();
+export class ReadingBlocked extends Error {
+    status;
+    next_action;
+    constructor(status, next_action) {
+        super(status);
+        this.status = status;
+        this.next_action = next_action;
+    }
+}
+export function block(status, next) { throw new ReadingBlocked(status, next); }
+/** Recognise only real YouTube hosts and exact ids; never use URL-derived text as code. */
+export function canonicalVideo(input) {
+    if (/^[\w-]{11}$/.test(input))
+        return input;
+    try {
+        const u = new URL(input);
+        if (u.protocol !== "https:")
+            throw new Error();
+        const id = u.hostname === "youtu.be" ? u.pathname.slice(1) : ["youtube.com", "www.youtube.com", "m.youtube.com"].includes(u.hostname) ? u.searchParams.get("v") ?? u.pathname.match(/^\/(?:shorts|embed)\/([\w-]+)$/)?.[1] : undefined;
+        if (id && /^[\w-]{11}$/.test(id))
+            return id;
+    }
+    catch { /* fail closed */ }
+    return block("blocked_permission", "Supply an exact YouTube video id or supported HTTPS URL.");
+}

package/dist/reading/markdown.d.ts

@@ -0,0 +1,47 @@
+import { type Reflection, type Survey } from "./contract.js";
+/** UTF-16 string offsets outside code fences, retaining CRLF. No Markdown reserialization. */
+export declare function headings(markdown: string): {
+    name: string;
+    at: number;
+}[];
+export declare function insert(base: string, at: number, addition: string): {
+    markdown: string;
+    diff: {
+        operation: string;
+        at: number;
+        addition: string;
+        base_sha256: string;
+        sha256: string;
+        bytes: number;
+        retained: boolean;
+    };
+};
+export declare function academic(base: string, s: Survey): {
+    markdown: string;
+    diffs: {
+        operation: string;
+        at: number;
+        addition: string;
+        base_sha256: string;
+        sha256: string;
+        bytes: number;
+        retained: boolean;
+    }[];
+};
+export declare function reflective(base: string, r: Reflection, companion?: {
+    text: string;
+    author: string;
+    tool: string;
+    supplied_at: string;
+}): {
+    markdown: string;
+    diff: {
+        operation: string;
+        at: number;
+        addition: string;
+        base_sha256: string;
+        sha256: string;
+        bytes: number;
+        retained: boolean;
+    };
+};

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 {};