@markstanden/opencode-test-container 0.0.0-stage → 0.1.1

package/dist/campaign/ledger.d.ts

@@ -0,0 +1,64 @@
+/** The finite ledger event names the lifecycle understands. */
+export declare const LEDGER_EVENTS: readonly ["trial-start", "trial-end", "primary-check", "assessment", "judge-attempt", "judge-selection", "close"];
+/** One ledger event name. */
+export type LedgerEventName = (typeof LEDGER_EVENTS)[number];
+/** An append-only lifecycle event. */
+export interface LedgerEvent {
+    /** The schema version value. */
+    schemaVersion: 1;
+    /** The event value. */
+    event: LedgerEventName;
+    /** The at value. */
+    at: string;
+    /** The campaign id value. */
+    campaignId: string;
+    [field: string]: unknown;
+}
+/** The readable ledger state: absence, open, closed or malformed. */
+export interface LedgerRead {
+    /** The state value. */
+    state: "absent" | "open" | "closed" | "malformed";
+    /** The events value. */
+    events: LedgerEvent[];
+    /** The problems value. */
+    problems: string[];
+    /** The closed at value. */
+    closedAt: string | null;
+}
+/** Path of the append-only attempts ledger. */
+export declare function ledgerPath(root: string): string;
+/**
+ * Parse ledger text without trusting it. Missing is an explicit state, and a
+ * malformed line poisons the ledger: no later event is credited.
+ * @param text The exact ledger bytes, or undefined when absent.
+ * @returns The parse result.
+ */
+export declare function parseLedger(text: string | undefined): LedgerRead;
+/**
+ * Read the ledger from a campaign root.
+ * @param root The campaign root.
+ * @returns The parse result.
+ */
+export declare function readLedger(root: string): LedgerRead;
+/**
+ * Append one event. The caller owns the decision that the ledger is open;
+ * this helper only writes a complete line.
+ * @param root The campaign root.
+ * @param event The event without the stamp.
+ * @param at The event time; defaults to now.
+ * @returns The written event.
+ */
+export declare function appendLedgerEvent(root: string, event: {
+    event: LedgerEventName;
+    campaignId: string;
+} & Record<string, unknown>, at?: string): LedgerEvent;
+/** Count the trial launches recorded in a ledger. */
+export declare function trialStarts(events: readonly LedgerEvent[]): LedgerEvent[];
+/** Count the durable assessments recorded in a ledger. */
+export declare function assessmentEvents(events: readonly LedgerEvent[]): LedgerEvent[];
+/** The slot ids that have started, in order. */
+export declare function startedSlots(events: readonly LedgerEvent[]): string[];
+/** Why a launch is refused by ledger/budget state, or null when permitted. */
+export declare function launchRefusal(read: LedgerRead, budget: {
+    trials: number;
+}): string | null;

package/dist/campaign/ledger.js

@@ -0,0 +1,149 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isRecord } from "../contracts/validate.js";
+/** The finite ledger event names the lifecycle understands. */
+export const LEDGER_EVENTS = [
+    "trial-start",
+    "trial-end",
+    "primary-check",
+    "assessment",
+    "judge-attempt",
+    "judge-selection",
+    "close",
+];
+/** Path of the append-only attempts ledger. */
+export function ledgerPath(root) {
+    return join(root, "evidence", "ATTEMPTS.jsonl");
+}
+/** Whether a value names a known event. */
+function isEventName(value) {
+    return (typeof value === "string" &&
+        LEDGER_EVENTS.includes(value));
+}
+/** Parse one non-blank ledger line into an event, or a problem. */
+function parseEventLine(line, index) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, problem: `line ${index + 1} is not JSON` };
+    }
+    if (!isRecord(parsed)) {
+        return { ok: false, problem: `line ${index + 1} is not an object` };
+    }
+    if (parsed.schemaVersion !== 1) {
+        return {
+            ok: false,
+            problem: `line ${index + 1} has an unsupported schemaVersion`,
+        };
+    }
+    if (!isEventName(parsed.event)) {
+        return { ok: false, problem: `line ${index + 1} has an unknown event` };
+    }
+    if (typeof parsed.at !== "string" ||
+        typeof parsed.campaignId !== "string") {
+        return {
+            ok: false,
+            problem: `line ${index + 1} lacks at/campaignId`,
+        };
+    }
+    return { ok: true, event: parsed };
+}
+/**
+ * Parse ledger text without trusting it. Missing is an explicit state, and a
+ * malformed line poisons the ledger: no later event is credited.
+ * @param text The exact ledger bytes, or undefined when absent.
+ * @returns The parse result.
+ */
+export function parseLedger(text) {
+    if (text === undefined) {
+        return { state: "absent", events: [], problems: [], closedAt: null };
+    }
+    const events = [];
+    const problems = [];
+    for (const [index, line] of text.split("\n").entries()) {
+        if (line.trim() === "")
+            continue;
+        const parsed = parseEventLine(line, index);
+        if (parsed.ok)
+            events.push(parsed.event);
+        else
+            problems.push(parsed.problem);
+    }
+    if (problems.length > 0) {
+        return { state: "malformed", events, problems, closedAt: null };
+    }
+    const closure = events.filter((event) => event.event === "close").at(-1);
+    return {
+        state: closure === undefined ? "open" : "closed",
+        events,
+        problems: [],
+        closedAt: closure?.at ?? null,
+    };
+}
+/**
+ * Read the ledger from a campaign root.
+ * @param root The campaign root.
+ * @returns The parse result.
+ */
+export function readLedger(root) {
+    const path = ledgerPath(root);
+    if (!existsSync(path))
+        return parseLedger(undefined);
+    try {
+        return parseLedger(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        return {
+            state: "malformed",
+            events: [],
+            problems: [
+                `ledger is unreadable: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+            closedAt: null,
+        };
+    }
+}
+/**
+ * Append one event. The caller owns the decision that the ledger is open;
+ * this helper only writes a complete line.
+ * @param root The campaign root.
+ * @param event The event without the stamp.
+ * @param at The event time; defaults to now.
+ * @returns The written event.
+ */
+export function appendLedgerEvent(root, event, at = new Date().toISOString()) {
+    const path = ledgerPath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    const written = { schemaVersion: 1, ...event, at };
+    appendFileSync(path, `${JSON.stringify(written)}\n`, "utf8");
+    return written;
+}
+/** Count the trial launches recorded in a ledger. */
+export function trialStarts(events) {
+    return events.filter((event) => event.event === "trial-start");
+}
+/** Count the durable assessments recorded in a ledger. */
+export function assessmentEvents(events) {
+    return events.filter((event) => event.event === "assessment");
+}
+/** The slot ids that have started, in order. */
+export function startedSlots(events) {
+    return trialStarts(events)
+        .map((event) => typeof event.slotId === "string" ? event.slotId : null)
+        .filter((slot) => slot !== null);
+}
+/** Why a launch is refused by ledger/budget state, or null when permitted. */
+export function launchRefusal(read, budget) {
+    if (read.state === "malformed") {
+        return `attempt ledger is malformed: ${read.problems.join("; ")}`;
+    }
+    if (read.state === "closed") {
+        return "campaign is closed; no further dispatch is permitted";
+    }
+    if (trialStarts(read.events).length >= budget.trials) {
+        return `trial budget exhausted (${budget.trials})`;
+    }
+    return null;
+}

package/dist/campaign/prepare.d.ts

@@ -0,0 +1,129 @@
+import type { Campaign, CampaignBundle, Suite } from "../contracts/types.ts";
+import { type Inventory } from "./inventory.ts";
+import { type ToolIdentity } from "../contracts/version.ts";
+/** A staged arm: every source path is now a root-relative payload. */
+export interface StagedArm {
+    /** The arm id value. */
+    armId: string;
+    /** The skills value. */
+    skills: Array<{
+        id: string;
+        path: string;
+    }>;
+    /** The plugins value. */
+    plugins: Array<{
+        id: string;
+        path: string;
+        options?: unknown;
+    }>;
+    /** The instructions value. */
+    instructions: Array<{
+        id: string;
+        path: string;
+        as: string;
+    }>;
+    /** The inventory value. */
+    inventory: Inventory;
+}
+/** One prepared case: prompt and pristine workspace only. */
+export interface PreparedCase {
+    /** The case id value. */
+    caseId: string;
+    /** The prompt sha256 value. */
+    promptSha256: string;
+    /** The workspace value. */
+    workspace: Inventory;
+    /** The staged product primary check, when the case declares one. */
+    primaryCheck?: {
+        id: string;
+        /** Root-relative staged directory. */
+        directory: string;
+        script: string;
+        timeoutMs: number;
+        inventory: Inventory;
+    };
+}
+/** The immutable record of everything preparation staged. */
+export interface PreparedManifest {
+    /** The schema version value. */
+    schemaVersion: 1;
+    /** The campaign id value. */
+    campaignId: string;
+    /** The suite id value. */
+    suiteId: string;
+    /** The campaign sha256 value. */
+    campaignSha256: string;
+    /** The suite sha256 value. */
+    suiteSha256: string;
+    /** The suite canonical sha256 value. */
+    suiteCanonicalSha256: string;
+    /** The schedule sha256 value. */
+    scheduleSha256: string;
+    /** The subjects sha256 value. */
+    subjectsSha256: string;
+    /** The workspaces sha256 value. */
+    workspacesSha256: string;
+    /** The prompts sha256 value. */
+    promptsSha256: string;
+    /** The product primary-check payloads sha256; empty object when none. */
+    primaryChecksSha256: string;
+    /** The artefact that prepared this manifest. */
+    tool: ToolIdentity;
+    /** The suite value. */
+    suite: Suite;
+    /** The campaign value. */
+    campaign: Campaign;
+    /** The subjects value. */
+    subjects: StagedArm[];
+    /** The cases value. */
+    cases: PreparedCase[];
+}
+/** The staging result, or the problems that prevented it. */
+export type PrepareResult = {
+    ok: true;
+    root: string;
+    manifest: PreparedManifest;
+} | {
+    ok: false;
+    problems: string[];
+};
+/**
+ * A campaign with source paths erased: identities are staged content, not the
+ * developer's checkout paths.
+ * @param bundle The validated campaign and suite.
+ * @returns The normalised campaign stored in the manifest.
+ */
+export declare function normaliseCampaign(bundle: CampaignBundle): Campaign;
+/** The default plugin members staged for the runtime. */
+export declare const DEFAULT_PLUGIN_INCLUDE: readonly ["package.json", "package-lock.json", "src", "dist", "node_modules", "CONVENTION.md", "README.md", "LICENSE"];
+/**
+ * Validate a campaign, then stage an immutable root: suite, prompts, pristine
+ * workspaces and subject payloads. Truth never enters a workspace.
+ * @param campaignPath The campaign document.
+ * @param root The fresh campaign root.
+ * @returns The prepared manifest, or actionable problems.
+ */
+export declare function prepareCampaign(campaignPath: string, root: string): PrepareResult;
+/** The hash of a prepared manifest's canonical content. */
+export declare function manifestSha256(manifest: PreparedManifest): string;
+/** Read the prepared manifest. */
+export declare function loadPreparedManifest(root: string): {
+    ok: true;
+    manifest: PreparedManifest;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Recheck every staged payload against the prepared manifest.
+ * @param root The campaign root.
+ * @param manifest The prepared manifest.
+ * @returns Differences; empty means the payload is intact.
+ */
+export declare function preparedDifferences(root: string, manifest: PreparedManifest): string[];
+/** The canonical text of a prepared manifest, for receipts and displays. */
+export declare function manifestText(manifest: PreparedManifest): string;
+/** A human-readable staging summary. */
+export declare function prepareSummary(manifest: PreparedManifest): string;
+/** A path's basename, used in diagnostics without exposing an absolute path. */
+export declare function displayPath(path: string): string;