cloving 0.3.19 → 1.0.1

package/dist/src/broker/decision-upgrade.js

@@ -0,0 +1,12 @@
+import { persistDecisions } from "../storage/domain-changes.js";
+import { decidedVersion, upgradeSchema } from "../storage/domain-schema.js";
+import { decisionRows } from "./decision-restore.js";
+export async function upgradeDecisions(database, state) {
+    await database.transaction(async (connection) => {
+        await upgradeSchema(connection, decidedVersion);
+        await persistDecisions(connection, {
+            ...decisionRows(state),
+            documents: [],
+        });
+    });
+}

package/dist/src/broker/effect-restore.d.ts

@@ -0,0 +1,20 @@
+import { type EffectState, type Evidence, type RunBudget } from "../authority/operations.ts";
+import type { BudgetRow, EffectRows } from "../storage/effect-rows.ts";
+export interface EffectInput {
+    readonly capability: string;
+    readonly method: string;
+    readonly target: string;
+    readonly payload: string;
+}
+export declare function effectInputDigest(effect: EffectInput): string;
+export declare function effectRows(effects: EffectState, evidence: readonly Evidence[]): EffectRows;
+export declare function storedBudget(row: BudgetRow): RunBudget;
+export type StoredEffects = Pick<EffectRows, "budgets" | "operations" | "leases" | "stops"> & {
+    readonly holding: number;
+};
+export declare function storedEffects(rows: StoredEffects): EffectState;
+export declare function effectDigests(effects: EffectState): readonly string[];
+export declare function effectChecks(rows: EffectRows, replay: {
+    readonly effects: EffectState;
+    readonly evidence: readonly Evidence[];
+}): readonly (readonly [string, boolean])[];

package/dist/src/broker/effect-restore.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { isHolding, } from "../authority/operations.js";
+export function effectInputDigest(effect) {
+    const text = JSON.stringify([
+        "cloving-effect-input",
+        1,
+        effect.capability,
+        effect.method,
+        effect.target,
+        effect.payload,
+    ]);
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+function budgetRecord(budget) {
+    return {
+        runId: budget.runId,
+        effectLimit: budget.limit,
+        spent: budget.spent,
+        capabilities: JSON.stringify(budget.capabilities),
+        exhaustedSequence: budget.exhaustedSequence,
+    };
+}
+function byText(key) {
+    return (left, right) => (key(left) < key(right) ? -1 : 1);
+}
+export function effectRows(effects, evidence) {
+    return {
+        budgets: Object.values(effects.budgets)
+            .map(budgetRecord)
+            .sort(byText((row) => row.runId)),
+        operations: Object.values(effects.operations).sort((left, right) => left.requestedSequence - right.requestedSequence),
+        leases: Object.values(effects.leases).sort(byText((row) => row.resourceKey)),
+        evidence,
+        stops: Object.entries(effects.stops)
+            .map(([operationId, stop]) => ({ operationId, ...stop }))
+            .sort(byText((row) => row.operationId)),
+    };
+}
+const statuses = [
+    "refused",
+    "waiting",
+    "dispatch-pending",
+    "running",
+    "recovering",
+    "blocked",
+    "completed",
+    "failed",
+    "stopped",
+    "cancelled",
+];
+const leaseStates = ["held", "expired", "released"];
+function storedOperation(row) {
+    const status = statuses.find((candidate) => candidate === row.status);
+    if (status === undefined)
+        throw new Error("invalid-operation-row");
+    return { ...row, status };
+}
+function storedLease(row) {
+    const state = leaseStates.find((candidate) => candidate === row.state);
+    if (state === undefined)
+        throw new Error("invalid-lease-row");
+    return { ...row, state };
+}
+export function storedBudget(row) {
+    const capabilities = JSON.parse(row.capabilities);
+    if (!Array.isArray(capabilities))
+        throw new Error("invalid-budget-row");
+    return {
+        runId: row.runId,
+        limit: row.effectLimit,
+        spent: row.spent,
+        capabilities: capabilities.map(String),
+        exhaustedSequence: row.exhaustedSequence,
+    };
+}
+export function storedEffects(rows) {
+    return {
+        budgets: Object.fromEntries(rows.budgets.map((row) => [row.runId, storedBudget(row)])),
+        operations: Object.fromEntries(rows.operations.map((row) => [row.operationId, storedOperation(row)])),
+        leases: Object.fromEntries(rows.leases.map((row) => [row.resourceKey, storedLease(row)])),
+        holding: rows.holding,
+        stops: Object.fromEntries(rows.stops.map((row) => [
+            row.operationId,
+            { runId: row.runId, sequence: row.sequence },
+        ])),
+    };
+}
+export function effectDigests(effects) {
+    return Object.values(effects.operations)
+        .flatMap((operation) => [operation.payload, operation.result])
+        .filter((digest) => digest !== null);
+}
+export function effectChecks(rows, replay) {
+    const expected = effectRows(replay.effects, replay.evidence);
+    return [
+        ["budgets", isDeepStrictEqual(rows.budgets, expected.budgets)],
+        ["operations", isDeepStrictEqual(rows.operations, expected.operations)],
+        ["leases", isDeepStrictEqual(rows.leases, expected.leases)],
+        ["effect-evidence", isDeepStrictEqual(rows.evidence, expected.evidence)],
+        ["stopped-operations", isDeepStrictEqual(rows.stops, expected.stops)],
+        [
+            "holding",
+            rows.operations.filter(isHolding).length === replay.effects.holding,
+        ],
+        [
+            "input-digests",
+            rows.operations.every((row) => effectInputDigest(row) === row.inputDigest),
+        ],
+    ];
+}

package/dist/src/broker/effect-upgrade.d.ts

@@ -0,0 +1,3 @@
+import type { Database } from "solid-objects";
+import type { AuthorityState } from "../authority/reducer.ts";
+export declare function upgradeEffects(database: Database, state: AuthorityState): Promise<void>;

package/dist/src/broker/effect-upgrade.js

@@ -0,0 +1,9 @@
+import { currentVersion, upgradeSchema } from "../storage/domain-schema.js";
+import { persistEffects } from "../storage/effect-changes.js";
+import { effectRows } from "./effect-restore.js";
+export async function upgradeEffects(database, state) {
+    await database.transaction(async (connection) => {
+        await upgradeSchema(connection, currentVersion);
+        await persistEffects(connection, effectRows(state.effects, []));
+    });
+}

package/dist/src/broker/operation-digest.d.ts

@@ -0,0 +1 @@
+export declare function operationDigest(operationId: string): string;

package/dist/src/broker/operation-digest.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function operationDigest(operationId) {
+    return createHash("sha256").update(operationId).digest("hex");
+}

package/dist/src/broker/socket-address.d.ts

@@ -0,0 +1,9 @@
+export type SocketAddress = {
+    readonly kind: "address";
+    readonly path: string;
+} | {
+    readonly kind: "refused";
+    readonly reason: "runtime-path-too-long";
+    readonly detail: string;
+};
+export declare function socketAddress(path: string): SocketAddress;

package/dist/src/broker/socket-address.js

@@ -0,0 +1,14 @@
+import { relative } from "node:path";
+const maximumBytes = 103;
+export function socketAddress(path) {
+    const [shortest] = [path, relative(process.cwd(), path)]
+        .filter((candidate) => candidate.length > 0)
+        .sort((left, right) => Buffer.byteLength(left) - Buffer.byteLength(right));
+    if (shortest === undefined || Buffer.byteLength(shortest) > maximumBytes)
+        return {
+            kind: "refused",
+            reason: "runtime-path-too-long",
+            detail: `The socket path ${path} is longer than ${String(maximumBytes)} bytes.`,
+        };
+    return { kind: "address", path: shortest };
+}

package/dist/src/broker/workflow-pin.d.ts

@@ -0,0 +1,2 @@
+import type { ExecutionManifest } from "../workflow-admission.ts";
+export declare function workflowPin(manifest: ExecutionManifest): string;

package/dist/src/broker/workflow-pin.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+import { pinnedIdentity } from "../execution-pin.js";
+export function workflowPin(manifest) {
+    return `sha256:${createHash("sha256").update(pinnedIdentity(manifest)).digest("hex")}`;
+}

package/dist/src/chats/destination.d.ts

@@ -0,0 +1,4 @@
+import { type FileHandle } from "node:fs/promises";
+export declare function importDirectory(runtime: string, importId: string): Promise<string>;
+export declare function validateDestination(directory: string): Promise<void>;
+export declare function createPrivateFile(path: string): Promise<FileHandle>;

package/dist/src/chats/destination.js

@@ -0,0 +1,94 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+function missing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function canonical(path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+        return join(await canonical(dirname(path)), basename(path));
+    }
+    return realpath(path);
+}
+async function outsideRepository(path) {
+    let ancestor = path;
+    for (;;) {
+        try {
+            await lstat(join(ancestor, ".git"));
+            throw new Error("destination-refused");
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            return;
+        ancestor = parent;
+    }
+}
+async function privateDirectory(path) {
+    try {
+        const stats = await lstat(path);
+        if (!stats.isDirectory())
+            throw new Error("destination-refused");
+        return;
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+    await privateDirectory(dirname(path));
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            throw error;
+        if (!(await lstat(path)).isDirectory())
+            throw new Error("destination-refused", { cause: error });
+    }
+}
+export async function importDirectory(runtime, importId) {
+    if (process.platform !== "darwin")
+        throw new Error("destination-refused");
+    let chats;
+    try {
+        chats = await canonical(join(resolve(runtime), "chats"));
+        await outsideRepository(chats);
+    }
+    catch {
+        throw new Error("destination-refused");
+    }
+    await privateDirectory(chats);
+    await validateDestination(chats);
+    const directory = join(chats, importId);
+    await mkdir(directory, { mode: 0o700 });
+    await validateDestination(directory);
+    return directory;
+}
+export async function validateDestination(directory) {
+    if ((await realpath(directory)) !== directory)
+        throw new Error("destination-refused");
+    await outsideRepository(directory);
+}
+export async function createPrivateFile(path) {
+    await validateDestination(dirname(path));
+    const darwinNoFollowAny = 0x20000000;
+    try {
+        return await open(path, constants.O_WRONLY |
+            constants.O_CREAT |
+            constants.O_EXCL |
+            darwinNoFollowAny, 0o600);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ELOOP")
+            throw new Error("destination-refused", { cause: error });
+        throw error;
+    }
+}

package/dist/src/chats/import.d.ts

@@ -0,0 +1,13 @@
+export interface ImportRequest {
+    readonly paths: readonly string[];
+    readonly workingDirectory: string;
+    readonly runtimeDirectory: string | undefined;
+}
+export interface ImportSummary {
+    readonly code: "import-complete" | "import-partial" | "runtime-directory-unknown" | "destination-refused" | "output-failed";
+    readonly importId: string | null;
+    readonly included: number;
+    readonly refused: number;
+    readonly records: number;
+}
+export declare function importChats(request: ImportRequest): Promise<ImportSummary>;

package/dist/src/chats/import.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createPrivateFile, importDirectory, validateDestination, } from "./destination.js";
+import { readTranscript } from "./reader.js";
+async function writeImport(directory, request) {
+    const files = [];
+    const corpus = await createPrivateFile(join(directory, "corpus.jsonl"));
+    try {
+        for (const selected of request.paths) {
+            const result = await readTranscript(resolve(request.workingDirectory, selected));
+            files.push(result.coverage);
+            for (const record of result.records)
+                await corpus.writeFile(`${JSON.stringify(record)}\n`);
+        }
+    }
+    finally {
+        await corpus.close();
+    }
+    return files;
+}
+async function writeCoverage(directory, coverage) {
+    const manifest = join(directory, "coverage.json");
+    let created = false;
+    try {
+        const handle = await createPrivateFile(manifest);
+        created = true;
+        try {
+            await handle.writeFile(`${JSON.stringify(coverage, null, 2)}\n`);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (created) {
+            await validateDestination(directory);
+            await rm(manifest, { force: true });
+        }
+        throw error;
+    }
+}
+export async function importChats(request) {
+    const empty = { importId: null, included: 0, refused: 0, records: 0 };
+    if (request.runtimeDirectory === undefined)
+        return { ...empty, code: "runtime-directory-unknown" };
+    try {
+        const importId = randomUUID();
+        const directory = await importDirectory(resolve(request.workingDirectory, request.runtimeDirectory), importId);
+        const files = await writeImport(directory, request);
+        const included = files.filter((file) => file.status === "included").length;
+        const records = files.reduce((count, file) => count + file.recordCount, 0);
+        const refused = files.length - included;
+        await writeCoverage(directory, { schemaVersion: 1, importId, files });
+        return {
+            code: refused === 0 ? "import-complete" : "import-partial",
+            importId,
+            included,
+            refused,
+            records,
+        };
+    }
+    catch (error) {
+        return {
+            ...empty,
+            code: error instanceof Error && error.message === "destination-refused"
+                ? "destination-refused"
+                : "output-failed",
+        };
+    }
+}

package/dist/src/chats/normalize.d.ts

@@ -0,0 +1,20 @@
+export interface Omissions {
+    metadataRecords: number;
+    thinkingBlocks: number;
+}
+export interface MessageRecord {
+    readonly schemaVersion: 1;
+    readonly sourceId: string;
+    readonly role: "user" | "assistant";
+    readonly timestamp: string | null;
+    readonly sessionId: string | null;
+    readonly text: string;
+    readonly blocks: readonly Record<string, unknown>[];
+}
+export interface NormalizedTranscript {
+    readonly status: "included" | "unsupported";
+    readonly reason: string;
+    readonly records: readonly MessageRecord[];
+    readonly omissions: Omissions;
+}
+export declare function normalizeTranscript(text: string, digest: string): NormalizedTranscript;

package/dist/src/chats/normalize.js

@@ -0,0 +1,139 @@
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function supportedBlock(block) {
+    const type = block["type"];
+    if (type === "text" && typeof block["text"] === "string")
+        return { type, text: block["text"] };
+    if (type === "tool_use" &&
+        typeof block["id"] === "string" &&
+        typeof block["name"] === "string" &&
+        Object.hasOwn(block, "input")) {
+        return {
+            type,
+            id: block["id"],
+            name: block["name"],
+            input: block["input"],
+        };
+    }
+    if (type === "tool_result")
+        return toolResult(block);
+    throw new Error("unsupported-block");
+}
+function toolResult(block) {
+    if (typeof block["tool_use_id"] !== "string" ||
+        !Object.hasOwn(block, "content"))
+        throw new Error("unsupported-block");
+    if (Object.hasOwn(block, "is_error") &&
+        typeof block["is_error"] !== "boolean")
+        throw new Error("unsupported-block");
+    return {
+        type: "tool_result",
+        tool_use_id: block["tool_use_id"],
+        content: block["content"],
+        ...(Object.hasOwn(block, "is_error")
+            ? { is_error: block["is_error"] }
+            : {}),
+    };
+}
+function optionalText(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string")
+        throw new Error("unsupported-message");
+    return value;
+}
+function rawJsonApi(value) {
+    return "rawJSON" in value && typeof value.rawJSON === "function";
+}
+function preserveJson(...argumentsList) {
+    const [, value, context] = argumentsList;
+    if (typeof value !== "number")
+        return value;
+    if (!object(context) || typeof context["source"] !== "string")
+        throw new Error("unsupported-record");
+    if (JSON.stringify(value) === context["source"])
+        return value;
+    if (!rawJsonApi(JSON))
+        throw new Error("unsupported-record");
+    return JSON.rawJSON(context["source"]);
+}
+function blocks(content, omissions) {
+    if (typeof content === "string")
+        return [{ position: 0, type: "text", text: content }];
+    if (!Array.isArray(content))
+        throw new Error("unsupported-message");
+    return content.flatMap((block, position) => {
+        if (!object(block))
+            throw new Error("unsupported-block");
+        if (block["type"] === "thinking") {
+            omissions.thinkingBlocks++;
+            return [];
+        }
+        return [{ ...supportedBlock(block), position }];
+    });
+}
+function message(value, context) {
+    if (!object(value) || typeof value["type"] !== "string")
+        throw new Error("unsupported-record");
+    if (value["type"] !== "user" &&
+        value["type"] !== "assistant" &&
+        Object.hasOwn(value, "message"))
+        throw new Error("unsupported-message");
+    if (value["type"] !== "user" && value["type"] !== "assistant") {
+        context.omissions.metadataRecords++;
+        return null;
+    }
+    const envelope = value["message"];
+    if (!object(envelope) || envelope["role"] !== value["type"])
+        throw new Error("unsupported-message");
+    const normalized = blocks(envelope["content"], context.omissions);
+    return {
+        schemaVersion: 1,
+        sourceId: context.sourceId,
+        role: value["type"],
+        timestamp: optionalText(value["timestamp"]),
+        sessionId: optionalText(value["sessionId"]),
+        text: normalized
+            .filter((block) => block["type"] === "text")
+            .map((block) => block["text"])
+            .join("\n"),
+        blocks: normalized,
+    };
+}
+export function normalizeTranscript(text, digest) {
+    const omissions = { metadataRecords: 0, thinkingBlocks: 0 };
+    const records = [];
+    if (text === "")
+        return { status: "unsupported", reason: "empty-file", records, omissions };
+    let offset = 0;
+    const lines = text.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    try {
+        for (const line of lines) {
+            const parsed = JSON.parse(line, preserveJson);
+            const record = message(parsed, {
+                sourceId: `${digest}:${String(offset)}`,
+                omissions,
+            });
+            if (record !== null)
+                records.push(record);
+            offset += new TextEncoder().encode(line).length + 1;
+        }
+    }
+    catch (error) {
+        let reason = "unsupported-record";
+        if (error instanceof Error)
+            reason = error.message;
+        if (error instanceof SyntaxError)
+            reason = "invalid-json";
+        return {
+            status: "unsupported",
+            reason,
+            records: [],
+            omissions,
+        };
+    }
+    return { status: "included", reason: "supported", records, omissions };
+}

package/dist/src/chats/reader.d.ts

@@ -0,0 +1,15 @@
+import { type MessageRecord, type Omissions } from "./normalize.ts";
+export declare const transcriptLimit = 10485760;
+export interface SelectedTranscript {
+    readonly path: string;
+    readonly status: "included" | "unreadable" | "unsupported" | "too-large";
+    readonly reason: string;
+    readonly digest: string | null;
+    readonly recordCount: number;
+    readonly omissions: Omissions;
+}
+export interface ReadTranscript {
+    readonly coverage: SelectedTranscript;
+    readonly records: readonly MessageRecord[];
+}
+export declare function readTranscript(path: string): Promise<ReadTranscript>;

package/dist/src/chats/reader.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { normalizeTranscript, } from "./normalize.js";
+export const transcriptLimit = 10_485_760;
+function refused(path, reason) {
+    const status = reason === "source-unreadable" ? "unreadable" : "unsupported";
+    return {
+        coverage: {
+            path,
+            status: reason === "file-too-large" ? "too-large" : status,
+            reason,
+            digest: null,
+            recordCount: 0,
+            omissions: { metadataRecords: 0, thinkingBlocks: 0 },
+        },
+        records: [],
+    };
+}
+async function boundedBytes(handle) {
+    const stats = await handle.stat();
+    if (!stats.isFile())
+        return "nonregular-file";
+    if (stats.size > transcriptLimit)
+        return "file-too-large";
+    const chunks = [];
+    let total = 0;
+    while (total <= transcriptLimit) {
+        const buffer = Buffer.alloc(Math.min(65_536, transcriptLimit + 1 - total));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+        chunks.push(buffer.subarray(0, bytesRead));
+    }
+    if (total > transcriptLimit || (await handle.stat()).size > transcriptLimit)
+        return "file-too-large";
+    return Buffer.concat(chunks, total);
+}
+function normalizeBytes(path, bytes) {
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        const result = refused(path, "invalid-utf8");
+        return { ...result, coverage: { ...result.coverage, digest } };
+    }
+    const result = normalizeTranscript(text, digest);
+    return {
+        coverage: {
+            path,
+            status: result.status,
+            reason: result.reason,
+            digest,
+            recordCount: result.records.length,
+            omissions: result.omissions,
+        },
+        records: result.records,
+    };
+}
+export async function readTranscript(path) {
+    try {
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink())
+            return refused(path, "symbolic-link");
+        if (!stats.isFile())
+            return refused(path, "nonregular-file");
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        let bytes;
+        try {
+            bytes = await boundedBytes(handle);
+        }
+        finally {
+            await handle.close();
+        }
+        return typeof bytes === "string"
+            ? refused(path, bytes)
+            : normalizeBytes(path, bytes);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ELOOP")
+            return refused(path, "symbolic-link");
+        return refused(path, "source-unreadable");
+    }
+}