cloving 1.0.1 → 1.2.0

package/dist/src/daemon/chats-files.js

@@ -0,0 +1,252 @@
+import { lstat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { record } from "../protocol.js";
+import { openInput } from "../chats/input-file.js";
+import { createPrivateFile, validateDestination, } from "../chats/destination.js";
+import { analysisDocumentBytes, } from "../chats/analysis-input.js";
+import { analysisCaptureBytes } from "../chats/analysis-batches.js";
+export async function readAnalysisCorpus(path, options = {}) {
+    const handle = await openInput(path);
+    let output;
+    try {
+        if (options.permissions !== undefined &&
+            ((await handle.stat()).mode & 0o777) !== options.permissions)
+            throw new Error("analysis-output-failed");
+        if (options.output !== undefined)
+            output = await createPrivateFile(options.output);
+        const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+        const buffer = Buffer.alloc(65_536);
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read({
+                buffer,
+                length: Math.min(buffer.length, analysisCaptureBytes + 1 - size),
+            });
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+            if (size > analysisCaptureBytes)
+                throw new Error("analysis-too-large");
+            if (output !== undefined)
+                await output.writeFile(buffer.subarray(0, bytesRead));
+            chunks.push(decoder.decode(buffer.subarray(0, bytesRead), { stream: true }));
+        }
+        chunks.push(decoder.decode());
+        return chunks.join("");
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        finally {
+            await output?.close();
+        }
+    }
+}
+export async function analysisDirectory(runtime, importId) {
+    if (process.platform !== "darwin")
+        throw new Error("platform-unsupported");
+    const directory = resolve(runtime, "chats", importId);
+    await checkedDirectory(directory);
+    return directory;
+}
+async function checkedDirectory(directory) {
+    try {
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error("analysis-input-refused");
+    }
+    catch (error) {
+        if (Reflect.get(Object(error), "code") !== "ENOENT")
+            throw error;
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw error;
+        await checkedDirectory(parent);
+        throw error;
+    }
+    await validateDestination(directory);
+}
+export async function boundedAnalysisFile(path, options = {}) {
+    const handle = await openInput(path);
+    try {
+        if (options.permissions !== undefined &&
+            ((await handle.stat()).mode & 0o777) !== options.permissions)
+            throw new Error("analysis-output-failed");
+        const buffer = Buffer.alloc(analysisDocumentBytes + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+        }
+        if (size > analysisDocumentBytes)
+            throw new Error("analysis-too-large");
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, size));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readAnalysisSnapshot(directory, input) {
+    const { importId, ...options } = input;
+    const required = async (name) => {
+        try {
+            return name === "redacted.jsonl"
+                ? await readAnalysisCorpus(join(directory, name), options)
+                : await boundedAnalysisFile(join(directory, name), options);
+        }
+        catch (error) {
+            if (Reflect.get(Object(error), "code") === "ENOENT")
+                throw new Error("redaction-required", { cause: error });
+            throw error;
+        }
+    };
+    return {
+        importId,
+        redaction: await required("redaction.json"),
+        corpus: await required("redacted.jsonl"),
+        structure: await boundedAnalysisFile(join(directory, "structure.json"), options),
+    };
+}
+export async function matchingPrivateFile(path, text) {
+    try {
+        const existing = await boundedAnalysisFile(path, { permissions: 0o600 });
+        if (existing !== text)
+            throw new Error("analysis-output-failed");
+        return;
+    }
+    catch (error) {
+        if (Reflect.get(Object(error), "code") !== "ENOENT")
+            throw error;
+    }
+    const handle = await createPrivateFile(path);
+    try {
+        await handle.writeFile(text);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function requireAbsent(directory, names) {
+    for (const name of names) {
+        const exists = await lstat(join(directory, name)).catch((error) => {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (exists !== undefined)
+            throw new Error("analysis-output-failed");
+    }
+}
+function outputClaim(directory, output) {
+    return {
+        path: join(directory, `${"draft" in output ? "final-claim" : "claim"}-${output.cycleId}.json`),
+        text: JSON.stringify({
+            schemaVersion: 1,
+            kind: "reply" in output ? "draft" : "final",
+            digest: createHash("sha256")
+                .update(JSON.stringify(output))
+                .digest("hex"),
+        }) + "\n",
+    };
+}
+async function inspectOutputClaim(claim) {
+    const text = await boundedAnalysisFile(claim.path, {
+        permissions: 0o600,
+    }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (text !== undefined && text !== claim.text)
+        throw new Error("analysis-output-failed");
+}
+export async function inspectAnalysisFiles(directory, output) {
+    if (Buffer.byteLength(JSON.stringify(output)) > analysisDocumentBytes)
+        throw new Error("analysis-too-large");
+    await inspectOutputClaim(outputClaim(directory, output));
+    if (output.draft === undefined)
+        await requireAbsent(directory, [`draft-${output.cycleId}.json`]);
+    else if ((await inspectAnalysisDraftRecord(directory, output.draft)) === undefined)
+        throw new Error("analysis-output-failed");
+    const proposal = join(directory, `proposal-${output.cycleId}.txt`);
+    const analysis = join(directory, `analysis-${output.cycleId}.json`);
+    const marker = await boundedAnalysisFile(analysis, {
+        permissions: 0o600,
+    }).catch((error) => {
+        if (Reflect.get(Object(error), "code") === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (marker === undefined)
+        return "absent";
+    if (marker !== output.analysis ||
+        (await boundedAnalysisFile(proposal, { permissions: 0o600 })) !==
+            output.proposal)
+        throw new Error("analysis-output-failed");
+    return "complete";
+}
+export async function saveAnalysisFiles(directory, output) {
+    if ((await inspectAnalysisFiles(directory, output)) === "complete")
+        return;
+    const claim = outputClaim(directory, output);
+    await matchingPrivateFile(claim.path, claim.text);
+    const proposal = join(directory, `proposal-${output.cycleId}.txt`);
+    const analysis = join(directory, `analysis-${output.cycleId}.json`);
+    await matchingPrivateFile(proposal, output.proposal);
+    await matchingPrivateFile(analysis, output.analysis);
+}
+function draftRecord(input, expiresAt) {
+    return {
+        schemaVersion: 1,
+        ...input,
+        candidateDigest: createHash("sha256").update(input.reply).digest("hex"),
+        expiresAt,
+    };
+}
+export async function inspectAnalysisDraft(directory, input) {
+    await requireAbsent(directory, [
+        `analysis-${input.cycleId}.json`,
+        `proposal-${input.cycleId}.txt`,
+    ]);
+    return inspectAnalysisDraftRecord(directory, input);
+}
+export async function inspectAnalysisDraftRecord(directory, input) {
+    await inspectOutputClaim(outputClaim(directory, input));
+    const text = await boundedAnalysisFile(join(directory, `draft-${input.cycleId}.json`), { permissions: 0o600 }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (text === undefined)
+        return undefined;
+    const expiresAt = record(JSON.parse(text))?.["expiresAt"];
+    if (typeof expiresAt !== "string" ||
+        !Number.isFinite(Date.parse(expiresAt)) ||
+        new Date(expiresAt).toISOString() !== expiresAt)
+        throw new Error("analysis-output-failed");
+    const expected = draftRecord(input, expiresAt);
+    if (text !== JSON.stringify(expected) + "\n")
+        throw new Error("analysis-output-failed");
+    return { candidateDigest: expected.candidateDigest, expiresAt };
+}
+export async function saveAnalysisDraft(directory, saving) {
+    const { input, now } = saving;
+    const existing = await inspectAnalysisDraft(directory, input);
+    if (existing !== undefined)
+        return existing;
+    const claim = outputClaim(directory, input);
+    await matchingPrivateFile(claim.path, claim.text);
+    const expiresAt = new Date(Date.parse(now()) + 86_400_000).toISOString();
+    const draft = draftRecord(input, expiresAt);
+    const text = JSON.stringify(draft) + "\n";
+    if (Buffer.byteLength(text) > analysisDocumentBytes)
+        throw new Error("analysis-output-failed");
+    await matchingPrivateFile(join(directory, `draft-${input.cycleId}.json`), text);
+    return { candidateDigest: draft.candidateDigest, expiresAt };
+}

package/dist/src/daemon/chats-follow-up.d.ts

@@ -0,0 +1,38 @@
+import type { AdapterOutcome, DeliveryIntent } from "../broker/actor/delivery-intents.ts";
+import { type Fields } from "../protocol.ts";
+import { type AnalysisSnapshot } from "../chats/analysis-input.ts";
+import type { AnalysisQuestion } from "../chats/analysis-contract.ts";
+import { analysisBatchData } from "../chats/analysis-batches.ts";
+import { type AnalysisDraftInput } from "./chats-files.ts";
+export type ChatsResult = ReturnType<typeof analysisBatchData> | ({
+    readonly kind: "analysis_batch";
+} & ReturnType<typeof analysisBatchData>) | {
+    readonly kind: "analysis_partial";
+    readonly reason: string;
+} | {
+    readonly kind: "analysis_draft";
+    readonly cycleId: string;
+    readonly candidateDigest: string;
+    readonly expiresAt: string;
+    readonly question: AnalysisQuestion;
+} | {
+    readonly kind: "handoff_requested";
+    readonly cycleId: string;
+    readonly promotionId: string;
+};
+interface FollowUpSave {
+    readonly intent: DeliveryIntent;
+    readonly payload: Fields;
+    readonly mode: "deliver" | "reconcile";
+    readonly input: {
+        readonly cycleId: string;
+        readonly snapshot: AnalysisSnapshot;
+        readonly candidate: unknown;
+    };
+}
+export declare function storedAnalysisDraft(directory: string, call: FollowUpSave): Promise<AnalysisDraftInput | undefined>;
+export declare function saveFollowUp(runtime: string, call: FollowUpSave): Promise<AdapterOutcome>;
+export declare function saveAcceptedAnalysis(runtime: string, call: FollowUpSave & {
+    readonly draft?: AnalysisDraftInput;
+}): Promise<AdapterOutcome>;
+export {};

package/dist/src/daemon/chats-follow-up.js

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { record } from "../protocol.js";
+import { analysisFollowUp } from "../chats/analysis-prompt.js";
+import { analysisEvidence, } from "../chats/analysis-input.js";
+import { validateAnalysis } from "../chats/analysis.js";
+import { analysisProposal } from "../chats/analysis-proposal.js";
+import { analysisBatchData } from "../chats/analysis-batches.js";
+import { finalizeAnalysis } from "./chats-checkpoints.js";
+import { operationKey } from "./operation-journal.js";
+import { analysisDirectory, boundedAnalysisFile, inspectAnalysisDraftRecord, inspectAnalysisFiles, saveAnalysisFiles, } from "./chats-files.js";
+function storedDraftIdentity(stored, call) {
+    return (stored?.["runId"] === call.intent.runId &&
+        stored["cycleId"] === call.input.cycleId &&
+        typeof stored["operationId"] === "string" &&
+        typeof stored["inputDigest"] === "string" &&
+        typeof stored["reply"] === "string" &&
+        stored["snapshotDigest"] ===
+            createHash("sha256")
+                .update(JSON.stringify(call.input.snapshot))
+                .digest("hex"));
+}
+export async function storedAnalysisDraft(directory, call) {
+    const { cycleId } = call.input;
+    const text = await boundedAnalysisFile(join(directory, `draft-${cycleId}.json`), { permissions: 0o600 }).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (text === undefined)
+        return undefined;
+    const stored = record(JSON.parse(text));
+    if (!storedDraftIdentity(stored, call))
+        throw new Error("analysis-follow-up-refused");
+    const draft = {
+        runId: call.intent.runId,
+        cycleId,
+        operationId: stored["operationId"],
+        inputDigest: stored["inputDigest"],
+        snapshotDigest: stored["snapshotDigest"],
+        reply: stored["reply"],
+        ...("batch" in stored ? { batch: stored["batch"] } : {}),
+    };
+    if ((await inspectAnalysisDraftRecord(directory, draft)) === undefined)
+        throw new Error("analysis-follow-up-refused");
+    return draft;
+}
+async function boundDraft(directory, call) {
+    const followUp = analysisFollowUp(call.payload["followUp"]);
+    const draft = await storedAnalysisDraft(directory, call);
+    if (draft === undefined ||
+        JSON.stringify(draft.batch) !== JSON.stringify(call.payload["batch"]) ||
+        JSON.stringify(JSON.parse(draft.reply)) !== JSON.stringify(followUp.draft))
+        throw new Error("analysis-follow-up-refused");
+    return draft;
+}
+function refused(reason, codes = [reason]) {
+    return {
+        kind: "failed",
+        reason,
+        result: JSON.stringify({ kind: "blocked", codes }),
+    };
+}
+export async function saveFollowUp(runtime, call) {
+    const { snapshot, candidate } = call.input;
+    try {
+        if ("batch" in call.payload &&
+            Object.hasOwn(record(candidate) ?? {}, "openQuestion"))
+            return refused("analysis-question-limit");
+        if (!("batch" in call.payload))
+            return await saveSnapshotFollowUp(runtime, call);
+        const directory = await analysisDirectory(runtime, snapshot.importId);
+        const draft = await boundDraft(directory, call);
+        return await saveAcceptedAnalysis(runtime, { ...call, draft });
+    }
+    catch {
+        return refused("analysis-follow-up-refused");
+    }
+}
+async function saveSnapshotFollowUp(runtime, call) {
+    const { snapshot, cycleId, candidate } = call.input;
+    const validation = validateAnalysis(candidate, analysisEvidence(snapshot));
+    if (!validation.accepted)
+        return refused("analysis-follow-up-refused", validation.codes);
+    if (validation.result.openQuestion !== undefined)
+        return refused("analysis-question-limit");
+    const directory = await analysisDirectory(runtime, snapshot.importId);
+    const draft = await boundDraft(directory, call);
+    const output = {
+        cycleId,
+        draft,
+        analysis: JSON.stringify(validation.result) + "\n",
+        proposal: analysisProposal(validation.result),
+    };
+    if (call.mode === "reconcile" &&
+        (await inspectAnalysisFiles(directory, output)) === "absent")
+        return { kind: "absent" };
+    if (call.mode === "deliver")
+        await saveAnalysisFiles(directory, output);
+    return {
+        kind: "completed",
+        worker: "chats",
+        receipt: operationKey(call.intent.operationId),
+        result: JSON.stringify({
+            kind: "handoff_requested",
+            cycleId,
+            promotionId: `analysis:${snapshot.importId}:${cycleId}`,
+        }),
+    };
+}
+async function acceptedDraft(directory, call) {
+    const draft = await storedAnalysisDraft(directory, call);
+    if (draft === undefined)
+        return undefined;
+    const batch = record(call.payload["batch"]);
+    const prior = record(draft.batch);
+    if (prior === undefined ||
+        batch === undefined ||
+        Number(batch["batchIndex"]) === Number(prior["batchIndex"]))
+        throw new Error("analysis-follow-up-refused");
+    if (Number(batch["batchIndex"]) < Number(prior["batchIndex"]))
+        return undefined;
+    return draft;
+}
+export async function saveAcceptedAnalysis(runtime, call) {
+    const { snapshot, cycleId, candidate } = call.input;
+    const { importId } = snapshot;
+    try {
+        const directory = await analysisDirectory(runtime, importId);
+        const draft = call.draft ??
+            ("batch" in call.payload
+                ? await acceptedDraft(directory, call)
+                : undefined);
+        const saved = await finalizeAnalysis(directory, {
+            runId: call.intent.runId,
+            importId,
+            cycleId,
+            snapshot: "snapshot" in call.payload ? snapshot : undefined,
+            candidate,
+            mode: call.mode,
+            batch: call.payload["batch"],
+            ...(draft === undefined ? {} : { draft }),
+        });
+        return savedOutcome(call, saved);
+    }
+    catch {
+        throw new Error("analysis-output-failed");
+    }
+}
+function savedOutcome(call, saved) {
+    const { cycleId, snapshot } = call.input;
+    const { importId } = snapshot;
+    if (saved.kind === "absent")
+        return { kind: "absent" };
+    if (saved.kind === "refused")
+        return refused(call.draft !== undefined &&
+            !saved.codes.includes("analysis-merge-conflict")
+            ? "analysis-follow-up-refused"
+            : (saved.codes[0] ?? "analysis-input-refused"), saved.codes);
+    let result = {
+        kind: "handoff_requested",
+        cycleId,
+        promotionId: `analysis:${importId}:${cycleId}`,
+    };
+    if (saved.next?.kind === "refused")
+        result = { kind: "analysis_partial", reason: saved.next.code };
+    if (saved.next?.kind === "batch")
+        result = {
+            kind: "analysis_batch",
+            ...analysisBatchData(saved.next, {
+                digest: saved.checkpoint.capturedDigest,
+            }),
+        };
+    return {
+        kind: "completed",
+        worker: "chats",
+        receipt: operationKey(call.intent.operationId),
+        result: JSON.stringify(result),
+    };
+}

package/dist/src/daemon/chats-question.d.ts

@@ -0,0 +1,15 @@
+import type { AdapterOutcome, DeliveryIntent } from "../broker/actor/delivery-intents.ts";
+import type { Fields } from "../protocol.ts";
+import { type analysisSaveInput } from "../chats/analysis-input.ts";
+interface QuestionSettings {
+    readonly runtimeDirectory: string;
+    readonly now?: () => string;
+}
+interface QuestionSave {
+    readonly intent: DeliveryIntent;
+    readonly mode: "deliver" | "reconcile";
+    readonly input: ReturnType<typeof analysisSaveInput>;
+    readonly payload: Fields;
+}
+export declare function saveQuestion(settings: QuestionSettings, call: QuestionSave): Promise<AdapterOutcome>;
+export {};

package/dist/src/daemon/chats-question.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { validateAnalysis } from "../chats/analysis.js";
+import { analysisEvidence, } from "../chats/analysis-input.js";
+import { mergeAnalysisBatch } from "../chats/analysis-merge.js";
+import { boundAnalysisBatch } from "./chats-batch-binding.js";
+import { analysisDirectory, inspectAnalysisDraft, saveAnalysisDraft, } from "./chats-files.js";
+import { operationKey } from "./operation-journal.js";
+import { storedAnalysisDraft } from "./chats-follow-up.js";
+async function validateQuestion(directory, call) {
+    const { input, payload, intent } = call;
+    if (!("batch" in payload))
+        return validateAnalysis(input.candidate, analysisEvidence(input.snapshot));
+    const bound = await boundAnalysisBatch(directory, {
+        runId: intent.runId,
+        importId: input.snapshot.importId,
+        snapshot: "snapshot" in payload ? input.snapshot : undefined,
+        batch: payload["batch"],
+    });
+    return mergeAnalysisBatch({
+        previousResult: bound.previous.result,
+        candidate: input.candidate,
+        evidence: analysisEvidence(bound.snapshot),
+        nextRecordIndex: bound.batch.nextRecordIndex,
+    });
+}
+function questionDraft(call) {
+    const { cycleId, snapshot, reply } = call.input;
+    return {
+        runId: call.intent.runId,
+        cycleId,
+        operationId: call.intent.operationId,
+        inputDigest: call.intent.inputDigest,
+        snapshotDigest: createHash("sha256")
+            .update(JSON.stringify(snapshot))
+            .digest("hex"),
+        reply,
+        ...("batch" in call.payload ? { batch: call.payload["batch"] } : {}),
+    };
+}
+async function additionalBatchQuestion(directory, call) {
+    const earlier = await storedAnalysisDraft(directory, call);
+    return (earlier !== undefined &&
+        "batch" in call.payload &&
+        earlier.operationId !== call.intent.operationId);
+}
+export async function saveQuestion(settings, call) {
+    try {
+        const { cycleId, snapshot } = call.input;
+        const directory = await analysisDirectory(settings.runtimeDirectory, snapshot.importId);
+        if (await additionalBatchQuestion(directory, call))
+            return {
+                kind: "failed",
+                reason: "analysis-question-limit",
+                result: JSON.stringify({
+                    kind: "blocked",
+                    codes: ["analysis-question-limit"],
+                }),
+            };
+        const validation = await validateQuestion(directory, call);
+        if (!validation.accepted)
+            return {
+                kind: "failed",
+                reason: validation.codes[0] ?? "analysis-input-refused",
+                result: JSON.stringify({ kind: "blocked", codes: validation.codes }),
+            };
+        const question = validation.result.openQuestion;
+        if (question === undefined)
+            throw new Error("analysis-input-refused");
+        const draft = questionDraft(call);
+        const metadata = call.mode === "reconcile"
+            ? await inspectAnalysisDraft(directory, draft)
+            : await saveAnalysisDraft(directory, {
+                input: draft,
+                now: settings.now ?? (() => new Date().toISOString()),
+            });
+        if (metadata === undefined)
+            return { kind: "absent" };
+        return {
+            kind: "completed",
+            worker: "chats",
+            receipt: operationKey(call.intent.operationId),
+            result: JSON.stringify({
+                kind: "analysis_draft",
+                cycleId,
+                ...metadata,
+                question,
+            }),
+        };
+    }
+    catch {
+        throw new Error("analysis-output-failed");
+    }
+}

package/dist/src/daemon/chats-worker.d.ts

@@ -0,0 +1,13 @@
+import type { AdapterOutcome, DeliveryIntent } from "../broker/actor/delivery-intents.ts";
+import type { EffectDelivery } from "./delivery-router.ts";
+export interface ChatsWorkerSettings {
+    readonly runtimeDirectory: string;
+    readonly document: (digest: string) => Promise<string | undefined>;
+    readonly workflowId: (runId: string) => Promise<string | undefined>;
+    readonly now?: () => string;
+}
+export interface ChatsWorker extends EffectDelivery {
+    readonly deliver: (intent: DeliveryIntent, signal: AbortSignal) => Promise<AdapterOutcome>;
+    readonly close: () => Promise<void>;
+}
+export declare function chatsWorker(settings: ChatsWorkerSettings): ChatsWorker;