humanish 0.105.0 → 0.106.0

package/dist/run/run.d.ts

@@ -0,0 +1,103 @@
+import { renderObserver, type ObserverResult } from "../observer/render.js";
+import { type RunBundle } from "./bundle.js";
+import type { ExecutionOutcome } from "./judge.js";
+import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
+import { type RunLabProvenance, type RunStatusHandle } from "./status.js";
+interface StartRunOptions {
+    /** Project directory, in the form the route resolved it. */
+    cwd: string;
+    /** Caller-supplied id (`--run-id`, library `runId`); `mintRunId` runs when it is absent. */
+    runId?: string | undefined;
+    mintRunId: () => string;
+    mode: "dry-run" | "live";
+    lab?: RunLabProvenance | undefined;
+    /** review.md for the published bundle. */
+    renderReview: (bundle: RunBundle) => string;
+    /** Used by `FinishedRun.renderObserver`; `render` is the routes' `renderObserverFn` seam. */
+    observer?: {
+        open: boolean;
+        render?: typeof renderObserver | undefined;
+    };
+    /** Clock for `createdAt` and the latest pointer. */
+    now?: (() => number) | undefined;
+}
+interface Run {
+    readonly runId: string;
+    readonly createdAt: string;
+    readonly mode: "dry-run" | "live";
+    /** Routes write their evidence files through these and hand them to lanes. */
+    readonly paths: PreparedRunArtifactPaths;
+    /**
+     * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and
+     * observer/observer-data.json, plus the latest pointer until one pointer write has succeeded,
+     * so a live run is `latest` from its first snapshot and a later flush never takes the pointer
+     * back from a newer run. status.json stays running. Writes are serialized with each other and
+     * with `finish`; a rejected write reaches only its caller. Rejects before writing once `finish`
+     * was called or the scope closed, or when the bundle names another run or mode, so a late flush
+     * can never overwrite the final bundle. Routes that throttle snapshots own their timers.
+     */
+    writeSnapshot(bundle: RunBundle): Promise<void>;
+    /**
+     * The one final publication: run.json, then the status outcome, then review.json, review.md,
+     * events.ndjson, observer/observer-data.json, and last the latest pointer. The status goes
+     * after run.json so the index never gets ahead of the evidence, and the pointer goes last so
+     * `latest` never selects a run whose projections are incomplete. Rejects before writing on a
+     * second call, after the scope closed, or when the bundle names another run or mode. A
+     * rejection partway leaves the files written so far and issues no FinishedRun.
+     */
+    finish(bundle: RunBundle): Promise<FinishedRun>;
+}
+export interface RunScope {
+    /**
+     * Create `.humanish/runs/<id>` exclusively, begin status.json and wait for its first write, so
+     * a run that got past this point has a status record before any sandbox exists. An id whose
+     * directory exists is refused before any write. A scope starts at most one run.
+     */
+    startRun(options: StartRunOptions): Promise<{
+        ok: true;
+        run: Run;
+    } | RunIdInUse>;
+}
+interface ObserverTarget {
+    cwd: string;
+    open: boolean;
+    render: typeof renderObserver;
+}
+declare const issueKey: unique symbol;
+/**
+ * Proof that one run published its final bundle, and the only input automatic analysis accepts.
+ * A private field makes the type nominal, so no object literal satisfies it, `isIssued` checks
+ * that field at runtime, and the constructor refuses callers without the module-private key. This
+ * guards against accidental misuse; code in the same process can still forge one.
+ */
+export declare class FinishedRun {
+    #private;
+    readonly runId: string;
+    /** The paths created by startRun and validated at the start of `finish`. */
+    readonly paths: PreparedRunArtifactPaths;
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, status: RunStatusHandle);
+    static isIssued(value: unknown): value is FinishedRun;
+    /** Render the Observer for exactly these paths, never a directory re-resolved by name. */
+    renderObserver(): Promise<ObserverResult>;
+    /**
+     * Record the result's ok and execution outcome in status.json. A route calls it once, after the
+     * Observer render, with the values its result returns, so the two agree.
+     */
+    recordOutcome(result: {
+        ok: boolean;
+        execution: ExecutionOutcome;
+    }): Promise<void>;
+}
+/**
+ * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
+ * so the scope and its run admit no further calls, even through references `fn` leaked into
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
+ * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
+ */
+export declare function runScope<T>(fn: (scope: RunScope) => Promise<T>): Promise<{
+    result: T;
+    finished: FinishedRun | undefined;
+}>;
+export {};

package/dist/run/run.js

@@ -0,0 +1,199 @@
+// One run's lifetime on disk: its directory, its status record, its final publication, and the
+// token that lets the Observer and automatic analysis read it. Routes build bundles and write
+// their own evidence files; this module owns when the run starts, how it is published, and how it
+// is closed on every exit.
+import { buildObserverData } from "../observer/data.js";
+import { renderObserver } from "../observer/render.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD } from "./bundle.js";
+import {} from "./results.js";
+import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
+import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
+import { beginRunStatus, runStatusOutcome, } from "./status.js";
+/** An entry point called in a state that does not admit it. */
+class RunLifecycleError extends Error {
+    name = "RunLifecycleError";
+}
+const issueKey = Symbol("FinishedRun");
+/**
+ * Proof that one run published its final bundle, and the only input automatic analysis accepts.
+ * A private field makes the type nominal, so no object literal satisfies it, `isIssued` checks
+ * that field at runtime, and the constructor refuses callers without the module-private key. This
+ * guards against accidental misuse; code in the same process can still forge one.
+ */
+export class FinishedRun {
+    #observer;
+    #status;
+    runId;
+    /** The paths created by startRun and validated at the start of `finish`. */
+    paths;
+    constructor(key, runId, paths, observer, status) {
+        if (key !== issueKey)
+            throw new Error("Only Run.finish issues a FinishedRun.");
+        this.runId = runId;
+        this.paths = paths;
+        this.#observer = observer;
+        this.#status = status;
+    }
+    static isIssued(value) {
+        return typeof value === "object" && value !== null && #observer in value;
+    }
+    /** Render the Observer for exactly these paths, never a directory re-resolved by name. */
+    renderObserver() {
+        const target = this.#observer;
+        if (target === undefined) {
+            return Promise.reject(new RunLifecycleError("This run was started without an Observer."));
+        }
+        return target.render(target.cwd, this.runId, { open: target.open, expectedRun: this.paths });
+    }
+    /**
+     * Record the result's ok and execution outcome in status.json. A route calls it once, after the
+     * Observer render, with the values its result returns, so the two agree.
+     */
+    recordOutcome(result) {
+        return this.#status.settle(result);
+    }
+}
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/**
+ * Run `fn` as the lifetime of at most one run. When `fn` settles the scope closes synchronously,
+ * so the scope and its run admit no further calls, even through references `fn` leaked into
+ * timers or callbacks. It then waits for the calls it admitted and, unless the run finished,
+ * finishes status.json with no outcome. The close cannot replace `fn`'s exception: admitted calls
+ * are awaited settled and the status finish swallows its own write errors. `finished` is set only
+ * when `Run.finish` resolved inside the scope, so a refusal cannot hand analysis another run.
+ */
+export async function runScope(fn) {
+    let closed = false;
+    let started = false;
+    let status;
+    let finished;
+    const admitted = new Set();
+    const admit = (operation) => {
+        admitted.add(operation);
+        const forget = () => admitted.delete(operation);
+        void operation.then(forget, forget);
+        return operation;
+    };
+    const refuse = (message) => Promise.reject(new RunLifecycleError(message));
+    const startRun = (options) => {
+        if (closed)
+            return refuse("The run scope has closed.");
+        if (started)
+            return refuse("A run scope starts one run.");
+        started = true;
+        return admit((async () => {
+            const runId = options.runId ?? options.mintRunId();
+            const created = await createRunArtifactPaths(options.cwd, runId);
+            if (!created.ok)
+                return created;
+            status = beginRunStatus(created.paths, {
+                runId,
+                mode: options.mode,
+                ...(options.lab === undefined ? {} : { lab: options.lab }),
+            });
+            await status.started;
+            return { ok: true, run: openRun(options, runId, created.paths, status) };
+        })());
+    };
+    const openRun = (options, runId, paths, runStatus) => {
+        const now = options.now ?? Date.now;
+        const createdAt = new Date(now()).toISOString();
+        const observer = options.observer === undefined
+            ? undefined
+            : {
+                cwd: options.cwd,
+                open: options.observer.open,
+                render: options.observer.render ?? renderObserver,
+            };
+        let finishCalled = false;
+        let pointerWritten = false;
+        // One chain serializes every write. A rejection reaches only the caller of that write; the
+        // chain itself continues, so a failed snapshot never blocks the final publication.
+        let tail = Promise.resolve();
+        const enqueue = (write) => {
+            const written = tail.then(write);
+            tail = written.then(() => undefined, () => undefined);
+            return written;
+        };
+        const checkIdentity = (bundle) => bundle.runId !== runId || bundle.mode !== options.mode
+            ? "The bundle names another run or mode than this run."
+            : undefined;
+        const writePointer = async () => {
+            const pointer = {
+                schema: "humanish.latest-run.v1",
+                runId,
+                path: paths.relativeRunRoot,
+                updatedAt: new Date(now()).toISOString(),
+            };
+            await writePreparedRunLatestPointer(paths, json(pointer), "utf8");
+            pointerWritten = true;
+        };
+        /** run.json, then `afterBundle`, then the review and projections. */
+        const writeBundleFiles = async (bundle, afterBundle) => {
+            await validatePreparedRunArtifactPaths(paths);
+            const publicBundle = { ...bundle, cwd: PUBLIC_TARGET_CWD };
+            await writeContainedOutputFile(paths, RUN_BUNDLE_FILE, json(publicBundle), "utf8");
+            await afterBundle(publicBundle);
+            await writeContainedOutputFile(paths, "review.json", json(publicBundle.review), "utf8");
+            await writeContainedOutputFile(paths, "review.md", options.renderReview(publicBundle), "utf8");
+            const events = publicBundle.events.map((event) => JSON.stringify(event)).join("\n");
+            await writeContainedOutputFile(paths, "events.ndjson", `${events}\n`, "utf8");
+            await writeContainedOutputFile(paths, "observer/observer-data.json", json(buildObserverData(publicBundle)), "utf8");
+        };
+        const snapshot = async (bundle) => {
+            await writeBundleFiles(bundle, async () => { });
+            if (!pointerWritten)
+                await writePointer();
+        };
+        const publish = async (bundle) => {
+            await writeBundleFiles(bundle, (publicBundle) => runStatus.finish(runStatusOutcome(publicBundle)));
+            await writePointer();
+            return new FinishedRun(issueKey, runId, paths, observer, runStatus);
+        };
+        return {
+            runId,
+            createdAt,
+            mode: options.mode,
+            paths,
+            writeSnapshot(bundle) {
+                if (closed)
+                    return refuse("The run scope has closed.");
+                if (finishCalled)
+                    return refuse("Run.finish was called; no snapshot follows it.");
+                const mismatch = checkIdentity(bundle);
+                if (mismatch !== undefined)
+                    return refuse(mismatch);
+                return admit(enqueue(() => snapshot(bundle)));
+            },
+            finish(bundle) {
+                if (closed)
+                    return refuse("The run scope has closed.");
+                if (finishCalled)
+                    return refuse("Run.finish admits one call.");
+                const mismatch = checkIdentity(bundle);
+                if (mismatch !== undefined)
+                    return refuse(mismatch);
+                finishCalled = true;
+                return admit(enqueue(() => publish(bundle)).then((issued) => {
+                    finished = issued;
+                    return issued;
+                }));
+            },
+        };
+    };
+    let outcome;
+    try {
+        outcome = { result: await fn({ startRun }) };
+    }
+    finally {
+        closed = true;
+        try {
+            await Promise.allSettled(admitted);
+        }
+        finally {
+            if (finished === undefined)
+                await status?.finish();
+        }
+    }
+    return { result: outcome.result, finished };
+}

package/dist/run/sandbox-receipts.d.ts

@@ -0,0 +1,31 @@
+import { type PreparedOutputRoot } from "./contained-output.js";
+export declare const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
+/** The providers humanish allocates sandboxes from. Reclaim dispatches on this id. */
+export type SandboxProviderId = "e2b";
+export interface SandboxReceipt {
+    at: string;
+    /** The lane/role/subject label the sandbox belongs to (public-safe token). */
+    laneId: string;
+    /** Who allocated the sandbox. Receipts written before this field existed have none. */
+    provider?: SandboxProviderId;
+    sandboxId: string;
+    /** The create-time sandbox TTL (ms), when known — how long the server-side backstop runs. */
+    timeoutMs?: number;
+}
+/**
+ * A receipt read back from disk. An absent provider reads as "e2b", the only provider before the
+ * field existed. A receipt written by a newer humanish may name a provider this version does not
+ * know, so the type keeps the raw string for reclaim to report.
+ */
+export interface ParsedSandboxReceipt extends Omit<SandboxReceipt, "provider"> {
+    provider: string;
+}
+/**
+ * Append one receipt. Best-effort BY DESIGN: the receipt exists to protect the run, so a failed
+ * receipt write must never fail the lane — the only cost of a miss is that `reclaim` cannot see
+ * this id and the TTL backstop covers it instead. Containment is the same prepare step every
+ * artifact write uses; append (not atomic-replace) keeps racing lanes' receipts intact.
+ */
+export declare function appendSandboxReceipt(root: PreparedOutputRoot, receipt: SandboxReceipt): Promise<void>;
+/** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
+export declare function parseSandboxReceipts(text: string): ParsedSandboxReceipt[];

package/dist/run/sandbox-receipts.js

@@ -0,0 +1,49 @@
+// Every created sandbox id is journaled to the run dir the moment create returns, before any work
+// happens in it. The lane loop lives in the caller's local process, so a sleeping laptop, crash or
+// kill loses every in-memory id; this append-only file keeps them for `humanish reclaim`.
+import { appendFile } from "node:fs/promises";
+import { prepareContainedOutputFile } from "./contained-output.js";
+export const SANDBOX_RECEIPTS_ARTIFACT = "sandbox-receipts.ndjson";
+/**
+ * Append one receipt. Best-effort BY DESIGN: the receipt exists to protect the run, so a failed
+ * receipt write must never fail the lane — the only cost of a miss is that `reclaim` cannot see
+ * this id and the TTL backstop covers it instead. Containment is the same prepare step every
+ * artifact write uses; append (not atomic-replace) keeps racing lanes' receipts intact.
+ */
+export async function appendSandboxReceipt(root, receipt) {
+    try {
+        const filePath = await prepareContainedOutputFile(root, SANDBOX_RECEIPTS_ARTIFACT);
+        await appendFile(filePath, `${JSON.stringify(receipt)}\n`, "utf8");
+    }
+    catch {
+        // Swallowed on purpose — see the contract above.
+    }
+}
+/** Parse a receipts file leniently: a torn final line (crash mid-append) drops, valid lines keep. */
+export function parseSandboxReceipts(text) {
+    const receipts = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed.sandboxId === "string" &&
+                parsed.sandboxId.length > 0 &&
+                typeof parsed.laneId === "string" &&
+                (parsed.provider === undefined || typeof parsed.provider === "string")) {
+                receipts.push({
+                    at: typeof parsed.at === "string" ? parsed.at : "",
+                    laneId: parsed.laneId,
+                    provider: parsed.provider ?? "e2b",
+                    sandboxId: parsed.sandboxId,
+                    ...(typeof parsed.timeoutMs === "number" ? { timeoutMs: parsed.timeoutMs } : {}),
+                });
+            }
+        }
+        catch {
+            // torn line — skip
+        }
+    }
+    return receipts;
+}

package/dist/run/shared-world-evidence.d.ts

@@ -0,0 +1,220 @@
+import type { ParticipantIds } from "./participant-records.js";
+export declare const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
+/** The ONE shared service-plane provenance for a shared-world run (#164): single commit + a
+ *  seed-recipe digest + the provisioned env NAMES (values never). */
+export interface SharedWorldPlane {
+    /** The cloned commit SHA of the shared plane (when the clone resolved one). */
+    commit?: string;
+    /** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity
+     *  (not the runtime state). Pins "same seed recipe" across bundles. */
+    seedDigest: string;
+    /** Declared env NAMES provisioned for the shared plane (values never surface). */
+    envNames: string[];
+    /**
+     * CONCURRENT route only (#164 phase 2): sha256-16 of the harness-minted `getHost` URL's ORIGIN
+     * (the first-class provisioned-subject target every actor drove — invariant 2). A DIGEST, not the
+     * raw URL: a getHost URL embeds the (live) sandbox id and matches the publish-safety e2b-URL
+     * redaction, so — like the stream URL and like sandbox ids — it never lands raw in a published
+     * bundle (the raw tokenless URL is surfaced only on the ephemeral lab result). The orchestrator
+     * confirms the URL is TOKENLESS (no authKey — invariant 1) before digesting. verify proves every
+     * actor drove this host by digest equality. Absent on the sequential route.
+     */
+    hostDigest?: string;
+    /**
+     * CONCURRENT route only: the author's REQUIRED attestation that the subject behind the
+     * internet-reachable getHost URL is synthetic seeded data (FIX-3). This is author-trust + a
+     * provenance gate, NOT a no-real-data guarantee. Verify fails closed if absent on the concurrent route.
+     *
+     * FORBIDDEN on the external-public plane class: claiming synthetic on a real public site the
+     * harness neither provisioned nor exposed would be a lie (verify asserts it ABSENT there).
+     */
+    exposure?: "synthetic";
+    /**
+     * EXTERNAL-PUBLIC plane class only (#164 phase 2): sha256-16 of the OBSERVED origin the seats
+     * CONVERGED on (the honest analog of hostDigest, but WEAKER and disclosed — the harness only
+     * OBSERVES that each seat reached this origin; it never MINTED it). It is derived from what the
+     * seats actually reached, NOT from the declared appUrl: verify proves every laneWindow.routeHostDigest
+     * (that seat's CDP-observed final URL origin) equals it — inter-seat convergence on ONE OBSERVED
+     * origin, not harness control of the plane. A digest, not the raw origin (kept consistent with
+     * hostDigest hygiene). Absent on getHost.
+     */
+    publicOriginDigest?: string;
+    /**
+     * EXTERNAL-PUBLIC plane class only: sha256-16 of the operator-DECLARED origin (from subject.appUrl),
+     * recorded for reference/evidence ONLY. It is NEVER asserted equal to publicOriginDigest: a normal
+     * cross-origin redirect (apex->www, http->https) makes the OBSERVED origin differ from the declared
+     * one, which is expected. Operator OWNERSHIP rests on the subject.publicTarget.authorized attestation
+     * + the declared appUrl, NOT on digest equality. A digest, not the raw origin. Absent on getHost.
+     */
+    declaredOriginDigest?: string;
+}
+/**
+ * CONCURRENT shape (#164 phase 2): one actor's harness-clocked activity window against the ONE
+ * shared plane. OVERLAPPING windows mechanically prove ≥2 personas were active simultaneously.
+ * `laneWindows` and `stateSeries` are INDEPENDENT series — there is deliberately NO per-delta→actor
+ * field (causation under concurrency is structurally inexpressible — FIX-7).
+ */
+export interface SharedWorldParticipantWindow {
+    roleId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    /** Resolves to a real RunSimulation in this bundle. */
+    simId: string;
+    /** Resolves to a real RunStream (the actor's trace) in this bundle. */
+    streamId: string;
+    /** ms on the ONE harness clock — the wrapped [start,end] the orchestrator MEASURED (FIX-1). */
+    startedAt: number;
+    endedAt: number;
+    /** The actor's terminal session verdict (per-persona). */
+    verdict: string;
+    /** sha256-16 of the ORIGIN of the getHost seat URL this actor drove. verify confirms it equals
+     *  plane.hostDigest — i.e. the actor drove EXACTLY the harness-minted host (invariant 2; FIX-2).
+     *  A digest, not the raw URL (a getHost URL is not publish-safe — see SharedWorldPlane.hostDigest). */
+    routeHostDigest: string;
+    /** The shared plane's commit this actor observed (omitted when unresolved). */
+    commit?: string;
+    /** The shared plane's seed-recipe digest this actor observed. */
+    seedDigest: string;
+}
+/** CONCURRENT shape: one cadence checkpoint of the shared world under load. DIGEST-ONLY — the
+ *  allowed-keys tripwire (SHARED_WORLD_STATESERIES_KEYS) permits ONLY {timestamp, digest}. */
+export interface SharedWorldStateSnapshot {
+    /** ms on the ONE harness clock. */
+    timestamp: number;
+    /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
+    digest: string;
+}
+/** CONCURRENT shape: one persona's OUTCOME against the contended world (the "M of N" headline). */
+export interface SharedWorldOutcome {
+    roleId: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+    simId: string;
+    streamId: string;
+    /** Terminal session status. */
+    status: string;
+    completionReason?: string;
+    /** Reached its goal (terminal, engaged, no harness error). */
+    ok: boolean;
+}
+/**
+ * The fields a window and an outcome start with, in the saved order: the participant id saved as
+ * `roleId`, its taxonomy labels when declared, then its record and stream ids.
+ */
+export declare function sharedWorldParticipantKeys(ids: ParticipantIds, participantId: string, labels: {
+    readonly actorType?: string;
+    readonly surface?: string;
+    readonly caseGroup?: string;
+}): Pick<SharedWorldOutcome, "roleId" | "actorType" | "surface" | "caseGroup" | "simId" | "streamId">;
+/** A timeline checkpoint: a read-only digest probe of the shared plane at one moment. Persisted
+ *  DIGEST-ONLY — `digest` is sha256-16(scrub+redact(stdout)); no raw value ever lands. */
+export interface SharedWorldCheckpoint {
+    kind: "checkpoint";
+    /** "cp-baseline" for the baseline snapshot; "cp-after-<roleId>" after each role's turn. */
+    name: string;
+    /** sha256-16 of the (scrubbed, redacted) combined probe output at this snapshot. */
+    digest: string;
+    /** True when this snapshot's digest differs from the previous checkpoint's — the observed
+     *  state changed across the intervening turn (delta attributed to the TURN, not an action). */
+    deltaFromPrev: boolean;
+}
+/** A timeline turn: one role's seat session against the shared plane. Carries the plane
+ *  provenance it observed (identical across turns by construction — the single-plane proof). */
+interface SharedWorldTurn {
+    kind: "turn";
+    roleId: string;
+    /** Resolves to a real RunSimulation in this bundle. */
+    simId: string;
+    /** Resolves to a real RunStream (the role's actor trace) in this bundle. */
+    streamId: string;
+    /** The shared plane's commit the role observed (omitted when unresolved). */
+    commit?: string;
+    /** The shared plane's seed-recipe digest the role observed. */
+    seedDigest: string;
+}
+type SharedWorldTimelineEntry = SharedWorldCheckpoint | SharedWorldTurn;
+/** Declared seats that were never started after one executed sequential role stopped the run.
+ * The executed timeline plus this ordered tail must account for every declared sim/stream. */
+interface SharedWorldSkippedTail {
+    afterRoleId: string;
+    roles: Array<{
+        roleId: string;
+        simId: string;
+        streamId: string;
+    }>;
+    cause: "harness_error" | "session_error" | "usage_unreported" | "study_spend_limit";
+    /** Present only for a measured aggregate threshold; estimates, not provider billing. */
+    maxTotalUsd?: number;
+    estimatedTotalUsd?: number;
+}
+/**
+ * The shared-world evidence block (`humanish.shared-world.v1`). TWO variants discriminated by
+ * `topologyMode` (FIX-8 — renamed off `RunBundle.mode` to avoid the dry-run|live collision):
+ *
+ * - SEQUENTIAL (`topologyMode: "sequential"`): `sequence` + an alternating `timeline`
+ *   (cp-baseline → turn → cp → … → cp); limits `sequential-only` etc. No route writes it since
+ *   0.106.0; verify still reads it so older bundles keep verifying.
+ * - CONCURRENT (`topologyMode: "concurrent"`, #164 phase 2): `laneWindows` + `stateSeries` +
+ *   `outcomes`; limits `concurrent` etc. NO `timeline`.
+ *
+ * Additive + optional on `humanish.run-bundle.v1` — absent on every non-shared-world bundle.
+ * The mandatory `attributionLimits` are verify-enforced (FAIL CLOSED on a missing required or a
+ * present forbidden limit).
+ */
+export interface SharedWorldEvidence {
+    schema: typeof SHARED_WORLD_SCHEMA;
+    topology: "shared-world";
+    /** The substrate discriminator (FIX-8). Branched on first by sharedWorldEvidenceFindings. */
+    topologyMode: "sequential" | "concurrent";
+    /**
+     * CONCURRENT route only (#164 phase 2): the PLANE-class discriminator. Absent == the historical
+     * "provisioned-getHost" plane (a clone/local-tree subject served + getHost-exposed in-sandbox — the
+     * harness MINTED the host; synthetic-seeded attestation + authoritative in-sandbox checkpoint
+     * stateSeries). "external-public" == a real operator-owned public deployment used directly as the
+     * plane (NO getHost/clone/seed; operator-attested, not harness-controlled; NO authoritative
+     * shared-state proof — concurrency evidenced by temporal co-occupancy + observed lobby convergence).
+     * verify gates EVERY getHost-specific assertion on this discriminator; existing bundles omit it and
+     * default to provisioned-getHost, byte-stable.
+     */
+    planeClass?: "provisioned-getHost" | "external-public";
+    /** The DECLARED number of role seats. */
+    roleCount: number;
+    plane: SharedWorldPlane;
+    /** The pinned, verify-enforced attribution ceiling (the set differs per topologyMode/planeClass). */
+    attributionLimits: string[];
+    /**
+     * EXTERNAL-PUBLIC plane class only (#164 phase 2, optional-but-strong): sha256-16 of the shared
+     * `/lobby/CODE` PATH every seat's CDP-observed URL converged on — the concrete "they were in ONE
+     * shared world" proof, observation-derived and needing no subject change. Digest-only (the raw
+     * 6-char CODE and full URLs are runtime-only and never land). Absent when seats did not converge.
+     */
+    lobbyConvergenceDigest?: string;
+    /** The role ids that actually took a turn, in declared order. */
+    sequence?: string[];
+    timeline?: SharedWorldTimelineEntry[];
+    /** Explicit unstarted suffix; absent on historical/full-execution bundles. */
+    skippedTail?: SharedWorldSkippedTail;
+    /** Per-actor harness-clocked windows (overlap proves simultaneity). */
+    laneWindows?: SharedWorldParticipantWindow[];
+    /** Cadence digests of the shared world under load (baseline + periodic + final). */
+    stateSeries?: SharedWorldStateSnapshot[];
+    /** Per-persona outcomes (the "M of N succeeded" headline). */
+    outcomes?: SharedWorldOutcome[];
+}
+/** A participant's time on the plane, in ms on the harness clock, as laneWindows record it. */
+interface ParticipantWindow {
+    startedAt: number;
+    endedAt: number;
+}
+/**
+ * What a shared-world run shows about concurrency, as verify's pass gate and the judge both read
+ * it: whether two or more seats were live at once, and, when the plane keeps a state series (the
+ * provisioned plane), whether the state changed at or after the first overlap started.
+ */
+export declare function concurrencyFacts(windows: readonly ParticipantWindow[], stateSeries: readonly SharedWorldStateSnapshot[] | undefined): {
+    overlap: boolean;
+    stateChangedUnderOverlap?: boolean;
+};
+export {};

package/dist/run/shared-world-evidence.js

@@ -0,0 +1,49 @@
+// The sharedWorld block of run.json (humanish.shared-world.v1): the one shared plane, each seat's
+// window, state snapshots and the interleaved timeline of checkpoints and turns.
+export const SHARED_WORLD_SCHEMA = "humanish.shared-world.v1";
+/**
+ * The fields a window and an outcome start with, in the saved order: the participant id saved as
+ * `roleId`, its taxonomy labels when declared, then its record and stream ids.
+ */
+export function sharedWorldParticipantKeys(ids, participantId, labels) {
+    return {
+        roleId: participantId,
+        ...(labels.actorType === undefined ? {} : { actorType: labels.actorType }),
+        ...(labels.surface === undefined ? {} : { surface: labels.surface }),
+        ...(labels.caseGroup === undefined ? {} : { caseGroup: labels.caseGroup }),
+        simId: ids.recordId,
+        streamId: ids.streamId,
+    };
+}
+/** Where two participant windows overlap in time, the start of each overlap (the later of the two starts). */
+function overlapStarts(windows) {
+    const starts = [];
+    for (let i = 0; i < windows.length; i += 1) {
+        for (let j = i + 1; j < windows.length; j += 1) {
+            const a = windows[i];
+            const b = windows[j];
+            if (a.startedAt < b.endedAt && b.startedAt < a.endedAt)
+                starts.push(Math.max(a.startedAt, b.startedAt));
+        }
+    }
+    return starts;
+}
+/**
+ * What a shared-world run shows about concurrency, as verify's pass gate and the judge both read
+ * it: whether two or more seats were live at once, and, when the plane keeps a state series (the
+ * provisioned plane), whether the state changed at or after the first overlap started.
+ */
+export function concurrencyFacts(windows, stateSeries) {
+    const starts = overlapStarts(windows);
+    const overlap = starts.length > 0;
+    if (stateSeries === undefined)
+        return { overlap };
+    if (!overlap)
+        return { overlap, stateChangedUnderOverlap: false };
+    const earliestOverlapStart = Math.min(...starts);
+    const sorted = [...stateSeries].sort((x, y) => x.timestamp - y.timestamp);
+    const stateChangedUnderOverlap = sorted.some((snapshot, i) => i > 0 &&
+        snapshot.digest !== sorted[i - 1].digest &&
+        snapshot.timestamp >= earliestOverlapStart);
+    return { overlap, stateChangedUnderOverlap };
+}