cueline 0.2.1 → 0.3.0

package/dist/src/diagnostics/offline-self-test.js

@@ -0,0 +1,163 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { runCueLine } from "../api.js";
+import { verifyCueLineRun } from "../api-run-verification.js";
+import { CueLineError } from "../core/errors.js";
+import { CUELINE_VERSION } from "../version.js";
+const EMPTY_CHECKS = {
+    controllerRounds: 0,
+    completedJobs: 0,
+    finalDelivery: false,
+    durableRunVerification: false,
+};
+function controlReply(input, command) {
+    return {
+        text: `<CueLineControl>${JSON.stringify({
+            protocol: "cueline/0.1",
+            run_id: input.runId,
+            round: input.round,
+            request_id: input.requestId,
+            ...command,
+        })}</CueLineControl>`,
+        conversationUrl: "https://chatgpt.com/c/cueline-offline-self-test",
+        model: {
+            provider: "chatgpt",
+            selectedLabel: "Pro",
+            responseModelSlug: "gpt-5-6-pro",
+            source: "composer_and_response",
+        },
+    };
+}
+class OfflineController {
+    rounds = 0;
+    async sendTurn(input) {
+        this.rounds += 1;
+        if (this.rounds === 1) {
+            if (!input.prompt.includes("offline [node-offline-self-test]")) {
+                throw new CueLineError("SELF_TEST_ROUTING_PROMPT_MISSING", "The controller prompt did not expose the isolated offline lane.");
+            }
+            return controlReply(input, {
+                action: "dispatch",
+                jobs: [
+                    {
+                        job_key: "offline-worker",
+                        lane: "offline",
+                        mode: "advise",
+                        task: "CUELINE_OFFLINE_WORKER_OK",
+                        required: true,
+                    },
+                ],
+            });
+        }
+        if (this.rounds === 2) {
+            if (!input.prompt.includes("WORKER:CUELINE_OFFLINE_WORKER_OK")) {
+                throw new CueLineError("SELF_TEST_WORKER_EVIDENCE_MISSING", "The controller did not receive the isolated worker evidence.");
+            }
+            return controlReply(input, {
+                action: "complete",
+                final_delivery_text: "CUELINE_OFFLINE_SELF_TEST_OK",
+            });
+        }
+        throw new CueLineError("SELF_TEST_CONTROLLER_ROUNDS_EXCEEDED", "The isolated controller requested an unexpected extra round.");
+    }
+}
+function failedReport(code, message) {
+    return {
+        schema: "cueline-offline-self-test/1",
+        version: CUELINE_VERSION,
+        status: "failed",
+        offline: true,
+        checks: { ...EMPTY_CHECKS },
+        findings: [{ code, message }],
+    };
+}
+/**
+ * Exercises the public controller loop with only an in-memory controller and
+ * the current Node executable. All durable state lives below two fresh temp
+ * directories and is removed before this function returns.
+ */
+export async function runOfflineSelfTest(environment = process.env) {
+    if (environment.CUELINE_DEPTH !== undefined) {
+        return failedReport("NESTED_ROUTING_REJECTED", "Offline self-test cannot run from inside another CueLine execution.");
+    }
+    let home;
+    let workspace;
+    try {
+        home = await mkdtemp(path.join(tmpdir(), "cueline-offline-self-test-home-"));
+        workspace = await mkdtemp(path.join(tmpdir(), "cueline-offline-self-test-workspace-"));
+        const controller = new OfflineController();
+        const routingConfig = {
+            version: 1,
+            lanes: {
+                offline: {
+                    enabled: true,
+                    candidates: [
+                        {
+                            id: "node-offline-self-test",
+                            argv: [
+                                process.execPath,
+                                "-e",
+                                "process.stdin.setEncoding('utf8'); let data=''; process.stdin.on('data', chunk => data += chunk); process.stdin.on('end', () => process.stdout.write('WORKER:' + data));",
+                            ],
+                            task_input: "stdin",
+                        },
+                    ],
+                },
+            },
+        };
+        const runId = `run_offline_self_test_${process.pid}_${Date.now()}`;
+        const result = await runCueLine({
+            executor: "process",
+            allowProcessExecution: true,
+            request: "Verify the installed CueLine controller loop offline.",
+            runId,
+            home,
+            cwd: workspace,
+            browser: controller,
+            routingConfig,
+            environment: { ...environment },
+            maxRounds: 2,
+        });
+        const verification = await verifyCueLineRun(runId, { home, environment });
+        const completedJobs = Object.values(result.state.jobs).filter((job) => job.runtime?.phase === "completed").length;
+        const checks = {
+            controllerRounds: controller.rounds,
+            completedJobs,
+            finalDelivery: result.status === "complete" &&
+                result.finalDeliveryText === "CUELINE_OFFLINE_SELF_TEST_OK",
+            durableRunVerification: verification.outcome === "verified",
+        };
+        const ok = checks.controllerRounds === 2 &&
+            checks.completedJobs === 1 &&
+            checks.finalDelivery &&
+            checks.durableRunVerification;
+        return {
+            schema: "cueline-offline-self-test/1",
+            version: CUELINE_VERSION,
+            status: ok ? "ok" : "failed",
+            offline: true,
+            checks,
+            findings: ok
+                ? []
+                : [
+                    {
+                        code: "SELF_TEST_INVARIANT_FAILED",
+                        message: "One or more isolated controller-loop invariants did not pass.",
+                    },
+                ],
+        };
+    }
+    catch (error) {
+        return failedReport(error instanceof CueLineError ? error.code : "SELF_TEST_EXECUTION_FAILED", error instanceof CueLineError
+            ? error.message
+            : "The isolated controller loop did not complete.");
+    }
+    finally {
+        await Promise.all([
+            ...(home === undefined ? [] : [rm(home, { recursive: true, force: true })]),
+            ...(workspace === undefined ? [] : [rm(workspace, { recursive: true, force: true })]),
+        ]);
+    }
+}
+//# sourceMappingURL=offline-self-test.js.map

package/dist/src/diagnostics/offline-self-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-self-test.js","sourceRoot":"","sources":["../../../src/diagnostics/offline-self-test.ts"],"names":[],"mappings":"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"}

package/dist/src/diagnostics/secret-audit.d.ts

@@ -0,0 +1,25 @@
+import type { CueLineRuntimeOptions } from "../api-contracts.js";
+export declare const SECRET_AUDIT_PROTOCOL = "cueline-secret-audit/0.1";
+export type SecretFindingKind = "aws_access_key_id" | "github_token" | "slack_token" | "anthropic_api_key" | "openai_api_key" | "google_api_key" | "jwt" | "private_key_block" | "bearer_token" | "credential_assignment";
+export interface CueLineSecretFinding {
+    kind: SecretFindingKind;
+    sequence: number;
+    eventType: string;
+    path: string;
+    matchLength: number;
+    maskedPreview: string;
+}
+export interface CueLineSecretAuditReport {
+    protocol: typeof SECRET_AUDIT_PROTOCOL;
+    runId: string;
+    scannedEvents: number;
+    scannedFields: number;
+    findings: CueLineSecretFinding[];
+    clean: boolean;
+}
+/**
+ * Read-only sweep of a run's durable events for secret-shaped strings.
+ * The report never contains the matched bytes; each finding carries only
+ * the kind, location, length, and a four-character masked preview.
+ */
+export declare function auditCueLineRunSecrets(runId: string, options?: Pick<CueLineRuntimeOptions, "home" | "environment">): Promise<CueLineSecretAuditReport>;

package/dist/src/diagnostics/secret-audit.js

@@ -0,0 +1,114 @@
+import { CueLineError } from "../core/errors.js";
+import { runtimeEnvironment } from "../core/runtime.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { readAuthoritativeRunEvents } from "../state/store.js";
+export const SECRET_AUDIT_PROTOCOL = "cueline-secret-audit/0.1";
+// Order matters: the first matching detector claims the span, so the more
+// specific prefixes (sk-ant-) must run before their generic parents (sk-).
+const DETECTORS = [
+    { kind: "private_key_block", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+    { kind: "aws_access_key_id", pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+    {
+        kind: "github_token",
+        pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})\b/g,
+    },
+    { kind: "slack_token", pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+    { kind: "anthropic_api_key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+    { kind: "openai_api_key", pattern: /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}\b/g },
+    { kind: "google_api_key", pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    {
+        kind: "jwt",
+        pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g,
+    },
+    { kind: "bearer_token", pattern: /\bBearer +[A-Za-z0-9._~+/=-]{20,}\b/g },
+    {
+        kind: "credential_assignment",
+        pattern: /\b(?:api[_-]?key|secret|token|password|passwd|credential)s?\b['"]? *[:=] *['"]?[A-Za-z0-9_/+.=-]{12,}/gi,
+    },
+];
+function maskedPreview(match) {
+    const visible = match.slice(0, 4);
+    return `${visible}…(${match.length} chars)`;
+}
+function scanText(text, sequence, eventType, fieldPath, findings) {
+    const claimed = [];
+    for (const detector of DETECTORS) {
+        detector.pattern.lastIndex = 0;
+        for (const match of text.matchAll(detector.pattern)) {
+            const start = match.index;
+            const end = start + match[0].length;
+            if (claimed.some(([from, to]) => start < to && end > from))
+                continue;
+            claimed.push([start, end]);
+            findings.push({
+                kind: detector.kind,
+                sequence,
+                eventType,
+                path: fieldPath,
+                matchLength: match[0].length,
+                maskedPreview: maskedPreview(match[0]),
+            });
+        }
+    }
+}
+/**
+ * Path segments are part of the report, so a secret-shaped object key must
+ * never appear verbatim: mask it in the path and report the key itself.
+ */
+function safePathSegment(key) {
+    for (const detector of DETECTORS) {
+        detector.pattern.lastIndex = 0;
+        if (detector.pattern.test(key))
+            return maskedPreview(key);
+    }
+    return key;
+}
+function walk(value, sequence, eventType, fieldPath, findings, counter) {
+    if (typeof value === "string") {
+        counter.fields += 1;
+        scanText(value, sequence, eventType, fieldPath, findings);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            walk(item, sequence, eventType, `${fieldPath}[${index}]`, findings, counter);
+        });
+        return;
+    }
+    if (typeof value === "object" && value !== null) {
+        for (const [key, item] of Object.entries(value)) {
+            const segment = safePathSegment(key);
+            const childPath = `${fieldPath}.${segment}`;
+            scanText(key, sequence, eventType, childPath, findings);
+            walk(item, sequence, eventType, childPath, findings, counter);
+        }
+    }
+}
+/**
+ * Read-only sweep of a run's durable events for secret-shaped strings.
+ * The report never contains the matched bytes; each finding carries only
+ * the kind, location, length, and a four-character masked preview.
+ */
+export async function auditCueLineRunSecrets(runId, options = {}) {
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const events = await readAuthoritativeRunEvents(home, runId);
+    if (events.length === 0) {
+        throw new CueLineError("RUN_NOT_FOUND", `Run '${runId}' has no durable events; refusing to report a missing run as clean.`);
+    }
+    const findings = [];
+    const counter = { fields: 0 };
+    for (const event of events) {
+        walk(event.payload, event.sequence, event.type, "payload", findings, counter);
+    }
+    findings.sort((left, right) => left.sequence - right.sequence || left.path.localeCompare(right.path));
+    return {
+        protocol: SECRET_AUDIT_PROTOCOL,
+        runId,
+        scannedEvents: events.length,
+        scannedFields: counter.fields,
+        findings,
+        clean: findings.length === 0,
+    };
+}
+//# sourceMappingURL=secret-audit.js.map

package/dist/src/diagnostics/secret-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-audit.js","sourceRoot":"","sources":["../../../src/diagnostics/secret-audit.ts"],"names":[],"mappings":"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"}

package/dist/src/diagnostics/upgrade-preflight.d.ts

@@ -0,0 +1,41 @@
+export type UpgradePreflightSurface = "version" | "node" | "config" | "state" | "runs";
+export interface UpgradePreflightFinding {
+    code: string;
+    severity: "blocker" | "warning";
+    surface: UpgradePreflightSurface;
+    message: string;
+}
+export interface UpgradePreflightReport {
+    schema: "cueline-upgrade-preflight/1";
+    version: string;
+    targetVersion: string;
+    status: "ready" | "blocked";
+    checks: {
+        node: {
+            version: string;
+            requirement: ">=22";
+            ok: boolean;
+        };
+        config: {
+            path: string;
+            valid: boolean;
+        };
+        stateHome: {
+            path: string;
+            kind: "missing" | "directory" | "symlink" | "other";
+            private: boolean | null;
+        };
+        runs: {
+            total: number;
+            nonTerminal: number;
+            unreadable: number;
+        };
+    };
+    findings: UpgradePreflightFinding[];
+}
+export interface UpgradePreflightOptions {
+    targetVersion: string;
+    environment?: NodeJS.ProcessEnv;
+    nodeVersion?: string;
+}
+export declare function collectUpgradePreflight(options: UpgradePreflightOptions): Promise<UpgradePreflightReport>;

package/dist/src/diagnostics/upgrade-preflight.js

@@ -0,0 +1,182 @@
+import { lstat } from "node:fs/promises";
+import { listCueLineRuns, routingConfigPath } from "../api.js";
+import { loadRoutingConfig } from "../router/config-loader.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { CUELINE_VERSION } from "../version.js";
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function parseStableVersion(value) {
+    const match = STABLE_SEMVER.exec(value);
+    if (match === null)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+function compareVersion(left, right) {
+    return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function collectUpgradePreflight(options) {
+    const environment = options.environment ?? process.env;
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    const targetVersion = options.targetVersion;
+    const configPath = routingConfigPath(environment);
+    const home = defaultCueLineHome(environment);
+    const findings = [];
+    const current = parseStableVersion(CUELINE_VERSION);
+    const target = parseStableVersion(targetVersion);
+    if (target === undefined) {
+        findings.push({
+            code: "TARGET_VERSION_INVALID",
+            severity: "blocker",
+            surface: "version",
+            message: "Target version must be a stable semantic version such as 1.0.0.",
+        });
+    }
+    else if (current !== undefined && compareVersion(target, current) < 0) {
+        findings.push({
+            code: "TARGET_VERSION_DOWNGRADE",
+            severity: "blocker",
+            surface: "version",
+            message: "Upgrade preflight does not authorize a downgrade.",
+        });
+    }
+    else if (current !== undefined && compareVersion(target, current) === 0) {
+        findings.push({
+            code: "TARGET_VERSION_NOT_NEWER",
+            severity: "warning",
+            surface: "version",
+            message: "Target version is already installed.",
+        });
+    }
+    const nodeMajor = Number.parseInt(nodeVersion.split(".")[0] ?? "0", 10);
+    const nodeOk = Number.isSafeInteger(nodeMajor) && nodeMajor >= 22;
+    if (!nodeOk) {
+        findings.push({
+            code: "NODE_VERSION_UNSUPPORTED",
+            severity: "blocker",
+            surface: "node",
+            message: "Node.js 22 or newer is required before upgrading CueLine.",
+        });
+    }
+    let configValid = true;
+    try {
+        await loadRoutingConfig(configPath);
+    }
+    catch {
+        configValid = false;
+        findings.push({
+            code: "ROUTING_CONFIG_INVALID",
+            severity: "blocker",
+            surface: "config",
+            message: "The active routing configuration cannot be loaded by this version.",
+        });
+    }
+    let stateKind = "missing";
+    let statePrivate = null;
+    try {
+        const state = await lstat(home);
+        if (state.isSymbolicLink()) {
+            stateKind = "symlink";
+            findings.push({
+                code: "STATE_HOME_SYMLINK_UNSAFE",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home is a symbolic link; resolve it explicitly before upgrading.",
+            });
+        }
+        else if (state.isDirectory()) {
+            stateKind = "directory";
+            statePrivate = (state.mode & 0o077) === 0;
+            if (!statePrivate) {
+                findings.push({
+                    code: "STATE_HOME_PERMISSIONS_UNSAFE",
+                    severity: "blocker",
+                    surface: "state",
+                    message: "CueLine state home grants group or other permissions.",
+                });
+            }
+        }
+        else {
+            stateKind = "other";
+            findings.push({
+                code: "STATE_HOME_NOT_DIRECTORY",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home exists but is not a directory.",
+            });
+        }
+    }
+    catch (error) {
+        if (!isNotFound(error)) {
+            stateKind = "other";
+            findings.push({
+                code: "STATE_HOME_UNREADABLE",
+                severity: "blocker",
+                surface: "state",
+                message: "CueLine state home metadata cannot be read.",
+            });
+        }
+    }
+    let totalRuns = 0;
+    let nonTerminalRuns = 0;
+    let unreadableRuns = 0;
+    if (stateKind === "missing" || (stateKind === "directory" && statePrivate === true)) {
+        try {
+            const runs = await listCueLineRuns({ home, environment });
+            totalRuns = runs.length;
+            unreadableRuns = runs.filter((run) => !run.readable).length;
+            nonTerminalRuns = runs.filter((run) => run.readable &&
+                run.status !== "complete" &&
+                run.status !== "blocked" &&
+                run.status !== "cancelled").length;
+            if (unreadableRuns > 0) {
+                findings.push({
+                    code: "RUN_EVIDENCE_UNREADABLE",
+                    severity: "blocker",
+                    surface: "runs",
+                    message: "At least one persisted run cannot be read safely.",
+                });
+            }
+            if (nonTerminalRuns > 0) {
+                findings.push({
+                    code: "NON_TERMINAL_RUNS_PRESENT",
+                    severity: "blocker",
+                    surface: "runs",
+                    message: "Finish, block, or cancel every persisted run before upgrading.",
+                });
+            }
+        }
+        catch {
+            findings.push({
+                code: "RUN_STORE_UNREADABLE",
+                severity: "blocker",
+                surface: "runs",
+                message: "The persisted run store cannot be inspected safely.",
+            });
+        }
+    }
+    return {
+        schema: "cueline-upgrade-preflight/1",
+        version: CUELINE_VERSION,
+        targetVersion,
+        status: findings.some((finding) => finding.severity === "blocker")
+            ? "blocked"
+            : "ready",
+        checks: {
+            node: { version: nodeVersion, requirement: ">=22", ok: nodeOk },
+            config: { path: configPath, valid: configValid },
+            stateHome: { path: home, kind: stateKind, private: statePrivate },
+            runs: { total: totalRuns, nonTerminal: nonTerminalRuns, unreadable: unreadableRuns },
+        },
+        findings,
+    };
+}
+//# sourceMappingURL=upgrade-preflight.js.map

package/dist/src/diagnostics/upgrade-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-preflight.js","sourceRoot":"","sources":["../../../src/diagnostics/upgrade-preflight.ts"],"names":[],"mappings":"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"}

package/dist/src/observation/run-bundle.d.ts

@@ -0,0 +1,27 @@
+import type { CueLineRunVerificationReport, CueLineRuntimeOptions } from "../api-contracts.js";
+import { safeCueLineRunStatus } from "../cli/run-status-view.js";
+import { type CueLineRunDiagnosis } from "../diagnostics/run-doctor.js";
+import { type CueLineRunTimeline } from "./run-timeline.js";
+export declare const RUN_BUNDLE_PROTOCOL = "cueline-run-bundle/0.1";
+export interface CueLineRunSupportBundle {
+    schema: "cueline-run-export/1";
+    protocol: typeof RUN_BUNDLE_PROTOCOL;
+    version: string;
+    generatedAt: string;
+    runId: string;
+    status: ReturnType<typeof safeCueLineRunStatus>;
+    verification: CueLineRunVerificationReport;
+    diagnosis: CueLineRunDiagnosis;
+    timeline: CueLineRunTimeline;
+}
+export interface CueLineRunSupportBundleOptions extends Pick<CueLineRuntimeOptions, "home" | "environment" | "now"> {
+    timelineLimit?: number;
+}
+/**
+ * One sanitized JSON document for bug reports and cross-machine support:
+ * metadata-only status, content-free verification, doctor diagnosis, and the
+ * hashed audit timeline. Every section reuses an existing sanitized surface;
+ * this module adds no new evidence projection of its own, so it cannot leak
+ * more than the surfaces it composes.
+ */
+export declare function buildCueLineRunSupportBundle(runId: string, options?: CueLineRunSupportBundleOptions): Promise<CueLineRunSupportBundle>;

package/dist/src/observation/run-bundle.js

@@ -0,0 +1,55 @@
+import { loadCueLineRunStatus } from "../api-runtime-lifecycle.js";
+import { verifyCueLineRun } from "../api-run-verification.js";
+import { safeCueLineRunStatus } from "../cli/run-status-view.js";
+import { CueLineError } from "../core/errors.js";
+import { runtimeEnvironment } from "../core/runtime.js";
+import { diagnoseCueLineRunStatus, } from "../diagnostics/run-doctor.js";
+import { defaultCueLineHome } from "../state/paths.js";
+import { CUELINE_VERSION } from "../version.js";
+import { loadCueLineRunTimeline } from "./run-timeline.js";
+export const RUN_BUNDLE_PROTOCOL = "cueline-run-bundle/0.1";
+/**
+ * One sanitized JSON document for bug reports and cross-machine support:
+ * metadata-only status, content-free verification, doctor diagnosis, and the
+ * hashed audit timeline. Every section reuses an existing sanitized surface;
+ * this module adds no new evidence projection of its own, so it cannot leak
+ * more than the surfaces it composes.
+ */
+export async function buildCueLineRunSupportBundle(runId, options = {}) {
+    const timelineLimit = options.timelineLimit ?? 1000;
+    if (!Number.isSafeInteger(timelineLimit) ||
+        timelineLimit < 1 ||
+        timelineLimit > 1000) {
+        throw new CueLineError("RUN_BUNDLE_LIMIT_INVALID", "timelineLimit must be an integer between 1 and 1000.");
+    }
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const shared = {
+        home,
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+    };
+    const status = await loadCueLineRunStatus(runId, {
+        ...shared,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const [verification, timeline] = await Promise.all([
+        verifyCueLineRun(runId, {
+            ...shared,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        }),
+        loadCueLineRunTimeline(runId, { ...shared, limit: timelineLimit }),
+    ]);
+    const generatedAt = (options.now === undefined ? new Date() : options.now()).toISOString();
+    return {
+        schema: "cueline-run-export/1",
+        protocol: RUN_BUNDLE_PROTOCOL,
+        version: CUELINE_VERSION,
+        generatedAt,
+        runId,
+        status: safeCueLineRunStatus(status),
+        verification,
+        diagnosis: diagnoseCueLineRunStatus(status),
+        timeline,
+    };
+}
+//# sourceMappingURL=run-bundle.js.map

package/dist/src/observation/run-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-bundle.js","sourceRoot":"","sources":["../../../src/observation/run-bundle.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,wBAAwB,GAEzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAA2B,MAAM,mBAAmB,CAAC;AAEpF,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAmB5D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,KAAa,EACb,OAAO,GAAmC,EAAE;IAE5C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;IACpD,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC;QACpC,aAAa,GAAG,CAAC;QACjB,aAAa,GAAG,IAAI,EACpB,CAAC;QACD,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,sDAAsD,CACvD,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAAC;IAChE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG;QACb,IAAI;QACJ,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;KACnF,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,KAAK,EAAE;QAC/C,GAAG,MAAM;QACT,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC3D,CAAC,CAAC;IACH,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjD,gBAAgB,CAAC,KAAK,EAAE;YACtB,GAAG,MAAM;YACT,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;SAC3D,CAAC;QACF,sBAAsB,CAAC,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;KACnE,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3F,OAAO;QACL,MAAM,EAAE,sBAAsB;QAC9B,QAAQ,EAAE,mBAAmB;QAC7B,OAAO,EAAE,eAAe;QACxB,WAAW;QACX,KAAK;QACL,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC;QACpC,YAAY;QACZ,SAAS,EAAE,wBAAwB,CAAC,MAAM,CAAC;QAC3C,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const CUELINE_VERSION = "0.2.1";
+export declare const CUELINE_VERSION = "0.3.0";

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const CUELINE_VERSION = "0.2.1";
+export const CUELINE_VERSION = "0.3.0";
 //# sourceMappingURL=version.js.map