@miadi/connector 0.1.19 → 0.1.21

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