@fungi.computer/computer 0.0.0-stage → 0.0.1

package/dist/fleet/runtime-usage.d.ts

@@ -0,0 +1,50 @@
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type ContainerRuntimeStart, type HostedBacking } from "../computer-backends.js";
+import type { ComputerFact, ComputerProvenance, ComputerUsageInterval } from "./wire.js";
+/**
+ * Computer-local interval ledger; the host owns usage settlement.
+ *
+ * A running runtime's checkpoint advances at most once per `checkpointMs`.
+ * Repeated reads inside one checkpoint expose the same interval so the host
+ * can deliver it idempotently.
+ */
+export declare class ComputerRuntimeUsage {
+    private readonly sql;
+    private readonly checkpointMs;
+    constructor(sql: WatchdogSqliteOwner["sql"], checkpointMs: number);
+    ensure(): void;
+    started(start: ContainerRuntimeStart): void;
+    touchActivity(backing: HostedBacking, at: number): void;
+    idleDeadline(runtimeId: string, idleMs: number, now: number): number | null;
+    hasOpen(backing: HostedBacking): boolean;
+    hasAnyOpen(): boolean;
+    open(): {
+        runtimeId: string;
+        backing: HostedBacking;
+    }[];
+    recycleCandidates(before: number): {
+        runtimeId: string;
+        backing: HostedBacking;
+    }[];
+    private ensureRecycle;
+    pendingRecycles(): {
+        runtimeId: string;
+        backing: Extract<HostedBacking, {
+            kind: "on-box-vm";
+        }>;
+        requestedAt: number;
+    }[];
+    requestRecycle(runtimeId: string, backing: HostedBacking, requestedAt: number): void;
+    finishRecycle(runtimeId: string): void;
+    oldestVmStart(): number | null;
+    observe(runtimeId: string, observed: {
+        running: boolean;
+        endedAt: number;
+    }): void;
+    pending(): ComputerUsageInterval[];
+    /** Read delivery facts without changing the retained checkpoint or acknowledgment. */
+    pendingFacts(computerId: string, provenance: ComputerProvenance): Extract<ComputerFact, {
+        kind: "interval";
+    }>[];
+    acknowledge(intervals: readonly ComputerUsageInterval[]): void;
+}

package/dist/fleet/runtime-usage.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { hostedBackingSchema, } from "../computer-backends.js";
+/**
+ * Computer-local interval ledger; the host owns usage settlement.
+ *
+ * A running runtime's checkpoint advances at most once per `checkpointMs`.
+ * Repeated reads inside one checkpoint expose the same interval so the host
+ * can deliver it idempotently.
+ */
+export class ComputerRuntimeUsage {
+    sql;
+    checkpointMs;
+    constructor(sql, checkpointMs) {
+        this.sql = sql;
+        this.checkpointMs = checkpointMs;
+    }
+    ensure() {
+        this.sql.exec("CREATE TABLE IF NOT EXISTS hub_computer_runtime_usage (runtime_id TEXT PRIMARY KEY, backing TEXT NOT NULL, started_at INTEGER NOT NULL, observed_at INTEGER NOT NULL, ended INTEGER NOT NULL CHECK (ended IN (0,1)), delivered_at INTEGER NOT NULL DEFAULT -1) STRICT");
+        this.sql.exec("CREATE TABLE IF NOT EXISTS hub_computer_runtime_activity (runtime_id TEXT PRIMARY KEY, last_activity_at INTEGER NOT NULL) STRICT");
+    }
+    started(start) {
+        this.ensure();
+        this.sql.exec("INSERT OR IGNORE INTO hub_computer_runtime_usage (runtime_id, backing, started_at, observed_at, ended) VALUES (?,?,?,?,0)", start.runtimeId, JSON.stringify(start.backing), start.startedAt, start.startedAt);
+        this.sql.exec("INSERT OR IGNORE INTO hub_computer_runtime_activity (runtime_id, last_activity_at) VALUES (?,?)", start.runtimeId, start.startedAt);
+    }
+    touchActivity(backing, at) {
+        this.ensure();
+        const encodedBacking = JSON.stringify(backing);
+        this.sql.exec("UPDATE hub_computer_runtime_activity SET last_activity_at=MAX(last_activity_at, ?) WHERE runtime_id IN (SELECT runtime_id FROM hub_computer_runtime_usage WHERE backing=? AND ended=0)", at, encodedBacking);
+        this.sql.exec("INSERT OR IGNORE INTO hub_computer_runtime_activity (runtime_id, last_activity_at) SELECT runtime_id, ? FROM hub_computer_runtime_usage WHERE backing=? AND ended=0", at, encodedBacking);
+    }
+    idleDeadline(runtimeId, idleMs, now) {
+        this.ensure();
+        this.sql.exec("INSERT OR IGNORE INTO hub_computer_runtime_activity (runtime_id, last_activity_at) SELECT runtime_id, ? FROM hub_computer_runtime_usage WHERE runtime_id=? AND ended=0", now, runtimeId);
+        const row = this.sql
+            .exec("SELECT last_activity_at FROM hub_computer_runtime_activity WHERE runtime_id=?", runtimeId)
+            .toArray()[0];
+        return row === undefined
+            ? null
+            : z.number().int().nonnegative().parse(row.last_activity_at) + idleMs;
+    }
+    hasOpen(backing) {
+        this.ensure();
+        return (this.sql
+            .exec("SELECT runtime_id FROM hub_computer_runtime_usage WHERE ended=0 AND backing=? LIMIT 1", JSON.stringify(backing))
+            .toArray().length > 0);
+    }
+    hasAnyOpen() {
+        return (this.sql
+            .exec("SELECT runtime_id FROM hub_computer_runtime_usage WHERE ended=0 LIMIT 1")
+            .toArray().length > 0);
+    }
+    open() {
+        return this.sql
+            .exec("SELECT runtime_id, backing FROM hub_computer_runtime_usage WHERE ended = 0 ORDER BY started_at DESC")
+            .toArray()
+            .map((row) => ({
+            runtimeId: z.string().parse(row.runtime_id),
+            backing: hostedBackingSchema.parse(JSON.parse(z.string().parse(row.backing))),
+        }));
+    }
+    recycleCandidates(before) {
+        return this.sql
+            .exec("SELECT runtime_id,backing FROM hub_computer_runtime_usage WHERE ended=0 AND started_at<=?", before)
+            .toArray()
+            .map((row) => ({
+            runtimeId: z.string().parse(row.runtime_id),
+            backing: hostedBackingSchema.parse(JSON.parse(z.string().parse(row.backing))),
+        }));
+    }
+    ensureRecycle() {
+        this.sql.exec("CREATE TABLE IF NOT EXISTS hub_computer_vm_recycle (runtime_id TEXT PRIMARY KEY, backing TEXT NOT NULL, requested_at INTEGER NOT NULL) STRICT");
+    }
+    pendingRecycles() {
+        this.ensureRecycle();
+        return this.sql
+            .exec("SELECT runtime_id,backing,requested_at FROM hub_computer_vm_recycle")
+            .toArray()
+            .map((row) => {
+            const backing = hostedBackingSchema.parse(JSON.parse(z.string().parse(row.backing)));
+            if (backing.kind !== "on-box-vm")
+                throw new Error("Invalid VM recycle backing");
+            return {
+                runtimeId: z.string().parse(row.runtime_id),
+                backing,
+                requestedAt: z.number().parse(row.requested_at),
+            };
+        });
+    }
+    requestRecycle(runtimeId, backing, requestedAt) {
+        this.ensureRecycle();
+        this.sql.exec("INSERT INTO hub_computer_vm_recycle (runtime_id,backing,requested_at) VALUES (?,?,?)", runtimeId, JSON.stringify(backing), requestedAt);
+    }
+    finishRecycle(runtimeId) {
+        this.sql.exec("DELETE FROM hub_computer_vm_recycle WHERE runtime_id=?", runtimeId);
+    }
+    oldestVmStart() {
+        return z
+            .number()
+            .nullable()
+            .parse(this.sql
+            .exec("SELECT MIN(started_at) AS started_at FROM hub_computer_runtime_usage WHERE ended=0 AND json_extract(backing,'$.kind')='on-box-vm'")
+            .toArray()[0]?.started_at ?? null);
+    }
+    observe(runtimeId, observed) {
+        if (!observed.running) {
+            this.sql.exec("UPDATE hub_computer_runtime_usage SET observed_at = MAX(observed_at, ?), ended = 1 WHERE runtime_id = ?", observed.endedAt, runtimeId);
+            return;
+        }
+        const now = Date.now();
+        this.sql.exec("UPDATE hub_computer_runtime_usage SET observed_at = ? WHERE runtime_id = ? AND ended = 0 AND observed_at <= ?", now, runtimeId, now - this.checkpointMs);
+    }
+    pending() {
+        return this.sql
+            .exec("SELECT runtime_id, backing, started_at, observed_at, ended FROM hub_computer_runtime_usage WHERE observed_at > delivered_at OR ended = 1 LIMIT 64")
+            .toArray()
+            .map((row) => ({
+            runtimeId: z.string().parse(row.runtime_id),
+            backing: hostedBackingSchema.parse(JSON.parse(z.string().parse(row.backing))),
+            startedAt: z.number().parse(row.started_at),
+            observedAt: z.number().parse(row.observed_at),
+            ended: row.ended === 1,
+        }));
+    }
+    /** Read delivery facts without changing the retained checkpoint or acknowledgment. */
+    pendingFacts(computerId, provenance) {
+        return this.pending().map((interval) => ({
+            kind: "interval",
+            computerId,
+            provenance,
+            ...interval,
+        }));
+    }
+    acknowledge(intervals) {
+        for (const interval of intervals)
+            this.sql.exec("UPDATE hub_computer_runtime_usage SET delivered_at = ? WHERE runtime_id = ?", interval.observedAt, interval.runtimeId);
+        // Ended and delivered intervals live on in the host's settlement ledger only.
+        for (const interval of intervals)
+            if (interval.ended)
+                this.sql.exec("DELETE FROM hub_computer_runtime_usage WHERE runtime_id = ? AND ended = 1 AND delivered_at >= observed_at", interval.runtimeId);
+        for (const interval of intervals)
+            if (interval.ended)
+                this.sql.exec("DELETE FROM hub_computer_runtime_activity WHERE runtime_id=? AND NOT EXISTS (SELECT 1 FROM hub_computer_runtime_usage WHERE runtime_id=?)", interval.runtimeId, interval.runtimeId);
+    }
+}

package/dist/fleet/slots.d.ts

@@ -0,0 +1,30 @@
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+/** Reservation facts; infrastructure capacity is supplied by the host. */
+type FleetSlotReservation = Readonly<{
+    kind: "reserved";
+    runningComputers: number;
+}> | Readonly<{
+    kind: "capacity";
+    runningComputers: number;
+    limit: number;
+    retryAfterSeconds: number;
+}> | Readonly<{
+    kind: "unavailable";
+    cause: unknown;
+}>;
+/** Atomically held hosted cold starts, independent of host policy. */
+export declare function createFleetSlots(options: Readonly<{
+    sql: WatchdogSqliteOwner["sql"];
+    transactionSync: <T>(body: () => T) => T;
+}>, capacity: Readonly<{
+    limit: number;
+    retryAfterSeconds: number;
+}>): {
+    ensure: () => Readonly<{
+        toArray: () => readonly import("@fungi.computer/watchdog").WatchdogSqliteRow[];
+    }>;
+    count: () => number;
+    reserve: (computerId: string) => FleetSlotReservation;
+    release: (computerId: string) => void;
+};
+export {};

package/dist/fleet/slots.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+/** Atomically held hosted cold starts, independent of host policy. */
+export function createFleetSlots(options, capacity) {
+    const { sql } = options;
+    const ensure = () => sql.exec(`CREATE TABLE IF NOT EXISTS hub_team_running_computers (
+      computer_id TEXT PRIMARY KEY
+    ) STRICT`);
+    const count = () => {
+        const row = sql
+            .exec("SELECT COUNT(*) AS count FROM hub_team_running_computers")
+            .toArray()[0];
+        if (row === undefined)
+            throw new Error("Running Computer count missing");
+        return z.number().int().nonnegative().parse(row.count);
+    };
+    /** Capacity-only synchronous admission for a hosted cold start. */
+    const reserve = (computerId) => {
+        try {
+            return options.transactionSync(() => {
+                const existing = sql
+                    .exec("SELECT computer_id FROM hub_team_running_computers WHERE computer_id = ?", computerId)
+                    .toArray()[0];
+                const running = count();
+                if (existing !== undefined)
+                    return { kind: "reserved", runningComputers: running };
+                if (running >= capacity.limit)
+                    return {
+                        kind: "capacity",
+                        runningComputers: running,
+                        limit: capacity.limit,
+                        retryAfterSeconds: capacity.retryAfterSeconds,
+                    };
+                sql.exec("INSERT INTO hub_team_running_computers (computer_id) VALUES (?)", computerId);
+                return { kind: "reserved", runningComputers: running + 1 };
+            });
+        }
+        catch (cause) {
+            return { kind: "unavailable", cause };
+        }
+    };
+    /** Releasing an absent slot is an ordinary replay from stop/sleep recovery. */
+    const release = (computerId) => {
+        options.transactionSync(() => sql.exec("DELETE FROM hub_team_running_computers WHERE computer_id = ?", computerId));
+    };
+    return { ensure, count, reserve, release };
+}

package/dist/fleet/wire.d.ts

@@ -0,0 +1,228 @@
+import { z } from "zod";
+import { hostedBackingSchema, type AttachedBackend } from "../computer-backends.js";
+/** Operations the host may admit on one Computer. */
+export declare const computerActionSchema: z.ZodEnum<{
+    exec: "exec";
+    start: "start";
+    delete: "delete";
+    "files.read": "files.read";
+    "files.readBytes": "files.readBytes";
+    "files.write": "files.write";
+    "files.writeBytes": "files.writeBytes";
+    "files.list": "files.list";
+    "files.glob": "files.glob";
+    "files.grep": "files.grep";
+    "files.edit": "files.edit";
+    "files.patch": "files.patch";
+    mkdir: "mkdir";
+    bash: "bash";
+    backing: "backing";
+    exposePort: "exposePort";
+    listPorts: "listPorts";
+    unexposePort: "unexposePort";
+    terminal: "terminal";
+    stop: "stop";
+    processStart: "processStart";
+    processList: "processList";
+    processKill: "processKill";
+}>;
+export type ComputerAction = z.output<typeof computerActionSchema>;
+/** Opaque host identities; the fleet does not derive authority from their text. */
+export declare const computerProvenanceSchema: z.ZodObject<{
+    actor: z.ZodString;
+    via: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ComputerProvenance = z.output<typeof computerProvenanceSchema>;
+/** Host-issued data, never a request body's claim to authority. Times are milliseconds. */
+export declare const computerGrantSchema: z.ZodObject<{
+    computerId: z.ZodString;
+    actions: z.ZodReadonly<z.ZodSet<z.ZodEnum<{
+        exec: "exec";
+        start: "start";
+        delete: "delete";
+        "files.read": "files.read";
+        "files.readBytes": "files.readBytes";
+        "files.write": "files.write";
+        "files.writeBytes": "files.writeBytes";
+        "files.list": "files.list";
+        "files.glob": "files.glob";
+        "files.grep": "files.grep";
+        "files.edit": "files.edit";
+        "files.patch": "files.patch";
+        mkdir: "mkdir";
+        bash: "bash";
+        backing: "backing";
+        exposePort: "exposePort";
+        listPorts: "listPorts";
+        unexposePort: "unexposePort";
+        terminal: "terminal";
+        stop: "stop";
+        processStart: "processStart";
+        processList: "processList";
+        processKill: "processKill";
+    }>>>;
+    expiresAt: z.ZodNumber;
+    egress: z.ZodOptional<z.ZodJSONSchema>;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ComputerGrant = z.output<typeof computerGrantSchema>;
+/** State visible without knowing which application hosts the Computer. */
+export declare const computerStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodEnum<{
+        running: "running";
+        sleeping: "sleeping";
+        starting: "starting";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"queued">;
+    position: z.ZodNumber;
+}, z.core.$strict>], "state">;
+export type ComputerRuntimeState = z.output<typeof computerStateSchema>;
+/** Hosted fallback order, with the same bound and identity law as the retained owner. */
+export declare const hostedBackingsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"platform-container">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"on-box-vm">;
+    hostId: z.ZodString;
+}, z.core.$strict>], "kind">>;
+/** The host delivers this complete revision to its Computer runtime. */
+export type ComputerBackendsProjection = Readonly<{
+    computerId: string;
+    revision: number;
+    backends: readonly AttachedBackend[];
+}>;
+/** An explicit override, or the fleet default when no Computer is selected. */
+export declare const computerBackingChangeSchema: z.ZodObject<{
+    computerId: z.ZodOptional<z.ZodString>;
+    backings: z.ZodNullable<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"platform-container">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"on-box-vm">;
+        hostId: z.ZodString;
+    }, z.core.$strict>], "kind">>>;
+}, z.core.$strict>;
+export type ComputerBackingChange = Readonly<{
+    computerId?: string | undefined;
+    backings: readonly z.output<typeof hostedBackingSchema>[] | null;
+}>;
+/** A backing operation was refused without changing the stored decision. */
+export declare class ComputerBackingError extends Error {
+    readonly code: "unknown_computer" | "not_enabled" | "invalid" | "request_conflict" | "local_limit" | "not_owner";
+    constructor(code: "unknown_computer" | "not_enabled" | "invalid" | "request_conflict" | "local_limit" | "not_owner");
+}
+/** Local device attachment uses an opaque actor supplied by the host. */
+export declare const localBackendAttachSchema: z.ZodObject<{
+    computerId: z.ZodString;
+    publicKey: z.ZodBase64;
+    hostLabel: z.ZodString;
+    folderLabel: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strict>;
+export type LocalBackendAttachInput = z.output<typeof localBackendAttachSchema>;
+export declare const localBackendDetachSchema: z.ZodObject<{
+    computerId: z.ZodString;
+    backendId: z.ZodString;
+}, z.core.$strict>;
+/** Recover a lost attach response without retaining the device key. */
+export declare const localBackendDetachRequestSchema: z.ZodObject<{
+    computerId: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strict>;
+export type LocalBackendDetachInput = z.output<typeof localBackendDetachSchema> | z.output<typeof localBackendDetachRequestSchema>;
+/** One runtime observation; the host owns delivery and settlement. */
+export declare const computerUsageIntervalSchema: z.ZodObject<{
+    runtimeId: z.ZodString;
+    backing: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"platform-container">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"on-box-vm">;
+        hostId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    startedAt: z.ZodNumber;
+    observedAt: z.ZodNumber;
+    ended: z.ZodBoolean;
+}, z.core.$strict>;
+/** Spelled out: it types a Durable Object RPC parameter. */
+export type ComputerUsageInterval = Readonly<{
+    runtimeId: string;
+    backing: Readonly<{
+        kind: "platform-container";
+    }> | Readonly<{
+        kind: "on-box-vm";
+        hostId: string;
+    }>;
+    startedAt: number;
+    observedAt: number;
+    ended: boolean;
+}>;
+/** Observations, not billing decisions. The host owns delivery and settlement. */
+export declare const computerFactSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"process.exited">;
+    requestId: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    cpuTimeMs: z.ZodNullable<z.ZodNumber>;
+    wallTimeMs: z.ZodNumber;
+    computerId: z.ZodString;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"files.written">;
+    path: z.ZodString;
+    bytes: z.ZodNumber;
+    computerId: z.ZodString;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"egress">;
+    host: z.ZodString;
+    method: z.ZodString;
+    status: z.ZodNumber;
+    computerId: z.ZodString;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"lifecycle">;
+    observedAt: z.ZodNumber;
+    state: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodEnum<{
+            running: "running";
+            sleeping: "sleeping";
+            starting: "starting";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"queued">;
+        position: z.ZodNumber;
+    }, z.core.$strict>], "state">;
+    computerId: z.ZodString;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    runtimeId: z.ZodString;
+    backing: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"platform-container">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"on-box-vm">;
+        hostId: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    startedAt: z.ZodNumber;
+    observedAt: z.ZodNumber;
+    ended: z.ZodBoolean;
+    kind: z.ZodLiteral<"interval">;
+    computerId: z.ZodString;
+    provenance: z.ZodObject<{
+        actor: z.ZodString;
+        via: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "kind">;
+export type ComputerFact = z.output<typeof computerFactSchema>;

package/dist/fleet/wire.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { computerOperationSchema, computerValueSchema, pathSchema, } from "../operation-contract.js";
+import { attachedBackendId, hostedBackingSchema, localBackendSchema, } from "../computer-backends.js";
+/** Operations the host may admit on one Computer. */
+export const computerActionSchema = z.enum([
+    ...computerOperationSchema.options,
+    "terminal",
+    "start",
+    "stop",
+    "processStart",
+    "processList",
+    "processKill",
+    "exposePort",
+    "unexposePort",
+    "listPorts",
+    "backing",
+    "delete",
+]);
+/** Opaque host identities; the fleet does not derive authority from their text. */
+export const computerProvenanceSchema = z.strictObject({
+    actor: z.string().min(1),
+    via: z.string().min(1).optional(),
+});
+/** Host-issued data, never a request body's claim to authority. Times are milliseconds. */
+export const computerGrantSchema = z.strictObject({
+    computerId: z.string().min(1).max(256),
+    actions: z.set(computerActionSchema).readonly(),
+    expiresAt: z.number().int().nonnegative(),
+    /** Host-specific policy data travels downward without an upward policy callback. */
+    egress: computerValueSchema.optional(),
+    provenance: computerProvenanceSchema,
+});
+/** State visible without knowing which application hosts the Computer. */
+export const computerStateSchema = z.discriminatedUnion("state", [
+    z.strictObject({ state: z.enum(["running", "sleeping", "starting"]) }),
+    z.strictObject({
+        state: z.literal("queued"),
+        position: z.number().int().positive(),
+    }),
+]);
+/** Hosted fallback order, with the same bound and identity law as the retained owner. */
+export const hostedBackingsSchema = z
+    .array(hostedBackingSchema)
+    .max(4)
+    .refine((backings) => new Set(backings.map(attachedBackendId)).size === backings.length, "hosted backings must be distinct");
+/** An explicit override, or the fleet default when no Computer is selected. */
+export const computerBackingChangeSchema = z.strictObject({
+    computerId: z.string().min(1).max(256).optional(),
+    backings: hostedBackingsSchema.nullable(),
+});
+/** A backing operation was refused without changing the stored decision. */
+export class ComputerBackingError extends Error {
+    code;
+    constructor(code) {
+        super(`Computer backing refused: ${code}`);
+        this.code = code;
+        this.name = "ComputerBackingError";
+    }
+}
+/** Local device attachment uses an opaque actor supplied by the host. */
+export const localBackendAttachSchema = z.strictObject({
+    computerId: z.string().min(1).max(256),
+    publicKey: localBackendSchema.shape.publicKey,
+    hostLabel: localBackendSchema.shape.hostLabel,
+    folderLabel: localBackendSchema.shape.folderLabel,
+    requestId: z.string().min(1).max(256),
+});
+export const localBackendDetachSchema = z.strictObject({
+    computerId: z.string().min(1).max(256),
+    backendId: z.string().regex(/^local-[a-z2-7]{16}$/),
+});
+/** Recover a lost attach response without retaining the device key. */
+export const localBackendDetachRequestSchema = z.strictObject({
+    computerId: localBackendAttachSchema.shape.computerId,
+    requestId: localBackendAttachSchema.shape.requestId,
+});
+const factIdentity = {
+    computerId: computerGrantSchema.shape.computerId,
+    provenance: computerProvenanceSchema,
+};
+/** One runtime observation; the host owns delivery and settlement. */
+export const computerUsageIntervalSchema = z.strictObject({
+    runtimeId: z.string().min(1).max(128),
+    backing: hostedBackingSchema,
+    startedAt: z.number().int().nonnegative(),
+    /** The last observed instant; final once `ended` is true. */
+    observedAt: z.number().int().nonnegative(),
+    ended: z.boolean(),
+});
+const timestamp = z.number().int().nonnegative();
+/** Observations, not billing decisions. The host owns delivery and settlement. */
+export const computerFactSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...factIdentity,
+        kind: z.literal("process.exited"),
+        requestId: z.string().min(1),
+        exitCode: z.number().int().nullable(),
+        /** Null means the backend did not measure CPU; it does not mean zero usage. */
+        cpuTimeMs: z.number().nonnegative().nullable(),
+        wallTimeMs: z.number().nonnegative(),
+    }),
+    z.strictObject({
+        ...factIdentity,
+        kind: z.literal("files.written"),
+        path: pathSchema,
+        bytes: z.number().int().nonnegative(),
+    }),
+    z.strictObject({
+        ...factIdentity,
+        kind: z.literal("egress"),
+        /** Only the destination host; URLs may carry credentials in paths or queries. */
+        host: z.string().min(1),
+        method: z.string().min(1),
+        status: z.number().int().min(100).max(599),
+    }),
+    z.strictObject({
+        ...factIdentity,
+        kind: z.literal("lifecycle"),
+        observedAt: timestamp,
+        state: computerStateSchema,
+    }),
+    z.strictObject({
+        ...factIdentity,
+        kind: z.literal("interval"),
+        ...computerUsageIntervalSchema.shape,
+    }),
+]);

package/dist/host-config.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** One VM host's active capacity, including slots held back as headroom. */
+export declare const hostCapacitySchema: z.ZodObject<{
+    maxActive: z.ZodNumber;
+    reservedHeadroom: z.ZodNumber;
+}, z.core.$strict>;
+/** Public Computer host capacity configuration, keyed by registered host ID. */
+export declare const hostCapacityRegistrySchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    maxActive: z.ZodNumber;
+    reservedHeadroom: z.ZodNumber;
+}, z.core.$strict>>;
+export type HostCapacity = z.infer<typeof hostCapacitySchema>;

package/dist/host-config.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** One VM host's active capacity, including slots held back as headroom. */
+export const hostCapacitySchema = z
+    .strictObject({
+    maxActive: z.number().int().positive(),
+    reservedHeadroom: z.number().int().nonnegative(),
+})
+    .refine((value) => value.reservedHeadroom < value.maxActive);
+/** Public Computer host capacity configuration, keyed by registered host ID. */
+export const hostCapacityRegistrySchema = z.record(z.string(), hostCapacitySchema);